@createcms/core 0.1.1 → 0.2.1

package/dist/next/index.d.cts

@@ -62,18 +62,70 @@ type BlockDefinition<TProps extends Record<string, BlockProperty> = Record<strin
     label: string;
     description?: string;
     previewImageUrl?: string;
+    /**
+     * Editor hint: the block-picker category this block is shown under (e.g.
+     * `'Forms'`, `'Layout'`). Purely presentational — the editor groups blocks by
+     * this label; the package never acts on it. Free-form by design; for
+     * consistent, autocompleted group names across blocks, reference a shared
+     * `as const` object (e.g. `group: BLOCK_GROUPS.forms`).
+     */
+    group?: string;
     /** Events this (functional) block can emit — see {@link EventDeclaration}. */
     events?: TEvents;
 } & ({
     allowChildren?: false;
 } | {
     allowChildren: true;
-    allowedChildBlocks?: string[];
 });
 type AnyBlockDefinition = BlockDefinition<Record<string, BlockProperty>, Record<string, EventDeclaration>>;
 type RootDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>> = {
     properties: TProps;
 };
+/**
+ * One PARENT's placement rule inside a collection's {@link CollectionStructure}
+ * — declares which child block types that parent (or the literal `'root'`) may
+ * contain. There are three mutually-exclusive modes, enforced by the type:
+ *
+ * - **open** — `{}` or `{ accepts: '*' }`: holds any block. (Same as having no
+ *   entry at all; `'*'` is just an explicit, readable form.)
+ * - **whitelist** — `{ accepts: ['a', 'b'] }`: holds ONLY `a`/`b`. Fail-closed —
+ *   a block added to the collection later is rejected until listed. `excludes`
+ *   is forbidden here (a concrete `accepts` already says exactly what's allowed).
+ * - **blacklist** — `{ excludes: ['z'] }` (or `{ accepts: '*', excludes: ['z'] }`):
+ *   holds anything EXCEPT `z`. Fail-open — a block added later is accepted.
+ *
+ * Whether a parent accepts children AT ALL is the separate, coarser
+ * `allowChildren` gate on the block (the root always accepts children); these
+ * rules only refine WHICH children an accepting parent may hold.
+ */
+type BlockStructureEntry<TBlockName extends string> = {
+    /** `'*'` = open base (optional, for readability). */
+    accepts?: '*';
+    /** Holds anything except these. */
+    excludes?: readonly TBlockName[];
+} | {
+    /** Holds ONLY these block types. */
+    accepts: readonly TBlockName[];
+    /**
+     * Forbidden alongside a concrete `accepts` list — the list already names
+     * exactly what is allowed, so `excludes` would be ignored.
+     */
+    excludes?: "Remove 'excludes': a concrete 'accepts' list already defines exactly which blocks are allowed. Use accepts: '*' with excludes for an all-except list.";
+};
+/**
+ * Placement rules for a collection, keyed by PARENT block name (or the literal
+ * `'root'` for the top level). Open by default: a parent with no entry holds any
+ * block. The keys and the `accepts` / `excludes` block names autocomplete against
+ * the collection's block names and are checked at compile time by
+ * {@link defineCollection} (the field type alone enforces this — no extra step).
+ *
+ * This is the single source of truth that the visual editor (drop-zone gating)
+ * and the server guard (createBlock / moveBlock / duplicateBlock) both read,
+ * alongside each block's `allowChildren` flag, so they can never diverge.
+ */
+type CollectionStructure<TBlocks extends Record<string, AnyBlockDefinition>> = {
+    [K in keyof TBlocks | 'root']?: BlockStructureEntry<keyof TBlocks & string>;
+};
 type SlugConfig = {
     enabled: false;
 } | {
@@ -97,6 +149,15 @@ type CollectionDefinition<TProps extends Record<string, BlockProperty> = Record<
      * regardless of this flag). Any collection can still be a reference target.
      */
     reusableBlock?: boolean;
