We stopped updating these notes once the real work moved to
focused-main-view-notes.md and the production plan, but two things in them
have since become actively misleading rather than merely stale: they say in
five places that the protocol is content-lines-only, and they use the env
var name from two renames ago.
Mark the document historical, name the spec as the authority, and correct
§11's outcome banner in place rather than rewriting it, so the reasoning
that led to dropping `f`/`h` is still on record next to the reason it was
reversed -- which is the very cost that banner judged acceptable.
Don't touch the `EMIT_OSC1717_METADATA` spellings further down: they are
what those prototypes were built with, and the status block now says so.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Record the third pager emitter (diff-so-fancy, commit c397cd6 on its
prototype-osc-metadata branch): the simplest of the three -- a line-oriented
Perl filter, unified single-column only, the same #2 category as delta's
default. Captures the diff-so-fancy-specific findings: sanitize_display strips
OSC so the record is prepended not embedded; the path is derived from
$file_1/$file_2 (not $last_file_seen, which is empty for a noprefix deletion);
combined diffs skipped; counters are file-scope globals so a chunk-spanning hunk
keeps counting; classification mirrors strip_leading_indicators so the
no-newline marker is correctly skipped.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Re-verified empirically: a pure deletion's new-line is exact at default context
(difftastic emits d;4;4) and only drifts at --context 0 (d;1;4, low by the elided
count); old-line is exact either way. lazygit renders at default context, so the
drift isn't reachable in normal use, and even at zero context the only effect is
that 'e' on a deleted line opens the new file a few lines off — inherently
approximate, since the line isn't in the new file. Too marginal to keep as a v1
limitation, so §8 collapses to the single token-vs-line note. Re-verification
recorded in the design notes.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Incorporate the round of feedback before circulating to pager developers. The
substantive decisions:
- Make f and h (file-header / hunk-header) mandatory v1 record types and drop the
speculative o; a header carries new-line = its hunk's first line so e lands near
what the user is looking at, and a multi-row header block (delta's box) re-emits
the record on every row, mirroring the wrapped-row rule. This replaces the old
reserved-and-unused framing and the host-side backUpOverHeader guessing.
- A host must ignore an unrecognized type rather than reject the record, so the
type set can grow without a version bump.
- Drop sections that were redundant or over-stated: §5.4 (the side is already
motivated in §1), §8.1 (c/a old-line is a host concern with no consumer), §8.4
(word-diff), and the at-most-two-records and trailing-fields paragraphs.
- Tighten the difftastic token-vs-line note (now §8.1): the c-on-a-pure-addition
old line only happens in difftastic's AST mode and the record faithfully matches
what difftastic renders (dim context); its line/Text fallback emits d/a normally.
- Document the rename rule for the file field, and reframe §7 as the host access
model the carrier is designed for rather than a description of the prototype.
Also record in the design notes the one user-visible bite of the token-vs-line
model: cross-pager selection preservation (delta d vs difftastic-AST c) — a host
concern kept out of the spec.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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) <noreply@anthropic.com>
Resolve the OSC number from the 456 placeholder to 1717. There is no central
registry for OSC numbers, so the audit reduces to: pick a high, distinctive
number that no real terminal *acts on* — an unknown OSC is skipped harmlessly,
but a recognized one can fire a visible side-effect (OSC 555 flashes foot, OSC
777 raises a desktop notification), and the metadata flows through real
terminals whenever the pager runs outside a host. Audited the live OSC
allocations of xterm, VTE, kitty, foot, WezTerm, iTerm2, Windows Terminal,
Ghostty, VS Code, ConEmu and urxvt; 1717 collides with none and sits in the
empty 1400-5000 band (only iTerm2's 1337 is nearby).
Write the spec as a standalone draft to circulate to pager developers for
feedback — separate from the internal session notes, with motivation, the v1
wire format, the env handshake, semantics, emit rules (including the per-row
wrapping correction and the side-by-side two-records-per-row case), and the
known v2 candidates (both-numbers-always, the difftastic token-vs-line
mismatch). The prototype code still emits the 456 placeholder; the 456->1717
rename across delta/difftastic/gocui/lazygit and the EMIT_OSC<n>_METADATA env
var is a tracked follow-up, not part of this commit.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Record session 8 — preserving scroll/selection when cycling pagers, as
the seventh consumer of the identity-based restore. Captures why both the
plain-pager (GIT_PAGER, line-number kept) and externalDiffCommand
(command changes, reset to top) cases needed it, the "main"-window-only
scope, the graceful no-op fallback, and that the side-by-side<->inline
structural win awaits the §17.4 row+column resolver.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The same pager-level wrapping gap found in difftastic (§10.8) was fixed in delta
too. Delta only wraps in side-by-side mode, so the bug was SxS-only; each wrapped
continuation row now re-emits the record of the primary line it continues,
without advancing delta's line-number counters (so subsequent lines keep correct
numbers). Update §9.3, §10.8, and the §17.1 correction note accordingly.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Testing the difftastic prototype in lazygit exposed that the "wrapped
continuation rows carry no attachment" convention is a bug whenever the pager
itself wraps a long line (difftastic side-by-side, delta with wrap-max-lines):
each wrapped row is a distinct host buffer line, so e/enter and hunk navigation
break on the un-tagged continuation rows. The fix -- emit the line's record on
every output row, not just the first -- was applied to difftastic; delta needs
the same. Record the underlying distinction (terminal/host wrapping vs
pager wrapping) and state the spec rule positively (§10.8).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
difftastic is now prototyped as an OSC-metadata emitter in both its modes
(side-by-side and inline), the one pager mechanism #1 categorically cannot
serve. The notes capture what was built and, more importantly, what it reveals
about the v1 format: it holds, but difftastic's token-granular structural model
surfaces a model mismatch the unified-diff pagers hid -- an aligned row whose
old side has no novel tokens is faithfully a context cell plus an addition cell,
with no deletion record for the old side. Also resolves the "how many regions
per row" open question (two, not N) and amplifies the §17.3 "context/added carry
no old-line" limitation, since difftastic's old/new line numbers diverge with no
constant offset.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Capture a design discussion (no code yet; implementation is a future session):
- The escape-from-staging restore should anchor on the explorer view's current
patch identity at escape time, not a saved numeric scroll/index, since staging
or dropping hunks changes the content. This is the inverse direction of the
diff-line-metadata primitive (identity -> rendered row) and the same operation
the -U scroll-preservation consumer needs; record it as consumer #6 and split
the consumer list into forward (1-4) and inverse (5-6) directions.
- Record the escape-routing cases the current prototype gets wrong (staging the
last hunk should land in the staged half; <tab> between staged/unstaged; the
empty-view and custom-patch-builder cases).
- Decide to solve the new restore mechanism, the §11 timing races, and the
BufferLineForViewLine staleness trap together in the prototype rather than
defer them to productionization (you can't plan around unsolved entangled
mechanisms), with a dependency-first attack order (§8 fix, characterize the
races, then the predicate-scroll restore).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The emitter (delta), carrier (gocui per-cell attachment), and consumer (the
GetDiffLineInfo metadata backend + env-var handshake) are now built for the
normal unified case and verified end-to-end — including in the running app with
delta's default mode, where clicking/enter/e/G resolve via #2 and deletions get
the correct side. Update §9 from "in progress" to a "built & verified" record
(what was built, how it was verified) mirroring §8 for #1, and mark the build
order (§7) accordingly. The remaining step-5 deliverables — finalizing/publishing
the spec and the production plan — and side-by-side/difftastic are still open.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Mechanism #2's emitter side is now prototyped on this branch (delta, normal
unified mode only) and the bytes are verified. Capture what that settled, since
the spec is meant to be published for pager-developer feedback:
- The single per-line emit point in delta and which fields are reachable there
(the gotcha: delta only maintains its line-number counters with --line-numbers
on, so the patch tracks its own), and why a dedicated additive emitter beats
reusing LineNumbersData.
- The pinned v1 wire format (positional, file last so it may contain ';',
empty old-line unless deleted) and the EMIT_OSC456_METADATA env-var handshake.
- Deferred items: the OSC-number terminal audit, wrapped continuation rows, and
header-row attachments.
Also resolves the §6 wire-format open question accordingly.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Record what the #1 prototype settled. The two open questions #1 touches are now
answered (the deleted-line new-line convention is patch.LineNumberOfLine's, and a
deletion carries both line numbers; multi-file diffs split on "diff --git" and
the section parses 1:1 with patch.Parse). Add a §8 capturing what landed, how it
was verified, and the implications for #2.
Two coverage corrections came out of verifying against real pager output, both
worth pinning before the spec is written: delta --color-only qualifies for #1
only *without* line numbers (the gutter pushes the +/- marker off column 0, so a
naive parse is confidently wrong — handled by an integrity check that falls back,
not by teaching the host delta's gutter), and diff-so-fancy strips the +/- markers
entirely, so it's a #2 case, not #1.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Captures a design discussion about the remaining big problem behind the
focused-main-view feature: recovering a diff row's patch-space identity
(file, type, source line) when the rendering came from a pager. Records
the two complementary mechanisms (a host-side parser for
structure-preserving renderings, and a pager-emitted OSC protocol for
ones that restructure), the per-cell carrier with its keyboard/mouse
access rules, the type + old?/new-line payload and why each field is
load-bearing, and the version-negotiation handshake. Design only; no
implementation yet.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
