@akinon/pz-theme 2.0.78-rc.1 → 2.0.78

package/src/custom/register.ts

@@ -36,6 +36,27 @@ import {
   getCustomBlockTypes,
   setCatalogVendor
 } from './catalog';
+import {
+  addSectionToCatalog,
+  getCustomSectionDescriptor,
+  getCustomSectionTypes
+} from './section-catalog';
+import {
+  addSectionDefinition,
+  hasCustomSectionDefinition
+} from './section-definitions';
+import { normalizeCustomSection } from './define-section';
+import type { CustomSectionDefinition } from './define-section';
+import type {
+  CustomRegionDeclaration,
+  CustomSectionInput,
+  CustomSectionOptions
+} from './define-section';
+import { CUSTOM_SECTION_LIMITS, regionNameError } from './section-types';
+import type {
+  CustomRegionDescriptor,
+  CustomSectionDescriptor
+} from './section-types';
 import {
   normalizeSettingChoices,
   settingKeyError,
@@ -120,14 +141,19 @@ const firstDivergentPath = (
   return null;
 };
 
-const assertSerializable = (descriptor: CustomBlockDescriptor): void => {
+/**
+ * Shared by both doors: the round trip is the actual transport either way, and
+ * a section descriptor carries more hand-written data than a block's (a
+ * region's seeded properties and styles), so it needs the check more.
+ */
+const assertSerializable = (descriptor: { type: string }): void => {
   let roundTripped: unknown;
 
   try {
     roundTripped = JSON.parse(JSON.stringify(descriptor));
   } catch (error) {
     throw new Error(
-      `[pz-theme] Custom block "${descriptor.type}" has a descriptor that cannot be serialized ` +
+      `[pz-theme] Custom unit "${descriptor.type}" has a descriptor that cannot be serialized ` +
         `(${String(
           error
         )}). The catalog is posted to the editor, so every declared value has to survive JSON.`
@@ -137,7 +163,7 @@ const assertSerializable = (descriptor: CustomBlockDescriptor): void => {
   const divergent = firstDivergentPath(descriptor, roundTripped, 'descriptor');
   if (divergent) {
     throw new Error(
-      `[pz-theme] Custom block "${descriptor.type}" declares a value at ${divergent} that does not survive JSON. ` +
+      `[pz-theme] Custom unit "${descriptor.type}" declares a value at ${divergent} that does not survive JSON. ` +
         `The catalog crosses postMessage, which drops functions, symbols and undefined without a word — ` +
         `the editor would receive the descriptor with that key missing and no error anywhere.`
     );
@@ -311,29 +337,36 @@ const bindHost = (
   return Host;
 };
 
-const buildDescriptor = (
+/**
+ * The settings half of a descriptor, shared by both doors.
+ *
+ * A second copy of this loop would drift within a release: the two doors have
+ * to refuse the same duplicate key, apply the same cap and derive the same
+ * `field-<key>` parts, and a section whose settings behaved differently from a
+ * block's would be a difference nobody could explain from the authoring API.
+ */
+const buildSettings = (
+  unit: string,
   type: string,
-  name: string,
-  options: CustomBlockOptions
-): CustomBlockDescriptor => {
-  const declaredSettings = options.settings ?? [];
-
-  if (declaredSettings.length > CUSTOM_LIMITS.settingsPerType) {
+  declared: readonly CustomSettingDeclaration[],
+  cap: number
+): { settings: CustomSettingDescriptor[]; parts: string[] } => {
+  if (declared.length > cap) {
     throw new Error(
-      `[pz-theme] Custom block "${type}" declares ${declaredSettings.length} settings, over the ` +
-        `${CUSTOM_LIMITS.settingsPerType} cap. The whole catalog is posted to the editor on every ` +
-        `placeholder announce; split the block.`
+      `[pz-theme] Custom ${unit} "${type}" declares ${declared.length} settings, over the ` +
+        `${cap} cap. The whole catalog is posted to the editor on every ` +
+        `placeholder announce; split it.`
     );
   }
 
   const settings: CustomSettingDescriptor[] = [];
   const parts: string[] = [];
 
-  for (const declaration of declaredSettings) {
+  for (const declaration of declared) {
     if (settings.some((setting) => setting.key === declaration.key)) {
       throw new Error(
-        `[pz-theme] Custom block "${type}" declares the setting key "${declaration.key}" twice. ` +
-          `Both write to block.properties.${declaration.key}, so one control would silently overwrite the other.`
+        `[pz-theme] Custom ${unit} "${type}" declares the setting key "${declaration.key}" twice. ` +
+          `Both write to properties.${declaration.key}, so one control would silently overwrite the other.`
       );
     }
 
@@ -345,40 +378,33 @@ const buildDescriptor = (
     if (setting.editable) parts.push(fieldPartName(setting.key));
   }
 
-  const declaredSlots = options.slots ?? [];
-
-  // The phase-1 twin of the cap the editor also applies: it drops the whole
-  // catalog over the limit, so a build that exceeds it would lose every block
-  // in the palette with only the receiving side able to say why.
-  if (declaredSlots.length > CUSTOM_LIMITS.slotsPerType) {
-    throw new Error(
-      `[pz-theme] Custom block "${type}" declares ${declaredSlots.length} slots, over the ` +
-        `${CUSTOM_LIMITS.slotsPerType} cap. The whole catalog is posted to the editor on every ` +
-        `placeholder announce; split the block.`
-    );
-  }
-
-  const slots: CustomSlotDescriptor[] = [];
-  for (const declaration of declaredSlots) {
-    slots.push(buildSlot(type, declaration, slots));
-  }
+  return { settings, parts };
+};
 
-  // Declared parts join the field-derived ones in the SAME list, after them, so
-  // the wire shape stays one array of names — see `CustomBlockDescriptor.parts`
-  // for why that list must not become a list of objects.
+/**
+ * Appends the developer-declared parts to the field-derived ones already in
+ * `parts`, and returns the states each declared. Shared by both doors.
+ */
+const buildParts = (
+  unit: string,
+  type: string,
+  declaration: CustomBlockOptions['parts'],
+  parts: string[],
+  cap: number
+): Record<string, string[]> => {
   const partStates: Record<string, string[]> = {};
 
-  for (const declared of normalizePartsDeclaration(options.parts)) {
+  for (const declared of normalizePartsDeclaration(declaration)) {
     const nameError = partNameError(declared.name);
     if (nameError) {
       throw new Error(
-        `[pz-theme] Custom block "${type}" declares a part: ${nameError}.`
+        `[pz-theme] Custom ${unit} "${type}" declares a part: ${nameError}.`
       );
     }
 
     if (parts.includes(declared.name)) {
       throw new Error(
-        `[pz-theme] Custom block "${type}" declares the part "${declared.name}" twice. ` +
+        `[pz-theme] Custom ${unit} "${type}" declares the part "${declared.name}" twice. ` +
           `The editor builds one control group per advertised part, so the second group would write ` +
           `the same style keys as the first with nothing to say which won.`
       );
@@ -388,7 +414,7 @@ const buildDescriptor = (
       const stateError = partStateError(state);
       if (stateError) {
         throw new Error(
-          `[pz-theme] Custom block "${type}" declares part "${declared.name}": ${stateError}.`
+          `[pz-theme] Custom ${unit} "${type}" declares part "${declared.name}": ${stateError}.`
         );
       }
     }
@@ -397,14 +423,58 @@ const buildDescriptor = (
     if (declared.states.length > 0) partStates[declared.name] = declared.states;
   }
 
-  if (parts.length > CUSTOM_LIMITS.partsPerType) {
+  if (parts.length > cap) {
     throw new Error(
-      `[pz-theme] Custom block "${type}" advertises ${parts.length} parts, over the ` +
-        `${CUSTOM_LIMITS.partsPerType} cap. The editor drops the whole catalog above it, so every ` +
-        `block in this build would disappear from the palette; declare fewer parts.`
+      `[pz-theme] Custom ${unit} "${type}" advertises ${parts.length} parts, over the ` +
+        `${cap} cap. The editor drops the whole catalog above it, so everything in this build ` +
+        `would disappear from the palette; declare fewer parts.`
     );
   }
 
+  return partStates;
+};
+
+const buildDescriptor = (
+  type: string,
+  name: string,
+  options: CustomBlockOptions
+): CustomBlockDescriptor => {
+  const { settings, parts } = buildSettings(
+    'block',
+    type,
+    options.settings ?? [],
+    CUSTOM_LIMITS.settingsPerType
+  );
+
+  const declaredSlots = options.slots ?? [];
+
+  // The phase-1 twin of the cap the editor also applies: it drops the whole
+  // catalog over the limit, so a build that exceeds it would lose every block
+  // in the palette with only the receiving side able to say why.
+  if (declaredSlots.length > CUSTOM_LIMITS.slotsPerType) {
+    throw new Error(
+      `[pz-theme] Custom block "${type}" declares ${declaredSlots.length} slots, over the ` +
+        `${CUSTOM_LIMITS.slotsPerType} cap. The whole catalog is posted to the editor on every ` +
+        `placeholder announce; split the block.`
+    );
+  }
+
+  const slots: CustomSlotDescriptor[] = [];
+  for (const declaration of declaredSlots) {
+    slots.push(buildSlot(type, declaration, slots));
+  }
+
+  // Declared parts join the field-derived ones in the SAME list, after them, so
+  // the wire shape stays one array of names — see `CustomBlockDescriptor.parts`
+  // for why that list must not become a list of objects.
+  const partStates = buildParts(
+    'block',
+    type,
+    options.parts,
+    parts,
+    CUSTOM_LIMITS.partsPerType
+  );
+
   return withoutUndefined<CustomBlockDescriptor>({
     type,
     name,
@@ -425,6 +495,183 @@ const buildDescriptor = (
   });
 };
 
+const isPlainRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * One region, refusing everything the editor would refuse the whole catalog
+ * over — and one thing the editor cannot see at all.
+ *
+ * `block` is the type the region is born as, and it is NOT validated against a
+ * registry here. It cannot be: `blockRendererRegistry` holds the built-ins this
+ * package ships, but a region may legitimately be born as another of the same
+ * brand's custom blocks, whose barrel may not have evaluated yet. The editor
+ * resolves it through `getBlockConfig`, which composes the built-ins with the
+ * brand's own catalog, and answers with an honest unknown-type card if it truly
+ * does not exist. What IS checked here is that the value is a usable type
+ * string at all, because an empty one seeds a block the merchant can neither
+ * see nor delete.
+ */
+const buildRegion = (
+  type: string,
+  declaration: CustomRegionDeclaration,
+  alreadyDeclared: readonly CustomRegionDescriptor[]
+): CustomRegionDescriptor => {
+  const nameError = regionNameError(declaration.name);
+  if (nameError) {
+    throw new Error(
+      `[pz-theme] Custom section "${type}" declares a region: ${nameError}.`
+    );
+  }
+
+  if (alreadyDeclared.some((region) => region.name === declaration.name)) {
+    throw new Error(
+      `[pz-theme] Custom section "${type}" declares the region "${declaration.name}" twice. ` +
+        `A region is addressed by its name, so both <ThemeRegion> placements would resolve to the ` +
+        `same seeded block and it would render twice — rename one of them.`
+    );
+  }
+
+  if (typeof declaration.block !== 'string' || declaration.block === '') {
+    throw new Error(
+      `[pz-theme] Custom section "${type}" declares the region "${declaration.name}" with no block ` +
+        `type. Name the block it is born as — "search-box", "image", "mini-basket" — which is what ` +
+        `gives the merchant that block's own panel and part groups.`
+    );
+  }
+
+  for (const [field, value] of [
+    ['properties', declaration.properties],
+    ['styles', declaration.styles]
+  ] as const) {
+    if (value !== undefined && !isPlainRecord(value)) {
+      throw new Error(
+        `[pz-theme] Custom section "${type}" declares the region "${declaration.name}" with a ` +
+          `${field} value that is not a plain object. The seed is written straight into the ` +
+          `composition, so it has to be the shape the composition stores.`
+      );
+    }
+  }
+
+  return withoutUndefined<CustomRegionDescriptor>({
+    name: declaration.name,
+    label: declaration.label,
+    block: declaration.block,
+    properties: declaration.properties,
+    styles: declaration.styles,
+    // Unvalidated beyond `assertSerializable` on the whole descriptor: a
+    // block's `value` is that block type's own shape — a string for an image, a
+    // record for a slider — and this module knows none of them. What it does
+    // guarantee is that whatever is written here survives JSON, which is the
+    // only property the transport needs.
+    value: declaration.value
+  });
+};
+
+const buildSectionDescriptor = (
+  type: string,
+  name: string,
+  options: CustomSectionOptions
+): CustomSectionDescriptor => {
+  const { settings, parts } = buildSettings(
+    'section',
+    type,
+    options.settings ?? [],
+    CUSTOM_SECTION_LIMITS.settingsPerType
+  );
+
+  const declaredRegions = options.regions ?? [];
+
+  if (declaredRegions.length > CUSTOM_SECTION_LIMITS.regionsPerType) {
+    throw new Error(
+      `[pz-theme] Custom section "${type}" declares ${declaredRegions.length} regions, over the ` +
+        `${CUSTOM_SECTION_LIMITS.regionsPerType} cap. Every region is seeded into the composition ` +
+        `when the merchant adds the section; split the section.`
+    );
+  }
+
+  const regions: CustomRegionDescriptor[] = [];
+  for (const declaration of declaredRegions) {
+    regions.push(buildRegion(type, declaration, regions));
+  }
+
+  const declaredSlots = options.slots ?? [];
+
+  if (declaredSlots.length > CUSTOM_SECTION_LIMITS.slotsPerType) {
+    throw new Error(
+      `[pz-theme] Custom section "${type}" declares ${declaredSlots.length} slots, over the ` +
+        `${CUSTOM_SECTION_LIMITS.slotsPerType} cap. The whole catalog is posted to the editor on ` +
+        `every placeholder announce; split the section.`
+    );
+  }
+
+  const slots: CustomSlotDescriptor[] = [];
+  for (const declaration of declaredSlots) {
+    slots.push(buildSlot(type, declaration, slots));
+  }
+
+  // A region and a slot are two different promises to the merchant, but they
+  // both become a row in one tree under one section. Two rows with one name is
+  // ambiguous in the UI even though the resolvers never collide, so it is
+  // refused where the message can name both.
+  for (const region of regions) {
+    if (slots.some((slot) => slot.name === region.name)) {
+      throw new Error(
+        `[pz-theme] Custom section "${type}" declares "${region.name}" as both a region and a slot. ` +
+          `They would appear as two rows with one name in the layer tree — rename one of them.`
+      );
+    }
+  }
+
+  const partStates = buildParts(
+    'section',
+    type,
+    options.parts,
+    parts,
+    CUSTOM_SECTION_LIMITS.partsPerType
+  );
+
+  if (options.styles !== undefined && !isPlainRecord(options.styles)) {
+    throw new Error(
+      `[pz-theme] Custom section "${type}" declares styles that are not a plain object. The seed is ` +
+        `written straight into the composition, so it has to be the shape the composition stores.`
+    );
+  }
+
+  if (
+    options.placeholders !== undefined &&
+    (!Array.isArray(options.placeholders) ||
+      options.placeholders.some(
+        (slug) => typeof slug !== 'string' || slug === ''
+      ))
+  ) {
+    throw new Error(
+      `[pz-theme] Custom section "${type}" declares a malformed placeholders list. Every entry has ` +
+        `to be a non-empty placeholder slug such as "header" — omit it to offer the section ` +
+        `everywhere.`
+    );
+  }
+
+  return withoutUndefined<CustomSectionDescriptor>({
+    type,
+    name,
+    label: options.label ?? name,
+    icon: options.icon,
+    group: options.group,
+    // A section always hosts children — its regions, its slots, or both — and
+    // the editor reads the same field off its own registry entry.
+    hasChildren: true,
+    settings,
+    regions,
+    slots,
+    parts,
+    partStates: Object.keys(partStates).length > 0 ? partStates : undefined,
+    styles: options.styles,
+    placeholders: options.placeholders,
+    lockRootTransforms: options.lockRootTransforms
+  });
+};
+
 /**
  * Registers a barrel of developer-authored blocks under one vendor. The one
  * entry point a brand calls — everything else in `src/custom` is consumed by
@@ -490,14 +737,24 @@ export const registerCustomBlocks = (
     // `blocks/block-renderer-registry.tsx` is a bare `Map.set`, so a second
     // claim on a type would silently render the later component everywhere the
     // earlier one was placed, with no signal on either side.
+    //
+    // ALL FOUR STORES, because blocks and sections share one type namespace.
+    // Checking only the block half here made the guard one-directional: a
+    // section registered first, then a block of the same type, was accepted
+    // and left `custom:acme:header` present in every store at once — after
+    // which the editor resolves it as a block or a section depending on which
+    // lookup ran first, which is the failure the section door's own comment
+    // describes and this one has to refuse identically.
     if (
       blockRendererRegistry.hasRenderer(type) ||
-      getCustomBlockDescriptor(type)
+      getCustomBlockDescriptor(type) ||
+      hasCustomSectionDefinition(type) ||
+      getCustomSectionDescriptor(type)
     ) {
       throw new Error(
-        `[pz-theme] Custom block "${type}" is already registered in this build. ` +
-          `Registration refuses to overwrite it. Rename one of them, or check whether the barrel is ` +
-          `being registered twice.`
+        `[pz-theme] "${type}" is already registered in this build, as a block or as a section. ` +
+          `Blocks and sections share one type namespace, so registration refuses to overwrite it. ` +
+          `Rename one of them, or check whether the barrel is being registered twice.`
       );
     }
 
@@ -545,3 +802,117 @@ export const registerCustomBlocks = (
   // document never mounts a placeholder.
   announceCustomBlocks();
 };
+
+
+/**
+ * Registers a barrel of developer-authored SECTIONS under one vendor.
+ *
+ * The section twin of `registerCustomBlocks`, and everything the file header
+ * says about that function applies here unchanged: import the barrel that calls
+ * this from the CLIENT ROOT ONLY, and the whole record is validated before
+ * anything is mutated.
+ *
+ * ONE TYPE NAMESPACE, TWO STORES. A `custom:<vendor>:<name>` may be claimed by
+ * a block or by a section and never by both — the check below consults all four
+ * stores. They share the grammar, so nothing downstream can tell the two apart
+ * from the string alone: the editor resolves a section type through its section
+ * catalog and a block type through its block catalog, and a type present in
+ * both would resolve differently depending on which lookup ran, which is the
+ * kind of bug that only shows up in one composition on one page.
+ */
+export const registerCustomSections = (
+  vendor: string,
+  record: Record<string, CustomSectionInput>
+): void => {
+  if (!CUSTOM_SEGMENT_PATTERN.test(vendor)) {
+    throw new Error(
+      `[pz-theme] registerCustomSections() vendor ${JSON.stringify(
+        vendor
+      )} is not a valid segment. ` +
+        `Use lowercase letters, digits and hyphens, starting with a letter or digit (max 48 characters) — ` +
+        `it becomes the middle segment of every type this call registers.`
+    );
+  }
+
+  const pending: Array<{
+    type: string;
+    descriptor: CustomSectionDescriptor;
+    definition: CustomSectionDefinition;
+  }> = [];
+  const claimed = new Set<string>();
+
+  for (const [name, input] of Object.entries(record ?? {})) {
+    if (!CUSTOM_SEGMENT_PATTERN.test(name)) {
+      throw new Error(
+        `[pz-theme] Custom section name ${JSON.stringify(
+          name
+        )} is not a valid segment. ` +
+          `Use lowercase letters, digits and hyphens, starting with a letter or digit (max 48 characters) — ` +
+          `the name is the published type and cannot be changed once a composition references it.`
+      );
+    }
+
+    const type = `custom:${vendor}:${name}`;
+
+    if (claimed.has(type)) {
+      throw new Error(
+        `[pz-theme] Custom section "${type}" appears twice in one registerCustomSections() call. ` +
+          `Rename one of them — the second would replace the first everywhere it is already placed.`
+      );
+    }
+
+    // All four stores, because the two namespaces are one. A type already
+    // claimed by a BLOCK is refused here with a message that says so, rather
+    // than registering a section the editor would then resolve as a block.
+    if (
+      hasCustomSectionDefinition(type) ||
+      getCustomSectionDescriptor(type) ||
+      blockRendererRegistry.hasRenderer(type) ||
+      getCustomBlockDescriptor(type)
+    ) {
+      throw new Error(
+        `[pz-theme] "${type}" is already registered in this build, as a block or as a section. ` +
+          `Blocks and sections share one type namespace, so registration refuses to overwrite it. ` +
+          `Rename one of them, or check whether the barrel is being registered twice.`
+      );
+    }
+
+    const definition = normalizeCustomSection(input, name);
+    const descriptor = buildSectionDescriptor(type, name, definition.options);
+    assertSerializable(descriptor);
+
+    claimed.add(type);
+    pending.push({ type, descriptor, definition });
+  }
+
+  const total = getCustomSectionTypes().length + pending.length;
+  if (total > CUSTOM_SECTION_LIMITS.sectionTypesPerBuild) {
+    throw new Error(
+      `[pz-theme] This build would declare ${total} custom sections, over the ` +
+        `${CUSTOM_SECTION_LIMITS.sectionTypesPerBuild} cap. The cap exists because the whole catalog ` +
+        `is posted to the editor on every placeholder announce; split the build or retire unused sections.`
+    );
+  }
+
+  const previousVendor = getCatalogVendor();
+  if (previousVendor && previousVendor !== vendor) {
+    devWarn(
+      'customSection',
+      `Catalog vendor changed from "${previousVendor}" to "${vendor}". The catalog carries ONE vendor ` +
+        `field, so everything already registered is announced under the new name — register one vendor per build.`
+    );
+  }
+
+  for (const entry of pending) {
+    addSectionToCatalog(entry.descriptor);
+    addSectionDefinition(entry.type, entry.definition);
+  }
+
+  setCatalogVendor(vendor);
+
+  // The same re-arm the block door uses, and the same reason: this runs at
+  // module evaluation, long before any placeholder has mounted, so it only
+  // schedules the announce that will eventually carry the slugs and both
+  // catalogs in one frame.
+  announceCustomBlocks();
+};

package/src/custom/section-catalog.ts

@@ -0,0 +1,98 @@
+import { devWarn } from '../utils/dev-warn';
+import { CUSTOM_SECTION_LIMITS } from './section-types';
+import type {
+  CustomSectionCatalog,
+  CustomSectionDescriptor
+} from './section-types';
+
+/**
+ * The serializable half of every registered custom section, for the editor.
+ *
+ * A SECOND map beside the block catalog rather than a `sections` key inside it.
+ * The editor validates the block catalog element by element and drops the whole
+ * thing on an unexpected shape, so nesting sections inside `CustomCatalog`
+ * would make every block in a build vanish from the palette of any editor older
+ * than this change. Sections ride as a sibling field instead — see
+ * `placeholder-registry.ts` — and get their own byte budget with it.
+ *
+ * The vendor string is shared with the block catalog through `catalog.ts`, not
+ * duplicated: a build has one vendor, and two sources for it is one more place
+ * for them to disagree.
+ *
+ * Directive-free, like `catalog.ts` and for the same reason:
+ * `placeholder-registry.ts` calls `getCustomSectionCatalog()` without a
+ * directive of its own, and a `'use client'` here would turn that call into a
+ * client reference that throws on the server side.
+ */
+const sectionCatalog = new Map<string, CustomSectionDescriptor>();
+
+/**
+ * Adds a descriptor, refusing rather than overwriting.
+ *
+ * Last-wins would be silent in the same way it is for blocks: nothing in the
+ * render path would report that two sections claimed one type, and every
+ * placement of the first would start rendering the second.
+ */
+export const addSectionToCatalog = (descriptor: CustomSectionDescriptor) => {
+  if (sectionCatalog.has(descriptor.type)) {
+    throw new Error(
+      `[pz-theme] Custom section "${descriptor.type}" is defined twice in this build. ` +
+        `Type names must be unique — rename one of them.`
+    );
+  }
+
+  if (sectionCatalog.size >= CUSTOM_SECTION_LIMITS.sectionTypesPerBuild) {
+    throw new Error(
+      `[pz-theme] This build declares more than ${CUSTOM_SECTION_LIMITS.sectionTypesPerBuild} custom ` +
+        `sections. The cap exists because the whole catalog is posted to the editor on every ` +
+        `placeholder announce; split the build or retire unused sections.`
+    );
+  }
+
+  sectionCatalog.set(descriptor.type, descriptor);
+};
+
+export const getCustomSectionDescriptor = (
+  type: string
+): CustomSectionDescriptor | undefined => sectionCatalog.get(type);
+
+export const getCustomSectionTypes = (): string[] =>
+  Array.from(sectionCatalog.keys());
+
+/**
+ * The payload the storefront announces. Null when nothing is registered, so the
+ * announcer omits the field entirely rather than posting an empty catalog on
+ * every placeholder mount.
+ */
+export const getCustomSectionCatalog = (
+  vendor: string
+): CustomSectionCatalog | null => {
+  if (sectionCatalog.size === 0) return null;
+
+  const payload: CustomSectionCatalog = {
+    vendor,
+    sections: Array.from(sectionCatalog.values())
+  };
+
+  // Measured at the source for the same reason the block catalog is: a section
+  // descriptor grows with every region's seeded properties and styles, and the
+  // editor drops the WHOLE catalog when it arrives over-cap. Failing here names
+  // the build that did it; failing at the receiver names nothing, in a repo the
+  // developer is not working in.
+  const bytes = JSON.stringify(payload).length;
+  if (bytes > CUSTOM_SECTION_LIMITS.catalogBytes) {
+    devWarn(
+      'customSectionCatalog',
+      `Section catalog is ${bytes} bytes, over the ${CUSTOM_SECTION_LIMITS.catalogBytes} byte cap. ` +
+        `The editor will reject it and this brand's whole section band will be empty; trim the ` +
+        `seeded region properties and styles, which are what a section descriptor is mostly made of.`
+    );
+  }
+
+  return payload;
+};
+
+/** Test-only. Module state outlives a test file otherwise. */
+export const resetCustomSectionCatalog = () => {
+  sectionCatalog.clear();
+};