- 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>
60 lines
4.6 KiB
Markdown
60 lines
4.6 KiB
Markdown
# 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.
|