fix(ai): loosen serialization of blocks in columns (#2716)

[nperez0111]

Fixes #2716.

Summary

Using AI inside a column (within a columnList) crashed with Unexpected Error calling LLM RangeError: Invalid content for node columnList: <>.

Rationale

xl-ai's flattenBlocks strips children from every block before piping each one through editor.blocksToHTMLLossy for the LLM. columnList (schema: column column+) and column (schema: blockContainer+) then hit createChecked in blockToNode with empty content and threw.

Changes

• blockToNode: bnBlock branch now uses Node.create (lenient) so partial container blocks can flow through HTML serialization.
• insertBlocks / replaceBlocks / updateBlock: each calls node.check() after blockToNode, so doc-mutating callers still reject invalid structures at the right boundary.
• Added @blocknote/xl-multi-column as a devDep of xl-ai plus a vite alias, so the regression test exercises the real schema.

Testing

• New packages/xl-ai/src/api/formats/html-blocks/columnContainerDocumentState.test.ts reproduces the issue's flow through htmlBlockLLMFormat.defaultDocumentStateBuilder; fails on main, passes here.
• core (422), xl-multi-column (62) and xl-ai (225) suites all green; the existing Insert empty column list etc. tests still throw, now via node.check().

Summary by CodeRabbit

• Bug Fixes

  • Added validation checks during block insertion, replacement, and updates to ensure data integrity before applying changes to the document.

• Tests

  • Added comprehensive tests for multi-column layout functionality to verify proper behavior in document state generation.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
blocknote	Ready	Preview	May 6, 2026 5:52pm
blocknote-website	Ready	Preview	May 6, 2026 5:52pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 84ecfaf2-8a9b-41b8-a761-db4fa66556a5

📥 Commits

Reviewing files that changed from the base of the PR and between b0d0985 and a7ceeef.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (7)

• packages/core/src/api/blockManipulation/commands/insertBlocks/insertBlocks.ts
• packages/core/src/api/blockManipulation/commands/replaceBlocks/replaceBlocks.ts
• packages/core/src/api/blockManipulation/commands/updateBlock/updateBlock.ts
• packages/core/src/api/nodeConversions/blockToNode.ts
• packages/xl-ai/package.json
• packages/xl-ai/src/api/formats/html-blocks/columnContainerDocumentState.test.ts
• packages/xl-ai/vite.config.ts

---

📝 Walkthrough

Walkthrough

This pull request refactors block validation from eager to deferred validation by changing blockToNode to use create() instead of createChecked(), delegating validation responsibility to callers. Concurrently, it integrates multi-column support into the xl-ai package with new test coverage for document state building with column layouts.

Changes

Block Validation Refactoring

Layer / File(s)	Summary
Core Validation Strategy packages/core/src/api/nodeConversions/blockToNode.ts	Switches from createChecked() to create() for bnBlock nodes, allowing partial/incomplete blocks to be constructed; validation is delegated to callers via node.check() with explanatory comments.
Caller-Side Validation packages/core/src/api/blockManipulation/commands/insertBlocks/insertBlocks.ts, packages/core/src/api/blockManipulation/commands/replaceBlocks/replaceBlocks.ts	Node insertion and replacement now explicitly call node.check() immediately after constructing each node via blockToNode(), ensuring validation before document mutation.
Block Update Validation packages/core/src/api/blockManipulation/commands/updateBlock/updateBlock.ts	Block replacement and child mapping both validate nodes by calling node.check() after construction; a CellAnchor type and JSDoc comment clarify the captureCellAnchor function's purpose.

Multi-Column Support in xl-ai

Layer / File(s)	Summary
Dependency Configuration packages/xl-ai/package.json	Adds @blocknote/xl-multi-column version 0.50.0 as a dev dependency.
Development Tooling packages/xl-ai/vite.config.ts	Introduces a Vite alias mapping @blocknote/xl-multi-column to its source path, enabling live-reload during development.
Integration Testing packages/xl-ai/src/api/formats/html-blocks/columnContainerDocumentState.test.ts	New test suite validates that htmlBlockLLMFormat.defaultDocumentStateBuilder correctly handles multi-column layouts with column-list blocks and paired columns, both with and without selected blocks.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Validation deferred, not too quick to fail,
Now multi-column blocks tell their tale.
Check them later, when they're complete and whole,
The rabbit hops through columns toward the goal! 🌻

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 20.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the fix: allowing AI serialization inside column containers, directly addressing the core issue.
Description check	✅ Passed	The description comprehensively covers Summary, Rationale, Changes, and Testing sections with specific technical details and test results, though Screenshots and full Checklist are absent.
Linked Issues check	✅ Passed	The PR fully addresses issue #2716 by fixing AI serialization with multi-column layouts through blockToNode modifications, validation additions, and regression testing.
Out of Scope Changes check	✅ Passed	All changes (blockToNode refactoring, validation in mutations, dependency addition, and regression test) are directly scoped to fixing the AI+column container compatibility issue.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/columnlist-ai-invalid-content

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@blocknote/ariakit

npm i https://pkg.pr.new/@blocknote/ariakit@2718

@blocknote/code-block

npm i https://pkg.pr.new/@blocknote/code-block@2718

@blocknote/core

npm i https://pkg.pr.new/@blocknote/core@2718

@blocknote/mantine

npm i https://pkg.pr.new/@blocknote/mantine@2718

@blocknote/react

npm i https://pkg.pr.new/@blocknote/react@2718

@blocknote/server-util

npm i https://pkg.pr.new/@blocknote/server-util@2718

@blocknote/shadcn

npm i https://pkg.pr.new/@blocknote/shadcn@2718

@blocknote/xl-ai

npm i https://pkg.pr.new/@blocknote/xl-ai@2718

@blocknote/xl-docx-exporter

npm i https://pkg.pr.new/@blocknote/xl-docx-exporter@2718

@blocknote/xl-email-exporter

npm i https://pkg.pr.new/@blocknote/xl-email-exporter@2718

@blocknote/xl-multi-column

npm i https://pkg.pr.new/@blocknote/xl-multi-column@2718

@blocknote/xl-odt-exporter

npm i https://pkg.pr.new/@blocknote/xl-odt-exporter@2718

@blocknote/xl-pdf-exporter

npm i https://pkg.pr.new/@blocknote/xl-pdf-exporter@2718

commit: a7ceeef