From 9aabb3a21da6832ac3134bc2515b5d37e0aeae22 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 31 Aug 2026 11:38:55 +0000
Subject: [PATCH 01/15] cms-api: Add createDamVideoBlock factory

The DamVideoBlock always stores everything it has (autoplay, loop, show
controls, preview image), even for sites that don't use any of it. The
Admin already has a createDamVideoBlock factory that hides unsupported
options from the editor, but they stay part of the block's data and of
the generated types.

Add the API counterpart: options left out of `supports` are part of
neither the block's data nor its input, so they don't show up in
blocks.generated.ts and aren't stored, even when the Admin still submits
them. DamVideoBlock is now created from the factory with both options
supported and still exported next to it, so this is non-breaking. Since
it occupies the block name DamVideo, a block created with the factory
needs a name of its own, which is why the Admin factory gains a `name`
option.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TsAAGJBYo4museJ93voh6i
---
 .changeset/admin-dam-video-block-name.md      |  15 +
 .changeset/api-dam-video-block-factory.md     |  25 ++
 .../2-core-concepts/2-blocks/4-factories.mdx  |  54 +++-
 .../src/blocks/createDamVideoBlock.test.tsx   |   4 +
 .../src/blocks/createDamVideoBlock.tsx        |   8 +-
 .../blocks/video/createDamVideoBlock.test.ts  |  53 ++++
 .../dam/blocks/video/createDamVideoBlock.ts   | 264 ++++++++++++++++++
 .../src/dam/blocks/video/dam-video.block.ts   | 153 +---------
 packages/api/cms-api/src/index.ts             |   1 +
 9 files changed, 415 insertions(+), 162 deletions(-)
 create mode 100644 .changeset/admin-dam-video-block-name.md
 create mode 100644 .changeset/api-dam-video-block-factory.md
 create mode 100644 packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
 create mode 100644 packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts

diff --git a/.changeset/admin-dam-video-block-name.md b/.changeset/admin-dam-video-block-name.md
new file mode 100644
index 00000000000..c5a4d237b30
--- /dev/null
+++ b/.changeset/admin-dam-video-block-name.md
@@ -0,0 +1,15 @@
+---
+"@dextinity/cms-admin": minor
+---
+
+Add `name` option to `createDamVideoBlock`
+
+A `DamVideoBlock` created with a custom `supports` needs a name of its own, because `DamVideo` is taken by the exported `DamVideoBlock`. The name must match the name of the block created with `createDamVideoBlock` in the API.
+
+**Example**
+
+```tsx
+import { createDamVideoBlock } from "@dextinity/cms-admin";
+
+export const TeaserVideoBlock = createDamVideoBlock({ name: "TeaserVideo", supports: [] });
+```
diff --git a/.changeset/api-dam-video-block-factory.md b/.changeset/api-dam-video-block-factory.md
new file mode 100644
index 00000000000..0b1a224e7eb
--- /dev/null
+++ b/.changeset/api-dam-video-block-factory.md
@@ -0,0 +1,25 @@
+---
+"@dextinity/cms-api": minor
+---
+
+Add `createDamVideoBlock` factory
+
+The `DamVideoBlock` always stores everything it has (autoplay, loop, show controls, preview image), even for sites that don't use any of it. `createDamVideoBlock` is the API counterpart of the Admin factory of the same name: pass what the site supports via `supports`, anything left out is part of neither the block's data nor its input, so it doesn't show up in `blocks.generated.ts` and isn't stored.
+
+`supports` takes:
+
+- `"controls"` — autoplay, loop and show controls, offered together
+- `"previewImage"` — the poster image
+
+`DamVideoBlock` is now created from the factory with both supported and still exported next to it, so this is non-breaking. Since it occupies the block name `DamVideo`, a block created with the factory needs a name of its own.
+
+**Example**
+
+```ts
+import { createDamVideoBlock } from "@dextinity/cms-api";
+
+// For a site that only reads the video's URL
+export const TeaserVideoBlock = createDamVideoBlock({ supports: [] }, "TeaserVideo");
+```
+
+Use the same `supports` and the same name for the Admin block.
diff --git a/docs/docs/2-core-concepts/2-blocks/4-factories.mdx b/docs/docs/2-core-concepts/2-blocks/4-factories.mdx
index d4bdcefb037..5d4a7d55763 100644
--- a/docs/docs/2-core-concepts/2-blocks/4-factories.mdx
+++ b/docs/docs/2-core-concepts/2-blocks/4-factories.mdx
@@ -227,30 +227,62 @@ export const FullWidthImageBlock = createCompositeBlock({
 });
 ```
 
-## DamVideoBlock (Admin only)
+## DamVideoBlock
 
 The DamVideoBlock factory creates a block for a video from the DAM.
-Use `supports` to restrict what editors can set besides the video file itself:
+Use `supports` to restrict what the block offers besides the video file itself:
 
 - `"controls"`: The playback options autoplay, loop and show controls.
 - `"previewImage"`: The poster image shown before playback.
 
 Both are supported by default.
-`@dextinity/cms-admin` exports a ready-made `DamVideoBlock` created with those defaults, use the `createDamVideoBlock` factory to change them:
+`@dextinity/cms-api` and `@dextinity/cms-admin` export a ready-made `DamVideoBlock` created with those defaults.
+Use the `createDamVideoBlock` factory when a site doesn't need all of them, for instance an app integration that only reads the video's URL.
 
-```tsx title="DamVideoBlock.tsx"
+Give the block a name of its own — `DamVideo` is taken by the exported `DamVideoBlock` — and use that same name and the same `supports` in both the API and the Admin.
+
+### API
+
+Use the `createDamVideoBlock` factory:
+
+```ts title="teaser-video.block.ts"
+import { createDamVideoBlock } from "@dextinity/cms-api";
+
+// For a site that only reads the video's URL
+export const TeaserVideoBlock = createDamVideoBlock({ supports: [] }, "TeaserVideo");
+```
+
+Unsupported options are part of neither the block's data nor its input, so they don't show up in `blocks.generated.ts` and aren't stored.
+
+### Admin
+
+Use the `createDamVideoBlock` factory:
+
+```tsx title="TeaserVideoBlock.tsx"
 import { createDamVideoBlock } from "@dextinity/cms-admin";
 
-// For a site that renders no poster image
-export const DamVideoBlock = createDamVideoBlock({ supports: ["controls"] });
+export const TeaserVideoBlock = createDamVideoBlock({ name: "TeaserVideo", supports: [] });
 ```
 
-:::note
+Unsupported options are hidden from the editor.
+Their stored values are kept as long as the API block supports them, so widening `supports` later brings them back.
 
-Leaving out an option only hides it from the editor.
-Values that are already stored are kept as they are.
-The preview image in particular stays part of the block's data either way, since the API's child block is non-nullable.
-:::
+### Site
+
+Render the video with the fields the block supports:
+
+```tsx title="TeaserVideoBlock.tsx"
+import { PropsWithData } from "@dextinity/site-nextjs";
+import { TeaserVideoBlockData } from "@src/blocks.generated";
+
+export function TeaserVideoBlock({ data: { damFile } }: PropsWithData<TeaserVideoBlockData>) {
+    if (!damFile) {
+        return null;
+    }
+
+    return <video src={damFile.fileUrl} />;
+}
+```
 
 ## FinalFormBlock (Admin only)
 
diff --git a/packages/admin/cms-admin/src/blocks/createDamVideoBlock.test.tsx b/packages/admin/cms-admin/src/blocks/createDamVideoBlock.test.tsx
index faf626835a2..8473ed36646 100644
--- a/packages/admin/cms-admin/src/blocks/createDamVideoBlock.test.tsx
+++ b/packages/admin/cms-admin/src/blocks/createDamVideoBlock.test.tsx
@@ -7,6 +7,10 @@ describe("createDamVideoBlock", () => {
         expect(createDamVideoBlock().name).toBe("DamVideo");
     });
 
+    it("should allow setting the name", () => {
+        expect(createDamVideoBlock({ name: "TeaserVideo" }).name).toBe("TeaserVideo");
+    });
+
     it("should allow overriding the tags", () => {
         expect(createDamVideoBlock({ tags: ["Movie"] }).tags).toEqual(["Movie"]);
     });
