From a31755de22bf9c0ffdd95c3779c86d29a2d4aee2 Mon Sep 17 00:00:00 2001 From: Stefan Haller Date: Thu, 11 Jun 2026 08:36:54 +0200 Subject: [PATCH] Rename the diff-line-metadata OSC from 456 to 1717 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The terminal-allocation audit settled the protocol's OSC number on 1717 (unused by every surveyed terminal — see diff-line-metadata-osc-spec.md), retiring the 456 placeholder. Rename the host side to match: the gocui carrier that accumulates and reads back the sequence, the parser, and the handshake env var the pager subprocess is given (now EMIT_OSC1717_METADATA). Flip the design notes and spec from 'rename pending' to done. The delta and difftastic emitters are renamed in their own repos. Co-Authored-By: Claude Opus 4.8 (1M context) --- diff-line-metadata-notes.md | 14 +++++++------- diff-line-metadata-osc-spec.md | 4 ++-- focused-main-view-notes.md | 8 +++++--- pkg/gocui/escape.go | 6 +++--- pkg/gocui/view.go | 8 ++++---- pkg/gocui/view_test.go | 6 +++--- pkg/gui/controllers/helpers/diff_line_parser.go | 2 +- pkg/gui/pty.go | 2 +- 8 files changed, 26 insertions(+), 24 deletions(-) diff --git a/diff-line-metadata-notes.md b/diff-line-metadata-notes.md index ba63c8acc..80e9a31fb 100644 --- a/diff-line-metadata-notes.md +++ b/diff-line-metadata-notes.md @@ -230,9 +230,9 @@ through `Diff.AdjustLineNumber` before opening the editor, exactly as today > iTerm2, Windows Terminal, Ghostty, VS Code, ConEmu, urxvt**; `1717` collides with > none and sits in the large empty 1400–5000 band (only iTerm2's `1337` is nearby). > The full danger list is in the spec appendix (`diff-line-metadata-osc-spec.md`). -> **The prototype code (delta/difftastic/gocui/lazygit + the `EMIT_OSC456_METADATA` -> env var) still uses `456`** — renaming `456`→`1717` across the three repos is a -> tracked follow-up, not yet done. +> **The prototype code has been renamed `456`→`1717`** across all three repos +> (delta/difftastic/gocui/lazygit), and the handshake env var is now +> `EMIT_OSC1717_METADATA`; builds + the metadata unit tests are green in each. Known-used slots to avoid (verified in the audit): `0–3` (title/icon/X11), `4/5/6` (palette/special/tab color), `7` (cwd), `8` (hyperlinks), `9` @@ -501,8 +501,8 @@ logic is a near-copy of `linenumbers_and_styles`. ### 9.2 Pinned v1 wire format (final OSC `1717`; prototype code still uses `456`) > The number was finalized to **`1717`** after the terminal audit (§3.4); the -> prototype code still emits `456` (rename is a tracked follow-up). The published -> spec (`diff-line-metadata-osc-spec.md`) uses `1717`. +> prototype code has been renamed from the `456` placeholder to emit `1717`. The +> published spec (`diff-line-metadata-osc-spec.md`) uses `1717`. ``` ESC ] 1717 ; ; ; ; ; ST @@ -530,8 +530,8 @@ emits V1 when the advertised list contains `V1`. - **Terminal-source audit of the OSC number is DONE** (§3.4). Final number is **`1717`** (audited against xterm/VTE/kitty/foot/WezTerm/iTerm2/Windows Terminal/ Ghostty/VS Code/ConEmu/urxvt; danger list in the spec appendix). The prototype - code still emits the `456` placeholder — the `456`→`1717` rename across - delta/difftastic/gocui/lazygit + the env var is a tracked follow-up. + code has been renamed `456`→`1717` across delta/difftastic/gocui/lazygit + the + `EMIT_OSC1717_METADATA` env var; builds and metadata unit tests green in each. - **Wrapped continuation rows** (`Hunk*Wrapped`) get no attachment in the prototype — only the primary content row does. Fine for the normal case (gocui's own wrapping is handled host-side by the view-line→buffer-line mapping); delta-level diff --git a/diff-line-metadata-osc-spec.md b/diff-line-metadata-osc-spec.md index 0ee3cf4ca..e0e2b975d 100644 --- a/diff-line-metadata-osc-spec.md +++ b/diff-line-metadata-osc-spec.md @@ -408,8 +408,8 @@ per-line identity and is not addressed. ## 10. Reference implementations (prototype) -All three are at prototype quality and emit the v1 format described here (modulo -the placeholder OSC number, which these used `456` for before `1717` was chosen): +All three are at prototype quality and emit the v1 format described here, over +OSC `1717`: - **delta** — a dedicated additive emitter that injects only OSC bytes (no change to styling, width, or wrapping); with the env var unset, output is byte-for-byte diff --git a/focused-main-view-notes.md b/focused-main-view-notes.md index 90dcadfb0..0f4fd8c0f 100644 --- a/focused-main-view-notes.md +++ b/focused-main-view-notes.md @@ -1339,9 +1339,11 @@ unified single-column wire format is validated (§9.2), side-by-side is validate (§17 — v1 needs no addition), and the draft speaks to difftastic's token-vs-line mismatch (diff-line-metadata-notes.md §10.2). The **OSC number is resolved to `1717`** after a terminal-allocation audit (diff-line-metadata-notes.md §3.4 + -the spec appendix); `456` is retired as the placeholder. **Still pending:** the -`456`→`1717` rename across the prototype code (delta/difftastic/gocui/lazygit + the -`EMIT_OSC456_METADATA` env var), and circulating the draft for feedback. +the spec appendix); `456` is retired as the placeholder. The `456`→`1717` rename +across the prototype code (delta/difftastic/gocui/lazygit + the env var, now +`EMIT_OSC1717_METADATA`) is **done** — builds + metadata unit tests green in each +repo, and fresh delta/difftastic release binaries built. **Still pending:** +circulating the draft for feedback. **Decisions locked (session 6):** concurrency stays **mutex-based**, including for productionization (the main-thread-mutation rework is a separate, later effort — do diff --git a/pkg/gocui/escape.go b/pkg/gocui/escape.go index b19bea235..2fe84e3be 100644 --- a/pkg/gocui/escape.go +++ b/pkg/gocui/escape.go @@ -22,7 +22,7 @@ type escapeInterpreter struct { // the OSC number being accumulated while we don't yet know which OSC this is oscNumber strings.Builder - // the payload of an OSC 456 per-line diff-metadata sequence (see + // the payload of an OSC 1717 per-line diff-metadata sequence (see // diff-line-metadata-notes.md), accumulated like hyperlink metadata strings.Builder @@ -435,7 +435,7 @@ func (ei *escapeInterpreter) parseOne(ch []byte) (isEscape bool, err error) { case stateOSC: // Accumulate the OSC number until its terminating ';', then dispatch on // it. (The previous code only recognised the single-digit '8'; a number - // like 456 needs more than one character.) + // like 1717 needs more than one character.) switch { case len(ch) == 1 && ch[0] >= '0' && ch[0] <= '9': ei.oscNumber.WriteByte(ch[0]) @@ -445,7 +445,7 @@ func (ei *escapeInterpreter) parseOne(ch []byte) (isEscape bool, err error) { case "8": ei.hyperlink.Reset() ei.state = stateOSCParams - case "456": + case "1717": ei.metadata.Reset() ei.state = stateOSCMetadata default: diff --git a/pkg/gocui/view.go b/pkg/gocui/view.go index 98c5a048d..d2dd9384c 100644 --- a/pkg/gocui/view.go +++ b/pkg/gocui/view.go @@ -538,7 +538,7 @@ type cell struct { width int // number of terminal cells occupied by chr (always 1 or 2) bgColor, fgColor Attribute hyperlink string - // per-line diff metadata from an OSC 456 sequence (see + // per-line diff metadata from an OSC 1717 sequence (see // diff-line-metadata-notes.md); empty unless a pager emitted it metadata string } @@ -923,7 +923,7 @@ func (b *viewBuffer) write(v *View, p []byte) { if b.wy >= len(b.lines) { b.lines = append(b.lines, lineType{}) } - // An OSC 456 diff-metadata sequence applies only to the line it prefixes + // An OSC 1717 diff-metadata sequence applies only to the line it prefixes // (the pager re-emits one per line and never closes it), so drop it at the // line boundary rather than letting it carry onto a line with no metadata. b.ei.metadata.Reset() @@ -1810,7 +1810,7 @@ func (v *View) HyperLinkInLine(y int, urlScheme string) (string, bool) { return "", false } -// DiffLineMetadataInLine returns the OSC 456 per-line diff metadata payload +// DiffLineMetadataInLine returns the OSC 1717 per-line diff metadata payload // attached to the given (wrapped) view line, if a pager emitted one. In the // single-column case every cell of the line carries the same payload, so the // first non-empty one is the answer. See diff-line-metadata-notes.md. @@ -1834,7 +1834,7 @@ func (v *View) DiffLineMetadataInLine(y int) (string, bool) { // DiffLineContent is the raw per-line material the diff-line backends parse to // recover a rendered row's patch-space identity (see diff-line-metadata-notes.md): -// the decolorized text (for host-side parsing, mechanism #1), the OSC-456 +// the decolorized text (for host-side parsing, mechanism #1), the OSC-1717 // metadata payload a pager emitted (#2), and the line's hyperlink (delta's // lazygit-edit fallback). It is indexed by unwrapped buffer line, so one entry // covers all the (wrapped) view lines that line maps to. diff --git a/pkg/gocui/view_test.go b/pkg/gocui/view_test.go index cfc92d267..357e9b163 100644 --- a/pkg/gocui/view_test.go +++ b/pkg/gocui/view_test.go @@ -163,10 +163,10 @@ func TestDiffLineMetadata(t *testing.T) { v := NewView("name", 0, 0, 80, 10, OutputNormal) // Synthetic delta-style output: each content line is prefixed with an - // OSC 456 sequence carrying version;type;new;old;file (old empty unless a + // OSC 1717 sequence carrying version;type;new;old;file (old empty unless a // deletion), and the OSC bytes themselves must not become visible cells. The // final line is a header with no OSC, to prove the metadata doesn't bleed. - osc := func(payload string) string { return "\x1b]456;" + payload + "\x1b\\" } + osc := func(payload string) string { return "\x1b]1717;" + payload + "\x1b\\" } v.writeString(strings.Join([]string{ osc("1;c;1;;foo.txt") + "line1", osc("1;d;2;2;foo.txt") + "old2", @@ -269,7 +269,7 @@ func TestOffscreenDiffLineContents(t *testing.T) { // No off-screen render in progress: nothing to scan. assert.Nil(t, v.OffscreenDiffLineContents()) - osc := func(payload string) string { return "\x1b]456;" + payload + "\x1b\\" } + osc := func(payload string) string { return "\x1b]1717;" + payload + "\x1b\\" } v.BeginOffscreenRender() v.writeString(strings.Join([]string{ osc("1;c;1;;foo.txt") + "context", diff --git a/pkg/gui/controllers/helpers/diff_line_parser.go b/pkg/gui/controllers/helpers/diff_line_parser.go index 7695edf0d..fd9c8a3cf 100644 --- a/pkg/gui/controllers/helpers/diff_line_parser.go +++ b/pkg/gui/controllers/helpers/diff_line_parser.go @@ -156,7 +156,7 @@ func pathFromDiffGitLine(line string) string { return "" } -// parseDiffLineMetadata parses mechanism #2's OSC 456 payload (v1): +// parseDiffLineMetadata parses mechanism #2's OSC 1717 payload (v1): // version;type;new-line;old-line;file — positional and ';'-delimited, with the // file last (so it may itself contain ';') and old-line empty unless the line is // a deletion. See diff-line-metadata-notes.md §9.2. ok is false for a payload of diff --git a/pkg/gui/pty.go b/pkg/gui/pty.go index 97a94aa58..65086c8f6 100644 --- a/pkg/gui/pty.go +++ b/pkg/gui/pty.go @@ -105,7 +105,7 @@ func (gui *Gui) newPtyTask(view *gocui.View, cmd *exec.Cmd, prefix string) error // an OSC sequence we can read back (see diff-line-metadata-notes.md). A // pager that doesn't understand it ignores the variable, so this is safe to // set unconditionally. - cmd.Env = append(cmd.Env, "EMIT_OSC456_METADATA=V1") + cmd.Env = append(cmd.Env, "EMIT_OSC1717_METADATA=V1") manager := gui.getManager(view)