@createcms/core 0.1.1 → 0.2.1

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

@@ -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'> & {

package/dist/plugins/i18n/index.js

@@ -925,6 +925,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/multi-tenant/index.d.cts

@@ -225,18 +225,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;
 } | {
@@ -260,6 +312,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/multi-tenant/index.d.ts

@@ -225,18 +225,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;
 } | {
@@ -260,6 +312,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/react/blocks.cjs

@@ -52,7 +52,8 @@ function isResolvedReference(value) {
     return {
         __brand: 'BlocksMap',
         _components: components,
-        _events: extractBlockEvents(collection.blocks)
+        _events: extractBlockEvents(collection.blocks),
+        _collection: collection
     };
 }
 // ============================================================================

package/dist/react/blocks.d.cts

@@ -133,18 +133,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;
 } | {
@@ -168,6 +220,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>>;
 
@@ -180,24 +241,33 @@ type BlockComponentProps<TProps extends Record<string, BlockProperty> = Record<s
     blockId: string;
     node: BlockTreeNode;
 };
-/** Shorthand to derive block component props from a collection definition. */
+/** Shorthand to derive block component props from a collection definition.
+ *  `blocks` is optional on `CollectionDefinition`, so the constraint accepts the
+ *  optional shape and `NonNullable` resolves it — passing `typeof myCollection`
+ *  directly works, and `TBlock` autocompletes the collection's block names. */
 type BlockProps<TCollection extends {
-    blocks: Record<string, AnyBlockDefinition>;
-}, TBlock extends keyof TCollection['blocks'] & string> = BlockComponentProps<TCollection['blocks'][TBlock]['properties']>;
+    blocks?: Record<string, AnyBlockDefinition>;
+}, TBlock extends keyof NonNullable<TCollection['blocks']> & string> = BlockComponentProps<NonNullable<TCollection['blocks']>[TBlock]['properties']>;
 type BlockComponentMap<TBlocks extends Record<string, AnyBlockDefinition>> = {
     [K in keyof TBlocks & string]: (props: BlockComponentProps<TBlocks[K]['properties']>) => ReactNode;
 };
 declare function isResolvedReference(value: unknown): value is ResolvedReference;
 /**
  * Opaque handle returned by `createBlocksMap`. Pass it to `<BlocksRenderer>`.
- * Carries the React component map AND the per-block-type event declarations
- * (the runtime half of the M2a typed-events seam) so the renderer can tell a
- * functional block (one that declared `events`) from a presentational one.
+ * Carries the React component map, the per-block-type event declarations (the
+ * runtime half of the M2a typed-events seam, so the renderer can tell a
+ * functional block from a presentational one), AND the collection definition
+ * itself. Bundling the collection means an editor can consume a single object
+ * for both rendering (`_components`) and schema/placement/grouping
+ * (`_collection`) — no separate `collection` handoff. The type parameter is
+ * preserved so that consumption stays typed; it defaults to the erased
+ * `AnyCollectionDefinition` for plain `BlocksMap` annotations.
  */