+    /**
+     * Placement rules keyed by PARENT block name (or `'root'`) — which children
+     * each container may hold, via `accepts` (whitelist) / `excludes` (blacklist)
+     * (see {@link CollectionStructure}). Read by the editor and the server guard
+     * together with each block's `allowChildren` flag. Open by default; block
+     * names are checked at compile time by the field type itself, so a typo is a
+     * compile error at the `defineCollection` call site.
+     */
+    structure?: CollectionStructure<TBlocks>;
 };
 type AnyCollectionDefinition = CollectionDefinition<Record<string, BlockProperty>, Record<string, AnyBlockDefinition>>;
 type RevalidateEvent<TCollections extends Record<string, AnyCollectionDefinition> = Record<string, AnyCollectionDefinition>> = {

package/dist/next/index.d.ts

@@ -62,18 +62,70 @@ type BlockDefinition<TProps extends Record<string, BlockProperty> = Record<strin
     label: string;
     description?: string;
     previewImageUrl?: string;
+    /**
+     * Editor hint: the block-picker category this block is shown under (e.g.
+     * `'Forms'`, `'Layout'`). Purely presentational — the editor groups blocks by
+     * this label; the package never acts on it. Free-form by design; for
+     * consistent, autocompleted group names across blocks, reference a shared
+     * `as const` object (e.g. `group: BLOCK_GROUPS.forms`).
+     */
+    group?: string;
     /** Events this (functional) block can emit — see {@link EventDeclaration}. */
     events?: TEvents;
 } & ({
     allowChildren?: false;
 } | {
     allowChildren: true;
-    allowedChildBlocks?: string[];
 });
 type AnyBlockDefinition = BlockDefinition<Record<string, BlockProperty>, Record<string, EventDeclaration>>;
 type RootDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>> = {
     properties: TProps;
 };
+/**
+ * One PARENT's placement rule inside a collection's {@link CollectionStructure}
+ * — declares which child block types that parent (or the literal `'root'`) may
+ * contain. There are three mutually-exclusive modes, enforced by the type:
+ *
+ * - **open** — `{}` or `{ accepts: '*' }`: holds any block. (Same as having no
+ *   entry at all; `'*'` is just an explicit, readable form.)
+ * - **whitelist** — `{ accepts: ['a', 'b'] }`: holds ONLY `a`/`b`. Fail-closed —
+ *   a block added to the collection later is rejected until listed. `excludes`
+ *   is forbidden here (a concrete `accepts` already says exactly what's allowed).
+ * - **blacklist** — `{ excludes: ['z'] }` (or `{ accepts: '*', excludes: ['z'] }`):
+ *   holds anything EXCEPT `z`. Fail-open — a block added later is accepted.
+ *
+ * Whether a parent accepts children AT ALL is the separate, coarser
+ * `allowChildren` gate on the block (the root always accepts children); these
+ * rules only refine WHICH children an accepting parent may hold.
+ */
+type BlockStructureEntry<TBlockName extends string> = {
+    /** `'*'` = open base (optional, for readability). */
+    accepts?: '*';
+    /** Holds anything except these. */
+    excludes?: readonly TBlockName[];
+} | {
+    /** Holds ONLY these block types. */
+    accepts: readonly TBlockName[];
+    /**
+     * Forbidden alongside a concrete `accepts` list — the list already names
+     * exactly what is allowed, so `excludes` would be ignored.
+     */
+    excludes?: "Remove 'excludes': a concrete 'accepts' list already defines exactly which blocks are allowed. Use accepts: '*' with excludes for an all-except list.";
+};
+/**
+ * Placement rules for a collection, keyed by PARENT block name (or the literal
+ * `'root'` for the top level). Open by default: a parent with no entry holds any
+ * block. The keys and the `accepts` / `excludes` block names autocomplete against
+ * the collection's block names and are checked at compile time by
+ * {@link defineCollection} (the field type alone enforces this — no extra step).
+ *
+ * This is the single source of truth that the visual editor (drop-zone gating)
+ * and the server guard (createBlock / moveBlock / duplicateBlock) both read,
+ * alongside each block's `allowChildren` flag, so they can never diverge.
+ */
+type CollectionStructure<TBlocks extends Record<string, AnyBlockDefinition>> = {
+    [K in keyof TBlocks | 'root']?: BlockStructureEntry<keyof TBlocks & string>;
+};
 type SlugConfig = {
     enabled: false;
 } | {
@@ -97,6 +149,15 @@ type CollectionDefinition<TProps extends Record<string, BlockProperty> = Record<
      * regardless of this flag). Any collection can still be a reference target.
      */
     reusableBlock?: boolean;
