1. Custom link fields can collide between editors

The generated Lexical node type name is based on a hash of nodeSchemas:

packages/richtext-lexical/src/types/schema.ts#L78-L80

For link fields with custom fields, the custom field schema is stored separately under a name derived from that same hash:

packages/richtext-lexical/src/features/link/server/schema.ts#L148-L151

The problem is that the hash is computed before those separate LexicalLinkFields_<hash> definitions are part of the hashed value. So two editors can have the same enabled Lexical nodes but different custom LinkFeature fields, and both can end up using the same LexicalNodes_* / LexicalLinkFields_* names.

Example:

// editor A
LinkFeature({
  fields: [{ name: 'label', type: 'text' }],
})

// editor B
LinkFeature({
  fields: [{ name: 'trackingId', type: 'text' }],
})

If everything else about the editor is the same, one generated LexicalLinkFields_* definition can overwrite the other. That would make one rich text field use the wrong link field type.

I think the link field schema, or some stable hash of it, needs to be included in the node union hash.

2. Duplicate explicit block interfaceName values can overwrite each other

registerBlockInterface handles collisions for auto-generated block interface names, but explicit interfaceName values skip that path:

packages/payload/src/utilities/configToJSONSchema.ts#L1361-L1364

The collision handling only runs after that early return:

packages/payload/src/utilities/configToJSONSchema.ts#L1374-L1379

So if two different blocks both set interfaceName: 'Hero', the second one replaces the first one in interfaceNameDefinitions. Any field that referenced the first one can now point at the second block's shape.

I think this should either throw a clear error for duplicate explicit names, or use the same hash fallback that auto-generated names use.

3. The migration guide says missing jsonSchema falls back to unknown, but the code omits those nodes

The migration guide says:

docs/migration-guide/v4.mdx#L536

But the code filters out any node that does not have jsonSchema:

packages/richtext-lexical/src/types/schema.ts#L68-L70

That means a custom node without jsonSchema is not typed as { [k: string]: unknown }. It is missing from the generated node union entirely.

That is important for third-party Lexical features. Their data can still exist at runtime, but generated TypeScript will not include those nodes. The docs should match the behavior, or the implementation should add the loose fallback described by the docs.

4. MCP schema simplification may loosen Lexical node unions

Lexical node unions are built as oneOf:

packages/richtext-lexical/src/types/schema.ts#L78

The MCP simplifier now walks definitions:

packages/plugin-mcp/src/utils/schemaConversion/simplifyRelationshipFields.ts#L66-L75

When it sees a oneOf with no $ref, it changes it into anyOf:

packages/plugin-mcp/src/utils/schemaConversion/simplifyRelationshipFields.ts#L47-L50

That can change the meaning of LexicalNodes_* inside MCP input schemas. These are discriminated node unions, so oneOf is stricter than anyOf. I would add a test with a collection that has a Lexical rich text field exposed through MCP, and assert the Lexical node union stays strict while relationship values are still simplified to IDs.

5. Upload extra fields are strict in JSON Schema but loose in generated TypeScript

The upload node TypeScript template always emits loose upload fields:

packages/richtext-lexical/src/features/upload/server/schema.ts#L53-L59

But the JSON Schema builder does know the configured upload extra fields:

packages/richtext-lexical/src/features/upload/server/schema.ts#L95-L120

So UploadFeature({ collections: { uploads: { fields: [...] } } }) can validate those fields strictly, but the generated TypeScript still exposes them as { [k: string]: unknown }.

If this PR's goal is accurate generated Lexical types, I think upload extra fields should either be represented in SerializedUploadNode generics, or this limitation should be called out clearly.

Suggested tests

• Two rich text fields with the same nodes but different custom LinkFeature fields should generate different link field types.
• Two different blocks with the same explicit interfaceName should not silently overwrite each other.
• A custom Lexical node without jsonSchema should either appear as unknown in the union, or docs should say it is omitted.
• MCP create/update schema for a collection with Lexical rich text should keep the Lexical node union strict.
• Upload feature custom fields should either be typed in generated TypeScript, or there should be a test showing they intentionally remain loose.

Thanks for working through the review points. Just two more small observations:

1. Upload extra fields are better, but I think one case is still loose

The upload field typing is definitely better than before. SerializedUploadNode now has a second generic for fields, and custom upload fields now get their own generated interface. So the old { [k: string]: unknown } issue is improved.

The part I am still unsure about is how the generated type combines all upload slugs with all upload field types. The current tsType builds one slug union and one fields union in the upload schema generator.

That means TypeScript may know "this upload node can use these upload collections" and "this upload node can use these field shapes", but it may not know which field shape belongs to which relationTo.

For example, imagine this config:

UploadFeature({
  collections: {
    uploads: {
      fields: [{ name: 'caption', type: 'text', required: true }],
    },
    uploads2: {
      fields: [{ name: 'credit', type: 'text', required: true }],
    },
  },
})

Ideally, TypeScript would understand this:

{ relationTo: 'uploads', fields: { caption: string } }
{ relationTo: 'uploads2', fields: { credit: string } }

But the current shape looks closer to this:

SerializedUploadNode<'uploads' | 'uploads2', UploadsFields | Uploads2Fields>

That means the slug and the fields can drift apart. For example, relationTo: 'uploads' could accidentally be paired with the fields intended for uploads2.

The current lexical test config has a smaller version of this: only uploads has the custom caption field, but the generated node type applies that custom fields interface to both uploads and uploads2 in the generated lexical types. The generated caption interface is here.

Ideally, the codegen would be able to differentiate this.

2. I think we need better type tests around the APIs users call

The fact that the existing test folder did not suddenly show a lot of new TypeScript errors might mean we do not have enough type-level tests around the main APIs where users pass data.

So I think it would be useful to add focused tstyche tests for the APIs that now enforce the stricter generated rich text shape.

For example:

• payload.create accepts a valid richText value generated with buildEditorState<Post['richText']>().
• payload.update accepts a valid generated rich text value.
• payload.update rejects an invalid lexical object, like a node with an unknown type, a block node missing required fields, or an upload node whose fields do not match its upload collection.
• payload.updateGlobal has the same coverage for a global rich text field.
• The SDK create and update APIs enforce the same shape.
• Converter functions still accept rich text data returned from Payload.

The important part is that some of these tests should fail before this PR and pass after it. That would show that the new generated types are not only being generated, but are also enforced where users will actually feel the change.

Without tests like that, I think we are mostly proving that the generated types exist. We are not proving enough that payload.update, payload.create, and the SDK are protected in real usage.