diff --git a/packages/admin/cms-admin/src/blocks/createDamVideoBlock.tsx b/packages/admin/cms-admin/src/blocks/createDamVideoBlock.tsx
index 0e2bd33e290..4d68b6c124d 100644
--- a/packages/admin/cms-admin/src/blocks/createDamVideoBlock.tsx
+++ b/packages/admin/cms-admin/src/blocks/createDamVideoBlock.tsx
@@ -32,6 +32,11 @@ type DamVideoBlockSupports = "controls" | "previewImage";
 const defaultSupports: DamVideoBlockSupports[] = ["controls", "previewImage"];
 
 interface DamVideoBlockFactoryOptions {
+    /**
+     * The block's name. Must match the name of the block created with `createDamVideoBlock` in the API.
+     * @default "DamVideo"
+     */
+    name?: string;
     /**
      * What the editor can set besides the video file itself. Leave out anything the site implementation
      * doesn't use, for instance `["controls"]` for a site that renders no poster image, or `[]` for a site
@@ -47,6 +52,7 @@ interface DamVideoBlockFactoryOptions {
 
 export const createDamVideoBlock = (
     {
+        name = "DamVideo",
         supports = defaultSupports,
         tags = [defineMessage({ id: "dextinity.damVideoBlock.tag.video", defaultMessage: "Video" })],
     }: DamVideoBlockFactoryOptions = {},
@@ -57,7 +63,7 @@ export const createDamVideoBlock = (
     const DamVideoBlock: BlockInterface<DamVideoBlockData, DamVideoBlockState, DamVideoBlockInput> = {
         ...createBlockSkeleton(),
 
-        name: "DamVideo",
+        name,
 
         displayName: <FormattedMessage id="dextinity.blocks.damVideo" defaultMessage="Video (CMS Asset)" />,
 
diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
new file mode 100644
index 00000000000..81b46040717
--- /dev/null
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+
+import { transformToBlockSave } from "../../../blocks/block";
+import { createDamVideoBlock } from "./createDamVideoBlock";
+import { DamVideoBlock } from "./dam-video.block";
+
+const damFileId = "0a3a4f9c-1b19-4f7e-bd0a-8e0b6b1a2c3d";
+
+describe("createDamVideoBlock", () => {
+    it("should support controls and preview image by default", () => {
+        expect(DamVideoBlock.name).toBe("DamVideo");
+        expect(DamVideoBlock.blockMeta.fields.map((field) => field.name)).toEqual(["autoplay", "showControls", "loop", "previewImage", "damFile"]);
+        expect(DamVideoBlock.blockInputMeta.fields.map((field) => field.name)).toEqual([
+            "autoplay",
+            "showControls",
+            "loop",
+            "previewImage",
+            "damFileId",
+        ]);
+    });
+
+    it("should leave out the preview image when it isn't supported", () => {
+        const block = createDamVideoBlock({ supports: ["controls"] }, "VideoWithoutPreviewImage");
+
+        expect(block.blockMeta.fields.map((field) => field.name)).toEqual(["autoplay", "showControls", "loop", "damFile"]);
+        expect(block.blockInputMeta.fields.map((field) => field.name)).toEqual(["autoplay", "showControls", "loop", "damFileId"]);
+    });
+
+    it("should leave out everything but the file when nothing is supported", () => {
+        const block = createDamVideoBlock({ supports: [] }, "FileOnlyVideo");
+
+        expect(block.blockMeta.fields.map((field) => field.name)).toEqual(["damFile"]);
+        expect(block.blockInputMeta.fields.map((field) => field.name)).toEqual(["damFileId"]);
+    });
+
+    it("should store only the supported options", () => {
+        const block = createDamVideoBlock({ supports: [] }, "StoringFileOnlyVideo");
+        const input = block.blockInputFactory({ damFileId, autoplay: true, showControls: true, loop: true, previewImage: {} });
+
+        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, $$version: 1 });
+    });
+
+    it("should store the supported options", () => {
+        const block = createDamVideoBlock({}, "StoringFullVideo");
+        const input = block.blockInputFactory({ damFileId, autoplay: true, previewImage: {} });
+
+        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, autoplay: true, previewImage: {}, $$version: 1 });
+    });
+
+    it("should reject a name that is already registered", () => {
+        expect(() => createDamVideoBlock({ supports: [] })).toThrow(/already registered/);
+    });
+});
diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
new file mode 100644
index 00000000000..6beef1c23f3
--- /dev/null
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
@@ -0,0 +1,264 @@
+import { IsBoolean, IsOptional, IsUUID } from "class-validator";
+
+import {
+    type Block,
+    BlockData,
+    type BlockDataInterface,
+    type BlockIndexData,
+    BlockInput,
+    type BlockMetaField,
+    BlockMetaFieldKind,
+    createBlock,
+    type ExtractBlockInput,
+    getRegisteredBlocks,
+    type SimpleBlockInputInterface,
+} from "../../../blocks/block";
+import { ChildBlock } from "../../../blocks/decorators/child-block";
+import { ChildBlockInput } from "../../../blocks/decorators/child-block-input";
+import { AnnotationBlockMeta, BlockField } from "../../../blocks/decorators/field";
+import { typeSafeBlockMigrationPipe } from "../../../blocks/migrations/typeSafeBlockMigrationPipe";
+import { DamFileAiContentType } from "../../files/entities/ai-content-type.enum";
+import { FILE_ENTITY } from "../../files/entities/file.entity";
+import { PixelImageBlock } from "../pixel-image.block";
+import { DamVideoBlockTransformerService } from "./dam-video-block-transformer.service";
+import { AddPreviewImageMigration } from "./migrations/1-add-preview-image.migration";
+
+/**
+ * What the block stores besides the video file itself:
+ * - `"controls"` — the playback options autoplay, loop and show controls. Bundled because autoplay and
+ *   show controls depend on each other (a video with neither can't be played), so they're all offered or none.
+ * - `"previewImage"` — the poster image shown before playback.
+ */
+export type DamVideoBlockSupports = "controls" | "previewImage";
+
+const defaultSupports: DamVideoBlockSupports[] = ["controls", "previewImage"];
+
+interface CreateDamVideoBlockOptions {
+    /**
+     * What the block stores besides the video file itself. Leave out anything the site implementation
+     * doesn't use, for instance `["controls"]` for a site that renders no poster image, or `[]` for a site
+     * that only reads the file's URL. Anything left out is neither part of the block's data nor of its input.
+     * @default ["controls", "previewImage"]
+     */
+    supports?: DamVideoBlockSupports[];
+}
+
+export interface DamVideoBlockDataInterface extends BlockDataInterface {
+    damFileId?: string;
+    autoplay?: boolean;
+    showControls?: boolean;
+    loop?: boolean;
+    previewImage?: BlockDataInterface;
+}
+
+export interface DamVideoBlockInputInterface extends SimpleBlockInputInterface {
+    damFileId?: string;
+    autoplay?: boolean;
+    showControls?: boolean;
+    loop?: boolean;
+    previewImage?: ExtractBlockInput<typeof PixelImageBlock>;
+}
+
+export function createDamVideoBlock(
+    { supports = defaultSupports }: CreateDamVideoBlockOptions = {},
+    name = "DamVideo",
+): Block<BlockDataInterface, DamVideoBlockInputInterface> {
+    if (getRegisteredBlocks().some((block) => block.name === name)) {
+        throw new Error(
+            `A block named "${name}" is already registered. @dextinity/cms-api exports a ready-made DamVideoBlock, so a block created with createDamVideoBlock needs its own name, for instance createDamVideoBlock({ supports: [] }, "TeaserVideo").`,
+        );
+    }
+
+    const supportsControls = supports.includes("controls");
+    const supportsPreviewImage = supports.includes("previewImage");
+
+    class DamVideoBlockData extends BlockData {
+        damFileId?: string;
+
+        autoplay?: boolean;
+
+        showControls?: boolean;
+
+        loop?: boolean;
+
+        previewImage?: BlockDataInterface;
+
+        async transformToPlain() {
+            return DamVideoBlockTransformerService;
+        }
+
+        indexData(): BlockIndexData {
+            if (this.damFileId === undefined) {
+                return {};
+            }
+
+            return {
+                dependencies: [
+                    {
+                        targetEntityName: FILE_ENTITY,
+                        id: this.damFileId,
+                    },
+                ],
+            };
+        }
+    }
+
+    class DamVideoBlockInput extends BlockInput {
+        damFileId?: string;
+
+        autoplay?: boolean;
+
+        showControls?: boolean;
+
+        loop?: boolean;
+
+        previewImage?: ExtractBlockInput<typeof PixelImageBlock>;
+
+        // Built by hand instead of via `blockInputToData` so that unsupported options are not stored,
+        // even when the admin still submits them because it is configured with a wider `supports`.
+        transformToBlockData(): BlockDataInterface {
+            const data = new DamVideoBlockData();
+
+            data.damFileId = this.damFileId;
+
+            if (supportsControls) {
+                data.autoplay = this.autoplay;
+                data.showControls = this.showControls;
+                data.loop = this.loop;
+            }
+
+            if (supportsPreviewImage) {
+                data.previewImage = this.previewImage?.transformToBlockData();
+            }
+
+            return data;
+        }
+    }
+
+    // The decorators are applied by hand because which fields exist depends on `supports`.
+    // Their order defines the order of the fields in the block meta, so keep data and input in sync.
+    if (supportsControls) {
+        for (const field of ["autoplay", "showControls", "loop"] as const) {
+            BlockField({ type: "boolean", nullable: true })(DamVideoBlockData.prototype, field);
+
+            IsBoolean()(DamVideoBlockInput.prototype, field);
+            IsOptional()(DamVideoBlockInput.prototype, field);
+            BlockField({ type: "boolean", nullable: true })(DamVideoBlockInput.prototype, field);
+        }
+    }
+
+    if (supportsPreviewImage) {
+        ChildBlock(PixelImageBlock)(DamVideoBlockData.prototype, "previewImage");
+        ChildBlockInput(PixelImageBlock)(DamVideoBlockInput.prototype, "previewImage");
+    }
+
+    IsUUID()(DamVideoBlockInput.prototype, "damFileId");
+    IsOptional()(DamVideoBlockInput.prototype, "damFileId");
+    BlockField({ type: "string", nullable: true })(DamVideoBlockInput.prototype, "damFileId");
+
+    class Meta extends AnnotationBlockMeta {
+        get fields(): BlockMetaField[] {
+            return [
+                ...super.fields,
+                {
+                    name: "damFile",
+                    kind: BlockMetaFieldKind.NestedObject,
+                    nullable: true,
+                    object: {
+                        fields: [
+                            {
+                                name: "id",
+                                kind: BlockMetaFieldKind.String,
+                                nullable: false,
+                            },
+                            {
+                                name: "name",
+                                kind: BlockMetaFieldKind.String,
+                                nullable: false,
+                            },
+                            {
+                                name: "size",
+                                kind: BlockMetaFieldKind.Number,
+                                nullable: false,
+                            },
+                            {
+                                name: "mimetype",
+                                kind: BlockMetaFieldKind.String,
+                                nullable: false,
+                            },
+                            {
+                                name: "contentHash",
+                                kind: BlockMetaFieldKind.String,
+                                nullable: false,
+                            },
+                            {
+                                name: "title",
+                                kind: BlockMetaFieldKind.String,
+                                nullable: true,
+                            },
+                            {
+                                name: "altText",
+                                kind: BlockMetaFieldKind.String,
+                                nullable: true,
+                            },
+                            {
+                                name: "aiContentType",
+                                kind: BlockMetaFieldKind.Enum,
+                                enum: Object.values(DamFileAiContentType),
+                                nullable: true,
+                            },
+                            {
+                                name: "archived",
+                                kind: BlockMetaFieldKind.Boolean,
+                                nullable: false,
+                            },
+                            {
+                                name: "scope",
+                                kind: BlockMetaFieldKind.Json,
+                                nullable: true,
+                            },
+                            {
+                                name: "fileUrl",
+                                kind: BlockMetaFieldKind.String,
+                                nullable: false,
+                            },
+                            {
+                                name: "captions",
+                                kind: BlockMetaFieldKind.NestedObjectList,
+                                nullable: true,
+                                object: {
+                                    fields: [
+                                        {
+                                            name: "id",
+                                            kind: BlockMetaFieldKind.String,
+                                            nullable: false,
+                                        },
+                                        {
+                                            name: "language",
+                                            kind: BlockMetaFieldKind.String,
+                                            nullable: false,
+                                        },
+                                        {
+                                            name: "fileUrl",
+                                            kind: BlockMetaFieldKind.String,
+                                            nullable: false,
+                                        },
+                                    ],
+                                },
+                            },
+                        ],
+                    },
+                },
+            ];
+        }
+    }
+
+    return createBlock(DamVideoBlockData, DamVideoBlockInput, {
+        name,
+        blockMeta: new Meta(DamVideoBlockData),
+        migrate: {
+            version: 1,
+            migrations: typeSafeBlockMigrationPipe([AddPreviewImageMigration]),
+        },
+    });
+}
diff --git a/packages/api/cms-api/src/dam/blocks/video/dam-video.block.ts b/packages/api/cms-api/src/dam/blocks/video/dam-video.block.ts
index 37c6828104f..76de7c37f42 100644
--- a/packages/api/cms-api/src/dam/blocks/video/dam-video.block.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/dam-video.block.ts
@@ -1,152 +1,5 @@
-import { IsOptional, IsUUID } from "class-validator";
+import { createDamVideoBlock } from "./createDamVideoBlock";
 
-import { BaseVideoBlockData, BaseVideoBlockInput } from "../../../blocks/base-video-block";
-import { BlockDataInterface, BlockIndexData, blockInputToData, BlockMetaField, BlockMetaFieldKind, createBlock } from "../../../blocks/block";
-import { AnnotationBlockMeta, BlockField } from "../../../blocks/decorators/field";
-import { typeSafeBlockMigrationPipe } from "../../../blocks/migrations/typeSafeBlockMigrationPipe";
-import { DamFileAiContentType } from "../../files/entities/ai-content-type.enum";
-import { FILE_ENTITY } from "../../files/entities/file.entity";
-import { DamVideoBlockTransformerService } from "./dam-video-block-transformer.service";
-import { AddPreviewImageMigration } from "./migrations/1-add-preview-image.migration";
+export const DamVideoBlock = createDamVideoBlock();
 
-class DamVideoBlockData extends BaseVideoBlockData {
-    damFileId?: string;
-
-    async transformToPlain() {
-        return DamVideoBlockTransformerService;
-    }
-
-    indexData(): BlockIndexData {
-        if (this.damFileId === undefined) {
-            return {};
-        }
-
-        return {
-            dependencies: [
-                {
-                    targetEntityName: FILE_ENTITY,
-                    id: this.damFileId,
-                },
-            ],
-        };
-    }
-}
-
-class DamVideoBlockInput extends BaseVideoBlockInput {
-    @BlockField({ nullable: true })
-    @IsUUID()
-    @IsOptional()
-    damFileId?: string;
-
-    transformToBlockData(): BlockDataInterface {
-        return blockInputToData(DamVideoBlockData, this);
-    }
-}
-
-class Meta extends AnnotationBlockMeta {
-    get fields(): BlockMetaField[] {
-        return [
-            ...super.fields,
-            {
-                name: "damFile",
-                kind: BlockMetaFieldKind.NestedObject,
-                nullable: true,
-                object: {
-                    fields: [
-                        {
-                            name: "id",
-                            kind: BlockMetaFieldKind.String,
-                            nullable: false,
-                        },
-                        {
-                            name: "name",
-                            kind: BlockMetaFieldKind.String,
-                            nullable: false,
-                        },
-                        {
-                            name: "size",
-                            kind: BlockMetaFieldKind.Number,
-                            nullable: false,
-                        },
-                        {
-                            name: "mimetype",
-                            kind: BlockMetaFieldKind.String,
-                            nullable: false,
-                        },
-                        {
-                            name: "contentHash",
-                            kind: BlockMetaFieldKind.String,
-                            nullable: false,
-                        },
-                        {
-                            name: "title",
-                            kind: BlockMetaFieldKind.String,
-                            nullable: true,
-                        },
-                        {
-                            name: "altText",
-                            kind: BlockMetaFieldKind.String,
-                            nullable: true,
-                        },
-                        {
-                            name: "aiContentType",
-                            kind: BlockMetaFieldKind.Enum,
-                            enum: Object.values(DamFileAiContentType),
-                            nullable: true,
-                        },
-                        {
-                            name: "archived",
-                            kind: BlockMetaFieldKind.Boolean,
-                            nullable: false,
-                        },
-                        {
-                            name: "scope",
-                            kind: BlockMetaFieldKind.Json,
-                            nullable: true,
-                        },
-                        {
-                            name: "fileUrl",
-                            kind: BlockMetaFieldKind.String,
-                            nullable: false,
-                        },
-                        {
-                            name: "captions",
-                            kind: BlockMetaFieldKind.NestedObjectList,
-                            nullable: true,
-                            object: {
-                                fields: [
-                                    {
-                                        name: "id",
-                                        kind: BlockMetaFieldKind.String,
-                                        nullable: false,
-                                    },
-                                    {
-                                        name: "language",
-                                        kind: BlockMetaFieldKind.String,
-                                        nullable: false,
-                                    },
-                                    {
-                                        name: "fileUrl",
-                                        kind: BlockMetaFieldKind.String,
-                                        nullable: false,
-                                    },
-                                ],
-                            },
-                        },
-                    ],
-                },
-            },
-        ];
-    }
-}
-
-export const DamVideoBlock = createBlock(DamVideoBlockData, DamVideoBlockInput, {
-    name: "DamVideo",
-    blockMeta: new Meta(DamVideoBlockData),
-    migrate: {
-        version: 1,
-        migrations: typeSafeBlockMigrationPipe([AddPreviewImageMigration]),
-    },
-});
-
-export type { DamVideoBlockData };
+export type { DamVideoBlockDataInterface as DamVideoBlockData } from "./createDamVideoBlock";
diff --git a/packages/api/cms-api/src/index.ts b/packages/api/cms-api/src/index.ts
index f47f689d8f7..6751eb42bbf 100644
--- a/packages/api/cms-api/src/index.ts
+++ b/packages/api/cms-api/src/index.ts
@@ -177,6 +177,7 @@ export { DamFileDownloadLinkBlock } from "./dam/blocks/dam-file-download-link.bl
 export { DamImageBlock } from "./dam/blocks/dam-image.block";
 export { PixelImageBlock } from "./dam/blocks/pixel-image.block";
 export { SvgImageBlock } from "./dam/blocks/svg-image.block";
+export { createDamVideoBlock, type DamVideoBlockSupports } from "./dam/blocks/video/createDamVideoBlock";
 export { DamVideoBlock } from "./dam/blocks/video/dam-video.block";
 export { DextinityImageResolutionException } from "./dam/common/errors/image-resolution.exception";
 export { damDefaultAcceptedMimetypes } from "./dam/common/mimeTypes/dam-default-accepted-mimetypes";

From c732e6532a8b5ba1e8c988c3245b5fe0232481ce Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 31 Aug 2026 11:56:41 +0000
Subject: [PATCH 02/15] cms-api: Keep the DamVideo block input type out of the
 public API

knip reported DamVideoBlockInputInterface as an unused export. It only
needs to be visible to the declaration emit of the module that creates
DamVideoBlock, so move that block into the factory's own module and drop
the export. dam-video.block.ts held nothing else.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TsAAGJBYo4museJ93voh6i
---
 .../src/dam/blocks/video/createDamVideoBlock.test.ts        | 3 +--
 .../api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts | 4 +++-
 .../dam/blocks/video/dam-video-block-transformer.service.ts | 6 +++---
 .../api/cms-api/src/dam/blocks/video/dam-video.block.ts     | 5 -----
 packages/api/cms-api/src/index.ts                           | 3 +--
 5 files changed, 8 insertions(+), 13 deletions(-)
 delete mode 100644 packages/api/cms-api/src/dam/blocks/video/dam-video.block.ts

diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
index 81b46040717..7cadadfd66a 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
@@ -1,8 +1,7 @@
 import { describe, expect, it } from "vitest";
 
 import { transformToBlockSave } from "../../../blocks/block";
-import { createDamVideoBlock } from "./createDamVideoBlock";
-import { DamVideoBlock } from "./dam-video.block";
+import { createDamVideoBlock, DamVideoBlock } from "./createDamVideoBlock";
 
 const damFileId = "0a3a4f9c-1b19-4f7e-bd0a-8e0b6b1a2c3d";
 
diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
index 6beef1c23f3..0dca00093e2 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
@@ -51,7 +51,7 @@ export interface DamVideoBlockDataInterface extends BlockDataInterface {
     previewImage?: BlockDataInterface;
 }
 
-export interface DamVideoBlockInputInterface extends SimpleBlockInputInterface {
+interface DamVideoBlockInputInterface extends SimpleBlockInputInterface {
     damFileId?: string;
     autoplay?: boolean;
     showControls?: boolean;
@@ -262,3 +262,5 @@ export function createDamVideoBlock(
         },
     });
 }
