From db5b2810a927bdd57c923247bc9da98f0eb9c18d Mon Sep 17 00:00:00 2001
From: mwiegand <martin.wiegand@seibert.group>
Date: Sun, 17 May 2026 00:57:33 +0200
Subject: [PATCH] spec(textarea-editor): handoff after contenteditable rollback

Briefs the next brainstorming session with: what we built, the four
contenteditable failure modes that made it unshippable, what's still
in the repo (Playwright harness, dev-server, original spec/plan as
historical reference), the decision pending (CodeMirror 6 vs
textarea-overlay), inputs to load, and an explicit "don't restart
this cycle" caveat against trying a third contenteditable variant.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../2026-05-17-textarea-editor-handoff.md     | 245 ++++++++++++++++++
 1 file changed, 245 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-17-textarea-editor-handoff.md

diff --git a/docs/superpowers/specs/2026-05-17-textarea-editor-handoff.md b/docs/superpowers/specs/2026-05-17-textarea-editor-handoff.md
new file mode 100644
index 0000000..6b50657
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-17-textarea-editor-handoff.md
@@ -0,0 +1,245 @@
+# Textarea code editor — handoff after rollback
+
+> Follow-up artifact after a 35-commit attempt at a syntax-highlighting
+> + autocomplete editor (CodeJar + Prism over `contenteditable`) was
+> rolled back in commit `f14d352`. This is **not an implementation plan**
+> — it's a brief for the next brainstorming session to pick a different
+> architecture and produce a new spec. The "Don't restart this cycle"
+> note below is load-bearing.
+
+## Context
+
+We shipped a 12-task implementation of an in-browser code editor that
+upgraded three `<textarea>` fields in `l4d2web`:
+
+- Blueprint config (Source-engine cvar syntax, with cvar autocomplete)
+- Overlay bash script
+- Files-editor modal (auto-detect language from filename + dropdown override)
+
+The architecture: vanilla JS, no bundler, CSP-self-hosted. CodeJar
+(~3 KB) provided the editor shell over a `contenteditable` element;
+Prism (~25 KB, custom build of core + clike + bash) provided syntax
+highlighting. A small custom Prism grammar covered Source-engine
+`.cfg` syntax. Autocomplete was a ~150-line popup widget we wrote
+ourselves, backed by a curated 30-cvar + 8-command JSON vocabulary.
+
+Every code-review iteration caught real correctness bugs that we
+addressed (capture-phase keydown so CodeJar's Tab handler didn't eat
+the popup-accept; popup leak on destroy; async race in vocab loader;
+try/catch on the Range manipulation; theme-aware syntax-token CSS
+variables). Then a live inspection session surfaced four further
+classes of bug that we couldn't address without more whack-a-mole:
+
+1. **Copy collapses multi-line selections to one line.**
+2. **Enter sometimes needs two presses + cursor color shifts.**
+3. **Auto-completion fails silently at end-of-line** (the caret sits
+   in a post-Prism-`<span>` text node, so the Range-API subtraction
+   goes negative).
+4. **Manual caret save/restore is required around any
+   `updateCode` call** — and even with that, the caret can land
+   "between" sibling nodes where browsers render it differently.
+
+All four are characteristic of `contenteditable` + manual Range API
+manipulation against tokenized DOM. The architecture was wrong for
+the goal. Rolling back to the editor-free baseline was the right call;
+each new fix was reinforcing a sunk-cost path.
+
+## What's in the repo now
+
+### Removed (in commit `f14d352`)
+
+- `l4d2web/l4d2web/static/js/editor.js`
+- `l4d2web/l4d2web/static/js/srccfg-grammar.js`
+- `l4d2web/l4d2web/static/css/editor.css`
+- `l4d2web/l4d2web/static/vendor/{prism.js,prism.css,codejar.js,README.md}`
+- `l4d2web/l4d2web/static/data/srccfg-vocab.json`
+- `l4d2web/l4d2web/templates/_editor_assets.html`
+- `l4d2web/tests/e2e/test_editor.py`
+- The `data-editor-language` attributes and partial includes on
+  `blueprint_detail.html`, `overlay_detail.html`
+- The files-overlay.js editor bridge (`setEditorContent`, dropdown
+  listener, filename auto-redetect)
+- The create-blueprint modal trim (Arguments + Config textareas restored)
+- The four syntax-color tokens added to `tokens.css`
+- Three form-contract tests in `test_blueprints.py` /
+  `test_script_overlay_routes.py`
+
+### Kept (informs the next attempt)
+
+- `docs/superpowers/specs/2026-05-16-textarea-code-editor-design.md` —
+  the original design spec. Still useful as the **functional**
+  requirements (which textareas to upgrade, what autocomplete should
+  do, what languages to support). The architectural choices in there
+  (CodeJar, Prism) are stale; the requirements are not.
+- `docs/superpowers/plans/2026-05-16-textarea-code-editor.md` — the
+  12-task plan. Stale architecturally; useful as a reference for the
+  testing strategy (form-contract assertions, Playwright e2e shape).
+- `scripts/dev-server.py` — boots Flask locally with all the
+  production-equivalent env vars (DATABASE_URL, LEFT4ME_ROOT,
+  SESSION_COOKIE_SECURE=0, JOB_WORKER_ENABLED=false). Auto-seeds an
+  admin user (`dev`/`devdevdev`) plus a blueprint, two overlays, and a
+  server on first run so the next iteration can be inspected
+  immediately at `/blueprints/1`, `/overlays/1`, `/overlays/2`, and
+  `/servers/1`.
+- `l4d2web/tests/e2e/{__init__.py,conftest.py,test_smoke.py}` —
+  Playwright scaffolding. The `live_server` fixture in `conftest.py`
+  boots the Flask app on an ephemeral port with a temp SQLite DB,
+  seeds a user + blueprint, yields `{base_url, user_id, blueprint_id}`.
+  Ready to receive a new `test_editor.py` against whatever shape the
+  next editor takes.
+- `pyproject.toml` — `playwright>=1.49.0` + `pytest-playwright>=0.6.0`
+  in `[dependency-groups].dev`, `e2e` marker registered,
+  `addopts = ["-m", "not e2e"]` so the default fast suite excludes
+  browser tests.
+- `AGENTS.md` — documents `uv run playwright install chromium` for
+  first-time setup, plus the Claude Code sandbox + Chromium Mach-port
+  workaround.
+
+## The four bugs (so the next attempt can sanity-check itself)
+
+These are the failure modes that surfaced. The next architecture
+should either *avoid the class of bug entirely* or *have evidence of
+having solved it in the chosen library*.
+
+1. **Selection.toString() collapses across span topology.** Prism's
+   tokenized output emits `<span>for</span>` `<span>vpk</span>`
+   `<span>in</span>` … with newlines either inside spans or as bare
+   sibling text nodes. The browser's copy implementation walks the
+   selection via `Selection.toString()` and doesn't reliably
+   reconstruct newlines across that mix. Workarounds need a `copy`
+   event handler that overrides the clipboard payload from the
+   editor's *source text*, not the DOM walk.
+
+2. **Caret can land "between" sibling DOM nodes.** When the caret is
+   at end-of-line or between two adjacent tokenized spans, the
+   browser's selection has `anchorNode === <code>` (the parent
+   element) and `anchorOffset` indexing into its children — NOT a
+   text node. Most range-manipulation code assumes text-node
+   containers and fails (silently or loudly) in this state. The
+   visual cue is a different-color caret.
+
+3. **Manual `Range.setStart(endContainer, endOffset - N)` is unsafe.**
+   It assumes the trailing N characters live in `endContainer`. When
+   the fragment is *upstream* of the caret's actual text node (case
+   2), the subtraction goes negative → `IndexSizeError`. We worked
+   around it with `Selection.modify('extend', 'backward', 'character')`
+   but the underlying fragility persists.
+
+4. **CodeJar's `updateCode(text)` does not preserve caret.** It does
+   `editor.textContent = code; highlight(editor)` and returns; the
+   caret resets to start. Manual `jar.save()` + `jar.restore(pos)` is
+   required around it. Even then, `save()` has a special case at
+   `codejar.js:122-127` that returns end-of-all-text if the selection
+   sits in the editor element rather than a text node — interacting
+   badly with case 2.
+
+In aggregate, these are the bugs a *generic* contenteditable wrapper
+inherits. A mature library (CodeMirror 6) has invested years in
+handling them. A textarea-overlay approach avoids them by construction
+because the editing surface is a real `<textarea>`.
+
+## Decision pending
+
+Two finalists for the next attempt:
+
+| Concern | Option 2: CodeMirror 6 | Option 3: Textarea-overlay |
+|---|---|---|
+| Bundler aversion | adds a one-time `npm install` + bundle step | no bundler |
+| Editing fluency (selections, IME, mobile, copy/paste) | strong (years of contenteditable hardening) | strong (native `<textarea>`) |
+| IDE features (line numbers, search, multi-cursor) | strong, built-in or import-away | basic only; you'd build them |
+| Autocomplete popup positioning | trivial (built-in `@codemirror/autocomplete`) | medium (mirror-div trick for caret pixel coords; well-known recipe, ~30 LOC) |
+| Risk of recurring contenteditable bugs | low (handled) | none (no contenteditable) |
+| Bundle weight | ~150 KB gzipped | ~10 KB Prism + ~80 LOC overlay JS |
+| Source-cfg language | Lezer parser (more correct, more work) | Prism regex grammar (we already wrote one) |
+| Long-term maintenance | high (heavy dep, but stable) | low (vanilla; font-metric edge cases) |
+
+### Recommendation (advisory only)
+
+**Option 2 (CodeMirror 6)** — the contenteditable bugs we just hit are
+exactly what CodeMirror 6 was built to solve, and the "no bundler"
+constraint we set originally cost us more in whack-a-mole than the
+one-time build step would have. But Option 3 is also defensible and
+carries zero contenteditable risk.
+
+Don't pre-commit to either before the brainstorming session
+re-examines the requirements; this is just the controller's lean
+after living through the failure.
+
+## Inputs for the next session
+
+When you start brainstorming the next attempt, load these:
+
+```
+docs/superpowers/specs/2026-05-16-textarea-code-editor-design.md
+    Original requirements (still valid)
+docs/superpowers/plans/2026-05-16-textarea-code-editor.md
+    Original plan (architecturally stale, useful for testing strategy)
+docs/superpowers/specs/2026-05-17-textarea-editor-handoff.md
+    This document
+```
+
+Useful runtime entry points:
+
+```bash
+# Local smoke (Flask + seeded demo content)
+./scripts/dev-server.py
+# Then visit http://127.0.0.1:5051/login as dev / devdevdev
+
+# Fast test suite (excludes e2e)
+uv run pytest
+
+# E2E suite (needs `playwright install chromium` once; pass
+# dangerouslyDisableSandbox: true on Claude Code's Bash tool because
+# Chromium's Mach-port IPC is blocked by the sandbox)
+uv run pytest -m e2e
+```
+
+The dev-server seeds (idempotent on `.tmp/dev-server` being clean):
+
+- Blueprint `id=1` `demo-srccfg` — has Source-engine `.cfg` content
+  ready to highlight
+- Script overlay `id=1` `demo-bash` — has example bash for highlighting
+- Files overlay `id=2` `demo-files` — has `test.cfg` ready to open in
+  the files-editor modal
+- Server `id=1` `demo-server` linked to the blueprint
+
+## Open questions for the brainstorming session
+
+1. **Decision: Option 2 or Option 3.** Don't skip this — it shapes
+   everything downstream.
+2. If **Option 2**: where does the `npm install` + `esbuild` step
+   live? `l4d2web/scripts/build-editor.sh`? A `Makefile` target?
+   How is the bundle's provenance recorded (SHA256s, as we did with
+   prism/codejar)? Does the bundle commit to `static/vendor/` or
+   gets generated on demand?
+3. If **Option 2**: which CodeMirror packages exactly? Minimum useful
+   set is probably `@codemirror/state`, `@codemirror/view`,
+   `@codemirror/commands`, `@codemirror/lang-bash`, `@codemirror/autocomplete`,
+   plus a custom Source-cfg StreamLanguage or Lezer grammar.
+4. If **Option 3**: how does the autocomplete popup re-position on
+   window scroll / page resize? Cross-browser font-metric quirks
+   (Safari vs Chrome vs Firefox) — are we OK testing only Chromium?
+5. **Form-contract testing**: the form-POST contract for the blueprint
+   config / overlay script doesn't change regardless of which option
+   we pick. Pre-write the form-contract tests against the textarea's
+   eventual hidden/upgraded state so we know the contract holds early.
+6. **Playwright e2e shape**: the harness is ready. The test that
+   types `sv_che`, asserts the popup, accepts via Tab, asserts the
+   textarea value — should be re-usable verbatim against either
+   approach. Use it as the gate.
+
+## Don't restart this cycle
+
+The temptation will be to try a third contenteditable variant ("maybe
+if we just add a different library on top of contenteditable…").
+**Resist.** The bug classes we hit are characteristic of
+contenteditable + tokenized DOM, not specific to CodeJar. A new
+contenteditable wrapper that hasn't been hardened against years of
+edge cases will reproduce the same bugs.
+
+The two options that survive this constraint:
+
+- A library that *has* been hardened (CodeMirror 6).
+- An approach that *doesn't use* contenteditable at all (textarea-overlay).
+
+Both are real options. Pick one.