+    /**
+     * Placement rules keyed by PARENT block name (or `'root'`) — which children
+     * each container may hold, via `accepts` (whitelist) / `excludes` (blacklist)
+     * (see {@link CollectionStructure}). Read by the editor and the server guard
+     * together with each block's `allowChildren` flag. Open by default; block
+     * names are checked at compile time by the field type itself, so a typo is a
+     * compile error at the `defineCollection` call site.
+     */
+    structure?: CollectionStructure<TBlocks>;
 };
 type AnyCollectionDefinition = CollectionDefinition<Record<string, BlockProperty>, Record<string, AnyBlockDefinition>>;
 type RevalidateEvent<TCollections extends Record<string, AnyCollectionDefinition> = Record<string, AnyCollectionDefinition>> = {

package/dist/plugins/ab-test/index.cjs

@@ -2455,6 +2455,10 @@ const CMS_ERRORS = {
         status: 404,
         message: 'Parent block not found'
     },
+    BLOCK_NOT_ALLOWED_IN_PARENT: {
+        status: 400,
+        message: 'This block type is not allowed inside the target parent'
+    },
     ROOT_NOT_FOUND: {
         status: 404,
         message: 'Root block not found in snapshot'

package/dist/plugins/ab-test/index.d.cts

@@ -323,18 +323,70 @@ type BlockDefinition<TProps extends Record<string, BlockProperty> = Record<strin
     label: string;
     description?: string;
     previewImageUrl?: string;
+    /**
+     * Editor hint: the block-picker category this block is shown under (e.g.
+     * `'Forms'`, `'Layout'`). Purely presentational — the editor groups blocks by
+     * this label; the package never acts on it. Free-form by design; for
+     * consistent, autocompleted group names across blocks, reference a shared
+     * `as const` object (e.g. `group: BLOCK_GROUPS.forms`).
+     */
+    group?: string;
     /** Events this (functional) block can emit — see {@link EventDeclaration}. */
     events?: TEvents;
 } & ({
     allowChildren?: false;
 } | {
     allowChildren: true;
-    allowedChildBlocks?: string[];
 });
 type AnyBlockDefinition = BlockDefinition<Record<string, BlockProperty>, Record<string, EventDeclaration>>;
 type RootDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>> = {
     properties: TProps;
 };
+/**
+ * One PARENT's placement rule inside a collection's {@link CollectionStructure}
+ * — declares which child block types that parent (or the literal `'root'`) may
+ * contain. There are three mutually-exclusive modes, enforced by the type:
+ *
+ * - **open** — `{}` or `{ accepts: '*' }`: holds any block. (Same as having no
+ *   entry at all; `'*'` is just an explicit, readable form.)
+ * - **whitelist** — `{ accepts: ['a', 'b'] }`: holds ONLY `a`/`b`. Fail-closed —
+ *   a block added to the collection later is rejected until listed. `excludes`
+ *   is forbidden here (a concrete `accepts` already says exactly what's allowed).
+ * - **blacklist** — `{ excludes: ['z'] }` (or `{ accepts: '*', excludes: ['z'] }`):
+ *   holds anything EXCEPT `z`. Fail-open — a block added later is accepted.
+ *
+ * Whether a parent accepts children AT ALL is the separate, coarser
+ * `allowChildren` gate on the block (the root always accepts children); these
+ * rules only refine WHICH children an accepting parent may hold.
+ */
+type BlockStructureEntry<TBlockName extends string> = {
+    /** `'*'` = open base (optional, for readability). */
+    accepts?: '*';
+    /** Holds anything except these. */
+    excludes?: readonly TBlockName[];
+} | {
+    /** Holds ONLY these block types. */
+    accepts: readonly TBlockName[];
+    /**
+     * Forbidden alongside a concrete `accepts` list — the list already names
+     * exactly what is allowed, so `excludes` would be ignored.
+     */
+    excludes?: "Remove 'excludes': a concrete 'accepts' list already defines exactly which blocks are allowed. Use accepts: '*' with excludes for an all-except list.";
+};
+/**
+ * Placement rules for a collection, keyed by PARENT block name (or the literal
+ * `'root'` for the top level). Open by default: a parent with no entry holds any
+ * block. The keys and the `accepts` / `excludes` block names autocomplete against
+ * the collection's block names and are checked at compile time by
+ * {@link defineCollection} (the field type alone enforces this — no extra step).
+ *
+ * This is the single source of truth that the visual editor (drop-zone gating)
+ * and the server guard (createBlock / moveBlock / duplicateBlock) both read,
+ * alongside each block's `allowChildren` flag, so they can never diverge.
+ */
+type CollectionStructure<TBlocks extends Record<string, AnyBlockDefinition>> = {
+    [K in keyof TBlocks | 'root']?: BlockStructureEntry<keyof TBlocks & string>;
+};
 type SlugConfig = {
     enabled: false;
 } | {
@@ -358,6 +410,15 @@ type CollectionDefinition<TProps extends Record<string, BlockProperty> = Record<
      * regardless of this flag). Any collection can still be a reference target.
      */
     reusableBlock?: boolean;
+    /**
+     * Placement rules keyed by PARENT block name (or `'root'`) — which children
+     * each container may hold, via `accepts` (whitelist) / `excludes` (blacklist)
+     * (see {@link CollectionStructure}). Read by the editor and the server guard
+     * together with each block's `allowChildren` flag. Open by default; block
+     * names are checked at compile time by the field type itself, so a typo is a
+     * compile error at the `defineCollection` call site.
+     */
+    structure?: CollectionStructure<TBlocks>;
 };
 type AnyCollectionDefinition = CollectionDefinition<Record<string, BlockProperty>, Record<string, AnyBlockDefinition>>;
 type CollectionWithName = Omit<AnyCollectionDefinition, 'blocks'> & {

package/dist/plugins/ab-test/index.d.ts

@@ -323,18 +323,70 @@ type BlockDefinition<TProps extends Record<string, BlockProperty> = Record<strin
     label: string;
     description?: string;
     previewImageUrl?: string;
+    /**
+     * Editor hint: the block-picker category this block is shown under (e.g.
+     * `'Forms'`, `'Layout'`). Purely presentational — the editor groups blocks by
+     * this label; the package never acts on it. Free-form by design; for
+     * consistent, autocompleted group names across blocks, reference a shared
+     * `as const` object (e.g. `group: BLOCK_GROUPS.forms`).
+     */
+    group?: string;
     /** Events this (functional) block can emit — see {@link EventDeclaration}. */
     events?: TEvents;
 } & ({
     allowChildren?: false;
 } | {
     allowChildren: true;
-    allowedChildBlocks?: string[];
 });
 type AnyBlockDefinition = BlockDefinition<Record<string, BlockProperty>, Record<string, EventDeclaration>>;
 type RootDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>> = {
     properties: TProps;
 };