+
+export const DamVideoBlock = createDamVideoBlock();
diff --git a/packages/api/cms-api/src/dam/blocks/video/dam-video-block-transformer.service.ts b/packages/api/cms-api/src/dam/blocks/video/dam-video-block-transformer.service.ts
index 4afca535338..4528b2ab9c4 100644
--- a/packages/api/cms-api/src/dam/blocks/video/dam-video-block-transformer.service.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/dam-video-block-transformer.service.ts
@@ -4,7 +4,7 @@ import { BlockContext, BlockTransformerServiceInterface, TraversableTransformBlo
 import { DamFileAiContentType } from "../../files/entities/ai-content-type.enum";
 import { FilesService } from "../../files/files.service";
 import { DamScopeInterface } from "../../types";
-import { DamVideoBlockData } from "./dam-video.block";
+import { DamVideoBlockDataInterface } from "./createDamVideoBlock";
 
 type TransformResponse = {
     damFile?: {
@@ -26,10 +26,10 @@ type TransformResponse = {
 };
 
 @Injectable()
-export class DamVideoBlockTransformerService implements BlockTransformerServiceInterface<DamVideoBlockData, TransformResponse> {
+export class DamVideoBlockTransformerService implements BlockTransformerServiceInterface<DamVideoBlockDataInterface, TransformResponse> {
     constructor(private readonly filesService: FilesService) {}
 
-    async transformToPlain(block: DamVideoBlockData, { previewDamUrls }: BlockContext) {
+    async transformToPlain(block: DamVideoBlockDataInterface, { previewDamUrls }: BlockContext) {
         const ret: TraversableTransformBlockResponse = {
             autoplay: block.autoplay,
             loop: block.loop,
diff --git a/packages/api/cms-api/src/dam/blocks/video/dam-video.block.ts b/packages/api/cms-api/src/dam/blocks/video/dam-video.block.ts
deleted file mode 100644
index 76de7c37f42..00000000000
--- a/packages/api/cms-api/src/dam/blocks/video/dam-video.block.ts
+++ /dev/null
@@ -1,5 +0,0 @@
-import { createDamVideoBlock } from "./createDamVideoBlock";
-
-export const DamVideoBlock = createDamVideoBlock();
-
-export type { DamVideoBlockDataInterface as DamVideoBlockData } from "./createDamVideoBlock";
diff --git a/packages/api/cms-api/src/index.ts b/packages/api/cms-api/src/index.ts
index 6751eb42bbf..61aee014e78 100644
--- a/packages/api/cms-api/src/index.ts
+++ b/packages/api/cms-api/src/index.ts
@@ -177,8 +177,7 @@ export { DamFileDownloadLinkBlock } from "./dam/blocks/dam-file-download-link.bl
 export { DamImageBlock } from "./dam/blocks/dam-image.block";
 export { PixelImageBlock } from "./dam/blocks/pixel-image.block";
 export { SvgImageBlock } from "./dam/blocks/svg-image.block";
-export { createDamVideoBlock, type DamVideoBlockSupports } from "./dam/blocks/video/createDamVideoBlock";
-export { DamVideoBlock } from "./dam/blocks/video/dam-video.block";
+export { createDamVideoBlock, DamVideoBlock, type DamVideoBlockSupports } from "./dam/blocks/video/createDamVideoBlock";
 export { DextinityImageResolutionException } from "./dam/common/errors/image-resolution.exception";
 export { damDefaultAcceptedMimetypes } from "./dam/common/mimeTypes/dam-default-accepted-mimetypes";
 export { type DamFileCategory, getDamFileCategory } from "./dam/common/mimeTypes/dam-file-category";

From abb6e6fb3b754d37b8e1665f7ed7ec1364b0953c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 1 Sep 2026 11:46:05 +0000
Subject: [PATCH 03/15] cms-api: Drop the explanatory comments from
 createDamVideoBlock

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TsAAGJBYo4museJ93voh6i
---
 .../api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts   | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
index 0dca00093e2..dcdf600b4f8 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
@@ -114,8 +114,6 @@ export function createDamVideoBlock(
 
         previewImage?: ExtractBlockInput<typeof PixelImageBlock>;
 
-        // Built by hand instead of via `blockInputToData` so that unsupported options are not stored,
-        // even when the admin still submits them because it is configured with a wider `supports`.
         transformToBlockData(): BlockDataInterface {
             const data = new DamVideoBlockData();
 
@@ -135,8 +133,6 @@ export function createDamVideoBlock(
         }
     }
 
-    // The decorators are applied by hand because which fields exist depends on `supports`.
-    // Their order defines the order of the fields in the block meta, so keep data and input in sync.
     if (supportsControls) {
         for (const field of ["autoplay", "showControls", "loop"] as const) {
             BlockField({ type: "boolean", nullable: true })(DamVideoBlockData.prototype, field);

From 0e4a423a0dc2b03c7dffd76f6b5882017b681c45 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 1 Sep 2026 14:36:09 +0000
Subject: [PATCH 04/15] cms-api: Register the preview image migration only for
 the exported DamVideoBlock

The migration only concerns the DamVideoBlock that shipped without a
preview image. A block created with createDamVideoBlock is new, so it has
no data from an earlier version and starts at version 1 with no
migrations to apply - all the more so when it doesn't support a preview
image at all.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XeNQQyTaYeWZpC758e2jrf
---
 .../blocks/video/createDamVideoBlock.test.ts  | 10 ++++++++
 .../dam/blocks/video/createDamVideoBlock.ts   | 24 ++++++++++++++++---
 2 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
index 7cadadfd66a..bfc9096f93b 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
@@ -46,6 +46,16 @@ describe("createDamVideoBlock", () => {
         expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, autoplay: true, previewImage: {}, $$version: 1 });
     });
 
+    it("should add a preview image to data from before the exported block had one", () => {
+        expect(transformToBlockSave(DamVideoBlock.blockDataFactory({ damFileId }))).toEqual({ damFileId, previewImage: {}, $$version: 1 });
+    });
+
+    it("should not migrate data of a block created by the factory", () => {
+        const block = createDamVideoBlock({}, "UnmigratedVideo");
+
+        expect(transformToBlockSave(block.blockDataFactory({ damFileId }))).toEqual({ damFileId, $$version: 1 });
+    });
+
     it("should reject a name that is already registered", () => {
         expect(() => createDamVideoBlock({ supports: [] })).toThrow(/already registered/);
     });
diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
index dcdf600b4f8..5f6a1691bd5 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
@@ -11,6 +11,7 @@ import {
     createBlock,
     type ExtractBlockInput,
     getRegisteredBlocks,
+    type MigrateOptions,
     type SimpleBlockInputInterface,
 } from "../../../blocks/block";
 import { ChildBlock } from "../../../blocks/decorators/child-block";
@@ -60,9 +61,23 @@ interface DamVideoBlockInputInterface extends SimpleBlockInputInterface {
 }
 
 export function createDamVideoBlock(
-    { supports = defaultSupports }: CreateDamVideoBlockOptions = {},
+    options: CreateDamVideoBlockOptions = {},
     name = "DamVideo",
 ): Block<BlockDataInterface, DamVideoBlockInputInterface> {
+    // A block created by the factory has no data from an earlier version, so it starts at version 1 without migrations.
+    return createDamVideoBlockWithMigrations({ ...options, name, migrations: [] });
+}
+
+interface CreateDamVideoBlockWithMigrationsOptions extends CreateDamVideoBlockOptions {
+    name: string;
+    migrations: MigrateOptions["migrations"];
+}
+
+function createDamVideoBlockWithMigrations({
+    supports = defaultSupports,
+    name,
+    migrations,
+}: CreateDamVideoBlockWithMigrationsOptions): Block<BlockDataInterface, DamVideoBlockInputInterface> {
     if (getRegisteredBlocks().some((block) => block.name === name)) {
         throw new Error(
             `A block named "${name}" is already registered. @dextinity/cms-api exports a ready-made DamVideoBlock, so a block created with createDamVideoBlock needs its own name, for instance createDamVideoBlock({ supports: [] }, "TeaserVideo").`,
@@ -254,9 +269,12 @@ export function createDamVideoBlock(
         blockMeta: new Meta(DamVideoBlockData),
         migrate: {
             version: 1,
-            migrations: typeSafeBlockMigrationPipe([AddPreviewImageMigration]),
+            migrations,
         },
     });
 }
 
-export const DamVideoBlock = createDamVideoBlock();
+export const DamVideoBlock = createDamVideoBlockWithMigrations({
+    name: "DamVideo",
+    migrations: typeSafeBlockMigrationPipe([AddPreviewImageMigration]),
+});

From dd3d82a4e2b41506362f41bd7b0b56369b2f2d0c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 1 Sep 2026 15:01:26 +0000
Subject: [PATCH 05/15] docs: Say that narrowing DamVideo `supports` keeps
 already stored values

The claim that unsupported options aren't stored only holds for new
content. createBlock builds the block data with plainToInstance, which
keeps every property of the stored data, so values stored while an option
was still supported are loaded and saved again.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XeNQQyTaYeWZpC758e2jrf
---
 .changeset/api-dam-video-block-factory.md          | 3 ++-
 docs/docs/2-core-concepts/2-blocks/4-factories.mdx | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/.changeset/api-dam-video-block-factory.md b/.changeset/api-dam-video-block-factory.md
index 0b1a224e7eb..a4182d1005e 100644
--- a/.changeset/api-dam-video-block-factory.md
+++ b/.changeset/api-dam-video-block-factory.md
@@ -4,7 +4,8 @@
 
 Add `createDamVideoBlock` factory
 
-The `DamVideoBlock` always stores everything it has (autoplay, loop, show controls, preview image), even for sites that don't use any of it. `createDamVideoBlock` is the API counterpart of the Admin factory of the same name: pass what the site supports via `supports`, anything left out is part of neither the block's data nor its input, so it doesn't show up in `blocks.generated.ts` and isn't stored.
+The `DamVideoBlock` always stores everything it has (autoplay, loop, show controls, preview image), even for sites that don't use any of it. `createDamVideoBlock` is the API counterpart of the Admin factory of the same name: pass what the site supports via `supports`, anything left out is part of neither the block's data nor its input, so it doesn't show up in `blocks.generated.ts` and isn't stored for new content.
+Values that were stored before an option was left out are kept and saved again, so narrowing `supports` doesn't remove them from existing content.
 
 `supports` takes:
 
diff --git a/docs/docs/2-core-concepts/2-blocks/4-factories.mdx b/docs/docs/2-core-concepts/2-blocks/4-factories.mdx
index 5d4a7d55763..78363539fb2 100644
--- a/docs/docs/2-core-concepts/2-blocks/4-factories.mdx
+++ b/docs/docs/2-core-concepts/2-blocks/4-factories.mdx
@@ -252,7 +252,8 @@ import { createDamVideoBlock } from "@dextinity/cms-api";
 export const TeaserVideoBlock = createDamVideoBlock({ supports: [] }, "TeaserVideo");
 ```
 
-Unsupported options are part of neither the block's data nor its input, so they don't show up in `blocks.generated.ts` and aren't stored.
+Unsupported options are part of neither the block's data nor its input, so they don't show up in `blocks.generated.ts` and aren't stored for new content.
+Values that were stored before an option was left out are kept: the block loads them and saves them again, so narrowing `supports` doesn't remove them from existing content.
 
 ### Admin
 

From 850d8d15a7726175fa7c07c403fae765110225c7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 1 Sep 2026 15:10:35 +0000
Subject: [PATCH 06/15] cms-api: Declare the DamVideo block fields instead of
 decorating imperatively

Applying the field decorators as function calls was the only place in the
package that did so, and it made the classes hard to read: what a block
has was spread over the class body and three conditional blocks below it,
in an order that mattered because it also determined the field order of
the generated block meta.

Declare all fields on the classes as everywhere else and leave the
unsupported ones out of the block meta instead, which is where `supports`
decides what is generated. The data and input meta of every `supports`
combination stay byte-identical, and so does what the block stores.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XeNQQyTaYeWZpC758e2jrf
---
 .../dam/blocks/video/createDamVideoBlock.ts   | 52 +++++++++++--------
 1 file changed, 30 insertions(+), 22 deletions(-)

diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
index 5f6a1691bd5..d9e42ad92d5 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
@@ -87,15 +87,22 @@ function createDamVideoBlockWithMigrations({
     const supportsControls = supports.includes("controls");
     const supportsPreviewImage = supports.includes("previewImage");
 
+    const unsupportedFields = [...(supportsControls ? [] : ["autoplay", "showControls", "loop"]), ...(supportsPreviewImage ? [] : ["previewImage"])];
+    const isSupported = (field: BlockMetaField) => !unsupportedFields.includes(field.name);
+
     class DamVideoBlockData extends BlockData {
         damFileId?: string;
 
+        @BlockField({ type: "boolean", nullable: true })
         autoplay?: boolean;
 
+        @BlockField({ type: "boolean", nullable: true })
         showControls?: boolean;
 
+        @BlockField({ type: "boolean", nullable: true })
         loop?: boolean;
 
+        @ChildBlock(PixelImageBlock)
         previewImage?: BlockDataInterface;
 
         async transformToPlain() {
@@ -119,16 +126,29 @@ function createDamVideoBlockWithMigrations({
     }
 
     class DamVideoBlockInput extends BlockInput {
-        damFileId?: string;
-
+        @IsBoolean()
+        @IsOptional()
+        @BlockField({ type: "boolean", nullable: true })
         autoplay?: boolean;
 
+        @IsBoolean()
+        @IsOptional()
+        @BlockField({ type: "boolean", nullable: true })
         showControls?: boolean;
 
+        @IsBoolean()
+        @IsOptional()
+        @BlockField({ type: "boolean", nullable: true })
         loop?: boolean;
 
+        @ChildBlockInput(PixelImageBlock)
         previewImage?: ExtractBlockInput<typeof PixelImageBlock>;
 
+        @IsUUID()
+        @IsOptional()
+        @BlockField({ type: "string", nullable: true })
+        damFileId?: string;
+
         transformToBlockData(): BlockDataInterface {
             const data = new DamVideoBlockData();
 
@@ -148,29 +168,10 @@ function createDamVideoBlockWithMigrations({
         }
     }
 
-    if (supportsControls) {
-        for (const field of ["autoplay", "showControls", "loop"] as const) {
-            BlockField({ type: "boolean", nullable: true })(DamVideoBlockData.prototype, field);
-
-            IsBoolean()(DamVideoBlockInput.prototype, field);
-            IsOptional()(DamVideoBlockInput.prototype, field);
-            BlockField({ type: "boolean", nullable: true })(DamVideoBlockInput.prototype, field);
-        }
-    }
-
-    if (supportsPreviewImage) {
-        ChildBlock(PixelImageBlock)(DamVideoBlockData.prototype, "previewImage");
-        ChildBlockInput(PixelImageBlock)(DamVideoBlockInput.prototype, "previewImage");
-    }
-
-    IsUUID()(DamVideoBlockInput.prototype, "damFileId");
-    IsOptional()(DamVideoBlockInput.prototype, "damFileId");
-    BlockField({ type: "string", nullable: true })(DamVideoBlockInput.prototype, "damFileId");
-
     class Meta extends AnnotationBlockMeta {
         get fields(): BlockMetaField[] {
             return [
-                ...super.fields,
+                ...super.fields.filter(isSupported),
                 {
                     name: "damFile",
                     kind: BlockMetaFieldKind.NestedObject,
@@ -264,9 +265,16 @@ function createDamVideoBlockWithMigrations({
         }
     }
 
+    class InputMeta extends AnnotationBlockMeta {
+        get fields(): BlockMetaField[] {
+            return super.fields.filter(isSupported);
+        }
+    }
+
     return createBlock(DamVideoBlockData, DamVideoBlockInput, {
         name,
         blockMeta: new Meta(DamVideoBlockData),
+        blockInputMeta: new InputMeta(DamVideoBlockInput),
         migrate: {
             version: 1,
             migrations,

From f518456d7fbd868c19d54c1f9d2e976502343cf7 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 2 Sep 2026 08:11:05 +0000
Subject: [PATCH 07/15] cms-api: Apply the DamVideo preview image decorators
 only when supported

ChildBlockInput rejects a missing child block, and its @Expose() makes
that transform run even when the input carries no value. Declaring
previewImage unconditionally therefore made blockInputFactory throw for
every block that doesn't support a preview image, so a file-only or
controls-only video could not be created at all.

Apply both child block decorators only when the preview image is
supported, and keep damFileId after them, because the block meta lists
the fields in the order they are applied. The boolean options stay
declared on the classes: they only feed the meta, which leaves them out
when they aren't supported.

Cover input without a preview image in the tests, for a block that
supports the controls and for one that supports nothing but the file.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XeNQQyTaYeWZpC758e2jrf
---
 .../blocks/video/createDamVideoBlock.test.ts   | 14 ++++++++++++++
 .../dam/blocks/video/createDamVideoBlock.ts    | 18 ++++++++++++------
 2 files changed, 26 insertions(+), 6 deletions(-)

diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
index bfc9096f93b..39028cd8795 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
@@ -39,6 +39,20 @@ describe("createDamVideoBlock", () => {
         expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, $$version: 1 });
     });
 
+    it("should create input for a block without a preview image", () => {
+        const block = createDamVideoBlock({ supports: ["controls"] }, "InputWithoutPreviewImage");
+        const input = block.blockInputFactory({ damFileId, autoplay: true });
+
+        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, autoplay: true, $$version: 1 });
+    });
+
+    it("should create input for a block that supports nothing but the file", () => {
+        const block = createDamVideoBlock({ supports: [] }, "InputWithFileOnly");
+        const input = block.blockInputFactory({ damFileId });
+
+        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, $$version: 1 });
+    });
+
     it("should store the supported options", () => {
         const block = createDamVideoBlock({}, "StoringFullVideo");
         const input = block.blockInputFactory({ damFileId, autoplay: true, previewImage: {} });
diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
index d9e42ad92d5..975767bb20e 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
@@ -87,7 +87,7 @@ function createDamVideoBlockWithMigrations({
     const supportsControls = supports.includes("controls");
     const supportsPreviewImage = supports.includes("previewImage");
 
-    const unsupportedFields = [...(supportsControls ? [] : ["autoplay", "showControls", "loop"]), ...(supportsPreviewImage ? [] : ["previewImage"])];
+    const unsupportedFields = supportsControls ? [] : ["autoplay", "showControls", "loop"];
     const isSupported = (field: BlockMetaField) => !unsupportedFields.includes(field.name);
 
     class DamVideoBlockData extends BlockData {
@@ -102,7 +102,6 @@ function createDamVideoBlockWithMigrations({
         @BlockField({ type: "boolean", nullable: true })
         loop?: boolean;
 
-        @ChildBlock(PixelImageBlock)
         previewImage?: BlockDataInterface;
 
         async transformToPlain() {
@@ -141,12 +140,8 @@ function createDamVideoBlockWithMigrations({
         @BlockField({ type: "boolean", nullable: true })
         loop?: boolean;
 
-        @ChildBlockInput(PixelImageBlock)
         previewImage?: ExtractBlockInput<typeof PixelImageBlock>;
 
-        @IsUUID()
-        @IsOptional()
-        @BlockField({ type: "string", nullable: true })
         damFileId?: string;
 
         transformToBlockData(): BlockDataInterface {
@@ -168,6 +163,17 @@ function createDamVideoBlockWithMigrations({
         }
     }
 
+    // The child block decorators reject a missing preview image, so they may only be applied when it is
+    // supported. damFileId follows, because the block meta lists the fields in the order they are applied.
+    if (supportsPreviewImage) {
+        ChildBlock(PixelImageBlock)(DamVideoBlockData.prototype, "previewImage");
+        ChildBlockInput(PixelImageBlock)(DamVideoBlockInput.prototype, "previewImage");
+    }
+
+    IsUUID()(DamVideoBlockInput.prototype, "damFileId");
+    IsOptional()(DamVideoBlockInput.prototype, "damFileId");
+    BlockField({ type: "string", nullable: true })(DamVideoBlockInput.prototype, "damFileId");
+
     class Meta extends AnnotationBlockMeta {
         get fields(): BlockMetaField[] {
             return [

From e0145058207e3b6d7b331d5a0f0296bf1c6141b9 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 2 Sep 2026 08:18:28 +0000
Subject: [PATCH 08/15] cms-api: Add damFileId to the DamVideo block input meta
 like the other DAM blocks

PixelImageBlock and SvgImageBlock don't decorate damFileId at all: their
input meta adds the field, which puts it last without depending on the
order the decorators run in. Follow that here, so the three imperatively
applied decorators can go and only the validators stay on the property.

The two child block decorators remain conditional, since they reject a
missing preview image. Block meta, block input meta and what the block
stores stay identical for every supports combination.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XeNQQyTaYeWZpC758e2jrf
---
 .../dam/blocks/video/createDamVideoBlock.ts    | 18 +++++++++++-------
 1 file changed, 11 insertions(+), 7 deletions(-)

diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
index 975767bb20e..ed304fdc5c8 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
@@ -142,6 +142,8 @@ function createDamVideoBlockWithMigrations({
 
         previewImage?: ExtractBlockInput<typeof PixelImageBlock>;
 
+        @IsOptional()
+        @IsUUID()
         damFileId?: string;
 
         transformToBlockData(): BlockDataInterface {
@@ -163,17 +165,12 @@ function createDamVideoBlockWithMigrations({
         }
     }
 
-    // The child block decorators reject a missing preview image, so they may only be applied when it is
-    // supported. damFileId follows, because the block meta lists the fields in the order they are applied.
+    // The child block decorators reject a missing preview image, so they may only be applied when it is supported.
     if (supportsPreviewImage) {
         ChildBlock(PixelImageBlock)(DamVideoBlockData.prototype, "previewImage");
         ChildBlockInput(PixelImageBlock)(DamVideoBlockInput.prototype, "previewImage");
     }
 
-    IsUUID()(DamVideoBlockInput.prototype, "damFileId");
-    IsOptional()(DamVideoBlockInput.prototype, "damFileId");
-    BlockField({ type: "string", nullable: true })(DamVideoBlockInput.prototype, "damFileId");
-
     class Meta extends AnnotationBlockMeta {
         get fields(): BlockMetaField[] {
             return [
@@ -273,7 +270,14 @@ function createDamVideoBlockWithMigrations({
 
     class InputMeta extends AnnotationBlockMeta {
         get fields(): BlockMetaField[] {
-            return super.fields.filter(isSupported);
+            return [
+                ...super.fields.filter(isSupported),
+                {
+                    name: "damFileId",
+                    kind: BlockMetaFieldKind.String,
+                    nullable: true,
+                },
+            ];
         }
     }
 

From 98f422750f918ab2711ed7804f00623d8dd7dffb Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 2 Sep 2026 08:20:54 +0000
Subject: [PATCH 09/15] cms-admin: Correct what the Admin `supports` says about
 stored values

The Admin factory promised that the preview image is part of the block's
data in any case, which only holds for the DamVideoBlock the API exports.
With the API factory, an option left out of its `supports` isn't stored at
all, so point at the API block instead of making a promise the Admin
can't keep.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XeNQQyTaYeWZpC758e2jrf
---
 packages/admin/cms-admin/src/blocks/createDamVideoBlock.tsx | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/admin/cms-admin/src/blocks/createDamVideoBlock.tsx b/packages/admin/cms-admin/src/blocks/createDamVideoBlock.tsx
index 4d68b6c124d..369cd4ae73a 100644
--- a/packages/admin/cms-admin/src/blocks/createDamVideoBlock.tsx
+++ b/packages/admin/cms-admin/src/blocks/createDamVideoBlock.tsx
@@ -43,7 +43,8 @@ interface DamVideoBlockFactoryOptions {
      * that only reads the file's URL.
      *
      * Values that are already stored are kept as they are, the editor just can't change them anymore.
-     * The preview image is always part of the block's data, leaving it out only hides it from the editor.
+     * Whether an option is part of the block's data at all is decided by the API block, so use the same
+     * `supports` there.
      * @default ["controls", "previewImage"]
      */
     supports?: DamVideoBlockSupports[];

From 6434d532899fc22ca04952d7f5c02d029dd0cef0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 2 Sep 2026 08:48:04 +0000
Subject: [PATCH 10/15] cms-api: Don't version a DamVideo block created by the
 factory

Stamping version 1 without a migration is pointless: applyMigrations
returns the raw data untouched for an empty pipe, so the version number
only burns the first slot. A project's first migration would then have to
be a no-op at toVersion 1, because the pipe has to start there, plus the
real one at toVersion 2.

Pass migrate only for the exported DamVideoBlock, which has the preview
image migration, and create blocks from the factory without it, like every
other block that has no migrations. Their data carries no $$version, so a
later first migration at toVersion 1 applies to it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XeNQQyTaYeWZpC758e2jrf
---
 .../blocks/video/createDamVideoBlock.test.ts  | 12 ++++++------
 .../dam/blocks/video/createDamVideoBlock.ts   | 19 ++++++++++---------
 2 files changed, 16 insertions(+), 15 deletions(-)

diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
index 39028cd8795..24d2033a0ac 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
@@ -36,38 +36,38 @@ describe("createDamVideoBlock", () => {
         const block = createDamVideoBlock({ supports: [] }, "StoringFileOnlyVideo");
         const input = block.blockInputFactory({ damFileId, autoplay: true, showControls: true, loop: true, previewImage: {} });
 
-        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, $$version: 1 });
+        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId });
     });
 
     it("should create input for a block without a preview image", () => {
         const block = createDamVideoBlock({ supports: ["controls"] }, "InputWithoutPreviewImage");
         const input = block.blockInputFactory({ damFileId, autoplay: true });
 
-        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, autoplay: true, $$version: 1 });
+        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, autoplay: true });
     });
 
     it("should create input for a block that supports nothing but the file", () => {
         const block = createDamVideoBlock({ supports: [] }, "InputWithFileOnly");
         const input = block.blockInputFactory({ damFileId });
 
-        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, $$version: 1 });
+        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId });
     });
 
     it("should store the supported options", () => {
         const block = createDamVideoBlock({}, "StoringFullVideo");
         const input = block.blockInputFactory({ damFileId, autoplay: true, previewImage: {} });
 
-        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, autoplay: true, previewImage: {}, $$version: 1 });
+        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, autoplay: true, previewImage: {} });
     });
 
     it("should add a preview image to data from before the exported block had one", () => {
         expect(transformToBlockSave(DamVideoBlock.blockDataFactory({ damFileId }))).toEqual({ damFileId, previewImage: {}, $$version: 1 });
     });
 
-    it("should not migrate data of a block created by the factory", () => {
+    it("should neither migrate nor version data of a block created by the factory", () => {
         const block = createDamVideoBlock({}, "UnmigratedVideo");
 
-        expect(transformToBlockSave(block.blockDataFactory({ damFileId }))).toEqual({ damFileId, $$version: 1 });
+        expect(transformToBlockSave(block.blockDataFactory({ damFileId }))).toEqual({ damFileId });
     });
 
     it("should reject a name that is already registered", () => {
diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
index ed304fdc5c8..f54fef67e3d 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
@@ -64,19 +64,20 @@ export function createDamVideoBlock(
     options: CreateDamVideoBlockOptions = {},
     name = "DamVideo",
 ): Block<BlockDataInterface, DamVideoBlockInputInterface> {
-    // A block created by the factory has no data from an earlier version, so it starts at version 1 without migrations.
-    return createDamVideoBlockWithMigrations({ ...options, name, migrations: [] });
+    // A block created by the factory has no data from an earlier version, so it needs no migrations - and
+    // no version either, like every other block without them.
+    return createDamVideoBlockWithMigrations({ ...options, name });
 }
 
 interface CreateDamVideoBlockWithMigrationsOptions extends CreateDamVideoBlockOptions {
     name: string;
-    migrations: MigrateOptions["migrations"];
+    migrate?: MigrateOptions;
 }
 
 function createDamVideoBlockWithMigrations({
     supports = defaultSupports,
     name,
-    migrations,
+    migrate,
 }: CreateDamVideoBlockWithMigrationsOptions): Block<BlockDataInterface, DamVideoBlockInputInterface> {
     if (getRegisteredBlocks().some((block) => block.name === name)) {
         throw new Error(
@@ -285,14 +286,14 @@ function createDamVideoBlockWithMigrations({
         name,
         blockMeta: new Meta(DamVideoBlockData),
         blockInputMeta: new InputMeta(DamVideoBlockInput),
-        migrate: {
-            version: 1,
-            migrations,
-        },
+        migrate,
     });
 }
 
 export const DamVideoBlock = createDamVideoBlockWithMigrations({
     name: "DamVideo",
-    migrations: typeSafeBlockMigrationPipe([AddPreviewImageMigration]),
+    migrate: {
+        version: 1,
+        migrations: typeSafeBlockMigrationPipe([AddPreviewImageMigration]),
+    },
 });

From e415f32759a984873805b14c482138d753b369ff Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 2 Sep 2026 08:55:05 +0000
Subject: [PATCH 11/15] cms-api: Take the standard nameOrOptions parameter in
 createDamVideoBlock

Every other block factory takes `nameOrOptions: BlockFactoryNameOrOptions`
as its second parameter and forwards its migrate option to createBlock, so
a project can migrate the block it created. createDamVideoBlock took a bare
name and passed no migrate at all, leaving projects without a way to
migrate their own video block.

Follow the convention instead: a string is the block's name, an object can
carry migrate too, and the exported DamVideoBlock passes its preview image
migration that way. The internal creator folds back into the factory, since
the factory can now express everything the exported block needs.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XeNQQyTaYeWZpC758e2jrf
---
 .changeset/api-dam-video-block-factory.md     |  1 +
 .../blocks/video/createDamVideoBlock.test.ts  | 23 ++++++++++++
 .../dam/blocks/video/createDamVideoBlock.ts   | 37 +++++++------------
 3 files changed, 38 insertions(+), 23 deletions(-)

diff --git a/.changeset/api-dam-video-block-factory.md b/.changeset/api-dam-video-block-factory.md
index a4182d1005e..6a6687cdf6b 100644
--- a/.changeset/api-dam-video-block-factory.md
+++ b/.changeset/api-dam-video-block-factory.md
@@ -13,6 +13,7 @@ Values that were stored before an option was left out are kept and saved again,
 - `"previewImage"` — the poster image
 
 `DamVideoBlock` is now created from the factory with both supported and still exported next to it, so this is non-breaking. Since it occupies the block name `DamVideo`, a block created with the factory needs a name of its own.
+The name is passed as the second parameter, the same `nameOrOptions` the other block factories take, so it can carry a `migrate` option as well.
 
 **Example**
 
diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
index 24d2033a0ac..d32d90b5a76 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
@@ -1,8 +1,22 @@
 import { describe, expect, it } from "vitest";
 
 import { transformToBlockSave } from "../../../blocks/block";
+import { BlockMigration } from "../../../blocks/migrations/BlockMigration";
+import type { BlockMigrationInterface } from "../../../blocks/migrations/types";
+import { typeSafeBlockMigrationPipe } from "../../../blocks/migrations/typeSafeBlockMigrationPipe";
 import { createDamVideoBlock, DamVideoBlock } from "./createDamVideoBlock";
 
+class AddLoopMigration
+    extends BlockMigration<(from: { damFileId?: string }) => { damFileId?: string; loop: boolean }>
+    implements BlockMigrationInterface
+{
+    public readonly toVersion = 1;
+
+    protected migrate(props: { damFileId?: string }) {
+        return { ...props, loop: true };
+    }
+}
+
 const damFileId = "0a3a4f9c-1b19-4f7e-bd0a-8e0b6b1a2c3d";
 
 describe("createDamVideoBlock", () => {
@@ -70,6 +84,15 @@ describe("createDamVideoBlock", () => {
         expect(transformToBlockSave(block.blockDataFactory({ damFileId }))).toEqual({ damFileId });
     });
 
+    it("should apply migrations passed to the factory", () => {
+        const block = createDamVideoBlock(
+            {},
+            { name: "MigratedVideo", migrate: { version: 1, migrations: typeSafeBlockMigrationPipe([AddLoopMigration]) } },
+        );
+
+        expect(transformToBlockSave(block.blockDataFactory({ damFileId }))).toEqual({ damFileId, loop: true, $$version: 1 });
+    });
+
     it("should reject a name that is already registered", () => {
         expect(() => createDamVideoBlock({ supports: [] })).toThrow(/already registered/);
     });
diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
index f54fef67e3d..6bd63f4cb74 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
@@ -11,12 +11,12 @@ import {
     createBlock,
     type ExtractBlockInput,
     getRegisteredBlocks,
-    type MigrateOptions,
     type SimpleBlockInputInterface,
 } from "../../../blocks/block";
 import { ChildBlock } from "../../../blocks/decorators/child-block";
 import { ChildBlockInput } from "../../../blocks/decorators/child-block-input";
 import { AnnotationBlockMeta, BlockField } from "../../../blocks/decorators/field";
+import type { BlockFactoryNameOrOptions } from "../../../blocks/factories/types";
 import { typeSafeBlockMigrationPipe } from "../../../blocks/migrations/typeSafeBlockMigrationPipe";
 import { DamFileAiContentType } from "../../files/entities/ai-content-type.enum";
 import { FILE_ENTITY } from "../../files/entities/file.entity";
@@ -61,24 +61,12 @@ interface DamVideoBlockInputInterface extends SimpleBlockInputInterface {
 }
 
 export function createDamVideoBlock(
-    options: CreateDamVideoBlockOptions = {},
-    name = "DamVideo",
+    { supports = defaultSupports }: CreateDamVideoBlockOptions = {},
+    nameOrOptions: BlockFactoryNameOrOptions = "DamVideo",
 ): Block<BlockDataInterface, DamVideoBlockInputInterface> {
-    // A block created by the factory has no data from an earlier version, so it needs no migrations - and
-    // no version either, like every other block without them.
-    return createDamVideoBlockWithMigrations({ ...options, name });
-}
-
-interface CreateDamVideoBlockWithMigrationsOptions extends CreateDamVideoBlockOptions {
-    name: string;
-    migrate?: MigrateOptions;
-}
+    const name = typeof nameOrOptions === "string" ? nameOrOptions : nameOrOptions.name;
+    const migrate = typeof nameOrOptions === "string" ? undefined : nameOrOptions.migrate;
 
-function createDamVideoBlockWithMigrations({
-    supports = defaultSupports,
-    name,
-    migrate,
-}: CreateDamVideoBlockWithMigrationsOptions): Block<BlockDataInterface, DamVideoBlockInputInterface> {
     if (getRegisteredBlocks().some((block) => block.name === name)) {
         throw new Error(
             `A block named "${name}" is already registered. @dextinity/cms-api exports a ready-made DamVideoBlock, so a block created with createDamVideoBlock needs its own name, for instance createDamVideoBlock({ supports: [] }, "TeaserVideo").`,
@@ -290,10 +278,13 @@ function createDamVideoBlockWithMigrations({
     });
 }
 
-export const DamVideoBlock = createDamVideoBlockWithMigrations({
-    name: "DamVideo",
-    migrate: {
-        version: 1,
-        migrations: typeSafeBlockMigrationPipe([AddPreviewImageMigration]),
+export const DamVideoBlock = createDamVideoBlock(
+    {},
+    {
+        name: "DamVideo",
+        migrate: {
+            version: 1,
+            migrations: typeSafeBlockMigrationPipe([AddPreviewImageMigration]),
+        },
     },
-});
+);

From 2e9423b4497e3a798b212ba3037c0b0d1050de38 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 14:47:15 +0000
Subject: [PATCH 12/15] cms-api: Migrate content of blocks created by
 createDamVideoBlock

Migrations were attached at the call site, so only the exported DamVideoBlock
had the preview image migration. Every block a project created with the factory
started at version 0 with an empty chain, which breaks replacing an existing
block: content that was never migrated keeps no preview image although the
block declares it non-nullable, and the block index doesn't cover it.

Let the factory contribute the migration itself, the way
createTipTapRichTextBlock does with its DraftJS migration. It reserves version
1 and throws when a caller's version or toVersion takes that slot, so own
migrations start with 2.

The migration stays in the chain for a block without preview image support and
only marks the data as up to date, so the version numbers don't shift when
supports is widened later on. It also keeps a preview image that was stored
without a version instead of overwriting it.

Also return the block's own data interface from the factory, so callers can
read previewImage off loaded data.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017hbMWudfh8zx48grTo47Bz
---
 .changeset/api-dam-video-block-factory.md     |  13 +++
 .../blocks/video/createDamVideoBlock.test.ts  | 102 +++++++++++++++---
 .../dam/blocks/video/createDamVideoBlock.ts   |  42 +++++---
 .../1-add-preview-image.migration.ts          |  36 +++++--
 4 files changed, 158 insertions(+), 35 deletions(-)

diff --git a/.changeset/api-dam-video-block-factory.md b/.changeset/api-dam-video-block-factory.md
index 6a6687cdf6b..3f5727238ca 100644
--- a/.changeset/api-dam-video-block-factory.md
+++ b/.changeset/api-dam-video-block-factory.md
@@ -25,3 +25,16 @@ export const TeaserVideoBlock = createDamVideoBlock({ supports: [] }, "TeaserVid
 ```
 
 Use the same `supports` and the same name for the Admin block.
+
+**Migrations**
+
+The factory brings its own migration, so a block created by it migrates content that was stored before the block had a preview image — even when no `migrate` is passed. This matters when the factory replaces a block that a project already has: without it, content that was never migrated keeps no preview image although the block declares one.
+
+That migration occupies version 1, so own migrations start with 2. The factory throws when a passed `version` or `toVersion` is 1.
+
+```ts
+export const TeaserVideoBlock = createDamVideoBlock(
+    { supports: ["controls"] },
+    { name: "TeaserVideo", migrate: { version: 2, migrations: typeSafeBlockMigrationPipe([AddSomethingMigration]) } },
+);
+```
diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
index d32d90b5a76..1d57586d512 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
@@ -10,13 +10,21 @@ class AddLoopMigration
     extends BlockMigration<(from: { damFileId?: string }) => { damFileId?: string; loop: boolean }>
     implements BlockMigrationInterface
 {
-    public readonly toVersion = 1;
+    public readonly toVersion = 2;
 
     protected migrate(props: { damFileId?: string }) {
         return { ...props, loop: true };
     }
 }
 
+class ReservedVersionMigration extends BlockMigration<(from: { damFileId?: string }) => { damFileId?: string }> implements BlockMigrationInterface {
+    public readonly toVersion = 1;
+
+    protected migrate(props: { damFileId?: string }) {
+        return props;
+    }
+}
+
 const damFileId = "0a3a4f9c-1b19-4f7e-bd0a-8e0b6b1a2c3d";
 
 describe("createDamVideoBlock", () => {
@@ -50,50 +58,118 @@ describe("createDamVideoBlock", () => {
         const block = createDamVideoBlock({ supports: [] }, "StoringFileOnlyVideo");
         const input = block.blockInputFactory({ damFileId, autoplay: true, showControls: true, loop: true, previewImage: {} });
 
-        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId });
+        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, $$version: 1 });
     });
 
     it("should create input for a block without a preview image", () => {
         const block = createDamVideoBlock({ supports: ["controls"] }, "InputWithoutPreviewImage");
         const input = block.blockInputFactory({ damFileId, autoplay: true });
 
-        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, autoplay: true });
+        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, autoplay: true, $$version: 1 });
     });
 
     it("should create input for a block that supports nothing but the file", () => {
         const block = createDamVideoBlock({ supports: [] }, "InputWithFileOnly");
         const input = block.blockInputFactory({ damFileId });
 
-        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId });
+        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, $$version: 1 });
     });
 
     it("should store the supported options", () => {
         const block = createDamVideoBlock({}, "StoringFullVideo");
         const input = block.blockInputFactory({ damFileId, autoplay: true, previewImage: {} });
 
-        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, autoplay: true, previewImage: {} });
+        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, autoplay: true, previewImage: {}, $$version: 1 });
+    });
+
+    it("should require a preview image in the input when it is supported", () => {
+        const block = createDamVideoBlock({}, "InputRequiringPreviewImage");
+
+        expect(() => block.blockInputFactory({ damFileId })).toThrow(/Missing child block input for 'previewImage'/);
     });
 
