@createcms/core 0.1.1 → 0.2.1

package/dist/index.cjs

@@ -1076,6 +1076,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'
@@ -4974,6 +4978,88 @@ notFound = 'ROOT_NOT_FOUND') {
     }
 }
 
+/** Builds the {@link PlacementIndex} from a collection's `structure` + blocks. */ function buildPlacementIndex(structure, blocks) {
+    const rules = new Map();
+    if (structure) {
+        for (const [parent, entry] of Object.entries(structure)){
+            if (!entry) continue;
+            const accepts = entry.accepts;
+            if (Array.isArray(accepts)) {
+                // Concrete whitelist (incl. the empty "holds nothing" list).
+                rules.set(parent, {
+                    mode: 'only',
+                    set: new Set(accepts)
+                });
+            } else if (entry.excludes && entry.excludes.length > 0) {
+                // Open base ('*' or omitted) minus an explicit blacklist.
+                rules.set(parent, {
+                    mode: 'except',
+                    set: new Set(entry.excludes)
+                });
+            }
+        // else: open ('*' / nothing, no excludes) — no rule.
+        }
+    }
+    const containers = new Set();
+    if (blocks) {
+        for (const [name, def] of Object.entries(blocks)){
+            if (def.allowChildren === true) containers.add(name);
+        }
+    }
+    return {
+        rules,
+        containers
+    };
+}
+/**
+ * Throws `BLOCK_NOT_ALLOWED_IN_PARENT` when placing a `childType` block under a
+ * `parentType` block would violate the collection's rules. `parentType` must be
+ * the literal `'root'` when the parent is the collection root.
+ *
+ * Two gates, in order:
+ *  1. Container gate — a non-root parent whose `allowChildren` is not `true`
+ *     rejects every child.
+ *  2. Acceptance gate — the parent's `accepts`/`excludes` rule, if any:
+ *     `only` rejects a child not in the set; `except` rejects a child in the set.
+ *
+ * A parent with no rule (open) and the root (always a container) pass gate 1
+ * and/or gate 2 trivially, so collections without a `structure` map only feel
+ * the `allowChildren` gate.
+ */ function assertPlacementAllowed(index, childType, parentType) {
+    if (parentType !== 'root' && !index.containers.has(parentType)) throw new CMSError('BLOCK_NOT_ALLOWED_IN_PARENT', {
+        message: `Block '${parentType}' does not accept child blocks (its 'allowChildren' is not set)`,
+        data: {
+            childType,
+            parentType,
+            reason: 'not-a-container'
+        }
+    });
+    const rule = index.rules.get(parentType);
+    if (!rule) return;
+    if (rule.mode === 'only' && !rule.set.has(childType)) throw new CMSError('BLOCK_NOT_ALLOWED_IN_PARENT', {
+        message: `Block '${parentType}' accepts only [${[
+            ...rule.set
+        ].join(', ')}] — ` + `'${childType}' is not allowed inside it`,
+        data: {
+            childType,
+            parentType,
+            accepts: [
+                ...rule.set
+            ]
+        }
+    });
+    if (rule.mode === 'except' && rule.set.has(childType)) throw new CMSError('BLOCK_NOT_ALLOWED_IN_PARENT', {
+        message: `Block '${childType}' is not allowed inside '${parentType}' (excluded)`,
+        data: {
+            childType,
+            parentType,
+            excludes: [
+                ...rule.set
+            ]
+        }
+    });
+}
+
 function assembleBlockTree(blocks, rootId) {
     const deletedBlockIds = new Set();
     const nodeMap = new Map();
@@ -5568,6 +5654,10 @@ const blockTreeNodeSchema = z__namespace.lazy(()=>z__namespace.object({
 function createBlocksEndpoints(def, cmsCtx) {
     const { db } = cmsCtx;
     const collectionName = def.name;
+    // Derived once per collection: the placement rules the create/move/duplicate
+    // routes enforce — `accepts`/`excludes` from `structure` plus the
+    // `allowChildren` container gate from the block defs.
+    const placementIndex = buildPlacementIndex(def.structure, def.blocks);
     return {
         /**
      * Creates a new root (page/entry) with initial draft branch and commit.
@@ -5940,6 +6030,10 @@ function createBlocksEndpoints(def, cmsCtx) {
                 if (parentVersion.deleted) throw new CMSError('BLOCK_ALREADY_DELETED', {
                     message: errorMessages.blockAlreadyDeleted(parentBlockId)
                 });
+                // Enforce the collection's placement rules. The root block's id equals
+                // the rootId and is stored with `type === collectionName`, so normalize
+                // it to the literal 'root' the structure map keys on.
+                assertPlacementAllowed(placementIndex, type, parentBlockId === rootId ? 'root' : parentVersion.type);
                 const childBlockId = newId('block');
                 const blockProps = properties ?? {};
                 const newChildrenArray = [
@@ -6147,6 +6241,7 @@ function createBlocksEndpoints(def, cmsCtx) {
                     if (newParent.deleted) throw new CMSError('BLOCK_ALREADY_DELETED', {
                         message: errorMessages.blockAlreadyDeleted(input.newParentBlockId)
                     });
+                    assertPlacementAllowed(placementIndex, movedBlock.type, input.newParentBlockId === input.rootId ? 'root' : newParent.type);
                     const oldChildren = (oldParent.children ?? []).filter((id)=>id !== input.blockId);
                     const newChildren = [
                         ...newParent.children ?? []
@@ -6434,6 +6529,7 @@ function createBlocksEndpoints(def, cmsCtx) {
                 if (parentVersion.deleted) throw new CMSError('BLOCK_ALREADY_DELETED', {
                     message: errorMessages.blockAlreadyDeleted(input.targetParentBlockId)
                 });
+                assertPlacementAllowed(placementIndex, sourceVersion.type, input.targetParentBlockId === input.rootId ? 'root' : parentVersion.type);
                 const topLevelCopyId = copies[0].newBlockId;
                 const updatedChildren = [
                     ...parentVersion.children ?? []
@@ -13725,6 +13821,15 @@ function definePluginSchema(schema) {
 /**
  * Defines a content collection with a root block and a set of child blocks.
  *
+ * Blocks may be referenced (`blocks: { hero }`) or written inline
+ * (`blocks: { hero: { label, properties } }`). For the inline form the `blocks`
+ * parameter is shaped as `{ [K in keyof TBlocks]: AnyBlockDefinition } & TBlocks`
+ * — the mapped half gives each block value the concrete `BlockDefinition`
+ * contextual type so editors autocomplete its fields (`label`, `properties`,
+ * `events`, …) instead of falling back to globals, while the `& TBlocks` half
+ * keeps inferring each block's specific shape (so the typed create/update API
+ * and `structure` autocomplete still see the exact block keys and properties).
+ *
  * @example
  * ```ts
  * const pages = defineCollection({

package/dist/index.d.cts

@@ -3856,13 +3856,20 @@ 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>>;
 /** Discriminated union input for creating a block: `{ type: 'paragraph', properties: { text: '...' } }`. */
@@ -4021,6 +4028,51 @@ type ListBranchesResult = {
 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;
 } | {
@@ -4053,6 +4105,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'> & {
@@ -9760,6 +9821,10 @@ declare const CMS_ERRORS: {
         readonly status: 404;
         readonly message: "Parent block not found";
     };
+    readonly BLOCK_NOT_ALLOWED_IN_PARENT: {
+        readonly status: 400;
+        readonly message: "This block type is not allowed inside the target parent";
+    };
     readonly ROOT_NOT_FOUND: {
         readonly status: 404;
         readonly message: "Root block not found in snapshot";
@@ -10220,6 +10285,15 @@ declare function defineRoot<const TProps extends Record<string, BlockProperty>>(
 /**
  * Defines a content collection with a root block and a set of child blocks.
  *
+ * Blocks may be referenced (`blocks: { hero }`) or written inline
+ * (`blocks: { hero: { label, properties } }`). For the inline form the `blocks`
+ * parameter is shaped as `{ [K in keyof TBlocks]: AnyBlockDefinition } & TBlocks`
+ * — the mapped half gives each block value the concrete `BlockDefinition`
+ * contextual type so editors autocomplete its fields (`label`, `properties`,
+ * `events`, …) instead of falling back to globals, while the `& TBlocks` half
+ * keeps inferring each block's specific shape (so the typed create/update API
+ * and `structure` autocomplete still see the exact block keys and properties).
+ *
  * @example
  * ```ts
  * const pages = defineCollection({
@@ -10229,7 +10303,11 @@ declare function defineRoot<const TProps extends Record<string, BlockProperty>>(
  * });
  * ```
  */
-declare function defineCollection<const TProps extends Record<string, BlockProperty>, const TBlocks extends Record<string, AnyBlockDefinition> = Record<string, never>>(collection: CollectionDefinition<TProps, TBlocks>): CollectionDefinition<TProps, TBlocks>;
+declare function defineCollection<const TProps extends Record<string, BlockProperty>, const TBlocks extends Record<string, AnyBlockDefinition> = Record<string, never>>(collection: Omit<CollectionDefinition<TProps, TBlocks>, 'blocks'> & {
+    blocks?: {
+        [K in keyof TBlocks]: AnyBlockDefinition;
+    } & TBlocks;
+}): CollectionDefinition<TProps, TBlocks>;
 type ExtractReferencedCollections<T extends Record<string, AnyCollectionDefinition>> = {
     [K in keyof T]: T[K] extends CollectionDefinition<infer _P, infer TBlocks> ? {
         [B in keyof TBlocks]: TBlocks[B] extends BlockDefinition<infer BProps, any> ? {
@@ -10274,4 +10352,4 @@ declare function defineCollections<const TCollections extends Record<string, Any
 declare function defineAuthMiddleware(middleware: CMSMiddleware): CMSMiddleware;
 
 export { CMSClientError, CMSError, CMS_ERRORS, buildFullPath, cmsContext, cmsMeta, createCMS, createCMSClient, createCMSEndpoint, createCMSQuery, defineAuthMiddleware, defineBlock, defineCollection, defineCollections, defineColumns, defineCoreSchema, definePluginSchema, defineRoot, defineTable, getCMSErrorCode, isCMSError, newId, normalizeSlug, registerIdPrefix, rootRevalidateTag, runPruningPass, splitPath, trackingId };
-export type { AnyBlockDefinition, AnyCollectionDefinition, Approval, Asset, AssetFolder, BlockDefinition, BlockEventFire, BlockEventNames, BlockProperty, BlockPropertyType, BlockTreeNode, BlockVersion, Branch, BranchListItem, CMSAPIError, CMSAfterHook, CMSAfterHookContext, CMSAtomListener, CMSBeforeHook, CMSBeforeHookContext, CMSClientInstance, CMSClientOptions, CMSClientPlugin, CMSClientStore, CMSConfigHooks, CMSCoreRootPruningPlan, CMSDefinition, CMSEndpointContext, CMSEndpointCtx, CMSEndpointKey, CMSEndpointMeta, CMSErrorCode, CMSFetch, CMSHandlerCtx, CMSHookAction, CMSHooks, CMSMiddleware, CMSMiddlewareCtx, CMSMiddlewareRequest, CMSOperation, CMSPlugin, CMSPluginContext, CMSPluginInitOptions, CMSPluginInitResult, CMSPluginPruning, CMSPluginPruningExecuteContext, CMSPluginPruningExecuteResult, CMSPluginPruningMetrics, CMSPluginPruningPlanContext, CMSPluginRootPruningPlan, CMSProcedureCtx, CMSSchemaConfig, CMSSystemHandlerCtx, CMSUserConfig, CollectionDefinition, CollectionWithName, CommentMention, CommentMessage, CommentThread, Commit, CommitSnapshot, ContentUsage, DataRetentionConfig, DrizzleInstance, EnumMap, EventDeclaration, IdPrefix, InferBlockInput, InferBlockProperties, InferBlockTreeNode, InferCreateBlockInput, InferEventParams, InferPartialBlockProperties, InferPluginContext, InferPluginEndpoints, InferPluginErrorCodes, InferUpdateBlockInput, ListBranchesResult, ListMergeRequestsResult, ListNotificationsResult, ListRootsResult, MediaUploadFileState, MediaUploadOptions, MediaUploadState, MergeConflict, MergeRequest, MergeRequestListItem, MiddlewareResult, NewApproval, NewAsset, NewAssetFolder, NewBlockVersion, NewBranch, NewCommentMention, NewCommentMessage, NewCommentThread, NewCommit, NewCommitSnapshot, NewContentUsage, NewMergeConflict, NewMergeRequest, NewNotification, NewPublication, NewRedirect, NewRoot, NewSearchIndex, NewTemplate, NewTemplateVariableUsage, NewVariable, Notification, NotificationInput, NotificationListItem, NotificationPayload, NotificationService, NotificationType, OnNotificationHandler, PruningPassOptions, PruningPassResult, PruningResult, Publication, QueryState, Redirect, ResolvedReference, ResolvedScope, ResolvedSlugConfig, RevalidateConfig, RevalidateEvent, RevalidateHandler, Root, RootDefinition, RootListItem, RootSummary, ScalarBlockProperty, SchemaModule, ScopeConditionFactory, SearchIndex, TableMap, TableScope, Template, TemplateVariableUsage, Variable };
+export type { AnyBlockDefinition, AnyCollectionDefinition, Approval, Asset, AssetFolder, BlockDefinition, BlockEventFire, BlockEventNames, BlockProperty, BlockPropertyType, BlockStructureEntry, BlockTreeNode, BlockVersion, Branch, BranchListItem, CMSAPIError, CMSAfterHook, CMSAfterHookContext, CMSAtomListener, CMSBeforeHook, CMSBeforeHookContext, CMSClientInstance, CMSClientOptions, CMSClientPlugin, CMSClientStore, CMSConfigHooks, CMSCoreRootPruningPlan, CMSDefinition, CMSEndpointContext, CMSEndpointCtx, CMSEndpointKey, CMSEndpointMeta, CMSErrorCode, CMSFetch, CMSHandlerCtx, CMSHookAction, CMSHooks, CMSMiddleware, CMSMiddlewareCtx, CMSMiddlewareRequest, CMSOperation, CMSPlugin, CMSPluginContext, CMSPluginInitOptions, CMSPluginInitResult, CMSPluginPruning, CMSPluginPruningExecuteContext, CMSPluginPruningExecuteResult, CMSPluginPruningMetrics, CMSPluginPruningPlanContext, CMSPluginRootPruningPlan, CMSProcedureCtx, CMSSchemaConfig, CMSSystemHandlerCtx, CMSUserConfig, CollectionDefinition, CollectionStructure, CollectionWithName, CommentMention, CommentMessage, CommentThread, Commit, CommitSnapshot, ContentUsage, DataRetentionConfig, DrizzleInstance, EnumMap, EventDeclaration, IdPrefix, InferBlockInput, InferBlockProperties, InferBlockTreeNode, InferCreateBlockInput, InferEventParams, InferPartialBlockProperties, InferPluginContext, InferPluginEndpoints, InferPluginErrorCodes, InferUpdateBlockInput, ListBranchesResult, ListMergeRequestsResult, ListNotificationsResult, ListRootsResult, MediaUploadFileState, MediaUploadOptions, MediaUploadState, MergeConflict, MergeRequest, MergeRequestListItem, MiddlewareResult, NewApproval, NewAsset, NewAssetFolder, NewBlockVersion, NewBranch, NewCommentMention, NewCommentMessage, NewCommentThread, NewCommit, NewCommitSnapshot, NewContentUsage, NewMergeConflict, NewMergeRequest, NewNotification, NewPublication, NewRedirect, NewRoot, NewSearchIndex, NewTemplate, NewTemplateVariableUsage, NewVariable, Notification, NotificationInput, NotificationListItem, NotificationPayload, NotificationService, NotificationType, OnNotificationHandler, PruningPassOptions, PruningPassResult, PruningResult, Publication, QueryState, Redirect, ResolvedReference, ResolvedScope, ResolvedSlugConfig, RevalidateConfig, RevalidateEvent, RevalidateHandler, Root, RootDefinition, RootListItem, RootSummary, ScalarBlockProperty, SchemaModule, ScopeConditionFactory, SearchIndex, TableMap, TableScope, Template, TemplateVariableUsage, Variable };

package/dist/index.d.ts

@@ -3856,13 +3856,20 @@ 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>>;
 /** Discriminated union input for creating a block: `{ type: 'paragraph', properties: { text: '...' } }`. */
@@ -4021,6 +4028,51 @@ type ListBranchesResult = {
 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;
 } | {
@@ -4053,6 +4105,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'> & {
@@ -9760,6 +9821,10 @@ declare const CMS_ERRORS: {
         readonly status: 404;
         readonly message: "Parent block not found";
     };
+    readonly BLOCK_NOT_ALLOWED_IN_PARENT: {
+        readonly status: 400;
+        readonly message: "This block type is not allowed inside the target parent";
+    };
     readonly ROOT_NOT_FOUND: {
         readonly status: 404;
         readonly message: "Root block not found in snapshot";
@@ -10220,6 +10285,15 @@ declare function defineRoot<const TProps extends Record<string, BlockProperty>>(
 /**
  * Defines a content collection with a root block and a set of child blocks.
  *
+ * Blocks may be referenced (`blocks: { hero }`) or written inline
+ * (`blocks: { hero: { label, properties } }`). For the inline form the `blocks`
+ * parameter is shaped as `{ [K in keyof TBlocks]: AnyBlockDefinition } & TBlocks`
+ * — the mapped half gives each block value the concrete `BlockDefinition`
+ * contextual type so editors autocomplete its fields (`label`, `properties`,
+ * `events`, …) instead of falling back to globals, while the `& TBlocks` half
+ * keeps inferring each block's specific shape (so the typed create/update API
+ * and `structure` autocomplete still see the exact block keys and properties).
+ *
  * @example
  * ```ts
  * const pages = defineCollection({
@@ -10229,7 +10303,11 @@ declare function defineRoot<const TProps extends Record<string, BlockProperty>>(
  * });
  * ```
  */
-declare function defineCollection<const TProps extends Record<string, BlockProperty>, const TBlocks extends Record<string, AnyBlockDefinition> = Record<string, never>>(collection: CollectionDefinition<TProps, TBlocks>): CollectionDefinition<TProps, TBlocks>;
+declare function defineCollection<const TProps extends Record<string, BlockProperty>, const TBlocks extends Record<string, AnyBlockDefinition> = Record<string, never>>(collection: Omit<CollectionDefinition<TProps, TBlocks>, 'blocks'> & {
+    blocks?: {
+        [K in keyof TBlocks]: AnyBlockDefinition;
+    } & TBlocks;
+}): CollectionDefinition<TProps, TBlocks>;
 type ExtractReferencedCollections<T extends Record<string, AnyCollectionDefinition>> = {
     [K in keyof T]: T[K] extends CollectionDefinition<infer _P, infer TBlocks> ? {
         [B in keyof TBlocks]: TBlocks[B] extends BlockDefinition<infer BProps, any> ? {
@@ -10274,4 +10352,4 @@ declare function defineCollections<const TCollections extends Record<string, Any
 declare function defineAuthMiddleware(middleware: CMSMiddleware): CMSMiddleware;
 
 export { CMSClientError, CMSError, CMS_ERRORS, buildFullPath, cmsContext, cmsMeta, createCMS, createCMSClient, createCMSEndpoint, createCMSQuery, defineAuthMiddleware, defineBlock, defineCollection, defineCollections, defineColumns, defineCoreSchema, definePluginSchema, defineRoot, defineTable, getCMSErrorCode, isCMSError, newId, normalizeSlug, registerIdPrefix, rootRevalidateTag, runPruningPass, splitPath, trackingId };
-export type { AnyBlockDefinition, AnyCollectionDefinition, Approval, Asset, AssetFolder, BlockDefinition, BlockEventFire, BlockEventNames, BlockProperty, BlockPropertyType, BlockTreeNode, BlockVersion, Branch, BranchListItem, CMSAPIError, CMSAfterHook, CMSAfterHookContext, CMSAtomListener, CMSBeforeHook, CMSBeforeHookContext, CMSClientInstance, CMSClientOptions, CMSClientPlugin, CMSClientStore, CMSConfigHooks, CMSCoreRootPruningPlan, CMSDefinition, CMSEndpointContext, CMSEndpointCtx, CMSEndpointKey, CMSEndpointMeta, CMSErrorCode, CMSFetch, CMSHandlerCtx, CMSHookAction, CMSHooks, CMSMiddleware, CMSMiddlewareCtx, CMSMiddlewareRequest, CMSOperation, CMSPlugin, CMSPluginContext, CMSPluginInitOptions, CMSPluginInitResult, CMSPluginPruning, CMSPluginPruningExecuteContext, CMSPluginPruningExecuteResult, CMSPluginPruningMetrics, CMSPluginPruningPlanContext, CMSPluginRootPruningPlan, CMSProcedureCtx, CMSSchemaConfig, CMSSystemHandlerCtx, CMSUserConfig, CollectionDefinition, CollectionWithName, CommentMention, CommentMessage, CommentThread, Commit, CommitSnapshot, ContentUsage, DataRetentionConfig, DrizzleInstance, EnumMap, EventDeclaration, IdPrefix, InferBlockInput, InferBlockProperties, InferBlockTreeNode, InferCreateBlockInput, InferEventParams, InferPartialBlockProperties, InferPluginContext, InferPluginEndpoints, InferPluginErrorCodes, InferUpdateBlockInput, ListBranchesResult, ListMergeRequestsResult, ListNotificationsResult, ListRootsResult, MediaUploadFileState, MediaUploadOptions, MediaUploadState, MergeConflict, MergeRequest, MergeRequestListItem, MiddlewareResult, NewApproval, NewAsset, NewAssetFolder, NewBlockVersion, NewBranch, NewCommentMention, NewCommentMessage, NewCommentThread, NewCommit, NewCommitSnapshot, NewContentUsage, NewMergeConflict, NewMergeRequest, NewNotification, NewPublication, NewRedirect, NewRoot, NewSearchIndex, NewTemplate, NewTemplateVariableUsage, NewVariable, Notification, NotificationInput, NotificationListItem, NotificationPayload, NotificationService, NotificationType, OnNotificationHandler, PruningPassOptions, PruningPassResult, PruningResult, Publication, QueryState, Redirect, ResolvedReference, ResolvedScope, ResolvedSlugConfig, RevalidateConfig, RevalidateEvent, RevalidateHandler, Root, RootDefinition, RootListItem, RootSummary, ScalarBlockProperty, SchemaModule, ScopeConditionFactory, SearchIndex, TableMap, TableScope, Template, TemplateVariableUsage, Variable };
+export type { AnyBlockDefinition, AnyCollectionDefinition, Approval, Asset, AssetFolder, BlockDefinition, BlockEventFire, BlockEventNames, BlockProperty, BlockPropertyType, BlockStructureEntry, BlockTreeNode, BlockVersion, Branch, BranchListItem, CMSAPIError, CMSAfterHook, CMSAfterHookContext, CMSAtomListener, CMSBeforeHook, CMSBeforeHookContext, CMSClientInstance, CMSClientOptions, CMSClientPlugin, CMSClientStore, CMSConfigHooks, CMSCoreRootPruningPlan, CMSDefinition, CMSEndpointContext, CMSEndpointCtx, CMSEndpointKey, CMSEndpointMeta, CMSErrorCode, CMSFetch, CMSHandlerCtx, CMSHookAction, CMSHooks, CMSMiddleware, CMSMiddlewareCtx, CMSMiddlewareRequest, CMSOperation, CMSPlugin, CMSPluginContext, CMSPluginInitOptions, CMSPluginInitResult, CMSPluginPruning, CMSPluginPruningExecuteContext, CMSPluginPruningExecuteResult, CMSPluginPruningMetrics, CMSPluginPruningPlanContext, CMSPluginRootPruningPlan, CMSProcedureCtx, CMSSchemaConfig, CMSSystemHandlerCtx, CMSUserConfig, CollectionDefinition, CollectionStructure, CollectionWithName, CommentMention, CommentMessage, CommentThread, Commit, CommitSnapshot, ContentUsage, DataRetentionConfig, DrizzleInstance, EnumMap, EventDeclaration, IdPrefix, InferBlockInput, InferBlockProperties, InferBlockTreeNode, InferCreateBlockInput, InferEventParams, InferPartialBlockProperties, InferPluginContext, InferPluginEndpoints, InferPluginErrorCodes, InferUpdateBlockInput, ListBranchesResult, ListMergeRequestsResult, ListNotificationsResult, ListRootsResult, MediaUploadFileState, MediaUploadOptions, MediaUploadState, MergeConflict, MergeRequest, MergeRequestListItem, MiddlewareResult, NewApproval, NewAsset, NewAssetFolder, NewBlockVersion, NewBranch, NewCommentMention, NewCommentMessage, NewCommentThread, NewCommit, NewCommitSnapshot, NewContentUsage, NewMergeConflict, NewMergeRequest, NewNotification, NewPublication, NewRedirect, NewRoot, NewSearchIndex, NewTemplate, NewTemplateVariableUsage, NewVariable, Notification, NotificationInput, NotificationListItem, NotificationPayload, NotificationService, NotificationType, OnNotificationHandler, PruningPassOptions, PruningPassResult, PruningResult, Publication, QueryState, Redirect, ResolvedReference, ResolvedScope, ResolvedSlugConfig, RevalidateConfig, RevalidateEvent, RevalidateHandler, Root, RootDefinition, RootListItem, RootSummary, ScalarBlockProperty, SchemaModule, ScopeConditionFactory, SearchIndex, TableMap, TableScope, Template, TemplateVariableUsage, Variable };

package/dist/index.js

@@ -1051,6 +1051,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'
@@ -4949,6 +4953,88 @@ notFound = 'ROOT_NOT_FOUND') {
     }
 }
 
+/** Builds the {@link PlacementIndex} from a collection's `structure` + blocks. */ function buildPlacementIndex(structure, blocks) {
+    const rules = new Map();
+    if (structure) {
+        for (const [parent, entry] of Object.entries(structure)){
+            if (!entry) continue;
+            const accepts = entry.accepts;
+            if (Array.isArray(accepts)) {
+                // Concrete whitelist (incl. the empty "holds nothing" list).
+                rules.set(parent, {
+                    mode: 'only',
+                    set: new Set(accepts)
+                });
+            } else if (entry.excludes && entry.excludes.length > 0) {
+                // Open base ('*' or omitted) minus an explicit blacklist.
+                rules.set(parent, {
+                    mode: 'except',
+                    set: new Set(entry.excludes)
+                });
+            }
+        // else: open ('*' / nothing, no excludes) — no rule.
+        }
+    }
+    const containers = new Set();
+    if (blocks) {
+        for (const [name, def] of Object.entries(blocks)){
+            if (def.allowChildren === true) containers.add(name);
+        }
+    }
+    return {
+        rules,
+        containers
+    };
+}
+/**
+ * Throws `BLOCK_NOT_ALLOWED_IN_PARENT` when placing a `childType` block under a
+ * `parentType` block would violate the collection's rules. `parentType` must be
+ * the literal `'root'` when the parent is the collection root.
+ *
+ * Two gates, in order:
+ *  1. Container gate — a non-root parent whose `allowChildren` is not `true`
+ *     rejects every child.
+ *  2. Acceptance gate — the parent's `accepts`/`excludes` rule, if any:
+ *     `only` rejects a child not in the set; `except` rejects a child in the set.
+ *
+ * A parent with no rule (open) and the root (always a container) pass gate 1
+ * and/or gate 2 trivially, so collections without a `structure` map only feel
+ * the `allowChildren` gate.
+ */ function assertPlacementAllowed(index, childType, parentType) {
+    if (parentType !== 'root' && !index.containers.has(parentType)) throw new CMSError('BLOCK_NOT_ALLOWED_IN_PARENT', {
+        message: `Block '${parentType}' does not accept child blocks (its 'allowChildren' is not set)`,
+        data: {
+            childType,
+            parentType,
+            reason: 'not-a-container'
+        }
+    });
+    const rule = index.rules.get(parentType);
+    if (!rule) return;
+    if (rule.mode === 'only' && !rule.set.has(childType)) throw new CMSError('BLOCK_NOT_ALLOWED_IN_PARENT', {
+        message: `Block '${parentType}' accepts only [${[
+            ...rule.set
+        ].join(', ')}] — ` + `'${childType}' is not allowed inside it`,
+        data: {
+            childType,
+            parentType,
+            accepts: [
+                ...rule.set
+            ]
+        }
+    });
+    if (rule.mode === 'except' && rule.set.has(childType)) throw new CMSError('BLOCK_NOT_ALLOWED_IN_PARENT', {
+        message: `Block '${childType}' is not allowed inside '${parentType}' (excluded)`,
+        data: {
+            childType,
+            parentType,
+            excludes: [
+                ...rule.set
+            ]
+        }
+    });
+}
+
 function assembleBlockTree(blocks, rootId) {
     const deletedBlockIds = new Set();
     const nodeMap = new Map();
@@ -5543,6 +5629,10 @@ const blockTreeNodeSchema = z.lazy(()=>z.object({
 function createBlocksEndpoints(def, cmsCtx) {
     const { db } = cmsCtx;
     const collectionName = def.name;
+    // Derived once per collection: the placement rules the create/move/duplicate
+    // routes enforce — `accepts`/`excludes` from `structure` plus the
+    // `allowChildren` container gate from the block defs.
+    const placementIndex = buildPlacementIndex(def.structure, def.blocks);
     return {
         /**
      * Creates a new root (page/entry) with initial draft branch and commit.
@@ -5915,6 +6005,10 @@ function createBlocksEndpoints(def, cmsCtx) {
                 if (parentVersion.deleted) throw new CMSError('BLOCK_ALREADY_DELETED', {
                     message: errorMessages.blockAlreadyDeleted(parentBlockId)
                 });
+                // Enforce the collection's placement rules. The root block's id equals
+                // the rootId and is stored with `type === collectionName`, so normalize
+                // it to the literal 'root' the structure map keys on.
+                assertPlacementAllowed(placementIndex, type, parentBlockId === rootId ? 'root' : parentVersion.type);
                 const childBlockId = newId('block');
                 const blockProps = properties ?? {};
                 const newChildrenArray = [
@@ -6122,6 +6216,7 @@ function createBlocksEndpoints(def, cmsCtx) {
                     if (newParent.deleted) throw new CMSError('BLOCK_ALREADY_DELETED', {
                         message: errorMessages.blockAlreadyDeleted(input.newParentBlockId)
                     });
+                    assertPlacementAllowed(placementIndex, movedBlock.type, input.newParentBlockId === input.rootId ? 'root' : newParent.type);
                     const oldChildren = (oldParent.children ?? []).filter((id)=>id !== input.blockId);
                     const newChildren = [
                         ...newParent.children ?? []
@@ -6409,6 +6504,7 @@ function createBlocksEndpoints(def, cmsCtx) {
                 if (parentVersion.deleted) throw new CMSError('BLOCK_ALREADY_DELETED', {
                     message: errorMessages.blockAlreadyDeleted(input.targetParentBlockId)
                 });
+                assertPlacementAllowed(placementIndex, sourceVersion.type, input.targetParentBlockId === input.rootId ? 'root' : parentVersion.type);
                 const topLevelCopyId = copies[0].newBlockId;
                 const updatedChildren = [
                     ...parentVersion.children ?? []
@@ -13700,6 +13796,15 @@ function definePluginSchema(schema) {
 /**
  * Defines a content collection with a root block and a set of child blocks.
  *
+ * Blocks may be referenced (`blocks: { hero }`) or written inline
+ * (`blocks: { hero: { label, properties } }`). For the inline form the `blocks`
+ * parameter is shaped as `{ [K in keyof TBlocks]: AnyBlockDefinition } & TBlocks`
+ * — the mapped half gives each block value the concrete `BlockDefinition`
+ * contextual type so editors autocomplete its fields (`label`, `properties`,
+ * `events`, …) instead of falling back to globals, while the `& TBlocks` half
+ * keeps inferring each block's specific shape (so the typed create/update API
+ * and `structure` autocomplete still see the exact block keys and properties).
+ *
  * @example
  * ```ts
  * const pages = defineCollection({