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>
This commit is contained in:
mwiegand
parent
f14d352657
commit
db5b2810a9
1 changed files with 245 additions and 0 deletions
245
docs/superpowers/specs/2026-05-17-textarea-editor-handoff.md
Normal file
245
docs/superpowers/specs/2026-05-17-textarea-editor-handoff.md
Normal file
|
|
@ -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.
|
||||||
Loading…
Reference in a new issue