+/**
+ * One PARENT's placement rule inside a collection's {@link CollectionStructure}
+ * — declares which child block types that parent (or the literal `'root'`) may
+ * contain. There are three mutually-exclusive modes, enforced by the type:
+ *
+ * - **open** — `{}` or `{ accepts: '*' }`: holds any block. (Same as having no
+ *   entry at all; `'*'` is just an explicit, readable form.)
+ * - **whitelist** — `{ accepts: ['a', 'b'] }`: holds ONLY `a`/`b`. Fail-closed —
+ *   a block added to the collection later is rejected until listed. `excludes`
+ *   is forbidden here (a concrete `accepts` already says exactly what's allowed).
+ * - **blacklist** — `{ excludes: ['z'] }` (or `{ accepts: '*', excludes: ['z'] }`):
+ *   holds anything EXCEPT `z`. Fail-open — a block added later is accepted.
+ *
+ * Whether a parent accepts children AT ALL is the separate, coarser
+ * `allowChildren` gate on the block (the root always accepts children); these
+ * rules only refine WHICH children an accepting parent may hold.
+ */
+type BlockStructureEntry<TBlockName extends string> = {
+    /** `'*'` = open base (optional, for readability). */
+    accepts?: '*';
+    /** Holds anything except these. */
+    excludes?: readonly TBlockName[];
+} | {
+    /** Holds ONLY these block types. */
+    accepts: readonly TBlockName[];
+    /**
+     * Forbidden alongside a concrete `accepts` list — the list already names
+     * exactly what is allowed, so `excludes` would be ignored.
+     */
+    excludes?: "Remove 'excludes': a concrete 'accepts' list already defines exactly which blocks are allowed. Use accepts: '*' with excludes for an all-except list.";
+};
+/**
+ * Placement rules for a collection, keyed by PARENT block name (or the literal
+ * `'root'` for the top level). Open by default: a parent with no entry holds any
+ * block. The keys and the `accepts` / `excludes` block names autocomplete against
+ * the collection's block names and are checked at compile time by
+ * {@link defineCollection} (the field type alone enforces this — no extra step).
+ *
+ * This is the single source of truth that the visual editor (drop-zone gating)
+ * and the server guard (createBlock / moveBlock / duplicateBlock) both read,
+ * alongside each block's `allowChildren` flag, so they can never diverge.
+ */
+type CollectionStructure<TBlocks extends Record<string, AnyBlockDefinition>> = {
+    [K in keyof TBlocks | 'root']?: BlockStructureEntry<keyof TBlocks & string>;
+};
 type SlugConfig = {
     enabled: false;
 } | {
@@ -358,6 +410,15 @@ type CollectionDefinition<TProps extends Record<string, BlockProperty> = Record<
      * regardless of this flag). Any collection can still be a reference target.
      */
     reusableBlock?: boolean;