+    it("should reject a name that is already registered", () => {
+        expect(() => createDamVideoBlock({ supports: [] })).toThrow(/already registered/);
+    });
+});
+
+describe("createDamVideoBlock migrations", () => {
+    // Content stored before the block gained its preview image: neither a version nor a preview image.
+    const legacyData = { damFileId, autoplay: true, showControls: true, loop: false };
+
     it("should add a preview image to data from before the exported block had one", () => {
         expect(transformToBlockSave(DamVideoBlock.blockDataFactory({ damFileId }))).toEqual({ damFileId, previewImage: {}, $$version: 1 });
     });
 
-    it("should neither migrate nor version data of a block created by the factory", () => {
-        const block = createDamVideoBlock({}, "UnmigratedVideo");
+    it("should migrate and version data of a block created by the factory", () => {
+        const block = createDamVideoBlock({}, "MigratedByTheFactory");
+
+        expect(transformToBlockSave(block.blockDataFactory(legacyData))).toEqual({ ...legacyData, previewImage: {}, $$version: 1 });
+    });
+
+    it("should read the migrated preview image as a child block", () => {
+        const block = createDamVideoBlock({}, "MigratedPreviewImageIsAChildBlock");
+        const data = block.blockDataFactory(legacyData);
 
-        expect(transformToBlockSave(block.blockDataFactory({ damFileId }))).toEqual({ damFileId });
+        expect(data.previewImage?.constructor.name).toBe("PixelImageBlockData");
+        expect(data.childBlocksInfo().map((child) => child.name)).toEqual(["PixelImage"]);
     });
 
-    it("should apply migrations passed to the factory", () => {
+    it("should keep a preview image that was stored without a version", () => {
+        const block = createDamVideoBlock({}, "KeepingAnUnversionedPreviewImage");
+        const data = block.blockDataFactory({ damFileId, previewImage: { damFileId } });
+
+        expect(transformToBlockSave(data)).toEqual({ damFileId, previewImage: { damFileId }, $$version: 1 });
+    });
+
+    it("should only version data of a block that doesn't support a preview image", () => {
+        const block = createDamVideoBlock({ supports: ["controls"] }, "VersionedWithoutPreviewImage");
+
+        expect(transformToBlockSave(block.blockDataFactory(legacyData))).toEqual({ ...legacyData, $$version: 1 });
+    });
+
+    it("should migrate only once", () => {
+        const block = createDamVideoBlock({}, "MigratingOnlyOnce");
+        const migrated = transformToBlockSave(block.blockDataFactory(legacyData));
+
+        expect(transformToBlockSave(block.blockDataFactory(migrated))).toEqual(migrated);
+    });
+
+    it("should apply migrations passed to the factory after its own", () => {
         const block = createDamVideoBlock(
             {},
-            { name: "MigratedVideo", migrate: { version: 1, migrations: typeSafeBlockMigrationPipe([AddLoopMigration]) } },
+            { name: "MigratedVideo", migrate: { version: 2, migrations: typeSafeBlockMigrationPipe([AddLoopMigration]) } },
         );
 
-        expect(transformToBlockSave(block.blockDataFactory({ damFileId }))).toEqual({ damFileId, loop: true, $$version: 1 });
+        expect(transformToBlockSave(block.blockDataFactory({ damFileId }))).toEqual({ damFileId, previewImage: {}, loop: true, $$version: 2 });
     });
 
-    it("should reject a name that is already registered", () => {
-        expect(() => createDamVideoBlock({ supports: [] })).toThrow(/already registered/);
+    it("should apply a migration passed to the factory to data that is already at the reserved version", () => {
+        const block = createDamVideoBlock(
+            {},
+            { name: "MigratedVideoFromVersionOne", migrate: { version: 2, migrations: typeSafeBlockMigrationPipe([AddLoopMigration]) } },
+        );
+
+        expect(transformToBlockSave(block.blockDataFactory({ damFileId, previewImage: {}, $$version: 1 }))).toEqual({
+            damFileId,
+            previewImage: {},
+            loop: true,
+            $$version: 2,
+        });
+    });
+
+    it("should reject a version that is reserved for the factory", () => {
+        expect(() =>
+            createDamVideoBlock({}, { name: "ReservedVersion", migrate: { version: 1, migrations: typeSafeBlockMigrationPipe([AddLoopMigration]) } }),
+        ).toThrow(/version=1 is reserved for createDamVideoBlock/);
+    });
+
+    it("should reject a migration whose version is reserved for the factory", () => {
+        expect(() =>
+            createDamVideoBlock(
+                {},
+                { name: "ReservedToVersion", migrate: { version: 2, migrations: typeSafeBlockMigrationPipe([ReservedVersionMigration]) } },
+            ),
+        ).toThrow(/toVersion=1 is reserved for createDamVideoBlock/);
     });
 });
diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
index 6bd63f4cb74..7bba7e8aafe 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
@@ -17,12 +17,11 @@ import { ChildBlock } from "../../../blocks/decorators/child-block";
 import { ChildBlockInput } from "../../../blocks/decorators/child-block-input";
 import { AnnotationBlockMeta, BlockField } from "../../../blocks/decorators/field";
 import type { BlockFactoryNameOrOptions } from "../../../blocks/factories/types";
-import { typeSafeBlockMigrationPipe } from "../../../blocks/migrations/typeSafeBlockMigrationPipe";
 import { DamFileAiContentType } from "../../files/entities/ai-content-type.enum";
 import { FILE_ENTITY } from "../../files/entities/file.entity";
 import { PixelImageBlock } from "../pixel-image.block";
 import { DamVideoBlockTransformerService } from "./dam-video-block-transformer.service";
-import { AddPreviewImageMigration } from "./migrations/1-add-preview-image.migration";
+import { buildAddPreviewImageMigration } from "./migrations/1-add-preview-image.migration";
 
 /**
  * What the block stores besides the video file itself:
@@ -34,6 +33,9 @@ export type DamVideoBlockSupports = "controls" | "previewImage";
 
 const defaultSupports: DamVideoBlockSupports[] = ["controls", "previewImage"];
 
+// Belongs to the factory's own migration, so a block created by it starts its migrations with 2.
+const reservedVersion = 1;
+
 interface CreateDamVideoBlockOptions {
     /**
      * What the block stores besides the video file itself. Leave out anything the site implementation
@@ -63,9 +65,9 @@ interface DamVideoBlockInputInterface extends SimpleBlockInputInterface {
 export function createDamVideoBlock(
     { supports = defaultSupports }: CreateDamVideoBlockOptions = {},
     nameOrOptions: BlockFactoryNameOrOptions = "DamVideo",
-): Block<BlockDataInterface, DamVideoBlockInputInterface> {
+): Block<DamVideoBlockDataInterface, DamVideoBlockInputInterface> {
     const name = typeof nameOrOptions === "string" ? nameOrOptions : nameOrOptions.name;
-    const migrate = typeof nameOrOptions === "string" ? undefined : nameOrOptions.migrate;
+    const baseMigrate = typeof nameOrOptions === "string" ? undefined : nameOrOptions.migrate;
 
     if (getRegisteredBlocks().some((block) => block.name === name)) {
         throw new Error(
@@ -76,6 +78,27 @@ export function createDamVideoBlock(
     const supportsControls = supports.includes("controls");
     const supportsPreviewImage = supports.includes("previewImage");
 
+    if (baseMigrate) {
+        if (baseMigrate.version === reservedVersion) {
+            throw new Error(`version=${reservedVersion} is reserved for createDamVideoBlock, start own migrations with ${reservedVersion + 1}.`);
+        }
+
+        for (const migration of baseMigrate.migrations) {
+            if (new migration().toVersion === reservedVersion) {
+                throw new Error(
+                    `toVersion=${reservedVersion} is reserved for createDamVideoBlock, start own migrations with ${reservedVersion + 1}.`,
+                );
+            }
+        }
+    }
+
+    // The factory brings its own migration, so a block it creates migrates existing content even when the
+    // caller passes no migrations of its own.
+    const migrate = {
+        version: baseMigrate && baseMigrate.version > reservedVersion ? baseMigrate.version : reservedVersion,
+        migrations: [buildAddPreviewImageMigration({ supportsPreviewImage }), ...(baseMigrate?.migrations ?? [])],
+    };
+
     const unsupportedFields = supportsControls ? [] : ["autoplay", "showControls", "loop"];
     const isSupported = (field: BlockMetaField) => !unsupportedFields.includes(field.name);
 
@@ -278,13 +301,4 @@ export function createDamVideoBlock(
     });
 }
 
-export const DamVideoBlock = createDamVideoBlock(
-    {},
-    {
-        name: "DamVideo",
-        migrate: {
-            version: 1,
-            migrations: typeSafeBlockMigrationPipe([AddPreviewImageMigration]),
-        },
-    },
-);
+export const DamVideoBlock = createDamVideoBlock({}, "DamVideo");
diff --git a/packages/api/cms-api/src/dam/blocks/video/migrations/1-add-preview-image.migration.ts b/packages/api/cms-api/src/dam/blocks/video/migrations/1-add-preview-image.migration.ts
index ef37aa19774..89010a0b496 100644
--- a/packages/api/cms-api/src/dam/blocks/video/migrations/1-add-preview-image.migration.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/migrations/1-add-preview-image.migration.ts
@@ -1,3 +1,5 @@
+import type { ClassConstructor } from "class-transformer";
+
 import { BlockMigration } from "../../../../blocks/migrations/BlockMigration";
 import type { BlockMigrationInterface } from "../../../../blocks/migrations/types";
 
@@ -6,16 +8,34 @@ interface From {
     autoplay?: boolean;
     showControls?: boolean;
     loop?: boolean;
+    previewImage?: unknown;
 }
 
-interface To extends From {
-    previewImage: unknown;
-}
+type To = From;
+
+/**
+ * Version 1 of every block created by `createDamVideoBlock`: the preview image the block gained after its
+ * first release.
+ *
+ * The migration is always part of the chain so that version 1 means the same thing for every block the
+ * factory creates, no matter what it supports. For a block without preview image support it only marks the
+ * data as up to date, which keeps the version numbers stable when `supports` is widened later on.
+ */
+export function buildAddPreviewImageMigration({
+    supportsPreviewImage,
+}: {
+    supportsPreviewImage: boolean;
+}): ClassConstructor<BlockMigrationInterface> {
+    return class AddPreviewImageMigration extends BlockMigration<(from: From) => To> implements BlockMigrationInterface {
+        public readonly toVersion = 1;
 
-export class AddPreviewImageMigration extends BlockMigration<(from: From) => To> implements BlockMigrationInterface {
-    public readonly toVersion = 1;
+        protected migrate(props: From): To {
+            if (!supportsPreviewImage) {
+                return props;
+            }
 
-    protected migrate(props: From): To {
-        return { ...props, previewImage: {} };
-    }
+            // Keep the preview image of a block that stored one without versioning its data.
+            return { ...props, previewImage: props.previewImage ?? {} };
+        }
+    };
 }

From 18116ecb75b1f2c3f6bb04016c6c3544fd73c397 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 14:47:41 +0000
Subject: [PATCH 13/15] docs: Describe how migrations work for the
 DamVideoBlock factory

The factory reserves version 1 for its own preview image migration, so a
project needs to know that own migrations start with 2 and that migrateBlocks
persists what is otherwise only migrated on load.

Also note that a value kept after narrowing supports is no longer a child
block, so it drops out of the block index.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017hbMWudfh8zx48grTo47Bz
---
 .../2-core-concepts/2-blocks/4-factories.mdx  | 26 +++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/docs/2-core-concepts/2-blocks/4-factories.mdx b/docs/docs/2-core-concepts/2-blocks/4-factories.mdx
index 78363539fb2..c31372bc9d1 100644
--- a/docs/docs/2-core-concepts/2-blocks/4-factories.mdx
+++ b/docs/docs/2-core-concepts/2-blocks/4-factories.mdx
@@ -254,6 +254,32 @@ export const TeaserVideoBlock = createDamVideoBlock({ supports: [] }, "TeaserVid
 
 Unsupported options are part of neither the block's data nor its input, so they don't show up in `blocks.generated.ts` and aren't stored for new content.
 Values that were stored before an option was left out are kept: the block loads them and saves them again, so narrowing `supports` doesn't remove them from existing content.
+Note that such a value is no longer treated as a child block, so a preview image kept this way isn't part of the block index either.
+
+#### Migrations
+
+The factory brings its own migration for the preview image the block gained after its first release.
+It runs for every block the factory creates, so replacing a block a project already has migrates content that was stored before the preview image existed.
+
+That migration occupies version 1, so own migrations start with 2.
+The factory throws when a passed `version` or `toVersion` is 1:
+
+```ts title="teaser-video.block.ts"
+import { createDamVideoBlock, typeSafeBlockMigrationPipe } from "@dextinity/cms-api";
+
+export const TeaserVideoBlock = createDamVideoBlock(
+    { supports: ["controls"] },
+    { name: "TeaserVideo", migrate: { version: 2, migrations: typeSafeBlockMigrationPipe([AddSomethingMigration]) } },
+);
+```
+
+Run `migrateBlocks` to write the migrated data back:
+
+```bash
+pnpm console migrateBlocks
+```
+
+Without it the migration still applies whenever a block is loaded, it just isn't persisted until the content is saved.
 
 ### Admin
 

From df736c0e3c386d379719c21a25cc48cc233e23ae Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 15:22:54 +0000
Subject: [PATCH 14/15] cms-api: Default the DamVideo preview image instead of
 reserving a version

Contributing the preview image migration from the factory only reaches content
whose version is behind. Content stored while supports left the preview image
out is already at the block's latest version, so widening supports later left
previewImage undefined although the block's meta declares it as always present.
Reserving version 1 for that migration also pushed a project's own migrations
to 2 and would shift them again for every field the block gains.

Default a missing preview image to an empty one when it loads instead. That
covers content from before the block had one and content no migration reaches,
so the factory needs neither its own migration nor a reserved version and just
forwards migrate again. The exported DamVideoBlock keeps its migration at the
call site, because its stored content carries that version already.

Expose is required for the transform to run at all when the stored data has no
preview image: ChildBlock alone leaves the property untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017hbMWudfh8zx48grTo47Bz
---
 .changeset/api-dam-video-block-factory.md     |  13 +-
 .../blocks/video/createDamVideoBlock.test.ts  | 117 ++++++++----------
 .../dam/blocks/video/createDamVideoBlock.ts   |  51 ++++----
 .../1-add-preview-image.migration.ts          |  32 +----
 4 files changed, 83 insertions(+), 130 deletions(-)

diff --git a/.changeset/api-dam-video-block-factory.md b/.changeset/api-dam-video-block-factory.md
index 3f5727238ca..7d6899651a1 100644
--- a/.changeset/api-dam-video-block-factory.md
+++ b/.changeset/api-dam-video-block-factory.md
@@ -26,15 +26,8 @@ export const TeaserVideoBlock = createDamVideoBlock({ supports: [] }, "TeaserVid
 
 Use the same `supports` and the same name for the Admin block.
 
-**Migrations**
+**Preview image of existing content**
 
-The factory brings its own migration, so a block created by it migrates content that was stored before the block had a preview image — even when no `migrate` is passed. This matters when the factory replaces a block that a project already has: without it, content that was never migrated keeps no preview image although the block declares one.
+A block created by the factory defaults a missing preview image to an empty one when it supports one. This matters when the factory replaces a block a project already has: content stored before the block had a preview image loads as a child block instead of leaving the field undefined, which the block's own meta declares as always present.
 
-That migration occupies version 1, so own migrations start with 2. The factory throws when a passed `version` or `toVersion` is 1.
-
-```ts
-export const TeaserVideoBlock = createDamVideoBlock(
-    { supports: ["controls"] },
-    { name: "TeaserVideo", migrate: { version: 2, migrations: typeSafeBlockMigrationPipe([AddSomethingMigration]) } },
-);
-```
+The default applies on read, so it also reaches content whose version is already the block's latest — for instance content stored while `supports` left the preview image out, before it was widened to include it.
diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
index 1d57586d512..2ac1a2a6e2b 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.test.ts
@@ -10,18 +10,10 @@ class AddLoopMigration
     extends BlockMigration<(from: { damFileId?: string }) => { damFileId?: string; loop: boolean }>
     implements BlockMigrationInterface
 {
-    public readonly toVersion = 2;
-
-    protected migrate(props: { damFileId?: string }) {
-        return { ...props, loop: true };
-    }
-}
-
-class ReservedVersionMigration extends BlockMigration<(from: { damFileId?: string }) => { damFileId?: string }> implements BlockMigrationInterface {
     public readonly toVersion = 1;
 
     protected migrate(props: { damFileId?: string }) {
-        return props;
+        return { ...props, loop: true };
     }
 }
 
@@ -58,28 +50,28 @@ describe("createDamVideoBlock", () => {
         const block = createDamVideoBlock({ supports: [] }, "StoringFileOnlyVideo");
         const input = block.blockInputFactory({ damFileId, autoplay: true, showControls: true, loop: true, previewImage: {} });
 
-        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, $$version: 1 });
+        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId });
     });
 
     it("should create input for a block without a preview image", () => {
         const block = createDamVideoBlock({ supports: ["controls"] }, "InputWithoutPreviewImage");
         const input = block.blockInputFactory({ damFileId, autoplay: true });
 
-        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, autoplay: true, $$version: 1 });
+        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, autoplay: true });
     });
 
     it("should create input for a block that supports nothing but the file", () => {
         const block = createDamVideoBlock({ supports: [] }, "InputWithFileOnly");
         const input = block.blockInputFactory({ damFileId });
 
-        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, $$version: 1 });
+        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId });
     });
 
     it("should store the supported options", () => {
         const block = createDamVideoBlock({}, "StoringFullVideo");
         const input = block.blockInputFactory({ damFileId, autoplay: true, previewImage: {} });
 
-        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, autoplay: true, previewImage: {}, $$version: 1 });
+        expect(transformToBlockSave(input.transformToBlockData())).toEqual({ damFileId, autoplay: true, previewImage: {} });
     });
 
     it("should require a preview image in the input when it is supported", () => {
@@ -93,83 +85,74 @@ describe("createDamVideoBlock", () => {
     });
 });
 
