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>
This commit is contained in:
2026-11-13 13:15:23 +01:00
parent 52204e171d
commit 6e0d4bbca7
2 changed files with 71 additions and 0 deletions

View File

@@ -0,0 +1,59 @@
# 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.

View File

@@ -81,6 +81,18 @@ Added 2026-10-12 (quick task 261012-s3g). Exact pins in `admin/package.json`, co
| @vitest/browser | 3.2.7 (dev) | Vitest browser mode for tests that need a real engine (`npm --prefix admin run test:browser`) | Must match vitest 3.2.7 exactly. See the decision note. |
| playwright | 1.60.0 (dev) | Chromium provider for Vitest browser mode | Not the deferred Phase 10 e2e suite (D-23). Needs the chromium build on the machine. See the decision note. |
Added 2026-11-06 (Phase 35 mail editor). Exact pins in `admin/package.json` after the human legitimacy checkpoint; committed lockfile; installed with `npm ci`. Lazy-loaded from `admin/src/components/form/codeeditor/editor.ts` only.
| Library | Version | Purpose | Notes |
|---------|---------|---------|-------|
| @codemirror/state | 6.7.6 | codeeditor field (Phase 35) | Runtime. See `.planning/notes/2026-11-06-admin-code-editor-codemirror.md`. |
| @codemirror/view | 6.43.15 | codeeditor field (Phase 35) | Runtime. [SUS] too-new on 2026-11-06 audit (past 7-day cooldown); same maintainer. Checkpoint before install. |
| @codemirror/language | 6.13.1 | codeeditor field (Phase 35) | Runtime. See the decision note. |
| @codemirror/commands | 6.11.1 | codeeditor field (Phase 35) | Runtime. defaultKeymap without Mod-Enter; no indentWithTab. |
| @codemirror/lang-html | 6.4.12 | codeeditor field (Phase 35) | Runtime. `language: html`. |
| @codemirror/lang-css | 6.3.1 | codeeditor field (Phase 35) | Runtime. `language: css`. |
| @lezer/highlight | 1.2.5 | codeeditor field (Phase 35) | Runtime. Direct pin for HighlightStyle tags. |
## Installation
```bash