@shoppexio/builder-contracts 0.1.1 → 0.1.2

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

@@ -1 +1 @@
-{"version":3,"file":"theme-manifest.d.ts","sourceRoot":"","sources":["../src/theme-manifest.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"theme-manifest.d.ts","sourceRoot":"","sources":["../src/theme-manifest.ts"],"names":[],"mappings":"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"}

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"];
+export declare const PUBLIC_BUILDER_THEME_SCHEMES: readonly ["default", "classic", "nebula", "pulse", "phantom", "starlight", "apex", "vault", "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"];
+export declare const BUILDER_READY_THEME_SCHEMES: readonly ["blank", "default", "classic", "nebula", "pulse", "phantom", "starlight", "apex", "vault", "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,6FAS/B,CAAC;AAEX,eAAO,MAAM,6BAA6B,oBAAqB,CAAC;AAEhE,eAAO,MAAM,2BAA2B,sGAG9B,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,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"}

package/dist/theme-schemes.js

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

package/dist/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,MAAM,kCAAkC,GAC1C,cAAc,GACd,oBAAoB,GACpB,oBAAoB,GACpB,mBAAmB,GACnB,0BAA0B,GAC1B,uBAAuB,GACvB,uBAAuB,GACvB,oBAAoB,GACpB,sBAAsB,CAAC;AAE3B,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,kCAAkC,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qBAAa,8BAA+B,SAAQ,KAAK;IACvD,QAAQ,CAAC,MAAM,EAAE,8BAA8B,EAAE,CAAC;gBAEtC,MAAM,EAAE,8BAA8B,EAAE;CAKrD;AAED,wBAAgB,sCAAsC,CACpD,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,aAAa,GACtB,8BAA8B,EAAE,CAoElC;AAwBD,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,aAAa,GACtB,IAAI,CAKN;AAED,wBAAgB,qCAAqC,CACnD,MAAM,EAAE,8BAA8B,EAAE,GACvC,MAAM,CAQR"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD,MAAM,MAAM,kCAAkC,GAC1C,cAAc,GACd,oBAAoB,GACpB,oBAAoB,GACpB,mBAAmB,GACnB,0BAA0B,GAC1B,uBAAuB,GACvB,uBAAuB,GACvB,oBAAoB,GACpB,sBAAsB,CAAC;AAE3B,MAAM,MAAM,8BAA8B,GAAG;IAC3C,IAAI,EAAE,kCAAkC,CAAC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,qBAAa,8BAA+B,SAAQ,KAAK;IACvD,QAAQ,CAAC,MAAM,EAAE,8BAA8B,EAAE,CAAC;gBAEtC,MAAM,EAAE,8BAA8B,EAAE;CAKrD;AAED,wBAAgB,sCAAsC,CACpD,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,aAAa,GACtB,8BAA8B,EAAE,CAqElC;AAwBD,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,eAAe,EACzB,QAAQ,EAAE,aAAa,GACtB,IAAI,CAKN;AAED,wBAAgB,qCAAqC,CACnD,MAAM,EAAE,8BAA8B,EAAE,GACvC,MAAM,CAQR"}

package/dist/validation.js

@@ -1,3 +1,4 @@
+import { mergeCustomPagesIntoManifest } from "./custom-pages.js";
 import { ThemeStyleSlotIdSchema } from "./style-slots.js";
 export class BuilderManifestValidationError extends Error {
     issues;
@@ -8,10 +9,11 @@ export class BuilderManifestValidationError extends Error {
     }
 }
 export function validateBuilderSettingsAgainstManifest(settings, manifest) {
+    const effectiveManifest = mergeCustomPagesIntoManifest(manifest, settings);
     const issues = [];
-    validateGlobalStyleSlots(settings, manifest, issues);
+    validateGlobalStyleSlots(settings, effectiveManifest, issues);
     for (const [pageId, layout] of Object.entries(settings.theme.layout)) {
-        const page = manifest.pages[pageId];
+        const page = effectiveManifest.pages[pageId];
         if (!page) {
             issues.push({
                 code: 'unknown_page',
@@ -32,7 +34,7 @@ export function validateBuilderSettingsAgainstManifest(settings, manifest) {
                 });
             }
             blockIds.add(block.id);
-            const blockDefinition = manifest.blocks[block.type];
+            const blockDefinition = effectiveManifest.blocks[block.type];
             if (!blockDefinition) {
                 issues.push({
                     code: 'unknown_block_type',
@@ -54,7 +56,7 @@ export function validateBuilderSettingsAgainstManifest(settings, manifest) {
             validateBlockStyleOverrides(block, blockDefinition.exposedStyleSlots, blockPath, issues);
         }
         for (const [blockType, count] of blockTypeCounts.entries()) {
-            const maxInstances = manifest.blocks[blockType]?.maxInstances;
+            const maxInstances = effectiveManifest.blocks[blockType]?.maxInstances;
             if (maxInstances !== undefined && count > maxInstances) {
                 issues.push({
                     code: 'too_many_block_instances',

package/package.json

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

package/src/builder-contracts.test.ts

@@ -1,4 +1,6 @@
 import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import {
   BuilderEventSchema,
   BuilderSettingsSchema,
@@ -17,6 +19,7 @@ import {
   migrateLegacyBuilderSettings,
   listThemeManifestPresets,
 } from './index.ts';
+import { ColorSchema } from './style-slots.ts';
 
 describe('@shoppex/builder-contracts', () => {
   test('accepts an empty builder settings document', () => {
@@ -797,4 +800,19 @@ describe('@shoppex/builder-contracts', () => {
     });
     expect(validateBuilderSettingsAgainstManifest(result.settings, manifest)).toEqual([]);
   });
+
+  test('accepts transparent color literals used by theme manifests', () => {
+    expect(ColorSchema.parse('transparent')).toBe('transparent');
+    expect(ColorSchema.parse('#ffffff')).toBe('#ffffff');
+    expect(ColorSchema.parse('#00000080')).toBe('#00000080');
+  });
+
+  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']) {
+      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/builder-settings.ts

@@ -31,11 +31,14 @@ export const PageLayoutSchema = z
   .strict();
 export type PageLayout = z.infer<typeof PageLayoutSchema>;
 
+export const CustomPageSlugSchema = z.string().min(1).regex(/^[a-z0-9][a-z0-9-_]*$/);
+export type CustomPageSlug = z.infer<typeof CustomPageSlugSchema>;
+
 export const CustomPageSchema = z
   .object({
     id: PageIdSchema,
     title: z.string().min(1),
-    slug: z.string().min(1).regex(/^[a-z0-9][a-z0-9-_/]*$/),
+    slug: CustomPageSlugSchema,
     visible: z.boolean().default(true),
     layout: PageLayoutSchema.default({ blocks: [] }),
     seo: z

package/src/custom-pages.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  MERCHANT_CUSTOM_PAGE_ALLOWED_BLOCKS,
+  mergeCustomPagesIntoManifest,
+} from './custom-pages.ts';
+import { CustomPageSchema } from './builder-settings.ts';
+import { createEmptyBuilderSettings } from './migrations.ts';
+import { convertLegacyThemeManifest } from './legacy-manifest.ts';
+import { validateBuilderSettingsAgainstManifest } from './validation.ts';
+
+function loadDefaultManifest() {
+  const manifestPath = join(import.meta.dir, '../../../themes/default/theme.manifest.json');
+  return convertLegacyThemeManifest(JSON.parse(readFileSync(manifestPath, 'utf8')) as unknown);
+}
+
+describe('custom pages manifest merge', () => {
+  test('keeps MERCHANT_CUSTOM_PAGE_ALLOWED_BLOCKS aligned with config SSOT', () => {
+    const configPath = join(import.meta.dir, '../../../config/builder-shared-manifest-blocks.json');
+    const config = JSON.parse(readFileSync(configPath, 'utf8')) as {
+      customPageAllowedBlocks: string[];
+    };
+
+    expect([...MERCHANT_CUSTOM_PAGE_ALLOWED_BLOCKS]).toEqual(config.customPageAllowedBlocks);
+  });
+
+  test('merges merchant custom pages into the effective manifest', () => {
+    const manifest = loadDefaultManifest();
+    const settings = createEmptyBuilderSettings(1);
+    settings.theme.pages = [
+      {
+        id: 'custom-about',
+        title: 'About Us',
+        slug: 'about-us',
+        visible: true,
+        layout: { blocks: [] },
+      },
+    ];
+    settings.theme.layout['custom-about'] = {
+      blocks: [
+        {
+          id: 'youtube-1',
+          type: 'youtube-embed',
+          visible: true,
+          settings: {
+            videoUrl: 'https://youtu.be/dQw4w9WgXcQ',
+          },
+        },
+      ],
+    };
+
+    const effective = mergeCustomPagesIntoManifest(manifest, settings);
+    expect(effective.pages['custom-about']).toEqual({
+      label: 'About Us',
+      previewPath: '/page/about-us',
+      allowedBlocks: expect.arrayContaining(['youtube-embed', 'custom-html']),
+      defaultBlocks: [],
+    });
+    expect(validateBuilderSettingsAgainstManifest(settings, manifest)).toEqual([]);
+  });
+
+  test('rejects multi-segment custom page slugs', () => {
+    const result = CustomPageSchema.safeParse({
+      id: 'custom-help-faq',
+      title: 'Help FAQ',
+      slug: 'help/faq',
+      visible: true,
+      layout: { blocks: [] },
+    });
+
+    expect(result.success).toBe(false);
+  });
+});

package/src/custom-pages.ts

@@ -0,0 +1,70 @@
+import type { BuilderSettings } from './builder-settings.ts';
+import type { ManifestPage, ThemeManifest } from './theme-manifest.ts';
+
+/**
+ * Allowed embed/content blocks on merchant custom pages (`theme.pages[]`).
+ * Keep aligned with `customPageAllowedBlocks` in
+ * `config/builder-shared-manifest-blocks.json`.
+ */
+export const MERCHANT_CUSTOM_PAGE_ALLOWED_BLOCKS = [
+  'custom-html',
+  'youtube-embed',
+  'text-block',
+] as const;
+
+export type MerchantCustomPageAllowedBlock =
+  (typeof MERCHANT_CUSTOM_PAGE_ALLOWED_BLOCKS)[number];
+
+export function resolveMerchantCustomPageAllowedBlocks(
+  manifest: ThemeManifest,
+): string[] {
+  return MERCHANT_CUSTOM_PAGE_ALLOWED_BLOCKS.filter(
+    (blockType) => blockType in manifest.blocks,
+  );
+}
+
+export function buildMerchantCustomPageManifestEntry(
+  customPage: BuilderSettings['theme']['pages'][number],
+  manifest: ThemeManifest,
+): ManifestPage {
+  return {
+    label: customPage.title,
+    previewPath: `/page/${customPage.slug}`,
+    allowedBlocks: resolveMerchantCustomPageAllowedBlocks(manifest),
+    defaultBlocks: [],
+  };
+}
+
+export function mergeCustomPagesIntoManifest(
+  manifest: ThemeManifest,
+  settings: BuilderSettings,
+): ThemeManifest {
+  if (settings.theme.pages.length === 0) {
+    return manifest;
+  }
+
+  const pages = { ...manifest.pages };
+  for (const customPage of settings.theme.pages) {
+    if (pages[customPage.id]) {
+      continue;
+    }
+
+    pages[customPage.id] = buildMerchantCustomPageManifestEntry(customPage, manifest);
+  }
+
+  return { ...manifest, pages };
+}
+
+export function findCustomPageBySlug(
+  settings: BuilderSettings,
+  slug: string,
+): BuilderSettings['theme']['pages'][number] | undefined {
+  return settings.theme.pages.find((page) => page.slug === slug);
+}
+
+export function findCustomPageById(
+  settings: BuilderSettings,
+  pageId: string,
+): BuilderSettings['theme']['pages'][number] | undefined {
+  return settings.theme.pages.find((page) => page.id === pageId);
+}

package/src/dedicated-pages.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  createDedicatedPageBlockType,
+  dedicatedPageContentKey,
+  dedicatedPagePreviewPath,
+  migrateDedicatedPageContent,
+  migrateDedicatedPageLayout,
+  normalizeDedicatedPageId,
+} from './dedicated-pages.ts';
+
+describe('dedicated-pages', () => {
+  test('normalizeDedicatedPageId maps legacy reviews id', () => {
+    expect(normalizeDedicatedPageId('reviews')).toBe('reviews-page');
+    expect(normalizeDedicatedPageId('faq-page')).toBe('faq-page');
+  });
+
+  test('createDedicatedPageBlockType follows page-{pageId} rule', () => {
+    expect(createDedicatedPageBlockType('faq-page')).toBe('page-faq-page');
+    expect(createDedicatedPageBlockType('reviews-page')).toBe('page-reviews-page');
+    expect(createDedicatedPageBlockType('reviews')).toBe('page-reviews');
+  });
+
+  test('dedicatedPagePreviewPath resolves known storefront paths', () => {
+    expect(dedicatedPagePreviewPath('contact-page')).toBe('/contact');
+    expect(dedicatedPagePreviewPath('reviews')).toBe('/reviews');
+    expect(dedicatedPagePreviewPath('home')).toBeNull();
+  });
+
+  test('dedicatedPageContentKey uses canonical page id', () => {
+    expect(dedicatedPageContentKey('reviews', 'title')).toBe('pages.reviews-page.title');
+  });
+
+  test('migrateDedicatedPageLayout renames legacy reviews page layout', () => {
+    const migrated = migrateDedicatedPageLayout({
+      home: { blocks: [] },
+      reviews: {
+        blocks: [{ id: 'reviews-1', type: 'page-reviews', visible: true, settings: {} }],
+      },
+    });
+
+    expect(migrated.reviews).toBeUndefined();
+    expect(migrated['reviews-page']).toMatchObject({
+      blocks: [{ id: 'reviews-1', type: 'page-reviews-page', visible: true, settings: {} }],
+    });
+  });
+
+  test('migrateDedicatedPageContent renames legacy content keys', () => {
+    const migrated = migrateDedicatedPageContent({
+      'pages.reviews.title': 'Reviews',
+      'tool.title': 'Free Tool',
+      'hero.title': 'Home',
+    });
+
+    expect(migrated['pages.reviews.title']).toBeUndefined();
+    expect(migrated['pages.reviews-page.title']).toBe('Reviews');
+    expect(migrated['tool.title']).toBeUndefined();
+    expect(migrated['pages.tool-page.title']).toBe('Free Tool');
+    expect(migrated['hero.title']).toBe('Home');
+  });
+
+  test('migrateDedicatedPageLayout renames legacy vault tool page', () => {
+    const migrated = migrateDedicatedPageLayout({
+      tool: {
+        blocks: [{
+          id: 'tool-1',
+          type: 'tool',
+          visible: true,
+          settings: { 'tool.title': 'Free Tool' },
+        }],
+      },
+    });
+
+    expect(migrated.tool).toBeUndefined();
+    expect(migrated['tool-page']).toMatchObject({
+      blocks: [{
+        id: 'tool-1',
+        type: 'page-tool-page',
+        visible: true,
+        settings: { 'pages.tool-page.title': 'Free Tool' },
+      }],
+    });
+  });
+
+  test('dedicatedPagePreviewPath resolves tool-page', () => {
+    expect(dedicatedPagePreviewPath('tool-page')).toBe('/tool');
+    expect(dedicatedPagePreviewPath('tool')).toBe('/tool');
+  });
+});

package/src/dedicated-pages.ts

@@ -0,0 +1,173 @@
+export const BUILDER_LAYOUT_PAGE_IDS = [
+  'home',
+  'navigation',
+  'product',
+  'footer',
+  'terms',
+] as const;
+
+export type BuilderLayoutPageId = (typeof BUILDER_LAYOUT_PAGE_IDS)[number];
+
+export const BUILDER_DEDICATED_PAGE_IDS = [
+  'contact-page',
+  'faq-page',
+  'reviews-page',
+  'feedback-page',
+  'guide-page',
+  'status-page',
+  'checkout-page',
+  'tool-page',
+] as const;
+
+export type BuilderDedicatedPageId = (typeof BUILDER_DEDICATED_PAGE_IDS)[number];
+
+/** @deprecated Legacy manifest page ids migrated on settings load. */
+export const DEDICATED_PAGE_ID_ALIASES: Readonly<Record<string, BuilderDedicatedPageId>> = {
+  reviews: 'reviews-page',
+  tool: 'tool-page',
+};
+
+const DEDICATED_PAGE_PREVIEW_PATHS: Readonly<Record<BuilderDedicatedPageId, string>> = {
+  'contact-page': '/contact',
+  'faq-page': '/faq',
+  'reviews-page': '/reviews',
+  'feedback-page': '/feedback',
+  'guide-page': '/guide',
+  'status-page': '/status',
+  'checkout-page': '/checkout',
+  'tool-page': '/tool',
+};
+
+export function normalizeDedicatedPageId(pageId: string): string {
+  return DEDICATED_PAGE_ID_ALIASES[pageId] ?? pageId;
+}
+
+export function isDedicatedPageId(pageId: string): pageId is BuilderDedicatedPageId {
+  return (BUILDER_DEDICATED_PAGE_IDS as readonly string[]).includes(pageId);
+}
+
+export function dedicatedPagePreviewPath(pageId: string): string | null {
+  const normalized = normalizeDedicatedPageId(pageId);
+  if (!isDedicatedPageId(normalized)) {
+    return null;
+  }
+  return DEDICATED_PAGE_PREVIEW_PATHS[normalized];
+}
+
+export function dedicatedPageContentKey(pageId: string, field: string): string {
+  return `pages.${normalizeDedicatedPageId(pageId)}.${field}`;
+}
+
+export function normalizeDedicatedPageBlockType(pageId: string): string {
+  return createDedicatedPageBlockType(normalizeDedicatedPageId(pageId));
+}
+
+export function createDedicatedPageBlockType(pageId: string): string {
+  const normalizedPageId = pageId
+    .toLowerCase()
+    .replace(/[^a-z0-9\-_.]+/g, '-')
+    .replace(/^[-_.]+/, '');
+  return `page-${normalizedPageId || 'custom'}`;
+}
+
+function migrateDedicatedPageBlockSettings(settings: unknown): Record<string, unknown> {
+  if (typeof settings !== 'object' || settings === null || Array.isArray(settings)) {
+    return {};
+  }
+
+  const next: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(settings)) {
+    if (key.startsWith('tool.')) {
+      next[`pages.tool-page.${key.slice('tool.'.length)}`] = value;
+      continue;
+    }
+    next[key] = value;
+  }
+  return next;
+}
+
+export function migrateDedicatedPageLayout(layout: Record<string, unknown>): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...layout };
+
+  for (const [legacyId, canonicalId] of Object.entries(DEDICATED_PAGE_ID_ALIASES)) {
+    if (!Object.prototype.hasOwnProperty.call(next, legacyId)) {
+      continue;
+    }
+
+    const legacyLayout = next[legacyId];
+    delete next[legacyId];
+
+    if (Object.prototype.hasOwnProperty.call(next, canonicalId)) {
+      continue;
+    }
+
+    if (typeof legacyLayout !== 'object' || legacyLayout === null || Array.isArray(legacyLayout)) {
+      continue;
+    }
+
+    const blocks = (legacyLayout as { blocks?: unknown }).blocks;
+    if (!Array.isArray(blocks)) {
+      next[canonicalId] = legacyLayout;
+      continue;
+    }
+
+    const legacyBlockType = createDedicatedPageBlockType(legacyId);
+    const canonicalBlockType = createDedicatedPageBlockType(canonicalId);
+
+    next[canonicalId] = {
+      ...legacyLayout,
+      blocks: blocks.map((block) => {
+        if (typeof block !== 'object' || block === null || Array.isArray(block)) {
+          return block;
+        }
+        const typed = block as { type?: unknown };
+        const isLegacyBlockType = typed.type === legacyBlockType
+          || (legacyId === 'tool' && typed.type === 'tool');
+        if (!isLegacyBlockType) {
+          return block;
+        }
+        return {
+          ...typed,
+          type: canonicalBlockType,
+          settings: migrateDedicatedPageBlockSettings(
+            (typed as { settings?: unknown }).settings,
+          ),
+        };
+      }),
+    };
+  }
+
+  return next;
+}
+
+export function migrateDedicatedPageContent(content: Record<string, unknown>): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...content };
+
+  for (const [key, value] of Object.entries(next)) {
+    if (key.startsWith('tool.') && !key.startsWith('tool-page.')) {
+      const canonicalKey = `pages.tool-page.${key.slice('tool.'.length)}`;
+      if (!Object.prototype.hasOwnProperty.call(next, canonicalKey)) {
+        next[canonicalKey] = value;
+      }
+      delete next[key];
+    }
+  }
+
+  for (const [legacyId, canonicalId] of Object.entries(DEDICATED_PAGE_ID_ALIASES)) {
+    const legacyPrefix = `pages.${legacyId}.`;
+    const canonicalPrefix = `pages.${canonicalId}.`;
+
+    for (const [key, value] of Object.entries(next)) {
+      if (!key.startsWith(legacyPrefix)) {
+        continue;
+      }
+      const canonicalKey = `${canonicalPrefix}${key.slice(legacyPrefix.length)}`;
+      if (!Object.prototype.hasOwnProperty.call(next, canonicalKey)) {
+        next[canonicalKey] = value;
+      }
+      delete next[key];
+    }
+  }
+
+  return next;
+}

package/src/fields.ts

@@ -8,10 +8,10 @@ const FieldBaseSchema = z
     defaultValue: z.unknown().optional(),
     required: z.boolean().optional(),
     // Groups settings within the Inspector. "content" (default) shows
-    // under the Block Settings collapsible; "style" shows under a
-    // separate Style collapsible. Themes pick up the value via the
-    // existing block.settings.path lookup — no runtime change.
-    group: z.enum(['content', 'style']).optional(),
+    // under the Block Settings collapsible; "profile" shows under Profile
+    // banner; "style" shows under Style; "search" shows under Search bar.
+    // Themes pick up the value via the existing block.settings.path lookup.
+    group: z.enum(['content', 'profile', 'style', 'search']).optional(),
   })
   .strict();
 

package/src/index.ts

@@ -1,3 +1,5 @@
+export * from './custom-pages.ts';
+export * from './dedicated-pages.ts';
 export * from './builder-settings.ts';
 export * from './canonical-settings.ts';
 export * from './events.ts';
@@ -10,6 +12,7 @@ export * from './preview-protocol.ts';
 export * from './preview-session-resolve.ts';
 export * from './preview-trusted-origins.ts';
 export * from './storefront-initial-data-html.ts';
+export * from './storefront-typography-fonts.ts';
 export * from './style-slots.ts';
 export * from './theme-manifest.ts';
 export * from './theme-schemes.ts';

package/src/legacy-manifest.ts

@@ -1,4 +1,5 @@
 import * as z from 'zod/v4';
+import { createDedicatedPageBlockType } from './dedicated-pages.ts';
 import { BuilderFieldSchema, type BuilderField } from './fields.ts';
 import { ThemeManifestSchema, type ThemeManifest } from './theme-manifest.ts';
 import { StyleSlotDefaultsSchema } from './style-slots.ts';
@@ -129,7 +130,7 @@ export function convertLegacyThemeManifest(input: unknown): ThemeManifest {
   );
 
   for (const page of legacy.builder.pages) {
-    const syntheticBlockType = createSyntheticPageBlockType(page.id);
+    const syntheticBlockType = createDedicatedPageBlockType(page.id);
     if ((page.fields?.length ?? 0) === 0 && (page.lists?.length ?? 0) === 0) {
       continue;
     }
@@ -161,7 +162,7 @@ export function convertLegacyThemeManifest(input: unknown): ThemeManifest {
     hotfixPaths: legacy.hotfixPaths,
     pages: Object.fromEntries(
       legacy.builder.pages.map((page) => {
-        const syntheticBlockType = createSyntheticPageBlockType(page.id);
+        const syntheticBlockType = createDedicatedPageBlockType(page.id);
         const hasSyntheticBlock = blocks[syntheticBlockType] !== undefined;
         const allowedBlocks = page.blocks.length > 0
           ? page.blocks
@@ -201,11 +202,6 @@ function normalizeLegacyThemeId(rawId: string): string {
   return `legacy-${lowered || 'theme'}`;
 }
 
-function createSyntheticPageBlockType(pageId: string): string {
-  const normalizedPageId = pageId.toLowerCase().replace(/[^a-z0-9\-_.]+/g, '-').replace(/^[-_.]+/, '');
-  return `page-${normalizedPageId || 'custom'}`;
-}
-
 function convertLegacyThemePresets(presets: LegacyThemePreset[]): ThemeManifest['presets'] {
   return Object.fromEntries(
     presets.map((preset) => {
@@ -410,3 +406,40 @@ function createListItemShape(kind: string): Extract<BuilderField, { type: 'list'
     body: { type: 'richtext', label: 'Body' },
   };
 }
+
+export type ThemePageBlockOrderPage = {
+  allowedBlocks?: string[];
+  defaultBlocks?: Array<{ type?: string }>;
+};
+
+function resolveManifestPagesForBlockOrder(manifest: unknown): Record<string, ThemePageBlockOrderPage> {
+  const canonical = ThemeManifestSchema.safeParse(manifest);
+  if (canonical.success) {
+    return canonical.data.pages;
+  }
+
+  try {
+    return convertLegacyThemeManifest(manifest).pages;
+  } catch {
+    if (typeof manifest === 'object' && manifest !== null && 'pages' in manifest) {
+      const pages = (manifest as { pages?: unknown }).pages;
+      if (typeof pages === 'object' && pages !== null && !Array.isArray(pages)) {
+        return pages as Record<string, ThemePageBlockOrderPage>;
+      }
+    }
+    return {};
+  }
+}
+
+export function getThemePageBlockOrderFromManifest(manifest: unknown, pageId: string): string[] {
+  const page = resolveManifestPagesForBlockOrder(manifest)[pageId];
+  if (!page) {
+    return [];
+  }
+
+  const defaultBlockTypes = (Array.isArray(page.defaultBlocks) ? page.defaultBlocks : [])
+    .map((block) => (typeof block === 'object' && block !== null ? block.type : undefined))
+    .filter((blockType): blockType is string => typeof blockType === 'string' && blockType.length > 0);
+
+  return defaultBlockTypes.length > 0 ? defaultBlockTypes : page.allowedBlocks ?? [];
+}