-describe("createDamVideoBlock migrations", () => {
-    // Content stored before the block gained its preview image: neither a version nor a preview image.
-    const legacyData = { damFileId, autoplay: true, showControls: true, loop: false };
-
-    it("should add a preview image to data from before the exported block had one", () => {
-        expect(transformToBlockSave(DamVideoBlock.blockDataFactory({ damFileId }))).toEqual({ damFileId, previewImage: {}, $$version: 1 });
-    });
-
-    it("should migrate and version data of a block created by the factory", () => {
-        const block = createDamVideoBlock({}, "MigratedByTheFactory");
-
-        expect(transformToBlockSave(block.blockDataFactory(legacyData))).toEqual({ ...legacyData, previewImage: {}, $$version: 1 });
-    });
-
-    it("should read the migrated preview image as a child block", () => {
-        const block = createDamVideoBlock({}, "MigratedPreviewImageIsAChildBlock");
-        const data = block.blockDataFactory(legacyData);
+describe("createDamVideoBlock preview image default", () => {
+    it("should default a missing preview image to an empty one", () => {
+        const block = createDamVideoBlock({}, "DefaultingPreviewImage");
+        const data = block.blockDataFactory({ damFileId, autoplay: true });
 
         expect(data.previewImage?.constructor.name).toBe("PixelImageBlockData");
         expect(data.childBlocksInfo().map((child) => child.name)).toEqual(["PixelImage"]);
+        expect(transformToBlockSave(data)).toEqual({ damFileId, autoplay: true, previewImage: {} });
     });
 
-    it("should keep a preview image that was stored without a version", () => {
-        const block = createDamVideoBlock({}, "KeepingAnUnversionedPreviewImage");
-        const data = block.blockDataFactory({ damFileId, previewImage: { damFileId } });
+    it("should default a preview image of content that is past the block's migrations", () => {
+        // Content stored while the preview image wasn't supported: no migration reaches it, because its
+        // version is already the block's latest.
+        const block = createDamVideoBlock({}, { name: "DefaultingPastMigrations", migrate: { version: 1, migrations: [AddLoopMigration] } });
+        const data = block.blockDataFactory({ damFileId, autoplay: true, $$version: 1 });
 
-        expect(transformToBlockSave(data)).toEqual({ damFileId, previewImage: { damFileId }, $$version: 1 });
+        expect(data.previewImage?.constructor.name).toBe("PixelImageBlockData");
+        expect(transformToBlockSave(data)).toEqual({ damFileId, autoplay: true, previewImage: {}, $$version: 1 });
     });
 
-    it("should only version data of a block that doesn't support a preview image", () => {
-        const block = createDamVideoBlock({ supports: ["controls"] }, "VersionedWithoutPreviewImage");
+    it("should keep a stored preview image", () => {
+        const block = createDamVideoBlock({}, "KeepingPreviewImage");
 
-        expect(transformToBlockSave(block.blockDataFactory(legacyData))).toEqual({ ...legacyData, $$version: 1 });
+        expect(transformToBlockSave(block.blockDataFactory({ damFileId, previewImage: { damFileId } }))).toEqual({
+            damFileId,
+            previewImage: { damFileId },
+        });
     });
 
-    it("should migrate only once", () => {
-        const block = createDamVideoBlock({}, "MigratingOnlyOnce");
-        const migrated = transformToBlockSave(block.blockDataFactory(legacyData));
+    it("should not add a preview image to a block that doesn't support one", () => {
+        const block = createDamVideoBlock({ supports: ["controls"] }, "NoDefaultWithoutSupport");
 
-        expect(transformToBlockSave(block.blockDataFactory(migrated))).toEqual(migrated);
+        expect(transformToBlockSave(block.blockDataFactory({ damFileId, autoplay: true }))).toEqual({ damFileId, autoplay: true });
     });
 
-    it("should apply migrations passed to the factory after its own", () => {
-        const block = createDamVideoBlock(
-            {},
-            { name: "MigratedVideo", migrate: { version: 2, migrations: typeSafeBlockMigrationPipe([AddLoopMigration]) } },
-        );
+    it("should default the preview image only once", () => {
+        const block = createDamVideoBlock({}, "DefaultingOnlyOnce");
+        const once = transformToBlockSave(block.blockDataFactory({ damFileId }));
 
-        expect(transformToBlockSave(block.blockDataFactory({ damFileId }))).toEqual({ damFileId, previewImage: {}, loop: true, $$version: 2 });
+        expect(transformToBlockSave(block.blockDataFactory(once))).toEqual(once);
     });
+});
 
-    it("should apply a migration passed to the factory to data that is already at the reserved version", () => {
-        const block = createDamVideoBlock(
-            {},
-            { name: "MigratedVideoFromVersionOne", migrate: { version: 2, migrations: typeSafeBlockMigrationPipe([AddLoopMigration]) } },
-        );
+describe("createDamVideoBlock migrations", () => {
+    it("should add a preview image to data from before the exported block had one", () => {
+        expect(transformToBlockSave(DamVideoBlock.blockDataFactory({ damFileId }))).toEqual({ damFileId, previewImage: {}, $$version: 1 });
+    });
 
-        expect(transformToBlockSave(block.blockDataFactory({ damFileId, previewImage: {}, $$version: 1 }))).toEqual({
+    it("should keep a preview image that the exported block stored without a version", () => {
+        expect(transformToBlockSave(DamVideoBlock.blockDataFactory({ damFileId, previewImage: { damFileId } }))).toEqual({
             damFileId,
-            previewImage: {},
-            loop: true,
-            $$version: 2,
+            previewImage: { damFileId },
+            $$version: 1,
         });
     });
 
-    it("should reject a version that is reserved for the factory", () => {
-        expect(() =>
-            createDamVideoBlock({}, { name: "ReservedVersion", migrate: { version: 1, migrations: typeSafeBlockMigrationPipe([AddLoopMigration]) } }),
-        ).toThrow(/version=1 is reserved for createDamVideoBlock/);
+    it("should neither migrate nor version data of a block created by the factory", () => {
+        const block = createDamVideoBlock({ supports: [] }, "UnmigratedVideo");
+
+        expect(transformToBlockSave(block.blockDataFactory({ damFileId }))).toEqual({ damFileId });
     });
 
-    it("should reject a migration whose version is reserved for the factory", () => {
-        expect(() =>
-            createDamVideoBlock(
-                {},
-                { name: "ReservedToVersion", migrate: { version: 2, migrations: typeSafeBlockMigrationPipe([ReservedVersionMigration]) } },
-            ),
-        ).toThrow(/toVersion=1 is reserved for createDamVideoBlock/);
+    it("should apply migrations passed to the factory", () => {
+        const block = createDamVideoBlock(
+            { supports: [] },
+            { name: "MigratedVideo", migrate: { version: 1, migrations: typeSafeBlockMigrationPipe([AddLoopMigration]) } },
+        );
+
+        expect(transformToBlockSave(block.blockDataFactory({ damFileId }))).toEqual({ damFileId, loop: true, $$version: 1 });
     });
 });
diff --git a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
index 7bba7e8aafe..b0dae32c810 100644
--- a/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/createDamVideoBlock.ts
@@ -1,3 +1,4 @@
+import { Expose, Transform } from "class-transformer";
 import { IsBoolean, IsOptional, IsUUID } from "class-validator";
 
 import {
@@ -11,17 +12,19 @@ import {
     createBlock,
     type ExtractBlockInput,
     getRegisteredBlocks,
+    isBlockDataInterface,
     type SimpleBlockInputInterface,
 } from "../../../blocks/block";
 import { ChildBlock } from "../../../blocks/decorators/child-block";
 import { ChildBlockInput } from "../../../blocks/decorators/child-block-input";
 import { AnnotationBlockMeta, BlockField } from "../../../blocks/decorators/field";
 import type { BlockFactoryNameOrOptions } from "../../../blocks/factories/types";
+import { typeSafeBlockMigrationPipe } from "../../../blocks/migrations/typeSafeBlockMigrationPipe";
 import { DamFileAiContentType } from "../../files/entities/ai-content-type.enum";
 import { FILE_ENTITY } from "../../files/entities/file.entity";
 import { PixelImageBlock } from "../pixel-image.block";
 import { DamVideoBlockTransformerService } from "./dam-video-block-transformer.service";
-import { buildAddPreviewImageMigration } from "./migrations/1-add-preview-image.migration";
+import { AddPreviewImageMigration } from "./migrations/1-add-preview-image.migration";
 
 /**
  * What the block stores besides the video file itself:
@@ -33,9 +36,6 @@ export type DamVideoBlockSupports = "controls" | "previewImage";
 
 const defaultSupports: DamVideoBlockSupports[] = ["controls", "previewImage"];
 
-// Belongs to the factory's own migration, so a block created by it starts its migrations with 2.
-const reservedVersion = 1;
-
 interface CreateDamVideoBlockOptions {
     /**
      * What the block stores besides the video file itself. Leave out anything the site implementation
@@ -67,7 +67,7 @@ export function createDamVideoBlock(
     nameOrOptions: BlockFactoryNameOrOptions = "DamVideo",
 ): Block<DamVideoBlockDataInterface, DamVideoBlockInputInterface> {
     const name = typeof nameOrOptions === "string" ? nameOrOptions : nameOrOptions.name;
-    const baseMigrate = typeof nameOrOptions === "string" ? undefined : nameOrOptions.migrate;
+    const migrate = typeof nameOrOptions === "string" ? undefined : nameOrOptions.migrate;
 
     if (getRegisteredBlocks().some((block) => block.name === name)) {
         throw new Error(
@@ -78,27 +78,6 @@ export function createDamVideoBlock(
     const supportsControls = supports.includes("controls");
     const supportsPreviewImage = supports.includes("previewImage");
 
-    if (baseMigrate) {
-        if (baseMigrate.version === reservedVersion) {
-            throw new Error(`version=${reservedVersion} is reserved for createDamVideoBlock, start own migrations with ${reservedVersion + 1}.`);
-        }
-
-        for (const migration of baseMigrate.migrations) {
-            if (new migration().toVersion === reservedVersion) {
-                throw new Error(
-                    `toVersion=${reservedVersion} is reserved for createDamVideoBlock, start own migrations with ${reservedVersion + 1}.`,
-                );
-            }
-        }
-    }
-
-    // The factory brings its own migration, so a block it creates migrates existing content even when the
-    // caller passes no migrations of its own.
-    const migrate = {
-        version: baseMigrate && baseMigrate.version > reservedVersion ? baseMigrate.version : reservedVersion,
-        migrations: [buildAddPreviewImageMigration({ supportsPreviewImage }), ...(baseMigrate?.migrations ?? [])],
-    };
-
     const unsupportedFields = supportsControls ? [] : ["autoplay", "showControls", "loop"];
     const isSupported = (field: BlockMetaField) => !unsupportedFields.includes(field.name);
 
@@ -181,6 +160,15 @@ export function createDamVideoBlock(
     if (supportsPreviewImage) {
         ChildBlock(PixelImageBlock)(DamVideoBlockData.prototype, "previewImage");
         ChildBlockInput(PixelImageBlock)(DamVideoBlockInput.prototype, "previewImage");
+
+        // Default a missing preview image to an empty one, so content that was stored before the block had
+        // one loads as a child block. `Expose` is what makes the transform run when the stored data has no
+        // preview image at all, `ChildBlock` alone leaves it undefined.
+        Expose()(DamVideoBlockData.prototype, "previewImage");
+        Transform(({ value }) => (isBlockDataInterface(value) ? value : PixelImageBlock.blockDataFactory(value ?? {})), { toClassOnly: true })(
+            DamVideoBlockData.prototype,
+            "previewImage",
+        );
     }
 
     class Meta extends AnnotationBlockMeta {
@@ -301,4 +289,13 @@ export function createDamVideoBlock(
     });
 }
 
-export const DamVideoBlock = createDamVideoBlock({}, "DamVideo");
+export const DamVideoBlock = createDamVideoBlock(
+    {},
+    {
+        name: "DamVideo",
+        migrate: {
+            version: 1,
+            migrations: typeSafeBlockMigrationPipe([AddPreviewImageMigration]),
+        },
+    },
+);
diff --git a/packages/api/cms-api/src/dam/blocks/video/migrations/1-add-preview-image.migration.ts b/packages/api/cms-api/src/dam/blocks/video/migrations/1-add-preview-image.migration.ts
index 89010a0b496..0d85d83df5f 100644
--- a/packages/api/cms-api/src/dam/blocks/video/migrations/1-add-preview-image.migration.ts
+++ b/packages/api/cms-api/src/dam/blocks/video/migrations/1-add-preview-image.migration.ts
@@ -1,5 +1,3 @@
-import type { ClassConstructor } from "class-transformer";
-
 import { BlockMigration } from "../../../../blocks/migrations/BlockMigration";
 import type { BlockMigrationInterface } from "../../../../blocks/migrations/types";
 
@@ -13,29 +11,11 @@ interface From {
 
 type To = From;
 
-/**
- * Version 1 of every block created by `createDamVideoBlock`: the preview image the block gained after its
- * first release.
- *
- * The migration is always part of the chain so that version 1 means the same thing for every block the
- * factory creates, no matter what it supports. For a block without preview image support it only marks the
- * data as up to date, which keeps the version numbers stable when `supports` is widened later on.
- */
-export function buildAddPreviewImageMigration({
-    supportsPreviewImage,
-}: {
-    supportsPreviewImage: boolean;
-}): ClassConstructor<BlockMigrationInterface> {
-    return class AddPreviewImageMigration extends BlockMigration<(from: From) => To> implements BlockMigrationInterface {
-        public readonly toVersion = 1;
-
-        protected migrate(props: From): To {
-            if (!supportsPreviewImage) {
-                return props;
-            }
+export class AddPreviewImageMigration extends BlockMigration<(from: From) => To> implements BlockMigrationInterface {
+    public readonly toVersion = 1;
 
-            // Keep the preview image of a block that stored one without versioning its data.
-            return { ...props, previewImage: props.previewImage ?? {} };
-        }
-    };
+    protected migrate(props: From): To {
+        // Keep the preview image of data that has one but was never versioned.
+        return { ...props, previewImage: props.previewImage ?? {} };
+    }
 }

From c41b08c96b34d915daebafe3a662f28711a4e001 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 8 Sep 2026 15:23:28 +0000
Subject: [PATCH 15/15] docs: Describe the DamVideo preview image default
 instead of migrations

The factory no longer reserves a version, so own migrations start with 1 like
for any other block. What a project needs to know is that a missing preview
image is defaulted on load and that migrateBlocks persists it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017hbMWudfh8zx48grTo47Bz
---
 .../2-core-concepts/2-blocks/4-factories.mdx  | 29 ++++++++++---------
 1 file changed, 15 insertions(+), 14 deletions(-)

diff --git a/docs/docs/2-core-concepts/2-blocks/4-factories.mdx b/docs/docs/2-core-concepts/2-blocks/4-factories.mdx
index c31372bc9d1..e9e7159e84c 100644
--- a/docs/docs/2-core-concepts/2-blocks/4-factories.mdx
+++ b/docs/docs/2-core-concepts/2-blocks/4-factories.mdx
@@ -256,31 +256,32 @@ Unsupported options are part of neither the block's data nor its input, so they
 Values that were stored before an option was left out are kept: the block loads them and saves them again, so narrowing `supports` doesn't remove them from existing content.
 Note that such a value is no longer treated as a child block, so a preview image kept this way isn't part of the block index either.
 
-#### Migrations
+#### Preview image of existing content
 
-The factory brings its own migration for the preview image the block gained after its first release.
-It runs for every block the factory creates, so replacing a block a project already has migrates content that was stored before the preview image existed.
+A block that supports the preview image defaults a missing one to an empty preview image when it loads content.
+So replacing a block a project already has works without a migration: content stored before the preview image existed loads as a child block instead of leaving the field undefined.
 
-That migration occupies version 1, so own migrations start with 2.
-The factory throws when a passed `version` or `toVersion` is 1:
+The default applies on read, which also covers content that no migration reaches — for instance content stored while `supports` left the preview image out, before it was widened to include it.
+
+Run `migrateBlocks` to write the defaulted data back:
+
+```bash
+pnpm console migrateBlocks
+```
+
+Without it the default still applies whenever a block is loaded, it just isn't persisted until the content is saved.
+
+Own migrations are passed via `migrate` and start with version 1, like for any other block:
 
 ```ts title="teaser-video.block.ts"
 import { createDamVideoBlock, typeSafeBlockMigrationPipe } from "@dextinity/cms-api";
 
 export const TeaserVideoBlock = createDamVideoBlock(
     { supports: ["controls"] },
-    { name: "TeaserVideo", migrate: { version: 2, migrations: typeSafeBlockMigrationPipe([AddSomethingMigration]) } },
+    { name: "TeaserVideo", migrate: { version: 1, migrations: typeSafeBlockMigrationPipe([AddSomethingMigration]) } },
 );
 ```
 
-Run `migrateBlocks` to write the migrated data back:
-
-```bash
-pnpm console migrateBlocks
-```
-
-Without it the migration still applies whenever a block is loaded, it just isn't persisted until the content is saved.
-
 ### Admin
 
 Use the `createDamVideoBlock` factory: