[lexical-code-core][lexical-code-prism][lexical-code-shiki] Refactor: move the duplicated updateCodeGutter into @lexical/code-core

[Om-singhaI]

Description

@lexical/code-prism and @lexical/code-shiki each had their own private copy of updateCodeGutter, and the two copies were identical line for line. @etrepum asked on #8468 for this gutter code to be consolidated into @lexical/code-core, and it's the first step of the plan I posted on #8459.

This moves it into @lexical/code-core as $updateCodeGutter in a new CodeGutter.ts, exports it from the package index and declares it in the Flow file. Both highlighters now import it from there and their copies are gone. The function body is unchanged byte for byte, so the data-gutter string and the __cachedChildrenLength check are exactly what they were.

I gave it the $ prefix because it reads the node's children, so it has to run inside a read or an update. That's already where both callers use it: the CodeNode mutation listener, inside editor.read('latest', ...). It's marked @internal like registerCodeIndentation, since only the two highlighters call it.

I also added unit tests in @lexical/code-core that pin the exact data-gutter value for a single line, several lines, an empty trailing line and an edit that changes the line count, plus the cache that skips the write when the child count doesn't change. They run in a real editor with a copy of the mutation listener both highlighters register.

Part of #8459

Test plan

Before

On origin/main (84eabc3). The packages/lexical-code filter picks up lexical-code, lexical-code-core, lexical-code-prism and lexical-code-shiki. The lexical-code tests already pin data-gutter through prism's registerCodeHighlighting.

$ pnpm exec vitest --project unit --no-watch --maxWorkers=2 packages/lexical-code
 Test Files  15 passed (15)
      Tests  291 passed | 1 skipped (292)

After

$ pnpm exec vitest --project unit --no-watch --maxWorkers=2 --reporter=verbose packages/lexical-code
 ✓ |unit| packages/lexical-code-core/src/__tests__/unit/CodeGutter.test.ts > $updateCodeGutter > numbers a single line 108ms
 ✓ |unit| packages/lexical-code-core/src/__tests__/unit/CodeGutter.test.ts > $updateCodeGutter > numbers several lines 6ms
 ✓ |unit| packages/lexical-code-core/src/__tests__/unit/CodeGutter.test.ts > $updateCodeGutter > numbers an empty trailing line 6ms
 ✓ |unit| packages/lexical-code-core/src/__tests__/unit/CodeGutter.test.ts > $updateCodeGutter > follows an edit that changes the line count 7ms
 ✓ |unit| packages/lexical-code-core/src/__tests__/unit/CodeGutter.test.ts > $updateCodeGutter > only rewrites the attribute when the number of children changes 4ms
 Test Files  16 passed (16)
      Tests  296 passed | 1 skipped (297)

$ pnpm run flow
Found 0 errors

tsc over the four code packages passes, and eslint and prettier are clean on the changed files. I ran this on Node 25 locally, so Node 22 and 24 are left to CI. I didn't run the browser or e2e suites locally either. The playground e2e specs pin data-gutter in a lot of places, and since the output is unchanged they should stay green.

[vercel]

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

Project	Deployment	Actions	Updated
lexical	Ready	Preview	Sep 18, 2026 3:01am UTC
lexical-playground	Ready	Preview	Sep 18, 2026 3:01am UTC

[Om-singhaI]

@etrepum I've got the next piece from #8459 ready, the per line numbers, opt in and stacked on this branch. Would you rather land this one first, or should I open it now so you can see both together?

[etrepum]

The editor argument is redundant, $getEditor can be used in the implementation

[Om-singhaI]

Done, thanks. Every call site already runs inside a read or an update context, so $getEditor() resolves there and the argument wasn't buying anything. The Flow declaration and both highlighters are updated to match, and the gutter tests and tsc are green.