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

package/src/custom/register.ts

@@ -0,0 +1,545 @@
+'use client';
+
+/**
+ * CLIENT-ONLY, and the directive is load-bearing rather than tidy.
+ *
+ * `block-renderer-registry` imports all ~99 block modules, and most of them
+ * call hooks without carrying a directive of their own — they have never
+ * needed one, because the only path that reaches them is `theme-block.tsx`,
+ * which is a client module. Importing the registry from a directive-free
+ * module drags that whole tree into whichever graph the importer sits in, so a
+ * brand barrel imported from a server layout fails the build at
+ * `accordion-block.tsx:1` with "You're importing a module that depends on
+ * `useState` into a React Server Component module" — before any of this code
+ * gets to run.
+ *
+ * Registering only on the client costs nothing: `theme-block.tsx` is the one
+ * production reader of the registry and is itself a client module, and the
+ * server-side CSS generator never consults it. SSR still resolves custom
+ * renderers, because Next renders client components on the server through the
+ * client module graph.
+ *
+ * Consequence for brands: the registration barrel is imported from the CLIENT
+ * ROOT ONLY, not from the server layout as well. See `custom/index.ts`.
+ */
+import blockRendererRegistry from '../blocks/block-renderer-registry';
+import type { BlockRendererProps } from '../blocks/block-renderer-registry';
+import { announceCustomBlocks } from '../placeholder-registry';
+import { devWarn } from '../utils/dev-warn';
+import { createElement } from 'react';
+import type { ComponentType } from 'react';
+import { CustomBlockHost } from './block-host';
+import {
+  addToCatalog,
+  getCatalogVendor,
+  getCustomBlockDescriptor,
+  getCustomBlockTypes,
+  setCatalogVendor
+} from './catalog';
+import {
+  normalizeSettingChoices,
+  settingKeyError,
+  settingTypeError
+} from './collect';
+import { fieldPartName } from './editable-tags';
+import { normalizeCustomBlock } from './define';
+import {
+  normalizePartsDeclaration,
+  partNameError,
+  partStateError
+} from './parts';
+import { slotNameError } from './slot-nodes';
+import type {
+  CustomBlockDefinition,
+  CustomBlockInput,
+  CustomBlockOptions,
+  CustomSettingDeclaration,
+  CustomSlotDeclaration
+} from './define';
+import {
+  CUSTOM_LIMITS,
+  CUSTOM_SEGMENT_PATTERN,
+  materializeDefault
+} from './types';
+import type {
+  CustomBlockDescriptor,
+  CustomSettingDescriptor,
+  CustomSlotDescriptor
+} from './types';
+
+/**
+ * Keys whose value is `undefined` are stripped rather than written.
+ *
+ * `JSON.stringify` drops an undefined-valued key entirely, so writing one would
+ * make the descriptor and the payload the editor receives structurally
+ * different — and `assertSerializable` below, which is the mechanical catch for
+ * a function slipping in, would fire on every block that merely omitted an
+ * optional field.
+ */
+const withoutUndefined = <T extends object>(value: T): T =>
+  Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== undefined)
+  ) as T;
+
+/**
+ * Path of the first value that changes across a JSON round trip, or null.
+ *
+ * Compared structurally rather than by scanning for function values, because
+ * the round trip is the actual transport: whatever `JSON.stringify` alters here
+ * is what the editor will never see. That covers functions and symbols (dropped
+ * silently) and the less obvious ones — a Date becomes a string, `NaN` and
+ * `Infinity` become null, a class instance loses its prototype.
+ */
+const firstDivergentPath = (
+  authored: unknown,
+  roundTripped: unknown,
+  path: string
+): string | null => {
+  if (authored === roundTripped) return null;
+  if (typeof authored !== typeof roundTripped) return path;
+  if (authored === null || roundTripped === null) return path;
+  if (typeof authored !== 'object') return path;
+  if (Array.isArray(authored) !== Array.isArray(roundTripped)) return path;
+
+  const keys = new Set([
+    ...Object.keys(authored as object),
+    ...Object.keys(roundTripped as object)
+  ]);
+
+  for (const key of keys) {
+    const divergent = firstDivergentPath(
+      (authored as Record<string, unknown>)[key],
+      (roundTripped as Record<string, unknown>)[key],
+      `${path}.${key}`
+    );
+    if (divergent) return divergent;
+  }
+
+  return null;
+};
+
+const assertSerializable = (descriptor: CustomBlockDescriptor): 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 ` +
+        `(${String(
+          error
+        )}). The catalog is posted to the editor, so every declared value has to survive JSON.`
+    );
+  }
+
+  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. ` +
+        `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.`
+    );
+  }
+};
+
+const buildSetting = (
+  type: string,
+  declaration: CustomSettingDeclaration
+): CustomSettingDescriptor => {
+  const keyError = settingKeyError(declaration.key);
+  if (keyError) {
+    throw new Error(
+      `[pz-theme] Custom block "${type}" declares a setting: ${keyError}.`
+    );
+  }
+
+  const typeError = settingTypeError(declaration.type);
+  if (typeError) {
+    throw new Error(
+      `[pz-theme] Custom block "${type}" declares setting "${declaration.key}" with ${typeError}.`
+    );
+  }
+
+  return withoutUndefined<CustomSettingDescriptor>({
+    key: declaration.key,
+    type: declaration.type,
+    // The panel renders this string as the control's caption; falling back to
+    // the key keeps an unlabelled control identifiable instead of blank.
+    label: declaration.label ?? declaration.key,
+    defaultValue: materializeDefault(declaration.defaultValue),
+    // Shared with `useThemeSetting` rather than reimplemented: a block that
+    // declares `tone` up front and a component that declares it through the
+    // hook have to produce byte-identical option lists, or the same `select`
+    // renders differently depending on which door it came through. It lives in
+    // `collect.ts` because that is the one module here with no inbound edge, so
+    // importing it from either door closes no cycle.
+    options: normalizeSettingChoices(declaration.options),
+    min: declaration.min,
+    max: declaration.max,
+    step: declaration.step,
+    unit: declaration.unit,
+    maxLength: declaration.maxLength,
+    helpText: declaration.helpText,
+    group: declaration.group,
+    showWhen: declaration.showWhen,
+    editable: declaration.editable
+  });
+};
+
+/**
+ * One slot, refusing a name that could not be matched and a name already taken.
+ *
+ * A duplicate is now a genuine collision rather than a limitation: two slots
+ * sharing a name resolve to the SAME slot node, so both would render its
+ * children and the composition would show every child twice — with two
+ * `data-block-id` wrappers answering to one id, which breaks selection on the
+ * canvas as well.
+ *
+ * `accepts` and `max` are checked here even though nothing on THIS side reads
+ * them, and that is the point. They are the only descriptor values a developer
+ * can write that pz-theme never looks at, so a mistake in one is invisible
+ * until the editor refuses the frame — and the editor refuses the WHOLE
+ * catalog, so a single `accepts: []` empties a brand's entire palette with the
+ * only diagnosis sitting in a repo the developer is not working in. `accepts:
+ * []` is a region nothing can ever go in, and a `max` that is not a positive
+ * whole number is not a count; both are declaration bugs wherever they are
+ * caught, and only here can the message name the block that wrote them.
+ */
+const buildSlot = (
+  type: string,
+  declaration: CustomSlotDeclaration,
+  alreadyDeclared: readonly CustomSlotDescriptor[]
+): CustomSlotDescriptor => {
+  const name = declaration.name ?? '';
+
+  const nameError = slotNameError(name);
+  if (nameError) {
+    throw new Error(
+      `[pz-theme] Custom block "${type}" declares a slot: ${nameError}.`
+    );
+  }
+
+  if (alreadyDeclared.some((slot) => slot.name === name)) {
+    throw new Error(
+      name === ''
+        ? `[pz-theme] Custom block "${type}" declares two unnamed slots. A slot is addressed by its ` +
+          `name, so both resolve to the same slot node and every child would appear twice. Give them names.`
+        : `[pz-theme] Custom block "${type}" declares the slot "${name}" twice. Both resolve to the same ` +
+          `slot node, so every child would appear twice — rename one of them.`
+    );
+  }
+
+  const named = name === '' ? 'its unnamed slot' : `the slot "${name}"`;
+
+  if (declaration.accepts !== undefined) {
+    const malformed =
+      !Array.isArray(declaration.accepts) ||
+      declaration.accepts.some(
+        (entry) => typeof entry !== 'string' || entry === ''
+      );
+
+    if (malformed) {
+      throw new Error(
+        `[pz-theme] Custom block "${type}" declares ${named} with a malformed accepts list. ` +
+          `Every entry has to be a non-empty block type string — the editor refuses the whole catalog ` +
+          `over one that is not, and every block in this build would disappear from the palette.`
+      );
+    }
+
+    if (declaration.accepts.length === 0) {
+      throw new Error(
+        `[pz-theme] Custom block "${type}" declares ${named} with an empty accepts list, which no block ` +
+          `could ever satisfy. Omit accepts to take anything; a block that means "no children here" ` +
+          `declares no slot at all.`
+      );
+    }
+  }
+
+  if (
+    declaration.max !== undefined &&
+    (typeof declaration.max !== 'number' ||
+      !Number.isInteger(declaration.max) ||
+      declaration.max < 1)
+  ) {
+    throw new Error(
+      `[pz-theme] Custom block "${type}" declares ${named} with max ${JSON.stringify(
+        declaration.max
+      )}, which is not a positive whole number of blocks. Omit max for an unbounded region.`
+    );
+  }
+
+  return withoutUndefined<CustomSlotDescriptor>({
+    name,
+    label: declaration.label,
+    // Carried for the editor's benefit; pz-theme enforces neither acceptance
+    // nor the cap at render time — it only guarantees, above, that what it
+    // hands over is a shape the editor will accept.
+    accepts: declaration.accepts,
+    max: declaration.max
+  });
+};
+
+/**
+ * Binds one type's identity onto the client host.
+ *
+ * `createElement` rather than a call into `block-host.tsx`, and the wrapper is
+ * the price of that. `block-host.tsx` is its own `'use client'` module and has
+ * to be — `React.Component` and `createContext` are both `undefined` under the
+ * `react-server` condition — so `CustomBlockHost` is a client EXPORT whichever
+ * graph ends up holding this file. Referencing a client export as an element
+ * type resolves from either graph; CALLING one throws "Attempted to call … from
+ * the server" as soon as the reference is the server-side one. `createElement`
+ * keeps the binding on the legal side of that line without this module having
+ * to reason about where a brand's import landed.
+ */
+const bindHost = (
+  type: string,
+  definition: CustomBlockDefinition,
+  label: string
+): ComponentType<BlockRendererProps> => {
+  const Host = (props: BlockRendererProps) =>
+    createElement(CustomBlockHost, { ...props, type, label, definition });
+
+  // Named for the React devtools tree: without this every custom block on the
+  // page appears as the same anonymous wrapper. Named for the BINDING and not
+  // for the host it renders, which is a separate fiber inside it carrying its
+  // own name.
+  Host.displayName = `CustomBlock(${type})`;
+
+  return Host;
+};
+
+const buildDescriptor = (
+  type: string,
+  name: string,
+  options: CustomBlockOptions
+): CustomBlockDescriptor => {
+  const declaredSettings = options.settings ?? [];
+
+  if (declaredSettings.length > CUSTOM_LIMITS.settingsPerType) {
+    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.`
+    );
+  }
+
+  const settings: CustomSettingDescriptor[] = [];
+  const parts: string[] = [];
+
+  for (const declaration of declaredSettings) {
+    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.`
+      );
+    }
+
+    const setting = buildSetting(type, declaration);
+    settings.push(setting);
+
+    // Same helper the render path stamps the element with, so a part the
+    // catalog advertises is always one the DOM actually carries.
+    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));
+  }
+
+  // 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: Record<string, string[]> = {};
+
+  for (const declared of normalizePartsDeclaration(options.parts)) {
+    const nameError = partNameError(declared.name);
+    if (nameError) {
+      throw new Error(
+        `[pz-theme] Custom block "${type}" declares a part: ${nameError}.`
+      );
+    }
+
+    if (parts.includes(declared.name)) {
+      throw new Error(
+        `[pz-theme] Custom block "${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.`
+      );
+    }
+
+    for (const state of declared.states) {
+      const stateError = partStateError(state);
+      if (stateError) {
+        throw new Error(
+          `[pz-theme] Custom block "${type}" declares part "${declared.name}": ${stateError}.`
+        );
+      }
+    }
+
+    parts.push(declared.name);
+    if (declared.states.length > 0) partStates[declared.name] = declared.states;
+  }
+
+  if (parts.length > CUSTOM_LIMITS.partsPerType) {
+    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.`
+    );
+  }
+
+  return withoutUndefined<CustomBlockDescriptor>({
+    type,
+    name,
+    label: options.label ?? name,
+    icon: options.icon,
+    group: options.group,
+    // Runtime collection flips this to true when a `<ThemeSlot />` renders in a
+    // block that declared none, so a developer who declares nothing still gets
+    // a droppable block.
+    hasChildren: slots.length > 0,
+    settings,
+    slots,
+    parts,
+    // Omitted rather than sent empty: an editor that has never heard of the key
+    // ignores it either way, and a brand that declares no state sends nothing
+    // extra on every placeholder announce.
+    partStates: Object.keys(partStates).length > 0 ? partStates : undefined
+  });
+};
+
+/**
+ * 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
+ * the block it registers or by the editor bridge that announces it.
+ *
+ * Import the barrel that calls this from the CLIENT ROOT ONLY — never from the
+ * server layout as well. This module is `'use client'` because it must be; the
+ * file header explains what importing it from a server graph does to a brand's
+ * build, and it is not subtle.
+ *
+ * ATOMIC ACROSS THE RECORD: everything is validated before anything is
+ * mutated. A half-registered barrel is worse than a rejected one — the editor
+ * would be offered blocks out of the catalog that the build cannot render, and
+ * the merchant would place one and get an unknown-type box on the storefront.
+ * Every phase-2 failure mode therefore has a phase-1 twin here, including the
+ * two caps `addToCatalog` also enforces.
+ */
+export const registerCustomBlocks = (
+  vendor: string,
+  record: Record<string, CustomBlockInput>
+): void => {
+  if (!CUSTOM_SEGMENT_PATTERN.test(vendor)) {
+    throw new Error(
+      `[pz-theme] registerCustomBlocks() 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: CustomBlockDescriptor;
+    host: ComponentType<BlockRendererProps>;
+  }> = [];
+  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 block 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}`;
+
+    // Also the guarantee that phase 2 cannot throw: without it two entries
+    // resolving to one type would pass validation and then fail inside
+    // `addToCatalog`, half-applying the record.
+    if (claimed.has(type)) {
+      throw new Error(
+        `[pz-theme] Custom block "${type}" appears twice in one registerCustomBlocks() call. ` +
+          `Rename one of them — the second would replace the first everywhere it is already placed.`
+      );
+    }
+
+    // Never shadow, never last-wins. `BlockRendererRegistry.register` in
+    // `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.
+    if (
+      blockRendererRegistry.hasRenderer(type) ||
+      getCustomBlockDescriptor(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.`
+      );
+    }
+
+    const definition = normalizeCustomBlock(input, name);
+    const descriptor = buildDescriptor(type, name, definition.options);
+    assertSerializable(descriptor);
+
+    claimed.add(type);
+    pending.push({
+      type,
+      descriptor,
+      host: bindHost(type, definition, descriptor.label)
+    });
+  }
+
+  const total = getCustomBlockTypes().length + pending.length;
+  if (total > CUSTOM_LIMITS.typesPerBuild) {
+    throw new Error(
+      `[pz-theme] This build would declare ${total} custom blocks, over the ` +
+        `${CUSTOM_LIMITS.typesPerBuild} cap. The cap exists because the whole catalog is posted to the ` +
+        `editor on every placeholder announce; split the build or retire unused blocks.`
+    );
+  }
+
+  const previousVendor = getCatalogVendor();
+  if (previousVendor && previousVendor !== vendor) {
+    devWarn(
+      'customBlock',
+      `Catalog vendor changed from "${previousVendor}" to "${vendor}". The catalog carries ONE vendor ` +
+        `field, so every block already registered is announced under the new name — register one vendor per build.`
+    );
+  }
+
+  for (const entry of pending) {
+    addToCatalog(entry.descriptor);
+    blockRendererRegistry.register(entry.type, entry.host);
+  }
+
+  setCatalogVendor(vendor);
+
+  // Tell the editor bridge a catalog now exists. This runs at module
+  // evaluation, long before any placeholder has mounted, so it only RE-ARMS
+  // the placeholder announce — the flush that eventually goes out carries the
+  // slugs and the catalog in one frame, and no frame is posted at all if this
+  // document never mounts a placeholder.
+  announceCustomBlocks();
+};

package/src/custom/slot-nodes.ts

@@ -0,0 +1,119 @@
+import type { Block } from '../theme-block';
+import {
+  CUSTOM_SLOT_BLOCK_TYPE,
+  SLOT_NAME_PATTERN,
+  SLOT_NAME_PROPERTY
+} from './types';
+
+/**
+ * Reading slots back out of a composition.
+ *
+ * A declared slot materializes as one reserved-type child of the custom block,
+ * so `<ThemeSlot name="promo" />` renders the children of THAT node rather than
+ * the block's whole child list. Everything in this file is the read half of
+ * that: the editor creates the nodes, the renderer finds them.
+ *
+ * Directive-free on purpose. `register.ts`, `collect.ts` and `theme-slot.tsx`
+ * all need the same answers, and only the last of the three is a client module.
+ */
+
+export const isSlotNode = (block: Block): boolean =>
+  block.type === CUSTOM_SLOT_BLOCK_TYPE;
+
+/**
+ * The name a slot node carries; the empty string for the unnamed slot.
+ *
+ * Both a bare string and a per-breakpoint bucket are read, and the second
+ * branch is not speculative tidiness. Every other value in `block.properties`
+ * is per-breakpoint, and `handlePropertyChange` in the editor re-buckets
+ * whatever it is given — so the day anything routes this key through a property
+ * control, a bare-string-only reader would detach every named slot in every
+ * published composition at once, silently. One branch buys immunity from that.
+ */
+export const slotNodeName = (block: Block): string => {
+  const raw = block.properties?.[SLOT_NAME_PROPERTY];
+
+  if (typeof raw === 'string') return raw;
+
+  if (raw && typeof raw === 'object') {
+    const desktop = (raw as Record<string, unknown>).desktop;
+    if (typeof desktop === 'string') return desktop;
+  }
+
+  return '';
+};
+
+/**
+ * The children one slot renders, or null when the slot has no node yet.
+ *
+ * Null and `[]` mean different things to the caller and both have to be
+ * distinguishable: an empty slot node is a region the merchant emptied, a
+ * missing node is a region the merchant has never opened. Neither renders
+ * anything on the live storefront, so the distinction costs shoppers nothing —
+ * it exists so the designer can say which is which.
+ *
+ * THE LEGACY BRANCH IS FOR THE UNNAMED SLOT AND NOTHING ELSE. Every composition
+ * saved before slots were nodes put the merchant's blocks directly into
+ * `block.blocks`, and the only slot that could have held them is the single
+ * unnamed one — a named slot was refused at define time, so it can have no
+ * legacy content to find. Slot nodes are filtered out of that branch so a block
+ * re-saved with nodes does not render another slot's content here as well.
+ */
+export const resolveSlotChildren = (
+  block: Block,
+  name: string
+): Block[] | null => {
+  const children = block.blocks ?? [];
+
+  const node = children.find(
+    (child) => isSlotNode(child) && slotNodeName(child) === name
+  );
+
+  if (node) return node.blocks ?? [];
+
+  if (name === '') return children.filter((child) => !isSlotNode(child));
+
+  return null;
+};
+
+/** The reason a slot name is refused, or null. Shared by every door. */
+export const slotNameError = (name: unknown): string | null => {
+  if (name === '') return null;
+
+  if (typeof name !== 'string' || !SLOT_NAME_PATTERN.test(name)) {
+    return (
+      `slot name ${JSON.stringify(name)} is not valid. Use a lowercase name ` +
+      `starting with a letter (letters, digits and hyphens, max 32 characters), or omit the ` +
+      `name entirely on a block that opens a single region — the name is matched literally ` +
+      `against the slot node the editor created`
+    );
+  }
+
+  return null;
+};
+
+/**
+ * Which slot a bare `<ThemeSlot />` means, or an explanation of why it is
+ * ambiguous.
+ *
+ * The single-slot spelling has to keep working untouched, so a block that
+ * declares one slot resolves to it WHATEVER it is called — that is also what
+ * lets a developer name their only slot without having to repeat the name at
+ * the usage. A block that declares an unnamed slot alongside named ones has an
+ * unambiguous answer too. Only several slots that are all named leave nothing
+ * to resolve, and then the message has to say what the alternatives are,
+ * because the developer's next edit is typing one of them.
+ */
+export const resolveUnnamedSlot = (
+  declaredNames: readonly string[]
+): { name: string } | { error: string } => {
+  if (declaredNames.length <= 1) return { name: declaredNames[0] ?? '' };
+
+  if (declaredNames.includes('')) return { name: '' };
+
+  return {
+    error:
+      `a bare <ThemeSlot /> cannot say which of the ${declaredNames.length} declared slots it opens. ` +
+      `Name it: ${declaredNames.map((slot) => `<ThemeSlot name="${slot}" />`).join(', ')}`
+  };
+};