+    /**
+     * Placement rules keyed by PARENT block name (or `'root'`) — which children
+     * each container may hold, via `accepts` (whitelist) / `excludes` (blacklist)
+     * (see {@link CollectionStructure}). Read by the editor and the server guard
+     * together with each block's `allowChildren` flag. Open by default; block
+     * names are checked at compile time by the field type itself, so a typo is a
+     * compile error at the `defineCollection` call site.
+     */
+    structure?: CollectionStructure<TBlocks>;
 };
 type AnyCollectionDefinition = CollectionDefinition<Record<string, BlockProperty>, Record<string, AnyBlockDefinition>>;
 type CollectionWithName = Omit<AnyCollectionDefinition, 'blocks'> & {

package/dist/plugins/ab-test/index.js

@@ -2430,6 +2430,10 @@ const CMS_ERRORS = {
         status: 404,
         message: 'Parent block not found'
     },
+    BLOCK_NOT_ALLOWED_IN_PARENT: {
+        status: 400,
+        message: 'This block type is not allowed inside the target parent'
+    },
     ROOT_NOT_FOUND: {
         status: 404,
         message: 'Root block not found in snapshot'

package/dist/plugins/consent/index.d.cts

@@ -226,18 +226,70 @@ type BlockDefinition<TProps extends Record<string, BlockProperty> = Record<strin
     label: string;
     description?: string;
     previewImageUrl?: string;
+    /**
+     * Editor hint: the block-picker category this block is shown under (e.g.
+     * `'Forms'`, `'Layout'`). Purely presentational — the editor groups blocks by
+     * this label; the package never acts on it. Free-form by design; for
+     * consistent, autocompleted group names across blocks, reference a shared
+     * `as const` object (e.g. `group: BLOCK_GROUPS.forms`).
+     */
+    group?: string;
     /** Events this (functional) block can emit — see {@link EventDeclaration}. */
     events?: TEvents;
 } & ({
     allowChildren?: false;
 } | {
     allowChildren: true;
-    allowedChildBlocks?: string[];
 });
 type AnyBlockDefinition = BlockDefinition<Record<string, BlockProperty>, Record<string, EventDeclaration>>;
 type RootDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>> = {
     properties: TProps;
 };
+/**
+ * One PARENT's placement rule inside a collection's {@link CollectionStructure}
+ * — declares which child block types that parent (or the literal `'root'`) may
+ * contain. There are three mutually-exclusive modes, enforced by the type:
+ *
+ * - **open** — `{}` or `{ accepts: '*' }`: holds any block. (Same as having no
+ *   entry at all; `'*'` is just an explicit, readable form.)
+ * - **whitelist** — `{ accepts: ['a', 'b'] }`: holds ONLY `a`/`b`. Fail-closed —
+ *   a block added to the collection later is rejected until listed. `excludes`
+ *   is forbidden here (a concrete `accepts` already says exactly what's allowed).
+ * - **blacklist** — `{ excludes: ['z'] }` (or `{ accepts: '*', excludes: ['z'] }`):
+ *   holds anything EXCEPT `z`. Fail-open — a block added later is accepted.
+ *
+ * Whether a parent accepts children AT ALL is the separate, coarser
+ * `allowChildren` gate on the block (the root always accepts children); these
+ * rules only refine WHICH children an accepting parent may hold.
+ */
+type BlockStructureEntry<TBlockName extends string> = {
+    /** `'*'` = open base (optional, for readability). */
+    accepts?: '*';
+    /** Holds anything except these. */
+    excludes?: readonly TBlockName[];
+} | {
+    /** Holds ONLY these block types. */
+    accepts: readonly TBlockName[];
+    /**
+     * Forbidden alongside a concrete `accepts` list — the list already names
+     * exactly what is allowed, so `excludes` would be ignored.
+     */
+    excludes?: "Remove 'excludes': a concrete 'accepts' list already defines exactly which blocks are allowed. Use accepts: '*' with excludes for an all-except list.";
+};
+/**
+ * Placement rules for a collection, keyed by PARENT block name (or the literal
+ * `'root'` for the top level). Open by default: a parent with no entry holds any
+ * block. The keys and the `accepts` / `excludes` block names autocomplete against
+ * the collection's block names and are checked at compile time by
+ * {@link defineCollection} (the field type alone enforces this — no extra step).
+ *
+ * This is the single source of truth that the visual editor (drop-zone gating)
+ * and the server guard (createBlock / moveBlock / duplicateBlock) both read,
+ * alongside each block's `allowChildren` flag, so they can never diverge.
+ */
+type CollectionStructure<TBlocks extends Record<string, AnyBlockDefinition>> = {
+    [K in keyof TBlocks | 'root']?: BlockStructureEntry<keyof TBlocks & string>;
+};
 type SlugConfig = {
     enabled: false;
 } | {
@@ -261,6 +313,15 @@ type CollectionDefinition<TProps extends Record<string, BlockProperty> = Record<
      * regardless of this flag). Any collection can still be a reference target.
      */
     reusableBlock?: boolean;
+    /**
+     * Placement rules keyed by PARENT block name (or `'root'`) — which children
+     * each container may hold, via `accepts` (whitelist) / `excludes` (blacklist)
+     * (see {@link CollectionStructure}). Read by the editor and the server guard
+     * together with each block's `allowChildren` flag. Open by default; block
+     * names are checked at compile time by the field type itself, so a typo is a
+     * compile error at the `defineCollection` call site.
+     */
+    structure?: CollectionStructure<TBlocks>;
 };
 type AnyCollectionDefinition = CollectionDefinition<Record<string, BlockProperty>, Record<string, AnyBlockDefinition>>;
 type CollectionWithName = Omit<AnyCollectionDefinition, 'blocks'> & {

package/dist/plugins/consent/index.d.ts

@@ -226,18 +226,70 @@ type BlockDefinition<TProps extends Record<string, BlockProperty> = Record<strin
     label: string;
     description?: string;
     previewImageUrl?: string;
+    /**
+     * Editor hint: the block-picker category this block is shown under (e.g.
+     * `'Forms'`, `'Layout'`). Purely presentational — the editor groups blocks by
+     * this label; the package never acts on it. Free-form by design; for
+     * consistent, autocompleted group names across blocks, reference a shared
+     * `as const` object (e.g. `group: BLOCK_GROUPS.forms`).
+     */
+    group?: string;
     /** Events this (functional) block can emit — see {@link EventDeclaration}. */
     events?: TEvents;
 } & ({
     allowChildren?: false;
 } | {
     allowChildren: true;
-    allowedChildBlocks?: string[];
 });
 type AnyBlockDefinition = BlockDefinition<Record<string, BlockProperty>, Record<string, EventDeclaration>>;
 type RootDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>> = {
     properties: TProps;
 };
