@payloadcms/codemod 4.0.0-internal.8001944 → 4.0.0-internal.934870d

package/README.md

@@ -87,11 +87,14 @@ The tool loads your project via [ts-morph](https://ts-morph.com/), using your `t
 - `globals-components-edit`: Globals: rename `admin.components.elements` to `admin.components.edit` and hoist `Description` to top-level `admin.components.Description` to match Collection conventions.
 - `migrate-force-select`: migrates `forceSelect: { ... }` on Collection/Global configs to a `select` function that augments the caller's `select` when present and returns `undefined` (preserving full-document reads) when not. Shallow values become a spread (`{ ...select, ... }`); nested values use `deepMergeSimple` from `payload/shared` (auto-imported) to preserve the previous deep-merge semantics. Non-literal values, sibling `select` already present, and unsupported member kinds are surfaced as notes for manual review.
 - `migrate-field-component-types`: replaces field component aliases—including concrete fields, canonical generics, labels, descriptions, errors, diffs, and block row labels—with the corresponding props types wrapped in `React.FC`. Generic arguments are preserved. Explicit class components, re-exports, namespace references, and inline imports are left unchanged with notes for manual migration.
+- `rename-diff-value-props`: renames the `comparisonValue` and `versionValue` props read by custom Diff components to `valueFrom` and `valueTo`. Detects components whose props are typed with a Diff type imported from `payload`, in either the v3 component form (`TextFieldDiffClientComponent`) or the props form (`TextFieldDiffClientProps`), including same-file type aliases and interfaces built from one. Renames destructured props (along with the local variables they declare, unless the new name is already taken), `props.comparisonValue` and `props['comparisonValue']` reads, and `TextFieldDiffClientProps['comparisonValue']` indexed access types. Untyped components are not detected; remaining old prop names in property positions (e.g. JSX attributes passed to other components) are surfaced as notes in files that import a Diff type.
 - `migrate-block-references-to-blocks`: renames blocks field `blockReferences` configs to `blocks`, and removes a sibling `blocks: []` placeholder when present. If a non-empty `blocks` sibling already exists, the transform leaves the field untouched and surfaces a note for manual review.
 - `migrate-hide-api-url`: migrates `admin.hideAPIURL: true` to `admin.components.views.edit.api.tab.condition: () => false` on collection and global configs.
 - `migrate-aliased-exports`: rewrites imports of types and utilities that used to be re-exported from `@payloadcms/ui` and `@payloadcms/next/utilities` to their canonical sources in `payload` / `payload/shared`.
 - `migrate-payload-request-creation`: renames named request-helper and admin-context imports from `payload` and `payload/internal`. Calls migrate only with a plain identifier payload and either `{}` or an initialized local `const` options identifier whose type exposes all seven old option properties (or is `any`). The generated argument captures payload first and forwards only `context`, `depth`, `fallbackLocale`, `locale`, `req`, `urlSuffix`, and `user` through getters, preserving inherited getters, read order, and async rejection behavior. Existing `CreateLocalReqOptions` named imports from `payload` become options-only usages of `Omit<CreatePayloadRequestArgs, 'payload'>`; relative/private imports of that internal type require manual migration. Unsupported shapes, type usages, and collisions leave the affected binding unchanged with notes.
+- `migrate-admin-context-properties`: rewrites reads of `headers` and `languageCode`, removed from `AdminContext` in v4, to `req.headers` and `req.i18n.language` (`i18n.language` on `PartialAdminContext`). Covers `initAdminContext()` results (property access, destructures, and `const` bindings), parameters and variables typed as `AdminContext`, and `Pick<AdminContext, ...>` and `AdminContext['...']` types. Drops both arguments from `getRootLayoutData()` calls, then drops destructured bindings that are no longer read. Element access such as `context['headers']` and `Pick` types that only pick removed properties are left unchanged with notes. Run after `migrate-payload-request-creation`; the default run order handles this.
 - `migrate-document-title-context`: migrates `title` and `setDocumentTitle` destructured from `useDocumentInfo()` to `useDocumentTitle()`. They were removed from `DocumentInfoContext` in v4 and now live on `DocumentTitleContext`.
+- `migrate-sharp-to-transformer`: moves a top-level `sharp` dependency and per-collection Sharp-specific `upload` options (`resizeOptions`, `imageSizes`, `formatOptions`, `trimOptions`, `constructorOptions`, `withMetadata`, `crop`, `focalPoint`) into `sharpTransformer({ collections })`, registered under `upload.transformers`. Appends to an existing `transformers` array instead of overwriting it, and no-ops if a `sharpTransformer` call is already present. **Limitations:** only inline `buildConfig({...})` object literals and inline collection/`upload` object literals are migrated; a dynamic `collections` array, an externally-defined collection, or a non-inline `upload` object are left untouched with a note for manual review. A collection's `upload` object built from a spread (e.g. `upload: { ...sharedUploadConfig }`) is noted for manual review, since Sharp-specific fields hidden inside the spread aren't visible to the transform and are left un-migrated. Surfaces a note reminding you to install `@payloadcms/transformer-sharp` (`pnpm add @payloadcms/transformer-sharp`). The transform preserves AST structure but does not re-format output. Run `prettier --write` (or your project's formatter) after applying.
 - `migrate-storage-adapters-to-config`: moves storage adapter factory calls (`s3Storage`, `gcsStorage`, `azureStorage`, `r2Storage`, `vercelBlobStorage`) from `plugins` to the new top-level `storage` array. Removes `plugins` if it becomes empty after the move. **Limitations:** aliased imports (e.g. `import { s3Storage as myS3 }`) are not detected; rename any aliases to the canonical factory name before running, or migrate those calls manually. The transform preserves AST structure but does not re-format output. Run `prettier --write` (or your project's formatter) after applying.
 - `rename-storage-adapters-to-storage`: renames the top-level `storageAdapters` config property to `storage`. Skips any object that already has a `storage` property. Run this if you previously ran `migrate-storage-adapters-to-config` and need to update the property name.
 - `migrate-azure-chunk-large-files`: removes the `chunkLargeFiles` option from `azureStorage` `clientUploads` config. Chunked client uploads are the default in v4, so the flag no longer exists; `clientUploads: { chunkLargeFiles: true }` collapses to `clientUploads: true`. Surfaces a note when `chunkLargeFiles: false` was removed, since v4 can no longer disable chunking (and its broader CORS requirements apply).
@@ -100,6 +103,7 @@ The tool loads your project via [ts-morph](https://ts-morph.com/), using your `t
 - `migrate-db-types-subpath`: rewrites imports from the removed `/types` subpath exports of `@payloadcms/drizzle`, `@payloadcms/db-postgres`, `@payloadcms/db-sqlite`, `@payloadcms/db-vercel-postgres`, and `@payloadcms/db-d1-sqlite` to their main entry points. Also handles re-export declarations and `declare module` augmentations.
 - `migrate-next-subpath-exports`: rewrites imports, re-exports, and string-literal component paths from the removed `@payloadcms/next/client`, `@payloadcms/next/rsc`, and `@payloadcms/next/templates` subpaths to their canonical `@payloadcms/ui` or `@payloadcms/ui/rsc` sources. After running, regenerate the import map with `payload generate:importmap`.
 - `migrate-next-generate-viewport-export`: adds a `generateViewport` export to app router layout files that already use Payload's shared Next.js layout, preserving Next.js viewport behavior without touching custom viewport implementations.
+- `migrate-lexical-is-html-element`: rewrites imports of the removed `isHTMLElement` utility from `@payloadcms/richtext-lexical` (and `/client`) to its canonical source, `lexical`, splitting it out of mixed imports and merging into an existing `lexical` import when present. Surfaces a note reminding you that `lexical` is now a required dependency (`pnpm add lexical`).
 - `migrate-after-operation-read`: rewrites `operation === 'read'` checks inside collection `afterOperation` hooks to handle the `find` and `findByID` operations (the deprecated `'read'` value was removed). Handles `===`/`!==`/`==`/`!=` against a destructured (or aliased) or property-accessed `operation` argument. Leaves `beforeOperation` (which still uses `'read'`) untouched, and surfaces notes for non-inline hooks and `switch` statements that need manual review.
 - `migrate-versions-default`: adds `versions: false` to every `CollectionConfig` or `GlobalConfig` object that does not already have a `versions` property. Preserves the previous opt-in behaviour now that `versions` defaults to `true` for both collections and globals. Detects the three common annotation forms: `: CollectionConfig`, `satisfies GlobalConfig`, and `as CollectionConfig`.
 - `migrate-authorship-default`: adds `authorship: false` to every `CollectionConfig` or `GlobalConfig` object that does not already have an `authorship` property. Preserves the previous behaviour now that authorship tracking (`createdBy` / `updatedBy`) is enabled by default for both collections and globals. Detects the three common annotation forms: `: CollectionConfig`, `satisfies GlobalConfig`, and `as CollectionConfig`.

package/dist/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAmC3C,eAAO,MAAM,UAAU,EAAE,SAAS,EAiCjC,CAAA"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAsC3C,eAAO,MAAM,UAAU,EAAE,SAAS,EAoCjC,CAAA"}

package/dist/registry.js

@@ -1,6 +1,7 @@
 import { addOverrideAccessTrue } from './transforms/add-override-access-true/index.js';
 import { exampleNoop } from './transforms/example-noop/index.js';
 import { globalsComponentsEdit } from './transforms/globals-components-edit/index.js';
+import { migrateAdminContextProperties } from './transforms/migrate-admin-context-properties/index.js';
 import { migrateAfterOperationRead } from './transforms/migrate-after-operation-read/index.js';
 import { migrateAliasedExports } from './transforms/migrate-aliased-exports/index.js';
 import { migrateAuthorshipDefault } from './transforms/migrate-authorship-default/index.js';
@@ -18,6 +19,7 @@ import { migrateListViewSelectAPI } from './transforms/migrate-list-view-select-
 import { migrateNextGenerateViewportExport } from './transforms/migrate-next-generate-viewport-export/index.js';
 import { migrateNextSubpathExports } from './transforms/migrate-next-subpath-exports/index.js';
 import { migratePayloadRequestCreation } from './transforms/migrate-payload-request-creation/index.js';
+import { migrateSharpToTransformer } from './transforms/migrate-sharp-to-transformer/index.js';
 import { migrateSlugField } from './transforms/migrate-slug-field/index.js';
 import { migrateStorageAdaptersToConfig } from './transforms/migrate-storage-adapters-to-config/index.js';
 import { migrateVersionsDefault } from './transforms/migrate-versions-default/index.js';
@@ -27,6 +29,7 @@ import { removeLocalizeStatusConfig } from './transforms/remove-localize-status-
 import { removePublishSpecificLocale } from './transforms/remove-publish-specific-locale/index.js';
 import { removeStorageAlwaysInsertFields } from './transforms/remove-storage-always-insert-fields/index.js';
 import { removeVersionsTrue } from './transforms/remove-versions-true/index.js';
+import { renameDiffValueProps } from './transforms/rename-diff-value-props/index.js';
 import { renameExperimentalTableFeature } from './transforms/rename-experimental-table-feature/index.js';
 import { renameStorageAdaptersToStorage } from './transforms/rename-storage-adapters-to-storage/index.js';
 import { renameTypescriptSchemaToJsonSchema } from './transforms/rename-typescript-schema-to-json-schema/index.js';
@@ -40,11 +43,14 @@ export const transforms = [
     migrateDisabledFields,
     migrateForceSelect,
     migrateFieldComponentTypes,
+    renameDiffValueProps,
     migrateAliasedExports,
     migratePayloadRequestCreation,
+    migrateAdminContextProperties,
     migrateBlockReferencesToBlocks,
     migrateBuildScript,
     migrateDocumentTitleContext,
+    migrateSharpToTransformer,
     migrateStorageAdaptersToConfig,
     migrateAzureChunkLargeFiles,
     renameStorageAdaptersToStorage,

package/dist/registry.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/registry.ts"],"sourcesContent":["import type { Transform } from './types.js'\n\nimport { addOverrideAccessTrue } from './transforms/add-override-access-true/index.js'\nimport { exampleNoop } from './transforms/example-noop/index.js'\nimport { globalsComponentsEdit } from './transforms/globals-components-edit/index.js'\nimport { migrateAfterOperationRead } from './transforms/migrate-after-operation-read/index.js'\nimport { migrateAliasedExports } from './transforms/migrate-aliased-exports/index.js'\nimport { migrateAuthorshipDefault } from './transforms/migrate-authorship-default/index.js'\nimport { migrateAzureChunkLargeFiles } from './transforms/migrate-azure-chunk-large-files/index.js'\nimport { migrateBlockReferencesToBlocks } from './transforms/migrate-block-references-to-blocks/index.js'\nimport { migrateBuildScript } from './transforms/migrate-build-script/index.js'\nimport { migrateDbTypesSubpath } from './transforms/migrate-db-types-subpath/index.js'\nimport { migrateDisabledFields } from './transforms/migrate-disabled-fields/index.js'\nimport { migrateDocumentTitleContext } from './transforms/migrate-document-title-context/index.js'\nimport { migrateFieldComponentTypes } from './transforms/migrate-field-component-types/index.js'\nimport { migrateForceSelect } from './transforms/migrate-force-select/index.js'\nimport { migrateHideAPIURL } from './transforms/migrate-hide-api-url/index.js'\nimport { migrateImportExportHooks } from './transforms/migrate-import-export-hooks/index.js'\nimport { migrateListViewSelectAPI } from './transforms/migrate-list-view-select-api/index.js'\nimport { migrateNextGenerateViewportExport } from './transforms/migrate-next-generate-viewport-export/index.js'\nimport { migrateNextSubpathExports } from './transforms/migrate-next-subpath-exports/index.js'\nimport { migratePayloadRequestCreation } from './transforms/migrate-payload-request-creation/index.js'\nimport { migrateSlugField } from './transforms/migrate-slug-field/index.js'\nimport { migrateStorageAdaptersToConfig } from './transforms/migrate-storage-adapters-to-config/index.js'\nimport { migrateVersionsDefault } from './transforms/migrate-versions-default/index.js'\nimport { removeDefaultLocalePublishOption } from './transforms/remove-default-locale-publish-option/index.js'\nimport { removeGroupByTrue } from './transforms/remove-group-by-true/index.js'\nimport { removeLocalizeStatusConfig } from './transforms/remove-localize-status-config/index.js'\nimport { removePublishSpecificLocale } from './transforms/remove-publish-specific-locale/index.js'\nimport { removeStorageAlwaysInsertFields } from './transforms/remove-storage-always-insert-fields/index.js'\nimport { removeVersionsTrue } from './transforms/remove-versions-true/index.js'\nimport { renameExperimentalTableFeature } from './transforms/rename-experimental-table-feature/index.js'\nimport { renameStorageAdaptersToStorage } from './transforms/rename-storage-adapters-to-storage/index.js'\nimport { renameTypescriptSchemaToJsonSchema } from './transforms/rename-typescript-schema-to-json-schema/index.js'\n\nexport const transforms: Transform[] = [\n  exampleNoop,\n  addOverrideAccessTrue,\n  migrateAfterOperationRead,\n  migrateHideAPIURL,\n  globalsComponentsEdit,\n  migrateListViewSelectAPI,\n  migrateDisabledFields,\n  migrateForceSelect,\n  migrateFieldComponentTypes,\n  migrateAliasedExports,\n  migratePayloadRequestCreation,\n  migrateBlockReferencesToBlocks,\n  migrateBuildScript,\n  migrateDocumentTitleContext,\n  migrateStorageAdaptersToConfig,\n  migrateAzureChunkLargeFiles,\n  renameStorageAdaptersToStorage,\n  migrateImportExportHooks,\n  migrateDbTypesSubpath,\n  migrateNextGenerateViewportExport,\n  migrateNextSubpathExports,\n  migrateSlugField,\n  migrateVersionsDefault,\n  migrateAuthorshipDefault,\n  removeDefaultLocalePublishOption,\n  removeGroupByTrue,\n  removeLocalizeStatusConfig,\n  removeVersionsTrue,\n  removePublishSpecificLocale,\n  removeStorageAlwaysInsertFields,\n  renameTypescriptSchemaToJsonSchema,\n  renameExperimentalTableFeature,\n]\n"],"names":["addOverrideAccessTrue","exampleNoop","globalsComponentsEdit","migrateAfterOperationRead","migrateAliasedExports","migrateAuthorshipDefault","migrateAzureChunkLargeFiles","migrateBlockReferencesToBlocks","migrateBuildScript","migrateDbTypesSubpath","migrateDisabledFields","migrateDocumentTitleContext","migrateFieldComponentTypes","migrateForceSelect","migrateHideAPIURL","migrateImportExportHooks","migrateListViewSelectAPI","migrateNextGenerateViewportExport","migrateNextSubpathExports","migratePayloadRequestCreation","migrateSlugField","migrateStorageAdaptersToConfig","migrateVersionsDefault","removeDefaultLocalePublishOption","removeGroupByTrue","removeLocalizeStatusConfig","removePublishSpecificLocale","removeStorageAlwaysInsertFields","removeVersionsTrue","renameExperimentalTableFeature","renameStorageAdaptersToStorage","renameTypescriptSchemaToJsonSchema","transforms"],"mappings":"AAEA,SAASA,qBAAqB,QAAQ,iDAAgD;AACtF,SAASC,WAAW,QAAQ,qCAAoC;AAChE,SAASC,qBAAqB,QAAQ,gDAA+C;AACrF,SAASC,yBAAyB,QAAQ,qDAAoD;AAC9F,SAASC,qBAAqB,QAAQ,gDAA+C;AACrF,SAASC,wBAAwB,QAAQ,mDAAkD;AAC3F,SAASC,2BAA2B,QAAQ,wDAAuD;AACnG,SAASC,8BAA8B,QAAQ,2DAA0D;AACzG,SAASC,kBAAkB,QAAQ,6CAA4C;AAC/E,SAASC,qBAAqB,QAAQ,iDAAgD;AACtF,SAASC,qBAAqB,QAAQ,gDAA+C;AACrF,SAASC,2BAA2B,QAAQ,uDAAsD;AAClG,SAASC,0BAA0B,QAAQ,sDAAqD;AAChG,SAASC,kBAAkB,QAAQ,6CAA4C;AAC/E,SAASC,iBAAiB,QAAQ,6CAA4C;AAC9E,SAASC,wBAAwB,QAAQ,oDAAmD;AAC5F,SAASC,wBAAwB,QAAQ,qDAAoD;AAC7F,SAASC,iCAAiC,QAAQ,8DAA6D;AAC/G,SAASC,yBAAyB,QAAQ,qDAAoD;AAC9F,SAASC,6BAA6B,QAAQ,yDAAwD;AACtG,SAASC,gBAAgB,QAAQ,2CAA0C;AAC3E,SAASC,8BAA8B,QAAQ,2DAA0D;AACzG,SAASC,sBAAsB,QAAQ,iDAAgD;AACvF,SAASC,gCAAgC,QAAQ,6DAA4D;AAC7G,SAASC,iBAAiB,QAAQ,6CAA4C;AAC9E,SAASC,0BAA0B,QAAQ,sDAAqD;AAChG,SAASC,2BAA2B,QAAQ,uDAAsD;AAClG,SAASC,+BAA+B,QAAQ,4DAA2D;AAC3G,SAASC,kBAAkB,QAAQ,6CAA4C;AAC/E,SAASC,8BAA8B,QAAQ,0DAAyD;AACxG,SAASC,8BAA8B,QAAQ,2DAA0D;AACzG,SAASC,kCAAkC,QAAQ,gEAA+D;AAElH,OAAO,MAAMC,aAA0B;IACrC/B;IACAD;IACAG;IACAW;IACAZ;IACAc;IACAN;IACAG;IACAD;IACAR;IACAe;IACAZ;IACAC;IACAG;IACAU;IACAf;IACAwB;IACAf;IACAN;IACAQ;IACAC;IACAE;IACAE;IACAjB;IACAkB;IACAC;IACAC;IACAG;IACAF;IACAC;IACAI;IACAF;CACD,CAAA"}
+{"version":3,"sources":["../src/registry.ts"],"sourcesContent":["import type { Transform } from './types.js'\n\nimport { addOverrideAccessTrue } from './transforms/add-override-access-true/index.js'\nimport { exampleNoop } from './transforms/example-noop/index.js'\nimport { globalsComponentsEdit } from './transforms/globals-components-edit/index.js'\nimport { migrateAdminContextProperties } from './transforms/migrate-admin-context-properties/index.js'\nimport { migrateAfterOperationRead } from './transforms/migrate-after-operation-read/index.js'\nimport { migrateAliasedExports } from './transforms/migrate-aliased-exports/index.js'\nimport { migrateAuthorshipDefault } from './transforms/migrate-authorship-default/index.js'\nimport { migrateAzureChunkLargeFiles } from './transforms/migrate-azure-chunk-large-files/index.js'\nimport { migrateBlockReferencesToBlocks } from './transforms/migrate-block-references-to-blocks/index.js'\nimport { migrateBuildScript } from './transforms/migrate-build-script/index.js'\nimport { migrateDbTypesSubpath } from './transforms/migrate-db-types-subpath/index.js'\nimport { migrateDisabledFields } from './transforms/migrate-disabled-fields/index.js'\nimport { migrateDocumentTitleContext } from './transforms/migrate-document-title-context/index.js'\nimport { migrateFieldComponentTypes } from './transforms/migrate-field-component-types/index.js'\nimport { migrateForceSelect } from './transforms/migrate-force-select/index.js'\nimport { migrateHideAPIURL } from './transforms/migrate-hide-api-url/index.js'\nimport { migrateImportExportHooks } from './transforms/migrate-import-export-hooks/index.js'\nimport { migrateListViewSelectAPI } from './transforms/migrate-list-view-select-api/index.js'\nimport { migrateNextGenerateViewportExport } from './transforms/migrate-next-generate-viewport-export/index.js'\nimport { migrateNextSubpathExports } from './transforms/migrate-next-subpath-exports/index.js'\nimport { migratePayloadRequestCreation } from './transforms/migrate-payload-request-creation/index.js'\nimport { migrateSharpToTransformer } from './transforms/migrate-sharp-to-transformer/index.js'\nimport { migrateSlugField } from './transforms/migrate-slug-field/index.js'\nimport { migrateStorageAdaptersToConfig } from './transforms/migrate-storage-adapters-to-config/index.js'\nimport { migrateVersionsDefault } from './transforms/migrate-versions-default/index.js'\nimport { removeDefaultLocalePublishOption } from './transforms/remove-default-locale-publish-option/index.js'\nimport { removeGroupByTrue } from './transforms/remove-group-by-true/index.js'\nimport { removeLocalizeStatusConfig } from './transforms/remove-localize-status-config/index.js'\nimport { removePublishSpecificLocale } from './transforms/remove-publish-specific-locale/index.js'\nimport { removeStorageAlwaysInsertFields } from './transforms/remove-storage-always-insert-fields/index.js'\nimport { removeVersionsTrue } from './transforms/remove-versions-true/index.js'\nimport { renameDiffValueProps } from './transforms/rename-diff-value-props/index.js'\nimport { renameExperimentalTableFeature } from './transforms/rename-experimental-table-feature/index.js'\nimport { renameStorageAdaptersToStorage } from './transforms/rename-storage-adapters-to-storage/index.js'\nimport { renameTypescriptSchemaToJsonSchema } from './transforms/rename-typescript-schema-to-json-schema/index.js'\n\nexport const transforms: Transform[] = [\n  exampleNoop,\n  addOverrideAccessTrue,\n  migrateAfterOperationRead,\n  migrateHideAPIURL,\n  globalsComponentsEdit,\n  migrateListViewSelectAPI,\n  migrateDisabledFields,\n  migrateForceSelect,\n  migrateFieldComponentTypes,\n  renameDiffValueProps,\n  migrateAliasedExports,\n  migratePayloadRequestCreation,\n  migrateAdminContextProperties,\n  migrateBlockReferencesToBlocks,\n  migrateBuildScript,\n  migrateDocumentTitleContext,\n  migrateSharpToTransformer,\n  migrateStorageAdaptersToConfig,\n  migrateAzureChunkLargeFiles,\n  renameStorageAdaptersToStorage,\n  migrateImportExportHooks,\n  migrateDbTypesSubpath,\n  migrateNextGenerateViewportExport,\n  migrateNextSubpathExports,\n  migrateSlugField,\n  migrateVersionsDefault,\n  migrateAuthorshipDefault,\n  removeDefaultLocalePublishOption,\n  removeGroupByTrue,\n  removeLocalizeStatusConfig,\n  removeVersionsTrue,\n  removePublishSpecificLocale,\n  removeStorageAlwaysInsertFields,\n  renameTypescriptSchemaToJsonSchema,\n  renameExperimentalTableFeature,\n]\n"],"names":["addOverrideAccessTrue","exampleNoop","globalsComponentsEdit","migrateAdminContextProperties","migrateAfterOperationRead","migrateAliasedExports","migrateAuthorshipDefault","migrateAzureChunkLargeFiles","migrateBlockReferencesToBlocks","migrateBuildScript","migrateDbTypesSubpath","migrateDisabledFields","migrateDocumentTitleContext","migrateFieldComponentTypes","migrateForceSelect","migrateHideAPIURL","migrateImportExportHooks","migrateListViewSelectAPI","migrateNextGenerateViewportExport","migrateNextSubpathExports","migratePayloadRequestCreation","migrateSharpToTransformer","migrateSlugField","migrateStorageAdaptersToConfig","migrateVersionsDefault","removeDefaultLocalePublishOption","removeGroupByTrue","removeLocalizeStatusConfig","removePublishSpecificLocale","removeStorageAlwaysInsertFields","removeVersionsTrue","renameDiffValueProps","renameExperimentalTableFeature","renameStorageAdaptersToStorage","renameTypescriptSchemaToJsonSchema","transforms"],"mappings":"AAEA,SAASA,qBAAqB,QAAQ,iDAAgD;AACtF,SAASC,WAAW,QAAQ,qCAAoC;AAChE,SAASC,qBAAqB,QAAQ,gDAA+C;AACrF,SAASC,6BAA6B,QAAQ,yDAAwD;AACtG,SAASC,yBAAyB,QAAQ,qDAAoD;AAC9F,SAASC,qBAAqB,QAAQ,gDAA+C;AACrF,SAASC,wBAAwB,QAAQ,mDAAkD;AAC3F,SAASC,2BAA2B,QAAQ,wDAAuD;AACnG,SAASC,8BAA8B,QAAQ,2DAA0D;AACzG,SAASC,kBAAkB,QAAQ,6CAA4C;AAC/E,SAASC,qBAAqB,QAAQ,iDAAgD;AACtF,SAASC,qBAAqB,QAAQ,gDAA+C;AACrF,SAASC,2BAA2B,QAAQ,uDAAsD;AAClG,SAASC,0BAA0B,QAAQ,sDAAqD;AAChG,SAASC,kBAAkB,QAAQ,6CAA4C;AAC/E,SAASC,iBAAiB,QAAQ,6CAA4C;AAC9E,SAASC,wBAAwB,QAAQ,oDAAmD;AAC5F,SAASC,wBAAwB,QAAQ,qDAAoD;AAC7F,SAASC,iCAAiC,QAAQ,8DAA6D;AAC/G,SAASC,yBAAyB,QAAQ,qDAAoD;AAC9F,SAASC,6BAA6B,QAAQ,yDAAwD;AACtG,SAASC,yBAAyB,QAAQ,qDAAoD;AAC9F,SAASC,gBAAgB,QAAQ,2CAA0C;AAC3E,SAASC,8BAA8B,QAAQ,2DAA0D;AACzG,SAASC,sBAAsB,QAAQ,iDAAgD;AACvF,SAASC,gCAAgC,QAAQ,6DAA4D;AAC7G,SAASC,iBAAiB,QAAQ,6CAA4C;AAC9E,SAASC,0BAA0B,QAAQ,sDAAqD;AAChG,SAASC,2BAA2B,QAAQ,uDAAsD;AAClG,SAASC,+BAA+B,QAAQ,4DAA2D;AAC3G,SAASC,kBAAkB,QAAQ,6CAA4C;AAC/E,SAASC,oBAAoB,QAAQ,gDAA+C;AACpF,SAASC,8BAA8B,QAAQ,0DAAyD;AACxG,SAASC,8BAA8B,QAAQ,2DAA0D;AACzG,SAASC,kCAAkC,QAAQ,gEAA+D;AAElH,OAAO,MAAMC,aAA0B;IACrClC;IACAD;IACAI;IACAW;IACAb;IACAe;IACAN;IACAG;IACAD;IACAkB;IACA1B;IACAe;IACAjB;IACAK;IACAC;IACAG;IACAS;IACAE;IACAhB;IACA0B;IACAjB;IACAN;IACAQ;IACAC;IACAG;IACAE;IACAlB;IACAmB;IACAC;IACAC;IACAG;IACAF;IACAC;IACAK;IACAF;CACD,CAAA"}

package/dist/runbook/payload-v4-upgrade.md

@@ -19,11 +19,11 @@ while the v3 packages are still installed:
 
 ## 1. Next.js 16
 
-Payload v4 requires Next 16. The command did not touch Next. Run Next's own recommended agent
+Payload v4 requires Next 16.4 or higher. The command did not touch Next. Run Next's own recommended agent
 workflow, which bumps Next + React and migrates the code as one unit:
 <https://nextjs.org/docs/app/guides/upgrading/version-16#use-an-ai-agent-recommended>
 
-Keep the resulting Next version within `>=16.2.6 <17` (the exact target is printed in the
+Keep the resulting Next version within `>=16.4.0 <17` (the exact target is printed in the
 upgrade report), since Next's `upgrade latest` may point past 16 in future.
 
 ## 2. Regenerate generated files

package/dist/runbook/v4.mdx

@@ -156,6 +156,31 @@ Run a typecheck after the codemod. Three patterns it cannot resolve:
 
 `payload.jobs.queue`, `run`, `runByID`, `cancel`, and `cancelByID` now also default `overrideAccess` to `false`. The option remains optional, but omitting it runs the corresponding `jobs.access.queue`, `jobs.access.run`, or `jobs.access.cancel` function. The codemod adds `overrideAccess: true` to these calls—including zero-argument `payload.jobs.run()` calls—to preserve Payload 3 behavior for review.
 
+### On-demand validation adds a `validate` operation
+
+The `Operation` type now includes `validate`. The `operation` argument for collection, global, and field `beforeValidate` and `beforeChange` hooks also includes `validate`.
+
+On-demand validation runs these hooks without saving the candidate. Update exhaustive operation checks and skip external side effects that should only run during `create` or `update`:
+
+```ts
+import type { CollectionBeforeChangeHook } from 'payload'
+
+const syncCustomer: CollectionBeforeChangeHook = async ({
+  data,
+  operation,
+}) => {
+  if (operation === 'validate') {
+    return data
+  }
+
+  await syncCustomerWithStripe(data)
+
+  return data
+}
+```
+
+Sanitized collection and global access types now require a `validate` key. Payload supplies this key during configuration sanitization and uses `update` access by default. Code that constructs a sanitized access object directly must add the key.
+
 ### Collection and Global Access Control callbacks receive `slug`
 
 Collection and Global Access Control callback arguments now include the document's `slug`. This additive property is unlikely to affect most projects, but code that manually invokes access callbacks or `executeAccess` must now pass `slug`. Code that validates, enumerates, or compares the exact callback argument shape may also need updating.
@@ -558,6 +583,39 @@ To migrate automatically, there's a codemod for this change available by running
 npx @payloadcms/codemod --transform migrate-field-component-types
 ```
 
+### Diff component props `comparisonValue` and `versionValue` renamed to `valueFrom` and `valueTo`
+
+Custom Diff Components (`admin.components.Diff`) receive the two field values being compared as `valueFrom` and `valueTo`. The `comparisonValue` and `versionValue` props have been removed from `FieldDiffClientProps` and `FieldDiffServerProps`, including every field-specific variant such as `TextFieldDiffClientProps`.
+
+| Old prop          | New prop    | Description                                      |
+| ----------------- | ----------- | ------------------------------------------------ |
+| `comparisonValue` | `valueFrom` | Field value from the version being compared from |
+| `versionValue`    | `valueTo`   | Field value from the version being compared to   |
+
+```diff
+  import type { TextFieldDiffClientProps } from 'payload'
+  import type React from 'react'
+
+  export const MyTextDiff: React.FC<TextFieldDiffClientProps> = ({
+-   comparisonValue,
+-   versionValue,
++   valueFrom,
++   valueTo,
+  }) => {
+    // ...
+  }
+```
+
+#### Codemod
+
+To migrate automatically, there's a codemod for this change available by running:
+
+```bash
+npx @payloadcms/codemod --transform rename-diff-value-props
+```
+
+The codemod updates functions whose props are typed with a Diff props or component type imported from `payload` (e.g. `TextFieldDiffClientProps`), or with a type in the same file built from one. It renames destructured props and reads such as `props.comparisonValue`. Untyped components and props passed on to other components (e.g. `<OtherDiff comparisonValue={...} />`) aren't changed automatically; the codemod prints a note for each leftover in files that import a Diff type.
+
 ### `DefaultValue` function variant is now typed to allow returning a `Promise` ([#17522](https://github.com/payloadcms/payload/pull/17522))
 
 The exported `DefaultValue` type's function variant previously declared a synchronous-only return type (`SerializableValue`), even though Payload has always awaited the result of a `defaultValue` function at runtime. The type now correctly reflects this and allows `Promise<SerializableValue> | SerializableValue`.
@@ -855,6 +913,49 @@ When a missing locale is already valid for the receiving API, optional chaining
 const locale = useLocale()?.code
 ```
 
+### `readOnly` removed from the `useField` return type
+
+The deprecated `readOnly` property has been removed from `FieldType`, the object returned by `useField`. `useField` already stopped returning it in 3.x, so it was always `undefined` at runtime.
+
+Read `readOnly` from your field component's props instead:
+
+````diff
+'use client'
+import type { TextFieldClientComponent } from 'payload'
+import { useField } from '@payloadcms/ui'
+
+-export const MyField: TextFieldClientComponent = ({ path }) => {
+-  const { readOnly, value } = useField({ path })
++export const MyField: TextFieldClientComponent = ({ path, readOnly }) => {
++  const { value } = useField({ path })
+
+### Deprecated `TableColumnsProvider` props removed
+
+The following deprecated props have been removed from `TableColumnsProvider` and its `TableColumnsProviderProps` type:
+
+- `docs`
+- `enableRowSelections`
+- `listPreferences`
+- `preferenceKey`
+- `renderRowTypes`
+- `setTable`
+- `sortColumnProps`
+- `tableAppearance`
+
+`TableColumnsProvider` has ignored these props since 3.26.0, when column state moved to the URL. Remove them where you render the provider. It now only accepts `children`, `collectionSlug`, `columnState`, and `LinkedCellOverride`.
+
+```diff
+<TableColumnsProvider
+  collectionSlug={collectionSlug}
+  columnState={columnState}
+- enableRowSelections
+- preferenceKey={preferenceKey}
+- tableAppearance="condensed"
+>
+  {children}
+</TableColumnsProvider>
+````
+
 ### RichText adapter `i18n` property removed
 
 The `i18n` property on `RichTextAdapter` (and its return type from adapter provider functions) has been removed. It was deprecated in v3 in favour of merging translations directly into `config.i18n.translations` inside the adapter provider.
@@ -916,6 +1017,52 @@ If an affected adapter or feature performs asynchronous work, move that work to
 
 The `transactionIDPromise` property on `PayloadRequest` has been removed. It was deprecated and unused — `transactionID` (which already supports `Promise<number | string>`) is the correct property to use for both resolved values and pending transactions.
 
+### `headers` and `languageCode` removed from `AdminContext`
+
+The `headers` and `languageCode` properties have been removed from `AdminContext`, the object returned by `initAdminContext`. Both duplicated values that are already available on `req`:
+
+```diff
+const context = await initAdminContext(args)
+
+-const userAgent = context.headers.get('user-agent')
++const userAgent = context.req.headers.get('user-agent')
+
+-const languageCode = context.languageCode
++const languageCode = context.req.i18n.language
+```
+
+`req.i18n.language` is typed as `string`. Cast it to `AcceptedLanguages` if you need the narrower type.
+
+`languageCode` has also been removed from `PartialAdminContext`. Use `i18n.language` instead. `getRootLayoutData` from `@payloadcms/ui` no longer accepts `headers` or `languageCode` and reads both from `req`.
+
+#### Codemod
+
+To migrate automatically, run:
+
+```bash
+npx @payloadcms/codemod --transform migrate-admin-context-properties
+```
+
+The codemod rewrites property reads and destructures on `initAdminContext()` results and on parameters or variables typed as `AdminContext` or `PartialAdminContext`. It also updates `Pick<AdminContext, ...>` and `AdminContext['...']` types and drops both arguments from `getRootLayoutData()` calls. Element access such as `context['headers']`, and contexts passed through your own wrapper functions, are left unchanged for manual migration.
+
+### `DiffMethod` type removed
+
+The deprecated `DiffMethod` type has been removed from `payload`. It mirrored an enum from `react-diff-viewer-continued`, which Payload no longer depends on. Remove any imports of `DiffMethod`.
+
+### `diffMethod` prop removed from Diff components
+
+Custom Diff components (`admin.components.Diff`) no longer receive a `diffMethod` prop. It has been removed from `FieldDiffClientProps` and every field-specific variant like `TextFieldDiffClientProps`. Payload always passed the same `'diffWordsWithSpace'` value, so the prop carried no information. Each Diff component handles its own diffing.
+
+Remove `diffMethod` from your props. If you passed it on to a diffing utility, pass `'diffWordsWithSpace'` directly instead:
+
+```diff
+  export const MyTextDiff: React.FC<TextFieldDiffClientProps> = ({
+-   diffMethod,
+    valueFrom,
+    valueTo,
+  }) => {
+```
+
 ### Collection `afterOperation` hook: `operation: 'read'` removed
 
 The deprecated `'read'` value for the `operation` argument of collection `afterOperation` hooks has been removed. Payload has not dispatched `afterOperation` with `operation: 'read'` for some time — the `find` and `findByID` operations report their own names (`'find'` and `'findByID'`) instead.
@@ -1025,13 +1172,22 @@ If you use a `declare module` augmentation to extend `GeneratedDatabaseSchema` (
 
 Run `npx @payloadcms/codemod --transform migrate-db-types-subpath` to migrate automatically. The codemod handles import declarations, re-export declarations, and `declare module` augmentations.
 
+### `findMigrationDir` removed from `@payloadcms/drizzle`
+
+The deprecated `findMigrationDir` re-export has been removed from `@payloadcms/drizzle`. Import it from `payload` instead:
+
+```diff
+- import { findMigrationDir } from '@payloadcms/drizzle'
++ import { findMigrationDir } from 'payload'
+```
+
 ### Minimum supported Node.js version is now 24.15.0 ([#16540](https://github.com/payloadcms/payload/pull/16540))
 
 The minimum supported Node.js version is now **24.15.0** (previously 18.20.2). Upgrade your runtime — along with any CI, Docker images, and deployment targets — to the latest node LTS version or newer before upgrading to 4.0.
 
-### Minimum supported Next.js version is now 16.2.6 ([#16537](https://github.com/payloadcms/payload/pull/16537))
+### Minimum supported Next.js version is now 16.4.0 ([#16537](https://github.com/payloadcms/payload/pull/16537))
 
-Older versions of Next.js are no longer supported. Update Next.js to **16.2.6** or newer.
+Older versions of Next.js are no longer supported. Update Next.js to **16.4.0** or newer.
 
 ### Minimum supported TypeScript version is now 6.0.3 ([#16692](https://github.com/payloadcms/payload/pull/16692))
 
@@ -1140,6 +1296,43 @@ The table feature is no longer experimental, so it drops its prefix.
 
 Stored content is unaffected.
 
+### Lexical: `LexicalEditorProps` renamed to `LexicalEditorArgs`
+
+The `LexicalEditorProps` type exported from `@payloadcms/richtext-lexical` has been renamed to `LexicalEditorArgs`. It describes the arguments of the `lexicalEditor` function, not component props. The shape is unchanged.
+
+````diff
+- import type { LexicalEditorProps } from '@payloadcms/richtext-lexical'
++ import type { LexicalEditorArgs } from '@payloadcms/richtext-lexical'
+
+### Lexical: `UploadDataImproved` replaced by `UploadData` ([#18606](https://github.com/payloadcms/payload/pull/18606))
+
+The internal `UploadDataImproved` type has been removed, and its definition is now used by the public `UploadData` type. Replace any `UploadDataImproved` imports and type references with `UploadData`:
+
+```ts
+import type { UploadData } from '@payloadcms/richtext-lexical'
+````
+
+### Lexical: the `version` of nodes is ignored
+
+Lexical deprecated the `version` property of serialized nodes, and now ignores it when it loads a document. Payload no longer reads it either.
+
+**Rich text written by the Payload 3.0 betas is no longer upgraded when it's loaded.** Payload used `version: 1` to detect two older shapes:
+
+- Block nodes whose fields were wrapped in an extra `data` object (`fields.data`)
+- Relationship and upload nodes that stored the whole related document in `value`, instead of its ID
+
+If your database may still contain rich text from the 3.0 betas, run `upgradeLexicalData` on the latest 3.x release before you upgrade to 4.0. It re-saves every document, which converts these shapes:
+
+```ts
+import { upgradeLexicalData } from '@payloadcms/richtext-lexical'
+
+await upgradeLexicalData({ payload })
+```
+
+**`version` is optional in the JSON schema of Lexical nodes.** The CLI and MCP no longer require it, and leave it out of the schema they show agents. They still accept it, so existing documents, which contain `version`, stay valid input.
+
+**Payload doesn't add or remove `version` when it saves rich text.** Rich text created by Lexical, like in the admin panel, still has `version: 1` on every node, because Lexical's JSON export writes it. Payload's own nodes used to write their own numbers instead (like `2` for blocks), and now write `1` as well. Rich text sent through the API, CLI or MCP is saved as sent, so it may not contain `version`. The generated types still include `version`, marked as deprecated, so don't rely on it being there.
+
 ### Field `typescriptSchema` renamed to `jsonSchema`
 
 `typescriptSchema` accepted JSON Schema, not TypeScript, so the name lied. Renamed to `jsonSchema`. Same shape, same array of transforms. The underlying schema is now also consumed by the MCP plugin for runtime validation, not just type generation.
@@ -1677,6 +1870,8 @@ If you typed `clientUploads.access`, replace `ClientUploadsAccess` with `UploadI
 
 #### If you maintain a custom storage adapter
 
+File versioning adds a required `GeneratedAdapter.copyFile` method. Copy `from` to `to` (complete storage keys) without changing the source, reject an existing destination, and return only once the destination is readable. `moveFile` stays optional. See [Custom Storage Adapters](../upload/storage-adapters) for the full contract.
+
 Replace `clientUploadContext` with `uploadReference` in generated file metadata and static handler parameters. `handleUpload` no longer receives it because Payload skips uploading files that are already stored.
 
 Set `uploadInstructions.enabled`. When false, Payload adds `adminHandler` to the import map without rendering it. When true, Payload also renders it and exposes the instructions and supporting endpoint.
@@ -1814,6 +2009,126 @@ azureStorage({
 
 Run `npx @payloadcms/codemod --transform migrate-azure-chunk-large-files` to remove the flag automatically (it collapses `clientUploads: { chunkLargeFiles: true }` to `clientUploads: true` and keeps any other `clientUploads` options).
 
+### Sharp moved out of core into `@payloadcms/transformer-sharp`
+
+Image resizing is no longer built into `payload` itself. It now ships as an official [file transformer](../upload/transformers), `@payloadcms/transformer-sharp`, that you register under `upload.transformers`.
+
+This affects four things:
+
+1. The top-level `sharp` config property has been removed. Passing a Sharp instance now happens through `sharpTransformer({ sharp })` instead.
+2. Per-collection Sharp options — `constructorOptions`, `formatOptions`, `resizeOptions`, `trimOptions`, and `withMetadata` — have been removed from `CollectionConfig['upload']`. They're now authored through `sharpTransformer({ collections })`.
+   - `imageSizes` has also been removed from `CollectionConfig['upload']`. Image sizes are now declared as `variants` on `sharpTransformer({ collections: { <slug>: { variants } } })`. The entries themselves (`name`, `width`, `height`, `generateImageName`, and so on) are unchanged. A collection that still sets `upload.imageSizes` fails the build.
+3. `sharp` is no longer a dependency of `payload` at all (previously a `devDependency`, not a runtime `dependency`). Install `@payloadcms/transformer-sharp` explicitly.
+4. The Sharp-specific types `SharpDependency`, `ImageUploadFormatOptions`, `ImageUploadTrimOptions`, and `SharpImageSizeOptions` are no longer exported from `payload`. Import `SharpDependency` from `@payloadcms/transformer-sharp`. For the option types, use `SharpCollectionConfig['formatOptions']`, `SharpCollectionConfig['trimOptions']`, and `NonNullable<SharpCollectionConfig['variants']>[number]` from the same package.
+
+```sh
+pnpm add @payloadcms/transformer-sharp
+```
+
+```diff
++ import { sharpTransformer } from '@payloadcms/transformer-sharp'
+  import { buildConfig } from 'payload'
+
+  export default buildConfig({
+    collections: [
+      {
+        slug: 'media',
+        upload: {
+-         resizeOptions: { width: 2048, height: 2048 },
+-         imageSizes: [{ name: 'thumbnail', width: 400, height: 300 }],
+        },
+      },
+    ],
+-   sharp,
+    upload: {
++     transformers: [
++       sharpTransformer({
++         sharp,
++         collections: {
++           media: {
++             resizeOptions: { width: 2048, height: 2048 },
++             variants: [{ name: 'thumbnail', width: 400, height: 300 }],
++           },
++         },
++       }),
++     ],
+    },
+  })
+```
+
+Run `npx @payloadcms/codemod --transform migrate-sharp-to-transformer` to migrate automatically. The codemod moves a top-level `sharp` dependency and inline collection Sharp options — including `crop` and `focalPoint` — into `sharpTransformer({ collections })` (writing `imageSizes` as `variants`), appends to an existing `upload.transformers` array if you already have one, and leaves anything it can't safely rewrite in place with a note — for example, a `collections` array built by a function call, or a collection defined outside the `buildConfig` call. Review those manually. For a config that already registers `sharpTransformer`, it only renames `imageSizes` to `variants` inside the existing `sharpTransformer` call and flags a leftover top-level `sharp` property; it doesn't move any remaining collection options.
+
+Your `variants`, `crop`, and `focalPoint` are readable at `collection.upload.variants`/`.crop`/`.focalPoint` on the **sanitized** config (for example `req.payload.collections.media.config.upload.variants`). Code that read the sanitized `upload.imageSizes` in 3.x must read `upload.variants` instead. `sharpTransformer` writes a projection of what you configure back onto the sanitized collection at startup, so the Admin Panel and the rest of core see the same configuration. For a collection configured on `sharpTransformer`, a `crop` or `focalPoint` set on the transformer replaces the collection's own value; one left unset there keeps the collection's. Neither `imageSizes` nor `variants` can be set on the collection at all.
+
+If you inject a custom Sharp build or version, pass it the same way:
+
+```diff
+- buildConfig({ sharp: myCustomSharp })
++ sharpTransformer({ sharp: myCustomSharp })
+```
+
+`sharpTransformer` can also resize images at request time (`/api/media/file/photo.png?width=400`). This is new in Payload 4 and **disabled by default**, so a migrated config keeps serving only the original file and your pre-generated `variants`. The codemod doesn't enable it. To opt in, pass `dynamic: true` or `dynamic: { collections: ['media'] }` — see [Dynamic (request-time) resizing](../upload/transformers#dynamic-request-time-resizing), and [Securing dynamic resizing](../upload/transformers#securing-dynamic-resizing) before enabling it on a publicly readable collection.
+
+#### The stored `sizes` field on upload documents is renamed to `variants`
+
+The group field that holds each generated image size on an upload document is now `variants` instead of `sizes`. Every place that reads or queries it changes:
+
+```diff
+- doc.sizes?.thumbnail?.url
++ doc.variants?.thumbnail?.url
+
+- where: { 'sizes.thumbnail.filename': { equals: 'photo-400x300.png' } }
++ where: { 'variants.thumbnail.filename': { equals: 'photo-400x300.png' } }
+
+- select: { sizes: { thumbnail: true } }
++ select: { variants: { thumbnail: true } }
+```
+
+GraphQL queries select `variants { thumbnail { url } }` instead of `sizes { thumbnail { url } }`, and regenerated types expose `variants?: { ... }` (and `variants?: T | { ... }` on the `*Select` types) in place of `sizes`. Update any frontend code that reads `media.sizes`, including values you pass to helpers such as `getBestFitFromSizes({ sizes: doc.variants })`.
+
+Existing documents must be migrated. Create the predefined migration for your database adapter and run it:
+
+<Banner type="warning">
+  Payload 4 uses `variants` as the top-level field for generated upload
+  variants. If an upload collection already defines a custom field named
+  `variants`, rename that field before you run the predefined migration. Choose
+  a new name, update your config, and write a custom migration that moves the
+  existing custom data from `variants` to the new field. Then run the predefined
+  `sizes-to-variants` migration. If legacy `sizes` data or columns and custom
+  `variants` data or columns are both present, the predefined migration stops
+  before it changes data or indexes. It cannot choose a new name or merge this
+  custom data for you.
+</Banner>
+
+```sh
+# MongoDB
+payload migrate:create --file @payloadcms/db-mongodb/sizes-to-variants
+# Postgres
+payload migrate:create --file @payloadcms/db-postgres/sizes-to-variants
+# Vercel Postgres
+payload migrate:create --file @payloadcms/db-vercel-postgres/sizes-to-variants
+# SQLite
+payload migrate:create --file @payloadcms/db-sqlite/sizes-to-variants
+# Cloudflare D1
+payload migrate:create --file @payloadcms/db-d1-sqlite/sizes-to-variants
+
+payload migrate
+```
+
+**Postgres and SQLite (including Vercel Postgres and D1):** the columns are renamed in place from `sizes_<name>_<property>` to `variants_<name>_<property>`, on each upload collection's table and its versions table, along with their indexes. Use the predefined migration above **instead of** a plain `payload migrate:create` for this change. A generated migration would drop the `sizes_*` columns and add new `variants_*` columns, losing the stored image size data. The predefined migration also writes the schema snapshot, so the next generated migration starts from the renamed columns.
+
+On MongoDB the migration renames `sizes` (and `version.sizes` on versions) with `$rename` and re-creates the indexes on those fields under the new path. Run the migration before the upgraded app writes to upload documents.
+
+#### The file endpoint changes once any transformer is registered
+
+Registering any transformer under `upload.transformers` — including `sharpTransformer()` with dynamic resizing off — routes every file request through the transformer-aware handler:
+
+- A file must belong to an upload document to be served. A file that exists in storage without a matching document now returns `404`.
+- For files whose MIME type a transformer declares (every image, with `sharpTransformer()`), `access.read` can run twice per request: once with `req.fileTransform` set to `true` to decide a possible transform, and once without it for an ordinary read. Keep `access.read` cheap, and use `req.fileTransform` to restrict transformed reads — see [Access control](../upload/transformers#access-control).
+- Responses produced by a transformer always carry Payload's CORS headers, which `modifyResponseHeaders` can't override.
+
+To link to a file from your own code, including with transformer query parameters, use the new `generatePayloadFileURL` helper (exported from `payload` and `payload/shared`). It always builds the access-controlled Payload file endpoint, so links never bypass `access.read` by pointing straight at storage.
+
 ### Storage adapters always insert the `prefix` field now — `alwaysInsertFields` removed
 
 The `alwaysInsertFields` option (on `cloudStoragePlugin` and every `storage-*` adapter: `-s3`, `-azure`, `-gcs`, `-r2`, `-vercel-blob`) has been removed. The behavior it used to opt into — always inserting the hidden `prefix` field into the collection schema — is now unconditional, so the schema stays consistent whether or not a collection configures a `prefix` and whether or not the plugin is `enabled`.
@@ -1829,6 +2144,12 @@ The `alwaysInsertFields` option (on `cloudStoragePlugin` and every `storage-*` a
 - Remove `alwaysInsertFields` from your storage adapter or `cloudStoragePlugin` config — it has no effect and no longer exists on the option types.
 - For Postgres, SQLite, or D1 projects, run `payload migrate:create` to generate the migration that adds the `prefix` column, then run `payload migrate` to apply it.
 
+### Upload collections retain originals and file history
+
+Upload collections now store `original` metadata and a `prefix` and `_objectKey` for each stored file (the main file, `original`, and each variant), so saved versions can find their files. New uploads keep their source under an `-original` filename. Update any code or infrastructure that relies on the old filename, URL, or object key.
+
+**Postgres and SQLite:** after updating, run `payload migrate:create`, check that it adds these columns to each upload collection table and its versions table, then run `payload migrate`. Existing rows keep `null` values until their next write.
+
 ### `FileSizeImproved` removed — use `FileSize` ([#16593](https://github.com/payloadcms/payload/pull/16593))
 
 `FileSizeImproved` has been merged into `FileSize`. The `url`, `width`, `height`, `filesize`, `mimeType`, and `filename` properties now accept `null` directly on `FileSize`, matching what the database stores for sizes that were not generated.

package/dist/transforms/migrate-admin-context-properties/basic.input.js

@@ -0,0 +1,32 @@
+import { getRootLayoutData } from '@payloadcms/ui/layouts/Root/getRootLayoutData';
+import { initAdminContext } from 'payload/internal';
+export async function getLayoutData(args) {
+    const context = await initAdminContext(args);
+    const { cookies, headers, languageCode, permissions, req, user } = context;
+    const data = await getRootLayoutData({
+        cookies,
+        headers,
+        importMap: args.importMap,
+        languageCode,
+        permissions,
+        req,
+        user
+    });
+    return {
+        data,
+        userAgent: context.headers.get('user-agent')
+    };
+}
+export async function getTheme(args) {
+    const { headers: requestHeaders, languageCode, user } = await initAdminContext(args);
+    return {
+        languageCode,
+        theme: requestHeaders.get('sec-ch-prefers-color-scheme'),
+        user
+    };
+}
+export const getUserAgent = async (args)=>(await initAdminContext(args)).headers.get('user-agent');
+export const getDirection = (context)=>context.languageCode === 'ar' ? 'rtl' : 'ltr';
+export const getAcceptLanguage = ({ headers })=>headers.get('accept-language');
+
+//# sourceMappingURL=basic.input.js.map

package/dist/transforms/migrate-admin-context-properties/basic.input.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/transforms/migrate-admin-context-properties/basic.input.ts"],"sourcesContent":["import type { AdminContext } from 'payload'\nimport type { InitAdminContextArgs } from 'payload/internal'\n\nimport { getRootLayoutData } from '@payloadcms/ui/layouts/Root/getRootLayoutData'\nimport { initAdminContext } from 'payload/internal'\n\ntype LayoutArgs = Pick<AdminContext, 'cookies' | 'headers' | 'languageCode' | 'req'>\n\ntype LanguageCode = AdminContext['languageCode']\n\nexport async function getLayoutData(args: InitAdminContextArgs) {\n  const context = await initAdminContext(args)\n\n  const { cookies, headers, languageCode, permissions, req, user } = context\n\n  const data = await getRootLayoutData({\n    cookies,\n    headers,\n    importMap: args.importMap,\n    languageCode,\n    permissions,\n    req,\n    user,\n  })\n\n  return { data, userAgent: context.headers.get('user-agent') }\n}\n\nexport async function getTheme(args: InitAdminContextArgs) {\n  const { headers: requestHeaders, languageCode, user } = await initAdminContext(args)\n\n  return { languageCode, theme: requestHeaders.get('sec-ch-prefers-color-scheme'), user }\n}\n\nexport const getUserAgent = async (args: InitAdminContextArgs) =>\n  (await initAdminContext(args)).headers.get('user-agent')\n\nexport const getDirection = (context: AdminContext) =>\n  context.languageCode === 'ar' ? 'rtl' : 'ltr'\n\nexport const getAcceptLanguage = ({ headers }: AdminContext) => headers.get('accept-language')\n"],"names":["getRootLayoutData","initAdminContext","getLayoutData","args","context","cookies","headers","languageCode","permissions","req","user","data","importMap","userAgent","get","getTheme","requestHeaders","theme","getUserAgent","getDirection","getAcceptLanguage"],"mappings":"AAGA,SAASA,iBAAiB,QAAQ,gDAA+C;AACjF,SAASC,gBAAgB,QAAQ,mBAAkB;AAMnD,OAAO,eAAeC,cAAcC,IAA0B;IAC5D,MAAMC,UAAU,MAAMH,iBAAiBE;IAEvC,MAAM,EAAEE,OAAO,EAAEC,OAAO,EAAEC,YAAY,EAAEC,WAAW,EAAEC,GAAG,EAAEC,IAAI,EAAE,GAAGN;IAEnE,MAAMO,OAAO,MAAMX,kBAAkB;QACnCK;QACAC;QACAM,WAAWT,KAAKS,SAAS;QACzBL;QACAC;QACAC;QACAC;IACF;IAEA,OAAO;QAAEC;QAAME,WAAWT,QAAQE,OAAO,CAACQ,GAAG,CAAC;IAAc;AAC9D;AAEA,OAAO,eAAeC,SAASZ,IAA0B;IACvD,MAAM,EAAEG,SAASU,cAAc,EAAET,YAAY,EAAEG,IAAI,EAAE,GAAG,MAAMT,iBAAiBE;IAE/E,OAAO;QAAEI;QAAcU,OAAOD,eAAeF,GAAG,CAAC;QAAgCJ;IAAK;AACxF;AAEA,OAAO,MAAMQ,eAAe,OAAOf,OACjC,AAAC,CAAA,MAAMF,iBAAiBE,KAAI,EAAGG,OAAO,CAACQ,GAAG,CAAC,cAAa;AAE1D,OAAO,MAAMK,eAAe,CAACf,UAC3BA,QAAQG,YAAY,KAAK,OAAO,QAAQ,MAAK;AAE/C,OAAO,MAAMa,oBAAoB,CAAC,EAAEd,OAAO,EAAgB,GAAKA,QAAQQ,GAAG,CAAC,mBAAkB"}

package/dist/transforms/migrate-admin-context-properties/basic.output.js

@@ -0,0 +1,30 @@
+import { getRootLayoutData } from '@payloadcms/ui/layouts/Root/getRootLayoutData';
+import { initAdminContext } from 'payload/internal';
+export async function getLayoutData(args) {
+    const context = await initAdminContext(args);
+    const { cookies, permissions, req, user } = context;
+    const data = await getRootLayoutData({
+        cookies,
+        importMap: args.importMap,
+        permissions,
+        req,
+        user
+    });
+    return {
+        data,
+        userAgent: context.req.headers.get('user-agent')
+    };
+}
+export async function getTheme(args) {
+    const { req: { headers: requestHeaders, i18n: { language: languageCode } }, user } = await initAdminContext(args);
+    return {
+        languageCode,
+        theme: requestHeaders.get('sec-ch-prefers-color-scheme'),
+        user
+    };
+}
+export const getUserAgent = async (args)=>(await initAdminContext(args)).req.headers.get('user-agent');
+export const getDirection = (context)=>context.req.i18n.language === 'ar' ? 'rtl' : 'ltr';
+export const getAcceptLanguage = ({ req: { headers } })=>headers.get('accept-language');
+
+//# sourceMappingURL=basic.output.js.map

package/dist/transforms/migrate-admin-context-properties/basic.output.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/transforms/migrate-admin-context-properties/basic.output.ts"],"sourcesContent":["import type { AdminContext } from 'payload'\nimport type { InitAdminContextArgs } from 'payload/internal'\n\nimport { getRootLayoutData } from '@payloadcms/ui/layouts/Root/getRootLayoutData'\nimport { initAdminContext } from 'payload/internal'\n\ntype LayoutArgs = Pick<AdminContext, 'cookies' | 'req'>\n\ntype LanguageCode = AdminContext['req']['i18n']['language']\n\nexport async function getLayoutData(args: InitAdminContextArgs) {\n  const context = await initAdminContext(args)\n\n  const { cookies, permissions, req, user } = context\n\n  const data = await getRootLayoutData({\n    cookies,\n    importMap: args.importMap,\n    permissions,\n    req,\n    user,\n  })\n\n  return { data, userAgent: context.req.headers.get('user-agent') }\n}\n\nexport async function getTheme(args: InitAdminContextArgs) {\n  const { req: { headers: requestHeaders, i18n: { language: languageCode } }, user } = await initAdminContext(args)\n\n  return { languageCode, theme: requestHeaders.get('sec-ch-prefers-color-scheme'), user }\n}\n\nexport const getUserAgent = async (args: InitAdminContextArgs) =>\n  (await initAdminContext(args)).req.headers.get('user-agent')\n\nexport const getDirection = (context: AdminContext) =>\n  context.req.i18n.language === 'ar' ? 'rtl' : 'ltr'\n\nexport const getAcceptLanguage = ({ req: { headers } }: AdminContext) => headers.get('accept-language')\n"],"names":["getRootLayoutData","initAdminContext","getLayoutData","args","context","cookies","permissions","req","user","data","importMap","userAgent","headers","get","getTheme","requestHeaders","i18n","language","languageCode","theme","getUserAgent","getDirection","getAcceptLanguage"],"mappings":"AAGA,SAASA,iBAAiB,QAAQ,gDAA+C;AACjF,SAASC,gBAAgB,QAAQ,mBAAkB;AAMnD,OAAO,eAAeC,cAAcC,IAA0B;IAC5D,MAAMC,UAAU,MAAMH,iBAAiBE;IAEvC,MAAM,EAAEE,OAAO,EAAEC,WAAW,EAAEC,GAAG,EAAEC,IAAI,EAAE,GAAGJ;IAE5C,MAAMK,OAAO,MAAMT,kBAAkB;QACnCK;QACAK,WAAWP,KAAKO,SAAS;QACzBJ;QACAC;QACAC;IACF;IAEA,OAAO;QAAEC;QAAME,WAAWP,QAAQG,GAAG,CAACK,OAAO,CAACC,GAAG,CAAC;IAAc;AAClE;AAEA,OAAO,eAAeC,SAASX,IAA0B;IACvD,MAAM,EAAEI,KAAK,EAAEK,SAASG,cAAc,EAAEC,MAAM,EAAEC,UAAUC,YAAY,EAAE,EAAE,EAAEV,IAAI,EAAE,GAAG,MAAMP,iBAAiBE;IAE5G,OAAO;QAAEe;QAAcC,OAAOJ,eAAeF,GAAG,CAAC;QAAgCL;IAAK;AACxF;AAEA,OAAO,MAAMY,eAAe,OAAOjB,OACjC,AAAC,CAAA,MAAMF,iBAAiBE,KAAI,EAAGI,GAAG,CAACK,OAAO,CAACC,GAAG,CAAC,cAAa;AAE9D,OAAO,MAAMQ,eAAe,CAACjB,UAC3BA,QAAQG,GAAG,CAACS,IAAI,CAACC,QAAQ,KAAK,OAAO,QAAQ,MAAK;AAEpD,OAAO,MAAMK,oBAAoB,CAAC,EAAEf,KAAK,EAAEK,OAAO,EAAE,EAAgB,GAAKA,QAAQC,GAAG,CAAC,mBAAkB"}

package/dist/transforms/migrate-admin-context-properties/index.d.ts

@@ -0,0 +1,3 @@
+import type { Transform } from '../../types.js';
+export declare const migrateAdminContextProperties: Transform;
+//# sourceMappingURL=index.d.ts.map

package/dist/transforms/migrate-admin-context-properties/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/transforms/migrate-admin-context-properties/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAwC/C,eAAO,MAAM,6BAA6B,EAAE,SA8J3C,CAAA"}