@akinon/pz-theme 2.0.63-rc.0 → 2.0.63

package/CHANGELOG.md

@@ -1,36 +1,13 @@
 # @akinon/pz-theme
 
-## 2.0.63-rc.0
-
-### Patch Changes
-
-- Updated dependencies [0cf9ea239]
-- Updated dependencies [324f97d55]
-- Updated dependencies [51ea06888]
-- Updated dependencies
-- Updated dependencies [2fea4143]
-- Updated dependencies [b55acb768]
-- Updated dependencies [760258c1c]
-- Updated dependencies [143be2b9d]
-- Updated dependencies [7889b08fe]
-- Updated dependencies [9f8cd3bc5]
-- Updated dependencies [bfafa3f49]
-- Updated dependencies [57d7eb305]
-- Updated dependencies [d99a6a7d5]
-- Updated dependencies [9db81a714]
-- Updated dependencies [591e345e1]
-- Updated dependencies [4de5303c5]
-- Updated dependencies [95b139dc1]
-- Updated dependencies [1d00f2d06]
-- Updated dependencies [4ac7b2a1e]
-- Updated dependencies [e9598c71]
-- Updated dependencies [4998a9631]
-- Updated dependencies [804d2bd6]
-- Updated dependencies [3909d3224]
-- Updated dependencies [6a3d8a63]
-- Updated dependencies [e18836b20]
-  - @akinon/next@2.0.63-rc.0
-  - @akinon/theme-contract@2.0.63-rc.0
+## 2.0.63
+
+### Patch Changes
+
+- 72a62c6: ZERO-4823: Implement 404 and 500 pages for theme editor
+- Updated dependencies [72a62c6]
+  - @akinon/theme-contract@2.0.63
+  - @akinon/next@2.0.63
 
 ## 2.0.62
 

package/package.json

