simple-module-pagebuilder 0.0.1__py3-none-any.whl

pagebuilder/components/media/MediaUploadQueue.tsx

@@ -0,0 +1,103 @@
+/** Drag-and-drop target and the per-file upload progress list. */
+
+import type { DragEvent } from 'react';
+
+import type { UploadItem } from './types';
+
+interface DropzoneProps {
+  uploadFolder: string;
+  dragActive: boolean;
+  onDragActiveChange: (active: boolean) => void;
+  onDrop: (e: DragEvent<HTMLDivElement>) => void;
+}
+
+export function MediaDropzone({
+  uploadFolder,
+  dragActive,
+  onDragActiveChange,
+  onDrop,
+}: DropzoneProps) {
+  return (
+    // A drag-and-drop target has no interactive ARIA role that fits. The
+    // keyboard-accessible path to the same action is the header Upload button.
+    // biome-ignore lint/a11y/noStaticElementInteractions: drop target; keyboard path is the Upload button
+    <div
+      onDragOver={(e) => {
+        e.preventDefault();
+        onDragActiveChange(true);
+      }}
+      onDragLeave={(e) => {
+        e.preventDefault();
+        onDragActiveChange(false);
+      }}
+      onDrop={onDrop}
+      className={`mb-4 border-2 border-dashed rounded-lg p-6 text-center text-sm transition-colors ${
+        dragActive ? 'border-blue-500 bg-blue-50 text-blue-700' : 'border-gray-300 text-gray-500'
+      }`}
+      data-testid="media-dropzone"
+    >
+      Drop image files here to upload to <strong>{uploadFolder.trim() || 'Unfiled'}</strong>.
+      Multiple files are accepted.
+    </div>
+  );
+}
+
+interface QueueProps {
+  uploads: UploadItem[];
+  onDismiss: (id: string) => void;
+}
+
+export function MediaUploadQueue({ uploads, onDismiss }: QueueProps) {
+  if (uploads.length === 0) return null;
+  return (
+    <div className="mb-4 space-y-1" data-testid="upload-list">
+      {uploads.map((u) => (
+        <div
+          key={u.id}
+          className="border rounded p-2 text-xs flex items-center gap-3"
+          data-testid="upload-row"
+        >
+          <div className="flex-1 min-w-0">
+            <div className="font-medium truncate" title={u.file.name}>
+              {u.file.name}
+            </div>
+            <div className="h-1.5 bg-gray-100 rounded overflow-hidden mt-1">
+              <div
+                className={`h-full transition-all ${
+                  u.status === 'error'
+                    ? 'bg-red-500'
+                    : u.status === 'done'
+                      ? 'bg-green-500'
+                      : 'bg-blue-500'
+                }`}
+                style={{
+                  width: u.total
+                    ? `${Math.min(100, Math.round((u.loaded / u.total) * 100))}%`
+                    : '0%',
+                }}
+              />
+            </div>
+            {u.error && <div className="text-red-600 mt-1">{u.error}</div>}
+          </div>
+          <div className="w-16 text-right tabular-nums text-gray-500">
+            {u.status === 'done'
+              ? 'Done'
+              : u.status === 'error'
+                ? 'Failed'
+                : `${Math.round((u.loaded / Math.max(1, u.total)) * 100)}%`}
+          </div>
+          {(u.status === 'done' || u.status === 'error') && (
+            <button
+              type="button"
+              onClick={() => onDismiss(u.id)}
+              className="text-gray-400 hover:text-gray-700"
+              aria-label="Dismiss"
+            >
+              ×
+            </button>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}

pagebuilder/components/media/types.ts

@@ -0,0 +1,20 @@
+/** Shared view-model types for the media library. */
+
+export interface ListFilters {
+  search: string;
+  contentType: string;
+  folder: string | null; // null = Any; "" = Unfiled; "x" = exact folder.
+  minKB: string;
+  maxKB: string;
+}
+
+export type UploadStatus = 'pending' | 'uploading' | 'done' | 'error';
+
+export interface UploadItem {
+  id: string;
+  file: File;
+  status: UploadStatus;
+  loaded: number;
+  total: number;
+  error: string | null;
+}

pagebuilder/components/migrateContent.test.ts

@@ -0,0 +1,146 @@
+import type { Data } from '@puckeditor/core';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { migrateContent } from './migrateContent';
+import { getPuckConfig } from './puckConfig';
+
+/** A payload in the shape the current build writes. */
+const modern = {
+  content: [{ type: 'Heading', props: { id: 'h1', text: 'Modern', level: 'h2', align: 'left' } }],
+  root: { props: { title: 'Page', width: 'contained' } },
+} as unknown as Data;
+
+describe('migrateContent', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('returns modern data by identity, without walking it', () => {
+    // Identity rather than deep equality: the point of the version check is
+    // that the common path allocates nothing. A structural copy would pass
+    // toEqual and still have paid for both tree walks.
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {});
+    expect(migrateContent(modern, getPuckConfig())).toBe(modern);
+    expect(log).not.toHaveBeenCalledWith(expect.stringContaining('Migrating DropZones'));
+  });
+
+  it('folds Columns zones into the per-column array slots', () => {
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    const legacy = {
+      content: [{ type: 'Columns', props: { id: 'C1', gap: 'md', columns: [{}, {}] } }],
+      root: { props: {} },
+      zones: {
+        'C1:col-0': [{ type: 'Heading', props: { id: 'h1', text: 'Left', level: 'h2' } }],
+        'C1:col-1': [{ type: 'Text', props: { id: 't1', text: 'Right' } }],
+      },
+    } as unknown as Data;
+
+    const result = migrateContent(legacy, getPuckConfig());
+
+    expect((result as unknown as { zones?: unknown }).zones).toBeUndefined();
+    const columns = result.content?.[0]?.props?.columns as { content: { props: unknown }[] }[];
+    expect(columns[0].content[0].props).toMatchObject({ text: 'Left' });
+    expect(columns[1].content[0].props).toMatchObject({ text: 'Right' });
+  });
+
+  it('recovers a zone whose column was deleted before the migration', () => {
+    // A page saved after a column was removed still carries that column's
+    // zone. Sizing the result to the zone indices as well as the stored array
+    // means the orphaned block resurfaces in a real column instead of being
+    // dropped on the floor — silently losing author content during a migration
+    // is the one failure mode here that can't be undone.
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    const legacy = {
+      content: [{ type: 'Columns', props: { id: 'C1', gap: 'md', columns: [{ width: 1 }] } }],
+      root: { props: {} },
+      zones: {
+        'C1:col-1': [{ type: 'Heading', props: { id: 'h9', text: 'Orphan', level: 'h2' } }],
+      },
+    } as unknown as Data;
+
+    const result = migrateContent(legacy, getPuckConfig());
+
+    const columns = result.content?.[0]?.props?.columns as { content: { props: unknown }[] }[];
+    expect(columns).toHaveLength(2);
+    expect(columns[1].content[0].props).toMatchObject({ text: 'Orphan' });
+  });
+
+  it('rescues a zone whose name it does not recognise', () => {
+    // Puck deletes every zone it grouped for the block once the migrate fn
+    // returns, read or not — so a name this function ignores doesn't raise the
+    // "no slot exists" error, it just stops existing. Only `col-<int>` was
+    // ever written here, but the whole point of the function is that losing
+    // author content can't be silent.
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    const legacy = {
+      content: [{ type: 'Columns', props: { id: 'C1', gap: 'md', columns: [{ width: 1 }] } }],
+      root: { props: {} },
+      zones: {
+        'C1:col-0': [{ type: 'Heading', props: { id: 'h1', text: 'Kept', level: 'h2' } }],
+        'C1:mystery': [{ type: 'Heading', props: { id: 'h2', text: 'Rescued', level: 'h2' } }],
+      },
+    } as unknown as Data;
+
+    const result = migrateContent(legacy, getPuckConfig());
+
+    const columns = result.content?.[0]?.props?.columns as { content: { props: unknown }[] }[];
+    const everything = columns.flatMap((c) => c.content).map((b) => b.props);
+    expect(everything).toContainEqual(expect.objectContaining({ text: 'Kept' }));
+    expect(everything).toContainEqual(expect.objectContaining({ text: 'Rescued' }));
+    expect(warn).toHaveBeenCalled();
+  });
+
+  it('keeps every stored column, however many there are', () => {
+    // The zone-index ceiling exists to stop an absurd zone *name* sizing the
+    // loop. It must not clamp the stored `columns` array — that is real author
+    // data, and trading an allocation worry for silent content loss would be
+    // the wrong side of the deal.
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    const columns = Array.from({ length: 70 }, (_, i) => ({ width: i }));
+    const legacy = {
+      content: [{ type: 'Columns', props: { id: 'C1', gap: 'md', columns } }],
+      root: { props: {} },
+      zones: { 'C1:col-0': [{ type: 'Text', props: { id: 't', text: 'x' } }] },
+    } as unknown as Data;
+
+    const result = migrateContent(legacy, getPuckConfig());
+
+    const out = result.content?.[0]?.props?.columns as { width: number }[];
+    expect(out).toHaveLength(70);
+    expect(out[69].width).toBe(69);
+  });
+
+  it('leaves an empty zones map alone', () => {
+    // Puck writes `zones: {}` on pages that once held a DropZone and no longer
+    // do. Treating that as legacy would migrate every such page on every
+    // public request forever.
+    const emptyZones = { ...modern, zones: {} } as unknown as Data;
+    expect(migrateContent(emptyZones, getPuckConfig())).toBe(emptyZones);
+  });
+
+  it('migrates root props not yet nested under root.props', () => {
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    const legacyRoot = {
+      content: [],
+      root: { title: 'Old shape' },
+    } as unknown as Data;
+    expect(migrateContent(legacyRoot, getPuckConfig())).not.toBe(legacyRoot);
+  });
+
+  it('returns the original data when migration throws', () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    // A zone whose owning component isn't in the tree: migrate() has no slot
+    // field to resolve it against.
+    const unmigratable = {
+      content: [{ type: 'Heading', props: { id: 'h1', text: 'Survives', level: 'h2' } }],
+      root: { props: {} },
+      zones: { 'ghost-1:nowhere': [{ type: 'Heading', props: { id: 'h2', text: 'Orphan' } }] },
+    } as unknown as Data;
+
+    const result = migrateContent(unmigratable, getPuckConfig());
+
+    expect(error).toHaveBeenCalled();
+    // The guarantee: one bad zone costs you that zone, not the document.
+    expect(result.content?.[0]?.props?.text).toBe('Survives');
+  });
+});

pagebuilder/components/migrateContent.ts

@@ -0,0 +1,135 @@
+/**
+ * Bring stored page data up to the shape the current Puck version expects.
+ *
+ * Every load path — editor, public page, layout header/footer — runs its data
+ * through here before handing it to Puck, so a payload written by an older
+ * build can't reach `<Puck>`/`<Render>` in a shape they no longer understand.
+ */
+
+import { type Config, type Content, type Data, migrate } from '@puckeditor/core';
+
+/**
+ * Pre-slots payloads keep nested content in a top-level `zones` map keyed
+ * `"<componentId>:<zoneName>"`, and the very oldest ones store root props
+ * directly on `root` rather than under `root.props`. Neither key is in the
+ * modern `Data` type, so they're only visible through this widening.
+ */
+type LegacyData = Data & {
+  zones?: Record<string, unknown>;
+  root?: Record<string, unknown>;
+};
+
+function hasLegacyShape(data: Data): boolean {
+  const legacy = data as LegacyData;
+  if (legacy.zones && Object.keys(legacy.zones).length > 0) return true;
+  const root = legacy.root;
+  // `!root.props` rather than `!("props" in root)`, matching Puck's own check.
+  // A stored `root: { props: null, … }` has the key but no usable value, and
+  // treating it as modern would hand `<Render>` a null `root.props` instead of
+  // letting Puck normalise it.
+  return !!root && !root.props && Object.keys(root).length > 0;
+}
+
+/** A `Columns` column, pre- and post-migration. */
+type ColumnItem = { width?: number; content?: Content };
+
+/**
+ * Fold a pre-slots `Columns` block's zones into its array slots.
+ *
+ * Puck's own zone→slot conversion only matches a zone against a *top-level*
+ * slot field of the same name. `Columns` can't have one: the column count is
+ * author-controlled, so its slot lives at `columns[i].content` inside an array
+ * field. `migrateDynamicZonesForComponent` is the escape hatch for exactly
+ * that shape — Puck hands us the block's props plus its zones (keyed by bare
+ * prop name, `col-0` / `col-1` / …) and takes whatever props we return.
+ *
+ * The zone index is authoritative, not the stored `columns` array: a page
+ * saved after a column was removed can still carry a zone for it. Sizing the
+ * result to cover both means such orphaned content reappears in a real column
+ * instead of being silently dropped on migration.
+ *
+ * Anything left over is appended to the last column rather than abandoned.
+ * Puck deletes *every* zone it grouped for this block once we return, whether
+ * or not we read it — so a zone this function doesn't claim is not left behind
+ * to raise the "no slot exists" error, it simply stops existing. Only
+ * `col-<int>` was ever emitted here, so the sweep should find nothing; it costs
+ * one pass and removes the one path where losing author content would be
+ * silent, which is the failure this function exists to prevent.
+ */
+const COLUMN_ZONE = /^col-(\d+)$/;
+/**
+ * Ceiling on a column index taken from a *zone name*, which is the only input
+ * here with no natural bound — `col-500000` would otherwise size the loop
+ * below. It deliberately does not cap the stored `columns` array: that is real
+ * author data, however long, and clamping it would trade an allocation worry
+ * for silent content loss. An index past the ceiling isn't dropped either; it
+ * falls through to the unclaimed sweep.
+ */
+const MAX_ZONE_INDEX = 64;
+
+function migrateColumnsZones(
+  props: { id: string } & Record<string, unknown>,
+  zones: Record<string, Content>,
+): { id: string } & Record<string, unknown> {
+  const stored = Array.isArray(props.columns) ? (props.columns as ColumnItem[]) : [];
+  const indexed = new Map<number, Content>();
+  const unclaimed: Content = [];
+  for (const [name, blocks] of Object.entries(zones)) {
+    const match = COLUMN_ZONE.exec(name);
+    const index = match ? Number(match[1]) : -1;
+    if (index >= 0 && index < MAX_ZONE_INDEX) indexed.set(index, blocks);
+    else if (Array.isArray(blocks)) unclaimed.push(...blocks);
+  }
+
+  const count = Math.max(stored.length, ...[...indexed.keys()].map((n) => n + 1), 0);
+
+  const columns: ColumnItem[] = [];
+  for (let i = 0; i < count; i += 1) {
+    columns.push({
+      width: stored[i]?.width ?? 1,
+      content: indexed.get(i) ?? stored[i]?.content ?? [],
+    });
+  }
+
+  if (unclaimed.length > 0) {
+    if (columns.length === 0) columns.push({ width: 1, content: [] });
+    const last = columns[columns.length - 1];
+    last.content = [...(last.content ?? []), ...unclaimed];
+    console.warn(
+      `[pagebuilder] ${unclaimed.length} block(s) from an unrecognised Columns zone were ` +
+        `appended to the last column of "${props.id}" rather than dropped.`,
+    );
+  }
+  return { ...props, columns };
+}
+
+/**
+ * Run Puck's `migrate()`, but only when the payload actually carries a legacy
+ * shape.
+ *
+ * The version check is not just an optimisation. `migrate()` walks the tree
+ * twice and logs "Migrating DropZones..." unconditionally, and the public
+ * viewer renders on every request — so calling it for the modern payloads that
+ * are the overwhelming majority would put two needless walks and a console
+ * line on the hot path.
+ *
+ * `migrate()` still throws on a zone nothing claims — a zone whose owning
+ * component is no longer in the tree, say. Returning the original data there
+ * keeps the rest of the page rendering: the blast radius stays at the one bad
+ * zone rather than the whole document.
+ */
+export function migrateContent<T extends Data>(data: T, config: Config): T {
+  if (!hasLegacyShape(data)) return data;
+  try {
+    // Generic because this is shape-preserving: the same document comes back,
+    // only reshaped internally. `migrate()` is declared against the loose
+    // `Data`, so the narrowing it can't express is asserted once here rather
+    // than at each of the four call sites.
+    return migrate(data, config, {
+      migrateDynamicZonesForComponent: { Columns: migrateColumnsZones },
+    }) as T;
+  } catch (err) {
+    console.error('[pagebuilder] Could not migrate legacy content; rendering as-is:', err);
+    return data;
+  }
+}

pagebuilder/components/puckConfig.test.tsx

@@ -0,0 +1,118 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { type AnyBlock, registerPuckBlocks, resetBlockRegistry } from './blockRegistry';
+import { getLayoutPuckConfig } from './layoutPuckConfig';
+import { getPuckConfig } from './puckConfig';
+
+const stub = { render: () => null } as unknown as AnyBlock;
+
+describe('getPuckConfig', () => {
+  beforeEach(() => resetBlockRegistry());
+
+  it('includes pagebuilder’s own blocks', () => {
+    expect(Object.keys(getPuckConfig().components)).toContain('Heading');
+  });
+
+  it('includes a registered block', () => {
+    registerPuckBlocks({ blocks: { Widget: stub } });
+    expect(Object.keys(getPuckConfig().components)).toContain('Widget');
+  });
+
+  it('picks up a registration made after the first read', () => {
+    // The whole reason the memo keys on the registry version. Caching on first
+    // call would drop any block whose module loaded later.
+    expect(Object.keys(getPuckConfig().components)).not.toContain('Late');
+    registerPuckBlocks({ blocks: { Late: stub } });
+    expect(Object.keys(getPuckConfig().components)).toContain('Late');
+  });
+
+  it('files a registered block under its category', () => {
+    registerPuckBlocks({ blocks: { Widget: stub }, category: { key: 'feeds', title: 'Feeds' } });
+    expect(getPuckConfig().categories?.feeds).toEqual({
+      title: 'Feeds',
+      components: ['Widget'],
+    });
+  });
+
+  it('leaves pagebuilder’s own categories intact', () => {
+    registerPuckBlocks({ blocks: { Widget: stub }, category: { key: 'feeds', title: 'Feeds' } });
+    expect(getPuckConfig().categories?.sections?.components).toContain('Hero');
+  });
+});
+
+describe('getLayoutPuckConfig', () => {
+  beforeEach(() => resetBlockRegistry());
+
+  it('offers the site chrome', () => {
+    expect(Object.keys(getLayoutPuckConfig().components)).toEqual(
+      expect.arrayContaining(['SiteHeader', 'SiteFooter']),
+    );
+  });
+
+  it('drops Columns, which the slots have no room for', () => {
+    expect(Object.keys(getLayoutPuckConfig().components)).not.toContain('Columns');
+  });
+
+  it('offers only the curated chrome palette, not the whole page catalogue', () => {
+    // This used to be built subtractively — the page palette minus a couple of
+    // names — so every block added to the page silently appeared here too.
+    // When the catalogue went 20 → 56, the header/footer editor started
+    // offering Leaderboard, Timeline and ~45 other page sections under Puck's
+    // catch-all "Other" group. Site chrome is a deliberately small palette.
+    const names = Object.keys(getLayoutPuckConfig().components);
+    expect(names).toEqual(
+      expect.arrayContaining(['SiteHeader', 'SiteFooter', 'Heading', 'Text', 'Image']),
+    );
+    expect(names).not.toContain('Leaderboard');
+    expect(names).not.toContain('Timeline');
+    expect(names).not.toContain('Newsletter');
+    // Every built-in must be filed under a category, since an uncategorised
+    // block is what lands in Puck's "Other" group. This holds for built-ins
+    // only — the registry is empty here, and a module registering with
+    // `layout: true` and no category still joins `components` by design.
+    const categorised = Object.values(getLayoutPuckConfig().categories ?? {}).flatMap(
+      (c) => c.components ?? [],
+    );
+    expect(names.filter((n) => !categorised.includes(n))).toEqual([]);
+  });
+
+  it('still renders every block that was offered here before the palette was curated', () => {
+    // Puck renders nothing for a type its config doesn't know — no error, no
+    // placeholder. A footer saved with a ContactForm back when the layout
+    // palette was the whole page palette must not silently lose that section.
+    //
+    // The full list, not a sample: this is the set the site-layout editor
+    // offered before the catalogue grew, so any one of them could be sitting in
+    // a stored header or footer, and dropping any one is the same silent loss.
+    const names = Object.keys(getLayoutPuckConfig().components);
+    expect(names).toEqual(
+      expect.arrayContaining([
+        'PageHeader',
+        'Hero',
+        'EyebrowSection',
+        'MediaObject',
+        'CallToAction',
+        'FeatureCards',
+        'Faq',
+        'Stats',
+        'ArticleCards',
+        'ContactCards',
+        'ContactForm',
+        'Tags',
+      ]),
+    );
+    // ...but they are not offered: `_legacy` is `visible: false`.
+    expect(getLayoutPuckConfig().categories?._legacy?.visible).toBe(false);
+  });
+
+  it('excludes a page-only registration', () => {
+    // A news feed belongs on a page, not in the header or footer.
+    registerPuckBlocks({ blocks: { Widget: stub } });
+    expect(Object.keys(getLayoutPuckConfig().components)).not.toContain('Widget');
+  });
+
+  it('includes a registration that opts into the layout', () => {
+    registerPuckBlocks({ blocks: { Banner: stub }, layout: true });
+    expect(Object.keys(getLayoutPuckConfig().components)).toContain('Banner');
+  });
+});

pagebuilder/components/puckConfig.tsx

@@ -0,0 +1,121 @@
+/**
+ * Shared Puck configuration consumed by both `<Puck>` (editor) and
+ * `<Render>` (public viewer). The same component definitions are used
+ * in both places so what authors see in the editor matches what
+ * visitors see on the published page.
+ */
+
+import type { Config } from '@puckeditor/core';
+
+import {
+  type BlockRegistration,
+  declareBuiltInBlocks,
+  registeredBlocks,
+  registryVersion,
+} from './blockRegistry';
+
+import { type CatalogProps, catalogCategories, catalogComponents } from './widgetCatalog';
+
+export interface PageRootProps {
+  title: string;
+  /**
+   * `contained` keeps the original max-w-4xl column, which every page built
+   * before the section widgets existed relies on. `full` removes it: the
+   * ported widgets are full-bleed sections that bring their own container,
+   * and nesting them in a 4xl column crushes them.
+   */
+  width: 'contained' | 'full';
+}
+
+/**
+ * Puck 0.20 replaced the positional generics (`Config<Components, Root>`) with
+ * a single params object. The old form still resolves, but only the new one
+ * carries the category and field slots, so this is the shape to extend.
+ */
+type PageConfig = Config<{ components: CatalogProps; root: PageRootProps }>;
+
+export const basePageConfig: PageConfig = {
+  root: {
+    fields: {
+      title: { type: 'text' },
+      width: {
+        type: 'radio',
+        options: [
+          { label: 'Contained', value: 'contained' },
+          { label: 'Full width', value: 'full' },
+        ],
+      },
+    },
+    // The design pack used to be a root prop here. It is a site-wide branding
+    // setting now — one site, one look — so PublicPage applies its root class
+    // around the whole document instead, which is also what lets the header
+    // and footer adopt it.
+    defaultProps: { title: 'Untitled page', width: 'contained' },
+    render: ({ children, width }) => (
+      <div className={width === 'full' ? undefined : 'max-w-4xl mx-auto p-6'}>{children}</div>
+    ),
+  },
+  categories: catalogCategories,
+  components: catalogComponents,
+};
+
+// Names pagebuilder itself ships. Declared rather than duplicated in the
+// registry so there is only one list to keep in sync, and so a module that
+// tries to register one of these fails loudly instead of shadowing it.
+declareBuiltInBlocks(Object.keys(basePageConfig.components));
+
+/** Merge a registration's blocks and category into an accumulating config. */
+function applyRegistration(
+  components: Record<string, unknown>,
+  categories: Record<string, { title?: string; components: string[] }>,
+  registration: BlockRegistration,
+): void {
+  Object.assign(components, registration.blocks);
+  if (!registration.category) return;
+  const { key, title } = registration.category;
+  categories[key] = {
+    title,
+    components: [...(categories[key]?.components ?? []), ...Object.keys(registration.blocks)],
+  };
+}
+
+let cachedConfig: PageConfig | null = null;
+let cachedVersion = -1;
+
+/**
+ * The page palette: pagebuilder's own blocks plus whatever modules registered.
+ *
+ * Memoised on the registry version rather than unconditionally — caching on
+ * first call would silently drop any block registered after the first render.
+ * Call it inside a component, never at module scope.
+ */
+export function getPuckConfig(): PageConfig {
+  if (cachedConfig && cachedVersion === registryVersion()) return cachedConfig;
+  const components: Record<string, unknown> = { ...basePageConfig.components };
+  const categories = { ...basePageConfig.categories } as Record<
+    string,
+    { title?: string; components: string[] }
+  >;
+  for (const registration of registeredBlocks()) {
+    applyRegistration(components, categories, registration);
+  }
+  cachedConfig = { ...basePageConfig, categories, components } as PageConfig;
+  cachedVersion = registryVersion();
+  return cachedConfig;
+}
+
+export const emptyData = {
+  content: [],
+  root: { props: { title: 'Untitled page', width: 'contained' } },
+};
+
+/**
+ * Editor preview viewports surfaced as a switcher in the Puck toolbar.
+ * The pixel widths match common mobile/tablet/desktop breakpoints rather
+ * than specific devices so the preview reflects what visitors see.
+ */
+export const editorViewports = [
+  { width: 360, height: 640, label: 'Mobile', icon: 'Smartphone' },
+  { width: 768, height: 1024, label: 'Tablet', icon: 'Tablet' },
+  { width: 1280, height: 800, label: 'Desktop', icon: 'Monitor' },
+];