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:
59
.planning/notes/2026-11-06-admin-code-editor-codemirror.md
Normal file
59
.planning/notes/2026-11-06-admin-code-editor-codemirror.md
Normal 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.
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user