pmacs/docs/comment-toggle-framing.md

Comment/uncomment — framing (Arc 2, editing table stakes)

pmacs has no way to comment code out. This adds the table-stakes toggle: M-; comments or uncomments the current line or the selected lines, language-aware, as one undoable edit.

Roadmap: docs/roadmap-2026-07.md Arc 2 ("comment/uncomment").

Ground truth (as of 2dde4b8)

• No comment-syntax knowledge exists anywhere — not in the grammar registry, not in LSP config, not in Lua. A language → prefix table is new surface.
• Language detection: active_buffer_language() in builtin/runtime/lsp.lua chains grammar detection (pmacs.parse.language_for_path) with the user-extensible pmacs.lsp.filetypes map — but it is a local. Known languages today: rust/lua/c/cpp + js/ts via grammars; python, c, go, tsx/jsx, lua, bash, toml, zig via filetypes.
• Bindings: M-; (Emacs comment-dwim's home) is free. C-/ is taken by undo (terminal Ctrl+/ ambiguity — three undo bindings exist), so the VSCode-style toggle chord is unavailable.
• Undo granularity: every applied edit pushes one UndoEntry (src/buffer.rs:130) — there is no grouping/transaction. N per-line edits would need N undos.
• From Arc 2 (merged): the buffer mutators return the effective post-intercept edit (start, end, inserted_len); keybound commands rotate the command boundary and get buffer.after-edit from dispatch; M-x gets both via invoke_interactive + with_after_edit_check. Comment-toggle inherits all of it for free.

Decisions

Q#CT1 — Pure Lua, zero Rust changes

builtin/runtime/comment.lua. Everything needed exists: buf:slice, the effective-edit-returning buf:replace, ed.region/cursor/ goto_byte/clear_selection, and the language chain. The one lsp.lua touch: export the existing local as pmacs.lsp.active_buffer_language() (one line) rather than replicating its grammar+filetypes chain and drifting.

Q#CT2 — Command + binding

One command, edit.toggle-comment, bound M-;:

• Region active → toggle the whole lines the region touches, then clear the selection (CUA convention after a region op) and leave the cursor at the span start.
• No region → toggle the current line, then move to the next line — Emacs's comment-line behavior, which makes repeated M-; walk down a block toggling as it goes.

Named deviation from Emacs: M-; in Emacs is comment-dwim, whose no-region case appends an empty comment at end of line. That mode is rarely what modern muscle memory wants from the toggle key; pmacs's M-; behaves like Emacs C-x C-; (comment-line). DWIM's append-comment can come later under its own name.

Q#CT3 — The comment-string table

pmacs.comment.strings — a public, user-extensible map (the pmacs.lsp.filetypes pattern), language → line-comment prefix:

//: rust, c, cpp, go, zig, javascript, typescript, javascriptreact, typescriptreact · --: lua · #: python, bash, toml, yaml, sh.

Unknown language (or no language): status "no comment syntax known for <lang>", no edit. Users add entries from init.lua: pmacs.comment.strings.mylang = ";;". Block comments are deferred — line comments cover the table-stakes use, and block toggling has real edge cases (nesting, mid-line spans) that don't belong in v1.

Q#CT4 — Toggle semantics

Over the span's lines:

• Uncomment when every non-blank line starts (after its indentation) with the prefix; removal strips the prefix plus one following space if present.
• Comment otherwise: insert prefix + " " at the minimum indentation column of the span's non-blank lines (Emacs comment-region style — the comments line up instead of hugging each line's own indent). Blank lines are skipped in both directions and don't influence the min-indent computation.
• A span that is entirely blank is a no-op with a status.

Mixed spans (some commented, some not) therefore comment — the double-prefix on already-commented lines round-trips back out, which is Emacs's behavior and preserves inner commented-out code.

Q#CT5 — One edit, one undo step, one CRDT op

The whole toggle is a single buf:replace(span_start, span_end, new_text): Lua builds the rewritten span, one edit applies it. Consequences, all deliberate:

• One C-/ undoes the whole toggle (there is no undo grouping to lean on; N per-line edits would need N undos).
• One CRDT op for replica frontends.
• One effective-edit verification: the kill-ring discipline — if the returned (start, end, inserted_len) deviates from the request (a buffer intercept rewrote it), report "comment toggle altered by buffer intercept" and skip the cursor fix-up; the interceptor's result stands. pcall'd, so a rejecting intercept reports rather than throws.

Q#CT6 — Chain/hook plumbing: nothing to build

Keybound M-; rotates the command boundary (breaking kill chains — correct) and fires buffer.after-edit from dispatch's revision check; M-x edit.toggle-comment gets the same via invoke_interactive and the accept-path hook wrapper. Both are the Arc 2 substrate working as designed — the acceptance suite asserts the hook fires once anyway.

Bets

1. Single-replace is the right granularity — no complaint about whole-span replaces (vs. per-line edits) from CRDT replicas or LSP didChange (full-text sync makes this moot today).
2. Min-indent + skip-blank matches expectation — no "why is my comment at column 0" or "why did my blank line get a //".

Deferred (named)

• Block comments (/* */) and mid-line spans.
• comment-dwim's append-comment-at-EOL mode.
• Doc-comment continuation on newline (belongs to auto-indent).
• Per-language padding config (always one space in v1).

Acceptance (tests/comment_toggle_acceptance.rs, dispatch-driven)

• Rust buffer: M-; comments the line (// at indent), cursor moves to the next line; M-; on a commented line uncomments (round-trip, including the space).
• Region across mixed-indent lines → prefixes at min indent, aligned; blank line inside the span untouched; selection cleared.
• All-commented span → uncomments; mixed span → comments (inner prefix preserved, round-trips).
• Lua buffer gets --, Python #; unknown/no language → status, no edit.
• One undo step: multi-line toggle then a single buffer.undo restores the original text exactly.
• Intercept discipline: rejecting intercept → status, no throw; transforming intercept → reported, no cursor fix-up.
• after-edit probe fires exactly once per toggle (keybound and M-x).
• Kill-chain break: C-k, M-;, C-k → two ring entries.