+/**
+ * One PARENT's placement rule inside a collection's {@link CollectionStructure}
+ * — declares which child block types that parent (or the literal `'root'`) may
+ * contain. There are three mutually-exclusive modes, enforced by the type:
+ *
+ * - **open** — `{}` or `{ accepts: '*' }`: holds any block. (Same as having no
+ *   entry at all; `'*'` is just an explicit, readable form.)
+ * - **whitelist** — `{ accepts: ['a', 'b'] }`: holds ONLY `a`/`b`. Fail-closed —
+ *   a block added to the collection later is rejected until listed. `excludes`
+ *   is forbidden here (a concrete `accepts` already says exactly what's allowed).
+ * - **blacklist** — `{ excludes: ['z'] }` (or `{ accepts: '*', excludes: ['z'] }`):
+ *   holds anything EXCEPT `z`. Fail-open — a block added later is accepted.
+ *
+ * Whether a parent accepts children AT ALL is the separate, coarser
+ * `allowChildren` gate on the block (the root always accepts children); these
+ * rules only refine WHICH children an accepting parent may hold.
+ */
+type BlockStructureEntry<TBlockName extends string> = {
+    /** `'*'` = open base (optional, for readability). */
+    accepts?: '*';
+    /** Holds anything except these. */
+    excludes?: readonly TBlockName[];
+} | {
+    /** Holds ONLY these block types. */
+    accepts: readonly TBlockName[];
+    /**
+     * Forbidden alongside a concrete `accepts` list — the list already names
+     * exactly what is allowed, so `excludes` would be ignored.
+     */
+    excludes?: "Remove 'excludes': a concrete 'accepts' list already defines exactly which blocks are allowed. Use accepts: '*' with excludes for an all-except list.";
+};
+/**
+ * Placement rules for a collection, keyed by PARENT block name (or the literal
+ * `'root'` for the top level). Open by default: a parent with no entry holds any
+ * block. The keys and the `accepts` / `excludes` block names autocomplete against
+ * the collection's block names and are checked at compile time by
+ * {@link defineCollection} (the field type alone enforces this — no extra step).
+ *
+ * This is the single source of truth that the visual editor (drop-zone gating)
+ * and the server guard (createBlock / moveBlock / duplicateBlock) both read,
+ * alongside each block's `allowChildren` flag, so they can never diverge.
+ */
+type CollectionStructure<TBlocks extends Record<string, AnyBlockDefinition>> = {
+    [K in keyof TBlocks | 'root']?: BlockStructureEntry<keyof TBlocks & string>;
+};
 type SlugConfig = {
     enabled: false;
 } | {
@@ -261,6 +313,15 @@ type CollectionDefinition<TProps extends Record<string, BlockProperty> = Record<
      * regardless of this flag). Any collection can still be a reference target.
      */
     reusableBlock?: boolean;
