From 6e0d4bbca7175611fce66b1f7f0d39fb21025438 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Fri, 13 Nov 2026 13:15:23 +0100 Subject: [PATCH] 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 --- ...2026-11-06-admin-code-editor-codemirror.md | 59 +++++++++++++++++++ .planning/research/STACK.md | 12 ++++ 2 files changed, 71 insertions(+) create mode 100644 .planning/notes/2026-11-06-admin-code-editor-codemirror.md diff --git a/.planning/notes/2026-11-06-admin-code-editor-codemirror.md b/.planning/notes/2026-11-06-admin-code-editor-codemirror.md new file mode 100644 index 00000000..a59dc306 --- /dev/null +++ b/.planning/notes/2026-11-06-admin-code-editor-codemirror.md @@ -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 @ 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. diff --git a/.planning/research/STACK.md b/.planning/research/STACK.md index 14919146..09d82011 100644 --- a/.planning/research/STACK.md +++ b/.planning/research/STACK.md @@ -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