Files
summercms/.planning/notes/2026-11-06-admin-code-editor-codemirror.md
Jakub Zych 6e0d4bbca7 docs(35): CodeMirror decision note and STACK.md row for the admin code editor
- Document seven exact pins, integrity values, and the too-new flag on @codemirror/view
- Add Admin SPA STACK.md rows linking the decision note before any npm install

Plan 35-03, task 2

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-13 13:15:23 +01:00

4.6 KiB

Decision: CodeMirror 6 for the admin codeeditor field

Date: 2026-11-06 Status: Accepted pending human version check (Phase 35 plan 35-03 Task 3) Relates to: .planning/phases/35-mail-templates-and-layouts-editor/35-UI-SPEC.md (Why CodeMirror 6, Registry Safety), .planning/phases/35-mail-templates-and-layouts-editor/35-RESEARCH.md (Package Legitimacy Audit, Pitfall 5), .planning/research/STACK.md

Decision

The admin SPA (admin/package.json) adds seven npm runtime dependencies with exact pins and a committed package-lock.json. They load only from admin/src/components/form/codeeditor/editor.ts via a dynamic import in CodeEditorField.vue, so CodeMirror lands in its own chunk (same pattern as TipTap).

Package Version Use
@codemirror/state 6.7.6 EditorState
@codemirror/view 6.43.15 EditorView, keymap, lineNumbers, MatchDecorator, ViewPlugin, lineWrapping, contentAttributes
@codemirror/language 6.13.1 bracketMatching, HighlightStyle, syntaxHighlighting
@codemirror/commands 6.11.1 history, historyKeymap, defaultKeymap (without Mod-Enter)
@codemirror/lang-html 6.4.12 html() grammar
@codemirror/lang-css 6.3.1 css() grammar
@lezer/highlight 1.2.5 tags for HighlightStyle.define (direct pin; UI-SPEC lists it as transitive)

Not used: the codemirror meta package (basicSetup), and indentWithTab from @codemirror/commands.

Keymap rule (research Pitfall 5): extensions use keymap.of([...historyKeymap, ...defaultKeymap.filter((b) => b.key !== 'Mod-Enter')]). Tab is unbound so focus leaves the editor; Mod+S and Mod+Enter remain the form save hotkeys; Esc does not cancel the form.

Why

  • MIT, modular, no workers. CSP stays unchanged (worker-src not required). Accessible contenteditable surface.
  • Rejected alternatives (UI-SPEC): Monaco (size, workers), Ace (weaker a11y), a textarea overlay (caret sync), TipTap source mode (rich-text tool, not a code editor).

Transitive packages

Pulled in by the pins above (not listed as direct dependencies unless already above):

  • @lezer/* HTML/CSS grammars via @codemirror/lang-html / @codemirror/lang-css
  • @codemirror/autocomplete and @codemirror/lang-javascript via @codemirror/lang-html
  • style-mod, w3c-keyname, crelt
  • @marijn/find-cluster-break (transitive of @codemirror/state)

Legitimacy

Re-checked with read-only npm view <pkg>@<ver> dist.integrity on 2026-11-13 before any install. Matches the Phase 35 research Package Legitimacy Audit (maintainer marijn, no postinstall scripts, high weekly downloads, official CodeMirror / lezer sources).

Package Version dist.integrity Notes
@codemirror/state 6.7.6 sha512-kAz+AncRtKuIknedxT1bq4XwXv4UowhbkHU1myPrtVb/jZtImWuV5BXzv5vK6i3kYACsdiZiQKFQQ5Mq7elW8w== [OK]
@codemirror/view 6.43.15 sha512-HHsfpqFeHyXLs983pSRe38Xajs0vFWZQ2BuX0m7Ki8w3jZ5iD8cuR3lBz2/5/X53Dhf32SBHKh6rtSTB6tKeGw== [SUS] too-new — published 2026-10-19 (18 days old on 2026-11-06 audit; past the project's 7-day cooldown). Same maintainer as every other CodeMirror pin. Human checkpoint before install.
@codemirror/language 6.13.1 sha512-zfvU2r3TyylQLMj/te+5CnQ0rSqZi8B1oTCBbQkagcLW4Xc6imab6qN+pEJhsuNOLaJqiRyBXp9UhWA1DhVvDw== [OK]
@codemirror/commands 6.11.1 sha512-O/4hG3SC1YwcmQ0d2UVNDs+AsaNWd1iHVxbTeEBuqH+6bExAiPK3iS/BvpY6rZGURALv4ZD3sIgcCmRvw3ehBg== [OK]
@codemirror/lang-html 6.4.12 sha512-pw2ReWKUqSkbvh76RAT4NYxiogRu+PWkR2ukAwO9uOgrm8uipkzjtKKtNpyeAQwHOqxEeSvAXZ6vr3AfyB9y/w== [OK]
@codemirror/lang-css 6.3.1 sha512-kr5fwBGiGtmz6l0LSJIbno9QrifNMUusivHbnA1H6Dmqy4HZFte3UAICix1VuKo0lMPKQr2rqB+0BkKi/S3Ejg== [OK]; also maintainer adrianheine
@lezer/highlight 1.2.5 sha512-O1GMVKgtf5YspFaRzpmqkVgMtIk2HG9uMAbH6wdAIdNh3TVzCsch/+cRi+6l2//UGDKe6NB9BW3cvuR5ezMQ0w== [OK]

Install only after the Task 3 human gate: npm --prefix admin install --save-exact with exactly these pins, then npm --prefix admin ci against the committed lockfile. Lockfile integrity for each package must equal the values above.

Consequences

  • Layout and partial HTML/CSS/text editing uses a real editor with Go {{ ... }} action highlighting (cm-summer-action), without changing the design-system colour tokens.
  • A load failure falls back to a monospace textarea that still saves (UI-SPEC C1).
  • @codemirror/view 6.43.15 may be replaced with 6.43.14 or older if the human checkpoint rejects the too-new flag; update this note and STACK.md in that case before installing.