-type BlocksMap = {
+type BlocksMap<TCollection = AnyCollectionDefinition> = {
     readonly __brand: 'BlocksMap';
     readonly _components: Record<string, (props: any) => ReactNode>;
     readonly _events: Record<string, Record<string, EventDeclaration>>;
+    readonly _collection: TCollection;
 };
 /**
  * Extracts the per-block-type event declarations from a collection definition —
@@ -229,7 +299,7 @@ declare function extractBlockEvents(blocks: Record<string, AnyBlockDefinition> |
  * });
  * ```
  */
-declare function createBlocksMap<TProps extends Record<string, BlockProperty>, TBlocks extends Record<string, AnyBlockDefinition>>(collection: CollectionDefinition<TProps, TBlocks>, components: BlockComponentMap<TBlocks>): BlocksMap;
+declare function createBlocksMap<TProps extends Record<string, BlockProperty>, TBlocks extends Record<string, AnyBlockDefinition>>(collection: CollectionDefinition<TProps, TBlocks>, components: BlockComponentMap<TBlocks>): BlocksMap<CollectionDefinition<TProps, TBlocks>>;
 /**
  * Renders a `BlockTreeNode` tree using a block component map.
  *

package/dist/react/blocks.d.ts

@@ -133,18 +133,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;
 } | {
@@ -168,6 +220,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>>;
 
@@ -180,24 +241,33 @@ type BlockComponentProps<TProps extends Record<string, BlockProperty> = Record<s
     blockId: string;
     node: BlockTreeNode;
 };
-/** Shorthand to derive block component props from a collection definition. */
+/** Shorthand to derive block component props from a collection definition.
+ *  `blocks` is optional on `CollectionDefinition`, so the constraint accepts the
+ *  optional shape and `NonNullable` resolves it — passing `typeof myCollection`
+ *  directly works, and `TBlock` autocompletes the collection's block names. */
 type BlockProps<TCollection extends {
-    blocks: Record<string, AnyBlockDefinition>;
-}, TBlock extends keyof TCollection['blocks'] & string> = BlockComponentProps<TCollection['blocks'][TBlock]['properties']>;
+    blocks?: Record<string, AnyBlockDefinition>;
+}, TBlock extends keyof NonNullable<TCollection['blocks']> & string> = BlockComponentProps<NonNullable<TCollection['blocks']>[TBlock]['properties']>;
 type BlockComponentMap<TBlocks extends Record<string, AnyBlockDefinition>> = {
     [K in keyof TBlocks & string]: (props: BlockComponentProps<TBlocks[K]['properties']>) => ReactNode;
 };
 declare function isResolvedReference(value: unknown): value is ResolvedReference;
 /**
  * Opaque handle returned by `createBlocksMap`. Pass it to `<BlocksRenderer>`.
- * Carries the React component map AND the per-block-type event declarations
- * (the runtime half of the M2a typed-events seam) so the renderer can tell a
- * functional block (one that declared `events`) from a presentational one.
+ * Carries the React component map, the per-block-type event declarations (the
+ * runtime half of the M2a typed-events seam, so the renderer can tell a
+ * functional block from a presentational one), AND the collection definition
+ * itself. Bundling the collection means an editor can consume a single object
+ * for both rendering (`_components`) and schema/placement/grouping
+ * (`_collection`) — no separate `collection` handoff. The type parameter is
+ * preserved so that consumption stays typed; it defaults to the erased
+ * `AnyCollectionDefinition` for plain `BlocksMap` annotations.
  */
-type BlocksMap = {
+type BlocksMap<TCollection = AnyCollectionDefinition> = {
     readonly __brand: 'BlocksMap';
     readonly _components: Record<string, (props: any) => ReactNode>;
     readonly _events: Record<string, Record<string, EventDeclaration>>;
+    readonly _collection: TCollection;
 };
 /**
  * Extracts the per-block-type event declarations from a collection definition —
@@ -229,7 +299,7 @@ declare function extractBlockEvents(blocks: Record<string, AnyBlockDefinition> |
  * });
  * ```
  */
-declare function createBlocksMap<TProps extends Record<string, BlockProperty>, TBlocks extends Record<string, AnyBlockDefinition>>(collection: CollectionDefinition<TProps, TBlocks>, components: BlockComponentMap<TBlocks>): BlocksMap;
+declare function createBlocksMap<TProps extends Record<string, BlockProperty>, TBlocks extends Record<string, AnyBlockDefinition>>(collection: CollectionDefinition<TProps, TBlocks>, components: BlockComponentMap<TBlocks>): BlocksMap<CollectionDefinition<TProps, TBlocks>>;
 /**
  * Renders a `BlockTreeNode` tree using a block component map.
  *

package/dist/react/blocks.js

@@ -50,7 +50,8 @@ function isResolvedReference(value) {
     return {
         __brand: 'BlocksMap',
         _components: components,
-        _events: extractBlockEvents(collection.blocks)
+        _events: extractBlockEvents(collection.blocks),
+        _collection: collection
     };
 }
 // ============================================================================

package/dist/react/index.cjs

@@ -150,6 +150,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'