@@ -1,26 +1,26 @@
 {
   "name": "@akinon/pz-theme",
   "description": "Theme package for Project Zero Next — ThemePlaceholder system and theme editor infrastructure",
-  "version": "2.0.63-rc.0",
+  "version": "2.0.63",
   "license": "MIT",
   "main": "src/index.ts",
   "scripts": {
     "test": "jest"
   },
   "peerDependencies": {
-    "@akinon/next": "2.0.63-rc.0",
+    "@akinon/next": "2.0.63",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@akinon/theme-contract": "2.0.63-rc.0",
+    "@akinon/theme-contract": "2.0.63",
     "clsx": "2.1.1",
     "lottie-web": "^5.13.0",
     "tailwind-merge": "^2.5.4",
     "zod": "4.4.1"
   },
   "devDependencies": {
-    "@akinon/next": "2.0.63-rc.0",
+    "@akinon/next": "2.0.63",
     "@testing-library/jest-dom": "5.16.4",
     "@testing-library/react": "16.3.2",
     "@testing-library/user-event": "14.1.1",

package/src/__tests__/route-slug.test.ts

@@ -145,6 +145,23 @@ describe('resolveBodySlug', () => {
     expect(isPageMountedSlug('checkout-page-body')).toBe(true);
   });
 
+  it('resolves the 404 screen and keeps it page-mounted', () => {
+    expect(resolveBodySlug('/404')).toBe(PLACEHOLDER_SLUGS.notFound);
+    expect(resolveBodySlug('/not-found')).toBe(PLACEHOLDER_SLUGS.notFound);
+    // The boundary mounts its own slot; a root catch-all must not double it.
+    expect(isPageMountedSlug(PLACEHOLDER_SLUGS.notFound)).toBe(true);
+  });
+
+  it('resolves the 500 screen and keeps it page-mounted', () => {
+    expect(resolveBodySlug('/500')).toBe(PLACEHOLDER_SLUGS.serverError);
+    expect(resolveBodySlug('/server-error')).toBe(
+      PLACEHOLDER_SLUGS.serverError
+    );
+    // The error boundary reads its composition from the layout provider; a
+    // root catch-all must not mount this slug a second time.
+    expect(isPageMountedSlug(PLACEHOLDER_SLUGS.serverError)).toBe(true);
+  });
+
   it('returns null for a path with no placeholder', () => {
     expect(resolveBodySlug('/kampanya-bilgilendirme')).toBeNull();
   });

package/src/chrome/error-composition-source.ts

@@ -0,0 +1,43 @@
+import 'server-only';
+
+import { loadPlaceholderSections } from '../load-placeholder-sections';
+import { generateThemeCSS } from '../utils';
+import { getSlugCompositionState } from './composition-source';
+import { buildErrorPageContext } from './page-context';
+import { PLACEHOLDER_SLUGS } from './placeholder-slugs';
+import type { ErrorComposition } from './error-composition';
+
+/**
+ * Prefetches the server-error composition for the layout to hand to the
+ * error boundary (see error-composition.tsx for why it must travel early).
+ *
+ * The cheap request-memoized composition-state read gates the expensive
+ * reconstruction: until a designer composes the slug, every page pays one
+ * widget read that ChromeSlot/theme-config sharing already amortizes, and
+ * nothing more.
+ */
+export async function loadErrorComposition(): Promise<ErrorComposition | null> {
+  const slug = PLACEHOLDER_SLUGS.serverError;
+
+  try {
+    const state = await getSlugCompositionState(slug);
+    if (state.kind !== 'composed') return null;
+
+    const loaded = await loadPlaceholderSections(slug);
+    if (!loaded || loaded.sections.length === 0) return null;
+
+    return {
+      slug,
+      placeholderId: loaded.placeholderId,
+      sections: loaded.sections,
+      themeCSS: generateThemeCSS(loaded.sections),
+      themeSettings: loaded.themeSettings,
+      pageContext: buildErrorPageContext()
+    };
+  } catch (error) {
+    // A failed prefetch must never take the page down with it — the boundary
+    // falls back to the code-owned error UI instead.
+    console.warn('Server-error composition prefetch failed:', error);
+    return null;
+  }
+}

package/src/chrome/error-composition.tsx

@@ -0,0 +1,42 @@
+'use client';
+
+import React, { createContext, useContext } from 'react';
+import type { Section } from '../theme-section';
+
+/**
+ * The server-error composition, reconstructed BEFORE anything fails.
+ *
+ * Next.js forces `error.tsx` to be a client component and hands it nothing
+ * but `{ error, reset }` — it cannot fetch on the server and it cannot
+ * receive props from one. The only channel left is a client context mounted
+ * by the layout above the boundary: the layout survives a page failure, so
+ * whatever it put here is still readable when the boundary renders. It also
+ * means the composition arrives with the page, not during the outage — the
+ * one moment the widget API itself may be down.
+ */
+export interface ErrorComposition {
+  slug: string;
+  placeholderId: string;
+  sections: Section[];
+  /** Pre-generated on the server; the boundary only injects it. */
+  themeCSS: string;
+  themeSettings: Record<string, unknown> | null;
+  pageContext: Record<string, unknown>;
+}
+
+const ErrorCompositionContext = createContext<ErrorComposition | null>(null);
+
+export const ErrorCompositionProvider = ({
+  composition,
+  children
+}: {
+  composition: ErrorComposition | null;
+  children: React.ReactNode;
+}) => (
+  <ErrorCompositionContext.Provider value={composition}>
+    {children}
+  </ErrorCompositionContext.Provider>
+);
+
+/** `null` until a designer composes the server-error placeholder. */
+export const useErrorComposition = () => useContext(ErrorCompositionContext);

package/src/chrome/page-context.ts

@@ -534,6 +534,24 @@ export const buildCheckoutPageContext = ({
   };
 };
 
+/** The 404 screen: no commerce entity, just the page identity to bind. */
+export const buildNotFoundPageContext = (path?: string) => ({
+  page: {
+    type: 'not-found',
+    title: 'Page Not Found',
+    path: path || '/404'
+  }
+});
+
+/** The 500 screen: same shape as the 404, published ahead of the failure. */
+export const buildErrorPageContext = (path?: string) => ({
+  page: {
+    type: 'error',
+    title: 'Server Error',
+    path: path || '/500'
+  }
+});
+
 /** A CMS flat page: no commerce entity, but a title and a slug to bind. */
 export const buildFlatPageContext = (flatPage?: UnknownRecord | null) => {
   const source = toRecord(flatPage);

package/src/chrome/placeholder-slugs.ts

@@ -70,7 +70,8 @@ export const PLACEHOLDER_SLUGS = {
   sitemap: 'sitemap-page-body',
   brands: 'brands-page-body',
   flatPage: 'flat-page-body',
-  notFound: 'not-found-body'
+  notFound: 'not-found-body',
+  serverError: 'server-error-body'
 } as const;
 
 export type PlaceholderSlug =

package/src/chrome/route-slug.ts

@@ -93,6 +93,12 @@ const DEFAULT_RULES: RouteSlugRule[] = [
   [/^\/sitemap/, PLACEHOLDER_SLUGS.sitemap],
   [/^\/(markalar|brands)/, PLACEHOLDER_SLUGS.brands],
   [/^\/flat-page\//, PLACEHOLDER_SLUGS.flatPage],
+  // The not-found boundary renders on ANY unmatched path, so it mounts its
+  // own slot; this rule serves the routable /404 page the editor previews.
+  [/^\/(404|not-found)(\/|$)/, PLACEHOLDER_SLUGS.notFound],
+  // Like the 404 rule: the error boundary renders wherever a page fails, so
+  // this rule only serves the routable /500 page the editor previews.
+  [/^\/(500|server-error)(\/|$)/, PLACEHOLDER_SLUGS.serverError],
   [/^\/?$/, PLACEHOLDER_SLUGS.homepage]
 ];
 
@@ -136,7 +142,13 @@ const PAGE_MOUNTED_SLUGS = new Set<string>([
   PLACEHOLDER_SLUGS.register,
   PLACEHOLDER_SLUGS.forgotPassword,
   PLACEHOLDER_SLUGS.guestLogin,
-  PLACEHOLDER_SLUGS.flatPage
+  PLACEHOLDER_SLUGS.flatPage,
+  // Mounted by the not-found boundary itself, which renders on any unmatched
+  // path — a route-resolved catch-all would never fire there.
+  PLACEHOLDER_SLUGS.notFound,
+  // Same shape: the error boundary carries its own composition (prefetched
+  // through the layout provider), so no catch-all may mount this slug.
+  PLACEHOLDER_SLUGS.serverError
 ]);
 
 /** True when a deeper page/layout already mounts this slug's slot. */

package/src/index.ts

@@ -55,9 +55,17 @@ export {
   buildOrderPageContext,
   buildCheckoutPageContext,
   buildFlatPageContext,
+  buildNotFoundPageContext,
+  buildErrorPageContext,
   configurePageContextRoutes
 } from './chrome/page-context';
 
+export {
+  ErrorCompositionProvider,
+  useErrorComposition
+} from './chrome/error-composition';
+export type { ErrorComposition } from './chrome/error-composition';
+
 export {
   PLACEHOLDER_SLUGS,
   customPageSlug,

package/src/load-placeholder-sections.ts

@@ -0,0 +1,335 @@
+import 'server-only';
+
+import * as serverData from '@akinon/next/data/server';
+import appFetch from '@akinon/next/utils/app-fetch';
+import { ServerVariables } from '@akinon/next/utils/server-variables';
+
+import { Section } from './theme-section';
+import { devWarn } from './utils/dev-warn';
+import { validateThemeSectionsInDev } from './schemas/theme-schema';
+import { getThemeConfig, ThemeConfig } from './chrome/theme-config-source';
+
+const { getWidgetData } = serverData;
+
+/**
+ * v1 cores ship a smaller server data layer: only `getWidgetData` exists,
+ * `getWidgetSchemaData` and `getCollectionWidgetData` arrived with v2.
+ *
+ * The endpoints are identical on both backends — v1 just never wrapped them.
+ * Degrading to "no data" would render every published section *without its
+ * blocks* (a section's block tree lives in the widget schema, not in the
+ * widget), so on v1 we call the REST endpoints directly. This is what keeps
+ * composed pages rendering on the brands still running v1.
+ */
+type ServerDataFn = (<T>(args: never) => Promise<T | null>) | undefined;
+
+const optionalServerFn = (name: string): ServerDataFn =>
+  (serverData as unknown as Record<string, ServerDataFn>)[name];
+
+const directFetch = async <T,>(url: string): Promise<T | null> => {
+  try {
+    const result = await appFetch<T>({
+      url,
+      locale: ServerVariables.locale,
+      currency: ServerVariables.currency
+    });
+    return result ?? null;
+  } catch {
+    return null;
+  }
+};
+
+const getCollectionWidgetData = async <T,>(args: {
+  slug: string;
+}): Promise<T | null> => {
+  const fn = optionalServerFn('getCollectionWidgetData');
+  if (fn) return (await fn<T>(args as never)) ?? null;
+  if (!args?.slug) return null;
+  return directFetch<T>(`/product_collection_widgets/${args.slug}/`);
+};
+
+const getWidgetSchemaData = async <T,>(args: {
+  widgetSlug: string;
+}): Promise<T | null> => {
+  const fn = optionalServerFn('getWidgetSchemaData');
+  if (fn) return (await fn<T>(args as never)) ?? null;
+  if (!args?.widgetSlug) return null;
+  return directFetch<T>(`/widgets/${args.widgetSlug}/schema/`);
+};
+
+type ThemePlaceholderData = {
+  theme_editor_placeholder: Array<{
+    section_slug: string;
+    order: number;
+  }>;
+};
+
+export interface LoadedPlaceholder {
+  sections: Section[];
+  placeholderId: string;
+  dataSources: ThemeConfig['dataSources'];
+  themeSettings: ThemeConfig['settings'];
+}
+
+/**
+ * Fetches and reconstructs the composed section tree for a placeholder slug.
+ *
+ * Shared by `ThemePlaceholder` (render time) and the error-composition
+ * prefetch (layout time): the error boundary is a client component that can
+ * neither fetch nor receive server props, so its composition has to be
+ * reconstructed ahead of the failure — and by the same code path, or the two
+ * renders could disagree about what a saved section contains.
+ *
+ * Returns `null` only when the data layer fails outright; a slug nobody has
+ * composed resolves with an empty `sections` array.
+ */
+export async function loadPlaceholderSections(
+  slug: string
+): Promise<LoadedPlaceholder | null> {
+  try {
+    // theme-config is optional for placeholder rendering, and the reader is
+    // memoized per request — a page with several placeholders, or a ChromeSlot
+    // asking the same question to decide whether it is pinned, reads it once.
+    const { dataSources, settings: themeSettings } = await getThemeConfig();
+
+    let data: { slug?: string; attributes?: { theme_editor_placeholder?: unknown; [key: string]: unknown } } | null = null;
+    try {
+      data = await getWidgetData<ThemePlaceholderData>({
+        slug
+      }) as typeof data;
+    } catch (placeholderError) {
+      console.warn(
+        `Theme placeholder widget "${slug}" was not found. Rendering empty placeholder.`,
+        placeholderError
+      );
+    }
+
+    const sections: Section[] = [];
+
+    if (data?.attributes?.theme_editor_placeholder) {
+      let placeholderData: any = data.attributes.theme_editor_placeholder;
+
+      if (
+        typeof placeholderData === 'object' &&
+        placeholderData !== null &&
+        'value' in placeholderData
+      ) {
+        placeholderData = (
+          placeholderData as {
+            value: { section_slug: string; order: number }[];
+          }
+        ).value;
+      }
+
+      if (typeof placeholderData === 'string') {
+        try {
+          placeholderData = JSON.parse(placeholderData);
+        } catch {
+          devWarn(
+            'ThemePlaceholder',
+            `Placeholder "${slug}" layout JSON is malformed; rendering no sections`
+          );
+          placeholderData = [];
+        }
+      }
+
+      if (!Array.isArray(placeholderData)) {
+        placeholderData = [];
+      }
+
+      const sectionPromises = placeholderData.map(async (item: any) => {
+        try {
+          const sectionSlug = item.value?.section_slug || item.section_slug;
+          const sectionOrder = item.value?.order ?? item.order ?? 0;
+
+          if (!sectionSlug) {
+            return null;
+          }
+
+          const [regularSectionData, sectionSchema] = await Promise.all([
+            getWidgetData<any>({
+              slug: sectionSlug
+            }),
+            getWidgetSchemaData<any>({
+              widgetSlug: sectionSlug
+            })
+          ]);
+
+          let sectionData = regularSectionData;
+          if (!sectionData) {
+            try {
+              sectionData = await getCollectionWidgetData<any>({
+                slug: sectionSlug
+              });
+            } catch {
+              // Not a collection widget either; sectionData stays null
+              devWarn(
+                'ThemePlaceholder',
+                `Section "${sectionSlug}" data could not be resolved as a regular or collection widget; rendering from schema only`
+              );
+            }
+          }
+
+          const sectionSchemaEntry = sectionSchema?.schema?.[sectionSlug];
+          const sectionMetadata = sectionSchemaEntry?.metadata || {};
+
+          const getBlockValue = (blockId: string): unknown => {
+            const attrData = sectionData?.attributes?.[blockId];
+            if (attrData === undefined || attrData === null) return undefined;
+
+            if (typeof attrData === 'string') {
+              try {
+                return JSON.parse(attrData);
+              } catch {
+                const trimmed = attrData.trim();
+                if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+                  devWarn(
+                    'ThemePlaceholder',
+                    `Block "${blockId}" value looks like JSON but failed to parse; using the raw string`
+                  );
+                }
+                return attrData;
+              }
+            } else if (typeof attrData === 'object' && 'value' in attrData) {
+              return attrData.value;
+            }
+            return attrData;
+          };
+
+          const reconstructBlock = (blockSchema: any): any => {
+            return {
+              id: blockSchema.id,
+              type: blockSchema.type || 'text',
+              label: blockSchema.label || blockSchema.id,
+              order: blockSchema.order || 0,
+              isIterator: blockSchema.isIterator,
+              iteratorDataPath: blockSchema.iteratorDataPath,
+              value: getBlockValue(blockSchema.id),
+              styles: blockSchema.styles || {},
+              properties: blockSchema.properties || {},
+              hidden: blockSchema.hidden || false,
+              blocks: (blockSchema.blocks || []).map((b: any) =>
+                reconstructBlock(b)
+              )
+            };
+          };
+
+          const blocks: any[] = [];
+          if (sectionMetadata.blocks && Array.isArray(sectionMetadata.blocks)) {
+            sectionMetadata.blocks.forEach((blockSchema: any) => {
+              blocks.push(reconstructBlock(blockSchema));
+            });
+          }
+
+          blocks.sort((a, b) => a.order - b.order);
+
+          // dataSourceId may be stored in schema metadata OR in widget data attributes
+          // (theme editor saves it as a widget attribute when user selects a data source)
+          const dataSourceId =
+            sectionMetadata.dataSourceId ||
+            (getBlockValue('dataSourceId') as string | undefined) ||
+            (getBlockValue('selectedDataSourceId') as string | undefined);
+
+          const dataSource = dataSourceId
+            ? dataSources.find((ds) => ds.id === dataSourceId)
+            : undefined;
+
+          if (dataSourceId && !dataSource) {
+            devWarn(
+              'ThemePlaceholder',
+              `Section "${sectionSlug}" references data source "${dataSourceId}" which was not found; rendering placeholder items`
+            );
+          }
+
+          let dataSourceWithData = dataSource;
+          if (dataSource && dataSource.details) {
+            // Only fetch collection data if we have a valid widget slug
+            // (not the section's own slug which contains config, not products)
+            const collectionSlug = dataSource.details.collection?.slug;
+            if (collectionSlug) {
+              try {
+                let collectionData = await getWidgetData<{
+                  [key: string]: unknown;
+                }>({
+                  slug: collectionSlug
+                });
+
+                if (!collectionData) {
+                  collectionData = await getCollectionWidgetData<{
+                    [key: string]: unknown;
+                  }>({
+                    slug: collectionSlug
+                  });
+                }
+
+                if (collectionData) {
+                  dataSourceWithData = {
+                    ...dataSource,
+                    details: {
+                      ...dataSource.details,
+                      collection: {
+                        ...dataSource.details.collection,
+                        data: collectionData
+                      }
+                    }
+                  };
+                }
+              } catch (error) {
+                console.error(
+                  `Error fetching widget data for section ${sectionSlug}:`,
+                  error
+                );
+              }
+            }
+            // If no collection slug, the saved products from editor
+            // (details.collection.products) will be used as fallback
+          }
+
+          const section: Section = {
+            id: sectionSlug,
+            type: sectionMetadata.type || 'default',
+            name: sectionMetadata.name || sectionSlug,
+            label: sectionMetadata.label || sectionSlug,
+            properties: sectionMetadata.properties || {},
+            styles: sectionMetadata.styles || {},
+            blocks,
+            order: sectionOrder,
+            hidden: sectionMetadata.hidden || false,
+            dataSourceId,
+            dataSource: dataSourceWithData
+          };
+
+          return section;
+        } catch (error) {
+          const errorSlug =
+            item.value?.section_slug || item.section_slug || 'unknown';
+          console.error(
+            `Error parsing section metadata for ${errorSlug}:`,
+            error
+          );
+          return null;
+        }
+      });
+
+      const resolvedSections = await Promise.all(sectionPromises);
+      sections.push(
+        ...resolvedSections.filter((s): s is Section => s !== null)
+      );
+    }
+
+    // Dev-only, warn-only shape validation of the reconstructed tree. Surfaces
+    // structural drift between the editor/backend data and the render engine
+    // without changing what renders (no-op in production).
+    validateThemeSectionsInDev(sections);
+
+    return {
+      sections,
+      placeholderId: data?.slug?.toString() || slug,
+      dataSources,
+      themeSettings
+    };
+  } catch (error) {
+    console.error(`Error fetching theme placeholder data for ${slug}:`, error);
+    return null;
+  }
+}

package/src/theme-placeholder.tsx

@@ -1,69 +1,8 @@
 import 'server-only';
 
-import * as serverData from '@akinon/next/data/server';
-import appFetch from '@akinon/next/utils/app-fetch';
-import { ServerVariables } from '@akinon/next/utils/server-variables';
-
-const { getWidgetData } = serverData;
-
-/**
- * v1 cores ship a smaller server data layer: only `getWidgetData` exists,
- * `getWidgetSchemaData` and `getCollectionWidgetData` arrived with v2.
- *
- * The endpoints are identical on both backends — v1 just never wrapped them.
- * Degrading to "no data" would render every published section *without its
- * blocks* (a section's block tree lives in the widget schema, not in the
- * widget), so on v1 we call the REST endpoints directly. This is what keeps
- * composed pages rendering on the brands still running v1.
- */
-type ServerDataFn = (<T>(args: never) => Promise<T | null>) | undefined;
-
-const optionalServerFn = (name: string): ServerDataFn =>
-  (serverData as unknown as Record<string, ServerDataFn>)[name];
-
-const directFetch = async <T,>(url: string): Promise<T | null> => {
-  try {
-    const result = await appFetch<T>({
-      url,
-      locale: ServerVariables.locale,
-      currency: ServerVariables.currency
-    });
-    return result ?? null;
-  } catch {
-    return null;
-  }
-};
-
-const getCollectionWidgetData = async <T,>(args: {
-  slug: string;
-}): Promise<T | null> => {
-  const fn = optionalServerFn('getCollectionWidgetData');
-  if (fn) return (await fn<T>(args as never)) ?? null;
-  if (!args?.slug) return null;
-  return directFetch<T>(`/product_collection_widgets/${args.slug}/`);
-};
-
-const getWidgetSchemaData = async <T,>(args: {
-  widgetSlug: string;
-}): Promise<T | null> => {
-  const fn = optionalServerFn('getWidgetSchemaData');
-  if (fn) return (await fn<T>(args as never)) ?? null;
-  if (!args?.widgetSlug) return null;
-  return directFetch<T>(`/widgets/${args.widgetSlug}/schema/`);
-};
 import ThemePlaceholderWrapper from './theme-placeholder-wrapper';
-import { Section } from './theme-section';
+import { loadPlaceholderSections } from './load-placeholder-sections';
 import { generateThemeCSS } from './utils';
-import { devWarn } from './utils/dev-warn';
-import { validateThemeSectionsInDev } from './schemas/theme-schema';
-import { getThemeConfig } from './chrome/theme-config-source';
-
-type ThemePlaceholderData = {
-  theme_editor_placeholder: Array<{
-    section_slug: string;
-    order: number;
-  }>;
-};
 
 interface ThemePlaceholderProps {
   slug: string;
@@ -74,260 +13,27 @@ export default async function ThemePlaceholder({
   slug,
   pageContext = null
 }: ThemePlaceholderProps) {
-  try {
-    // theme-config is optional for placeholder rendering, and the reader is
-    // memoized per request — a page with several placeholders, or a ChromeSlot
-    // asking the same question to decide whether it is pinned, reads it once.
-    const { dataSources, settings: themeSettings } = await getThemeConfig();
-
-    let data: { slug?: string; attributes?: { theme_editor_placeholder?: unknown; [key: string]: unknown } } | null = null;
-    try {
-      data = await getWidgetData<ThemePlaceholderData>({
-        slug
-      }) as typeof data;
-    } catch (placeholderError) {
-      console.warn(
-        `Theme placeholder widget "${slug}" was not found. Rendering empty placeholder.`,
-        placeholderError
-      );
-    }
-
-    const sections: Section[] = [];
-
-    if (data?.attributes?.theme_editor_placeholder) {
-      let placeholderData: any = data.attributes.theme_editor_placeholder;
-
-      if (
-        typeof placeholderData === 'object' &&
-        placeholderData !== null &&
-        'value' in placeholderData
-      ) {
-        placeholderData = (
-          placeholderData as {
-            value: { section_slug: string; order: number }[];
-          }
-        ).value;
-      }
-
-      if (typeof placeholderData === 'string') {
-        try {
-          placeholderData = JSON.parse(placeholderData);
-        } catch {
-          devWarn(
-            'ThemePlaceholder',
-            `Placeholder "${slug}" layout JSON is malformed; rendering no sections`
-          );
-          placeholderData = [];
-        }
-      }
-
-      if (!Array.isArray(placeholderData)) {
-        placeholderData = [];
-      }
-
-      const sectionPromises = placeholderData.map(async (item: any) => {
-        try {
-          const sectionSlug = item.value?.section_slug || item.section_slug;
-          const sectionOrder = item.value?.order ?? item.order ?? 0;
-
-          if (!sectionSlug) {
-            return null;
-          }
-
-          const [regularSectionData, sectionSchema] = await Promise.all([
-            getWidgetData<any>({
-              slug: sectionSlug
-            }),
-            getWidgetSchemaData<any>({
-              widgetSlug: sectionSlug
-            })
-          ]);
+  const loaded = await loadPlaceholderSections(slug);
 
-          let sectionData = regularSectionData;
-          if (!sectionData) {
-            try {
-              sectionData = await getCollectionWidgetData<any>({
-                slug: sectionSlug
-              });
-            } catch {
-              // Not a collection widget either; sectionData stays null
-              devWarn(
-                'ThemePlaceholder',
-                `Section "${sectionSlug}" data could not be resolved as a regular or collection widget; rendering from schema only`
-              );
-            }
-          }
-
-          const sectionSchemaEntry = sectionSchema?.schema?.[sectionSlug];
-          const sectionMetadata = sectionSchemaEntry?.metadata || {};
-
-          const getBlockValue = (blockId: string): unknown => {
-            const attrData = sectionData?.attributes?.[blockId];
-            if (attrData === undefined || attrData === null) return undefined;
-
-            if (typeof attrData === 'string') {
-              try {
-                return JSON.parse(attrData);
-              } catch {
-                const trimmed = attrData.trim();
-                if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
-                  devWarn(
-                    'ThemePlaceholder',
-                    `Block "${blockId}" value looks like JSON but failed to parse; using the raw string`
-                  );
-                }
-                return attrData;
-              }
-            } else if (typeof attrData === 'object' && 'value' in attrData) {
-              return attrData.value;
-            }
-            return attrData;
-          };
-
-          const reconstructBlock = (blockSchema: any): any => {
-            return {
-              id: blockSchema.id,
-              type: blockSchema.type || 'text',
-              label: blockSchema.label || blockSchema.id,
-              order: blockSchema.order || 0,
-              isIterator: blockSchema.isIterator,
-              iteratorDataPath: blockSchema.iteratorDataPath,
-              value: getBlockValue(blockSchema.id),
-              styles: blockSchema.styles || {},
-              properties: blockSchema.properties || {},
-              hidden: blockSchema.hidden || false,
-              blocks: (blockSchema.blocks || []).map((b: any) =>
-                reconstructBlock(b)
-              )
-            };
-          };
-
-          const blocks: any[] = [];
-          if (sectionMetadata.blocks && Array.isArray(sectionMetadata.blocks)) {
-            sectionMetadata.blocks.forEach((blockSchema: any) => {
-              blocks.push(reconstructBlock(blockSchema));
-            });
-          }
-
-          blocks.sort((a, b) => a.order - b.order);
-
-          // dataSourceId may be stored in schema metadata OR in widget data attributes
-          // (theme editor saves it as a widget attribute when user selects a data source)
-          const dataSourceId =
-            sectionMetadata.dataSourceId ||
-            (getBlockValue('dataSourceId') as string | undefined) ||
-            (getBlockValue('selectedDataSourceId') as string | undefined);
-
-          const dataSource = dataSourceId
-            ? dataSources.find((ds) => ds.id === dataSourceId)
-            : undefined;
-
-          if (dataSourceId && !dataSource) {
-            devWarn(
-              'ThemePlaceholder',
-              `Section "${sectionSlug}" references data source "${dataSourceId}" which was not found; rendering placeholder items`
-            );
-          }
-
-          let dataSourceWithData = dataSource;
-          if (dataSource && dataSource.details) {
-            // Only fetch collection data if we have a valid widget slug
-            // (not the section's own slug which contains config, not products)
-            const collectionSlug = dataSource.details.collection?.slug;
-            if (collectionSlug) {
-              try {
-                let collectionData = await getWidgetData<{
-                  [key: string]: unknown;
-                }>({
-                  slug: collectionSlug
-                });
-
-                if (!collectionData) {
-                  collectionData = await getCollectionWidgetData<{
-                    [key: string]: unknown;
-                  }>({
-                    slug: collectionSlug
-                  });
-                }
-
-                if (collectionData) {
-                  dataSourceWithData = {
-                    ...dataSource,
-                    details: {
-                      ...dataSource.details,
-                      collection: {
-                        ...dataSource.details.collection,
-                        data: collectionData
-                      }
-                    }
-                  };
-                }
-              } catch (error) {
-                console.error(
-                  `Error fetching widget data for section ${sectionSlug}:`,
-                  error
-                );
-              }
-            }
-            // If no collection slug, the saved products from editor
-            // (details.collection.products) will be used as fallback
-          }
-
-          const section: Section = {
-            id: sectionSlug,
-            type: sectionMetadata.type || 'default',
-            name: sectionMetadata.name || sectionSlug,
-            label: sectionMetadata.label || sectionSlug,
-            properties: sectionMetadata.properties || {},
-            styles: sectionMetadata.styles || {},
-            blocks,
-            order: sectionOrder,
-            hidden: sectionMetadata.hidden || false,
-            dataSourceId,
-            dataSource: dataSourceWithData
-          };
-
-          return section;
-        } catch (error) {
-          const errorSlug =
-            item.value?.section_slug || item.section_slug || 'unknown';
-          console.error(
-            `Error parsing section metadata for ${errorSlug}:`,
-            error
-          );
-          return null;
-        }
-      });
-
-      const resolvedSections = await Promise.all(sectionPromises);
-      sections.push(
-        ...resolvedSections.filter((s): s is Section => s !== null)
-      );
-    }
-
-    // Dev-only, warn-only shape validation of the reconstructed tree. Surfaces
-    // structural drift between the editor/backend data and the render engine
-    // without changing what renders (no-op in production).
-    validateThemeSectionsInDev(sections);
-
-    const themeCSS = generateThemeCSS(sections);
-
-    return (
-      <>
-        {themeCSS && <style dangerouslySetInnerHTML={{ __html: themeCSS }} />}
-        <ThemePlaceholderWrapper
-          slug={slug}
-          initialSections={sections}
-          initialPlaceholderId={data?.slug?.toString() || slug}
-          isDesignMode={false}
-          dataSources={dataSources}
-          initialThemeSettings={themeSettings}
-          initialPageContext={pageContext}
-        />
-      </>
-    );
-  } catch (error) {
-    console.error(`Error fetching theme placeholder data for ${slug}:`, error);
+  if (!loaded) {
     return null;
   }
+
+  const { sections, placeholderId, dataSources, themeSettings } = loaded;
+  const themeCSS = generateThemeCSS(sections);
+
+  return (
+    <>
+      {themeCSS && <style dangerouslySetInnerHTML={{ __html: themeCSS }} />}
+      <ThemePlaceholderWrapper
+        slug={slug}
+        initialSections={sections}
+        initialPlaceholderId={placeholderId}
+        isDesignMode={false}
+        dataSources={dataSources}
+        initialThemeSettings={themeSettings}
+        initialPageContext={pageContext}
+      />
+    </>
+  );
 }