+    /**
+     * Placement rules keyed by PARENT block name (or `'root'`) — which children
+     * each container may hold, via `accepts` (whitelist) / `excludes` (blacklist)
+     * (see {@link CollectionStructure}). Read by the editor and the server guard
+     * together with each block's `allowChildren` flag. Open by default; block
+     * names are checked at compile time by the field type itself, so a typo is a
+     * compile error at the `defineCollection` call site.
+     */
+    structure?: CollectionStructure<TBlocks>;
 };
 type AnyCollectionDefinition = CollectionDefinition<Record<string, BlockProperty>, Record<string, AnyBlockDefinition>>;
 type CollectionWithName = Omit<AnyCollectionDefinition, 'blocks'> & {

package/dist/plugins/i18n/index.cjs

@@ -950,6 +950,10 @@ const CMS_ERRORS = {
         status: 404,
         message: 'Parent block not found'
     },
+    BLOCK_NOT_ALLOWED_IN_PARENT: {
+        status: 400,
+        message: 'This block type is not allowed inside the target parent'
+    },
     ROOT_NOT_FOUND: {
         status: 404,
         message: 'Root block not found in snapshot'

package/dist/plugins/i18n/index.d.cts

@@ -227,18 +227,70 @@ type BlockDefinition<TProps extends Record<string, BlockProperty> = Record<strin
     label: string;
     description?: string;
     previewImageUrl?: string;
+    /**
+     * Editor hint: the block-picker category this block is shown under (e.g.
+     * `'Forms'`, `'Layout'`). Purely presentational — the editor groups blocks by
+     * this label; the package never acts on it. Free-form by design; for
+     * consistent, autocompleted group names across blocks, reference a shared
+     * `as const` object (e.g. `group: BLOCK_GROUPS.forms`).
+     */
+    group?: string;
     /** Events this (functional) block can emit — see {@link EventDeclaration}. */
     events?: TEvents;
 } & ({
     allowChildren?: false;
 } | {
     allowChildren: true;
-    allowedChildBlocks?: string[];
 });
 type AnyBlockDefinition = BlockDefinition<Record<string, BlockProperty>, Record<string, EventDeclaration>>;
 type RootDefinition<TProps extends Record<string, BlockProperty> = Record<string, BlockProperty>> = {
     properties: TProps;
 };
+/**
+ * One PARENT's placement rule inside a collection's {@link CollectionStructure}
+ * — declares which child block types that parent (or the literal `'root'`) may
+ * contain. There are three mutually-exclusive modes, enforced by the type:
+ *
+ * - **open** — `{}` or `{ accepts: '*' }`: holds any block. (Same as having no
+ *   entry at all; `'*'` is just an explicit, readable form.)
+ * - **whitelist** — `{ accepts: ['a', 'b'] }`: holds ONLY `a`/`b`. Fail-closed —
+ *   a block added to the collection later is rejected until listed. `excludes`
+ *   is forbidden here (a concrete `accepts` already says exactly what's allowed).
+ * - **blacklist** — `{ excludes: ['z'] }` (or `{ accepts: '*', excludes: ['z'] }`):
+ *   holds anything EXCEPT `z`. Fail-open — a block added later is accepted.
+ *
+ * Whether a parent accepts children AT ALL is the separate, coarser
+ * `allowChildren` gate on the block (the root always accepts children); these
+ * rules only refine WHICH children an accepting parent may hold.
+ */
+type BlockStructureEntry<TBlockName extends string> = {
+    /** `'*'` = open base (optional, for readability). */
+    accepts?: '*';
+    /** Holds anything except these. */
+    excludes?: readonly TBlockName[];
+} | {
+    /** Holds ONLY these block types. */
+    accepts: readonly TBlockName[];
+    /**
+     * Forbidden alongside a concrete `accepts` list — the list already names
+     * exactly what is allowed, so `excludes` would be ignored.
+     */
+    excludes?: "Remove 'excludes': a concrete 'accepts' list already defines exactly which blocks are allowed. Use accepts: '*' with excludes for an all-except list.";
+};
+/**
+ * Placement rules for a collection, keyed by PARENT block name (or the literal
+ * `'root'` for the top level). Open by default: a parent with no entry holds any
+ * block. The keys and the `accepts` / `excludes` block names autocomplete against
+ * the collection's block names and are checked at compile time by
+ * {@link defineCollection} (the field type alone enforces this — no extra step).
+ *
+ * This is the single source of truth that the visual editor (drop-zone gating)
+ * and the server guard (createBlock / moveBlock / duplicateBlock) both read,
+ * alongside each block's `allowChildren` flag, so they can never diverge.
+ */
+type CollectionStructure<TBlocks extends Record<string, AnyBlockDefinition>> = {
+    [K in keyof TBlocks | 'root']?: BlockStructureEntry<keyof TBlocks & string>;
+};
 type SlugConfig = {
     enabled: false;
 } | {
@@ -262,6 +314,15 @@ type CollectionDefinition<TProps extends Record<string, BlockProperty> = Record<
      * regardless of this flag). Any collection can still be a reference target.
      */
     reusableBlock?: boolean;
+    /**
+     * Placement rules keyed by PARENT block name (or `'root'`) — which children
+     * each container may hold, via `accepts` (whitelist) / `excludes` (blacklist)
+     * (see {@link CollectionStructure}). Read by the editor and the server guard
+     * together with each block's `allowChildren` flag. Open by default; block
+     * names are checked at compile time by the field type itself, so a typo is a
+     * compile error at the `defineCollection` call site.
+     */
+    structure?: CollectionStructure<TBlocks>;
 };
 type AnyCollectionDefinition = CollectionDefinition<Record<string, BlockProperty>, Record<string, AnyBlockDefinition>>;
 type CollectionWithName = Omit<AnyCollectionDefinition, 'blocks'> & {