Agent layer

Diff

The main artefact of an agent's work: what exactly it changed in a file.

The component

terrain/heightmap.ts +3 −2

41const size = 256;

42let seed = 0;

42let seed = Date.now();

— 18 lines skipped —

Markup

<div class="inst-diff">
  <div class="inst-diff-head">
    <span class="inst-diff-path">terrain/heightmap.ts</span>
    <span class="inst-diff-stat"><span data-kind="add">+3</span> <span data-kind="del">−2</span></span>
  </div>
  <div class="inst-diff-body">
    <div class="inst-diff-line"><span class="inst-diff-num">41</span><span class="inst-diff-code">const size = 256;</span></div>
    <div class="inst-diff-line" data-kind="del"><span class="inst-diff-num">42</span><span class="inst-diff-code">let seed = 0;</span></div>
    <div class="inst-diff-line" data-kind="add"><span class="inst-diff-num">42</span><span class="inst-diff-code">let seed = Date.now();</span></div>
    <div class="inst-diff-fold">— 18 lines skipped —</div>
  </div>
</div>

Contract

What	Required	Why
A `data-kind` on a line	yes	The carrier of the category. A line without one is context, and that is the right default
An `inst-diff-num` as a separate node	yes	The number is not selected by the mouse: otherwise a copied diff arrives mixed up with line numbers
An `inst-diff-code` around the code	yes	Only it holds the monospaced setting and does not wrap the line
An `inst-diff-fold` in the place of a gap	no, but usually yes	A folded stretch is data about not everything being shown

Accessibility


Not colour alone	A `+`/`−` sign in the first column. That is the main requirement of the component
Line numbers	`user-select: none` — when a fragment is copied the numbers do not reach the clipboard along with the code
Copying	The sign is a pseudo-element, so what is copied is clean code rather than `+const size`
The path to the file	Truncated from the end with an ellipsis. The full path has to stay in a `title` — otherwise the diff has no name
Scrolling	The body scrolls horizontally and has to be reachable from the keyboard
Print	The tinted backgrounds are replaced with printable ones in `@media print`, and the sign stays: on paper the tone disappears altogether

Anatomy

A line of addition carries a +, a line of deletion a −. That is the library's law being carried out: colour has no right to be the only carrier of a state. A diff where the changes are told apart by green and red backgrounds alone turns into a continuous text for somebody colour-blind — and in black-and-white print.

The sign is drawn by a pseudo-element from data-kind, so it does not reach a selection and is not copied along with the code.

Variants

<div class="inst-diff-line" data-kind="add">…</div>

Value	What it means
no attribute	A line of context, unchanged
`add`	Added
`del`	Deleted

An added line is not in the "ok" state — it belongs to the kind "addition". So it has an attribute of its own rather than a data-tone: a tone would lie about the meaning. The numbers in the header of a diff carry the same data-kind — one axis, one record.

Behavior

<div class="inst-diff-fold">— 18 lines skipped —</div>

As with the folded output of a step, a stretch names its number in words. Skipping lines in silence is the same lie about the volume.

Patterns

A diff with a header, statistics and a folded stretch.

What to check by hand: select several lines and copy them. What reaches the clipboard is clean code — with no line numbers and no + and − signs. The numbers carry user-select: none and the sign is drawn by a pseudo-element. A diff whose code cannot be copied is useless at the moment it is wanted.

In context

src/world/biomes.ts +3 −2

118 lines folded

119119 const seed = opts.seed ?? 0;

120 const noise = simplex2(seed);

121 if (noise > 0.5) return TUNDRA;

120 const noise = simplex2(seed, { octaves: 3 });

121 // tundra and steppe overlapped in 12 cells — parting them by height

122 if (noise > 0.5 && height > 0.72) return TUNDRA;

122123 return STEPPE;