[zurfyx]

Description

The @lexical/y tests checked the shapes their authors thought of. Three bugs got through that way: list items numbered 1 in a freshly bound editor when the document holds a block with named slots, the documented $setBlockText throwing on a TabNode, and block handles that were long and typo-prone for ids that share a prefix. Each was one member of an input class nobody enumerated: blocks with slots, TextNode subclasses, id formats.

This adds catalogs of the input space under packages/lexical-y/src/__tests__/catalog/, as data that unit tests, fuzz and soak harnesses import, and contract tests that run over them in unit/matrix/:

• nodes.ts: 61 node shapes. Every LexicalNode subclass exported by lexical and the @lexical/* packages, every class in the playground's node list and the nodes its extensions register, in each mode that matters (token, segmented, tab, code highlight, hashtag, mention, emoji, keyword, ruby), inline elements that refuse text at their edges, inline and block decorators (with NodeState fields, nested editors, no text), named-slot hosts with declared and undeclared slots, every list type with a custom start and nesting, tables with merged cells and lists in cells, collapsibles, layouts and pages. downstream.ts adds stand-ins for shapes apps register that no package has: a component whose undeclared slots hold shadow roots of blocks, and inline atoms whose text comes from their state.
• NodeCatalog.test.ts fails when a package or the playground exports or declares a node class that no shape builds, and when a shape's tags (lists, slots, tables) do not say what it builds, since tests select cells by them.
• ids.ts: block id formats: random, positional, @lexical/y derived ids with their suffixes, duplicates awaiting repair, UUIDv7, counters, a legacy b + base 36 format, and mixed documents.
• configs.ts: the configuration dimensions (BlockIdExtension enabled, disabled or absent; bind mode; headless or jsdom; createYDoc or a plain Y.Doc; schema versions; read-only causes; marks; IME; batched updates; onError; HTML export) and a sampled product that keeps every value.
• bind.ts, peers.ts, ops.ts: seeding and binding the ways apps do; peers bound with @lexical/y, @lexical/yjs v1 and v2 with a delivery queue, app follow-up updates and an owner-gated table row repair; and edits from the core packages.

The contracts:

• C1: a bound editor shows what a fresh readYState of its own document shows, and the derived fields (list value, start, <li value>, element textFormat/textStyle) an editor without collab derives, at the first read with nothing awaited, after microtasks, a task, a remote change and once settled; also with an app keeping the editor busy, across full reconciles, for read-only documents (every cause, with the documented warning and nothing written), with marks and mark flavors, batched updates, IME, onError that logs and a newer schema version; text content listeners get every change of the text.
• C6: concurrent edits from the core packages on three peers settle (no update ping-pong) and converge, for each binding, also with app follow-ups and a row repair; concurrent table row and column inserts, enumerated, leave no duplicated cells.
• HTML export and import with block ids, for every shape; marks under an input method in every container.
• Ownership scans (OwnershipScans.test.ts, third to fifth commits, 224 cells): one client gives a range a value (bold, code, a comment, a link) or writes a node Lexical keeps apart (a tab, a token, a segmented node, a hashtag), types plain text elsewhere, writes the same again, and undoes 0 to 3 of those writes while a collaborator edits next to or inside the first one; every character is checked against a model of the edits (text nobody gave the value never has it, kept-apart nodes stay what they are), so a scan that takes a later write's item of the same client for its own write fails here.
• Structural commands in block containers (StructuralCommands.test.ts, 700 cells): list conversion of each type, Enter in an empty last list item, pasting two paragraphs, a horizontal rule at the nearest root, $wrapNodes, the markdown block shortcuts, and Backspace and Delete at a container's edges, in the root, a container that declares nothing, one that declares children: 'block', a shadow root, each nested, a shadow root in a named slot, the downstream component's undeclared slot and a slot host's declared slot; unbound with NodeStructureExtension and bound in every bind mode, also with a full reconcile. Checked against a model of the rule (structural commands act inside shadow roots and declared containers; only shadow roots are editing edges).
• CatalogSoakFuzz.test.ts: a seeded multi-peer soak over the catalog, every document holding a list next to a named-slot host.

Cells that fail on main because of a known bug are test.fails, selected exactly, with a comment naming the pull request or issue that fixes it, so each must pass once its fix lands (the table below). The catalog README says how to add a node class, id format or option, that new exports land with their catalog entry and contract, and what is not covered yet.

The default run takes about a minute; MATRIX_FULL=1 runs the full products.

Expected failures

Each is selected by an exact predicate in its test file, with a comment naming the fix. Cells marked for fixes that have merged since (#9573, #9540, #9584, #9578) are plain tests again.

Test file	Cells	Fixed by
C1FullReconcile.test.ts	bound documents whose first text is formatted (4)	#9553
C1FullReconcile.test.ts	the unbound paragraph with a formatted first text (1)	#9568
C7Html.test.ts	a list item that only wraps a nested list (bullet, number, check) and a page, export on (4)	#9606
StructuralCommands.test.ts	every structural command in a declared container and in one inside another, and list conversion in a box inside a box (135)	#9590

MATRIX_FULL=1 runs the full products (about 11,700 cells) to explore. Cells only the full run reaches are not marked, so it can fail on open issues (more seeds of #9581, #9583, the row repair races of #9582).

Not covered yet

• The read-only cause where a read throws and the binding stops reading (readOnly: 'frozen').
• Editors made with createEditor and a node list instead of extensions; the package's own tests bind those.
• Contracts for open pull requests' new exports live with those pull requests until they merge.

Rule

A new node class, option or export lands with its catalog entry and a contract over it. NodeCatalog.test.ts enforces the node classes; the catalog README says how to add each kind.

Test plan

pnpm run ci-check
pnpm exec vitest run --project unit packages/lexical-y/src/__tests__/unit/matrix

Before

The contracts on main, before marking the cells of known bugs:

 ❯ packages/lexical-y/src/__tests__/unit/matrix/C1ReadEqualsFresh.test.ts (435 tests | 139 failed)
 ❯ packages/lexical-y/src/__tests__/unit/matrix/C1Busy.test.ts (240 tests | 16 failed)
 ❯ packages/lexical-y/src/__tests__/unit/matrix/C1FullReconcile.test.ts (183 tests | 5 failed)
 ❯ packages/lexical-y/src/__tests__/unit/matrix/MarksIME.test.ts (56 tests | 26 failed)
 ❯ packages/lexical-y/src/__tests__/unit/matrix/CatalogSoakFuzz.test.ts (24 tests | 24 failed)
 ❯ packages/lexical-y/src/__tests__/unit/matrix/C6Settles.test.ts (360 tests | 1 failed)
   first read: numbering {"starts":[1,1],"values":[1,1,1,1,1,1]} != fresh {"starts":[1,1],"values":[1,2,3,1,2,3]}
   a full reconcile wrote to the document
   composed char 2 "e" ids [], expected ["c1"]
   B differs from A at /root/children/0/children/5/children/0

After

On main c514ea7, at the head:

$ pnpm exec vitest run --project unit packages/lexical-y/src/__tests__/unit/matrix
 Test Files  14 passed (14)
      Tests  2964 passed | 144 expected fail (3108)

$ pnpm run ci-check
Changeset check passed: 31 pending changeset(s) valid.
Found 0 errors

[vercel]

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

Project	Deployment	Actions	Updated
lexical	Ready	Preview	Oct 30, 2026 6:29pm UTC
lexical-playground	Ready	Preview	Oct 30, 2026 6:29pm UTC

[meta-code-review]

AI review status for this pull request.

Review status	Updated
⏳ Queued (for maintainers only)	Oct 30, 2026, 6:29 PM UTC

[pkg-pr-new]

lexical

npm i https://pkg.pr.new/lexical@9588

@lexical/a11y

npm i https://pkg.pr.new/@lexical/a11y@9588

@lexical/clipboard

npm i https://pkg.pr.new/@lexical/clipboard@9588

@lexical/code

npm i https://pkg.pr.new/@lexical/code@9588

@lexical/code-core

npm i https://pkg.pr.new/@lexical/code-core@9588

@lexical/code-prism

npm i https://pkg.pr.new/@lexical/code-prism@9588

@lexical/code-shiki

npm i https://pkg.pr.new/@lexical/code-shiki@9588

@lexical/compiler

npm i https://pkg.pr.new/@lexical/compiler@9588

@lexical/devtools-core

npm i https://pkg.pr.new/@lexical/devtools-core@9588

@lexical/dragon

npm i https://pkg.pr.new/@lexical/dragon@9588

@lexical/eslint-plugin

npm i https://pkg.pr.new/@lexical/eslint-plugin@9588

@lexical/extension

npm i https://pkg.pr.new/@lexical/extension@9588

@lexical/fast-check

npm i https://pkg.pr.new/@lexical/fast-check@9588

@lexical/file

npm i https://pkg.pr.new/@lexical/file@9588

@lexical/hashtag

npm i https://pkg.pr.new/@lexical/hashtag@9588

@lexical/headless

npm i https://pkg.pr.new/@lexical/headless@9588

@lexical/history

npm i https://pkg.pr.new/@lexical/history@9588

@lexical/html

npm i https://pkg.pr.new/@lexical/html@9588

@lexical/internal

npm i https://pkg.pr.new/@lexical/internal@9588

@lexical/link

npm i https://pkg.pr.new/@lexical/link@9588

@lexical/list

npm i https://pkg.pr.new/@lexical/list@9588

@lexical/mark

npm i https://pkg.pr.new/@lexical/mark@9588

@lexical/markdown

npm i https://pkg.pr.new/@lexical/markdown@9588

@lexical/mdast

npm i https://pkg.pr.new/@lexical/mdast@9588

@lexical/offset

npm i https://pkg.pr.new/@lexical/offset@9588

@lexical/overflow

npm i https://pkg.pr.new/@lexical/overflow@9588

@lexical/plain-text

npm i https://pkg.pr.new/@lexical/plain-text@9588

@lexical/react

npm i https://pkg.pr.new/@lexical/react@9588

@lexical/rich-text

npm i https://pkg.pr.new/@lexical/rich-text@9588

@lexical/selection

npm i https://pkg.pr.new/@lexical/selection@9588

@lexical/table

npm i https://pkg.pr.new/@lexical/table@9588

@lexical/tailwind

npm i https://pkg.pr.new/@lexical/tailwind@9588

@lexical/text

npm i https://pkg.pr.new/@lexical/text@9588

@lexical/utils

npm i https://pkg.pr.new/@lexical/utils@9588

@lexical/y

npm i https://pkg.pr.new/@lexical/y@9588

@lexical/yjs

npm i https://pkg.pr.new/@lexical/yjs@9588

commit: b96a07e

[meta-code-review]

This looks good. Catalogs of node shapes, id formats and configurations, with contracts run over them, are a solid way to keep @lexical/y honest across shapes and bindings, and every expected failure names the open pull request or issue behind it. All the suggestions below are optional and non-blocking.

Suggestions

1. C7Html.test.ts checks less than its header says (lines 9-14 against lines 106 and 139-143).
   • The export check fails only when no id is written, and the import check only when every imported id is new.
   • So two non-decorator shapes lose their data-block-id on export without a failure: the list item that wraps a nested list (list/*-nested) and the PageNode (page/content).
   • The reader is built from catalogAppExtension, which registers the nodes but not the DOMImportExtension rules their extensions add (for example RichTextExtension's). In that reader, headings, quotes and code blocks import as paragraphs, containers and slot hosts are flattened, and the YouTube, Figma and image decorators import as nothing.
   • Consider giving the reader those import rules and asserting both the exported ids and the imported top-level types, with explicit exceptions for what is intended. Anything that is a known bug can be test.fails, per the rule in catalog/README.md.
2. C6Settles.test.ts never runs the table-transform follow-up its header describes (lines 15-18). No entry of VARIANTS (lines 150-156) sets followUp: 'tables', which catalog/peers.ts:333-344 implements. With those variants added, most seeded cells fail to settle within LIMIT under all three bindings, which is the ping-pong reported in #9582. catalog/README.md says a cell that fails because of a known bug is test.fails, selected exactly. Consider adding the variants with an exact predicate for #9582 so they flip when it is fixed, or dropping the sentence from the header.
3. C1ReadOnly.test.ts promises checks it does not run (lines 12-17): a writable control and a derived-field comparison. An equal-schema cell that asserts status === 'active' and a changed state vector would show that the "nothing written" check can fail.
4. Log noise. catalogAppExtension (catalog/bind.ts:67) uses TableExtension's default hasHorizontalScroll: true with no theme. Every rendered table therefore logs TableNode: hasHorizontalScroll is active but theme.tableScrollableWrapper is not defined., about 11k lines in each unit job log. configExtension(TableExtension, {hasHorizontalScroll: false}) would quiet it.

Nits

• NodeCatalog.test.ts will now fail for anyone who adds a node class anywhere in the repo. An assertion message that points to catalog/nodes.ts and NODE_EXCLUSIONS, and perhaps a line in the testing section of AGENTS.md, would help them. Its "every shape builds" test (lines 286-292) also skips slot hosts; walking slots, as the tags test does, would cover them.
• AGENTS.md asks for // @vitest-environment node in tests that need no DOM. NodeCatalog, C6Tables and C6Settles never touch it.
• catalog/README.md:48-55 lists C2-C5 as standing contracts, but C4 and C5 have no matrix test yet and ID_FORMATS is not used by any test.
• catalog/ids.ts:16-17 refers to a $positional helper that does not exist.
• C1Configs.test.ts:11-12 mentions an update listener, but the code throws from a node transform.
• The PR body's Before shows C1Busy.test.ts (240 tests | 16 failed), which is the MATRIX_FULL count; the default run has 96 cells.

A test-only change needs no changeset (CONTRIBUTING.md).

[meta-code-review]

Optional: this fails only when no id is written, so partial loss passes. The list item that wraps a nested list (list/*-nested) and the PageNode (page/content) both lose their data-block-id today without failing. Consider checking missing against an explicit allowlist of the decorators that export no children, and marking anything that is a known bug test.fails, per catalog/README.md.

[meta-code-review]

Optional: the header (lines 15-18) promises a table-transform follow-up, but no variant here sets followUp: 'tables' (catalog/peers.ts:333-344). With it added, most seeded cells fail to settle within LIMIT under every binding, which is the ping-pong reported in #9582. Per catalog/README.md, consider adding the variant with an exact test.fails predicate so it flips when #9582 is fixed.

[meta-code-review]

Nit: with the default hasHorizontalScroll: true and no theme, every rendered table logs TableNode: hasHorizontalScroll is active but theme.tableScrollableWrapper is not defined., about 11k lines per unit job log. configExtension(TableExtension, {hasHorizontalScroll: false}) keeps the transforms and drops the noise.

[meta-code-review]

Nit: this file has no such control. Every cell is read only, and only numbering and text are compared, not the derived fields. An equal-schema cell asserting status === 'active' and a changed state vector would show that the "nothing written" check can fail.

[meta-code-review]

This looks good to me. It adds catalogs and contract tests only, nothing that ships, and it is a real step up for @lexical/y coverage. With every test.fails marker removed, exactly the 36 marked cells fail, each with the symptom its comment names, so the predicates are exact. Everything below is optional and non-blocking.

1. Marker hand-off to the open fixes. #9553, #9540, #9578 and #9561 predate these files. Whichever of them lands after this one has to delete its markers in the same change, or the unit job on main fails on cells that now pass. The markers are at C1FullReconcile.test.ts:166-180, MarksIME.test.ts:189-194 and OwnershipScans.test.ts:303-307; C6Settles.test.ts:166-171 waits on #9581. That is the rule the catalog README states (README.md:56-58), and it may be worth noting in those PRs.
2. C7Html.test.ts:106 checks less than the header (lines 9-14) promises. It fails only when export-on writes no data-block-id at all. BlockIdExtension also identifies list items and table-cell paragraphs, so losing their ids while keeping the top-level one would pass. Requiring missing to be empty, except for the shapes whose export omits children, would close that gap.
3. Some headers describe cells that don't exist.
   • C1ReadOnly.test.ts:16-17 describes an equal-schema control that stays editable, but all 28 cells expect readonly.
   • C6Settles.test.ts:15-18 describes a 'tables' follow-up that no VARIANTS entry uses.
   • C1Configs.test.ts:11-12 says an update listener throws. The cell actually registers a throwing transform, and never checks that onError received the error.
4. The README's standing contracts. README.md:48-55 lists C2–C5, but nothing here implements C4 (handles over every id format) or C5 (linear cost), and nothing yet consumes ID_FORMATS in ids.ts or configProduct's limit/filter. Listing them under "Not covered yet" until their tests land would keep the rule accurate.
5. State the node-catalog rule in AGENTS.md. Under NodeCatalog.test.ts, a new node class in any package or in the playground fails the @lexical/y suite until it gets a shape. AGENTS.md is where contributors and agents look for repository conventions. A line there, plus a pointer to the catalog README in the failure message, would tell them before CI does.
6. Small ones.
   • NodeCatalog.test.ts:287-292 skips the class check for slot-host shapes, though the walker at lines 205-217 already visits slots.
   • C1TextContent.test.ts:86-90 waits out the playground collapsible's toggle listener, which throws on a removed node (CollapsibleContainerNode.ts:86-89). The README rule asks for a marked cell for a known bug instead.
   • The branch predates #9573, so on its own it fails the cells the second commit un-marked; merged with main it is green. A rebase would make the branch green by itself.

[meta-code-review]

Optional: this fails only when export-on writes no data-block-id at all. BlockIdExtension also identifies list items and table-cell paragraphs ($defaultIsIdentifiedBlock), so dropping their ids while keeping the top-level one would pass. Requiring missing to be empty, except for the shapes whose export omits children, would match the header at lines 9-14.

[meta-code-review]

Optional: this file has no equal-schema control. All 28 cells expect readonly, so a binding that opened every document read only would still pass here. Either add the control (same documents, a reader that can write, status === 'active', and a local edit that reaches the doc) or drop the sentence.

[meta-code-review]

Optional: the header (lines 15-18) and CatalogPeer.followUp describe a 'tables' follow-up, but no variant here uses it, in the default or the MATRIX_FULL run. Either add e.g. {followUp: 'tables', repair: 'none', tables: true} or drop it from the header.

[meta-code-review]

Optional: this skips the class check for every class of a slot-host shape. The walker in the tags test (lines 205-217) already descends into $getSlotNames, so reusing it here would also verify SlotContainerNode and DownstreamComponentSlotNode.

[meta-code-review]

Optional: nothing in this PR implements C4 or C5, and nothing consumes ID_FORMATS yet. Listing them under "Not covered yet" until their tests land would keep this rule accurate for contributors. The node-catalog rule above may also deserve a line in AGENTS.md, where contributors look for repository conventions.

[meta-code-review]

Optional: this waits out a playground bug. The collapsible's toggle listener reads this.getOpen() on a node that may have been removed (CollapsibleContainerNode.ts:86-89, the <details> path). Per the rule at README.md:56-58, a marked cell naming an issue would keep it visible instead of hidden behind the await.