Placeholder tiles are content: printing over the cell removes the tile

[tomlm]

A Unicode-placeholder tile exists because its cell holds the placeholder character; the protocol has no command to remove one tile, because overwriting the cell IS the removal. Tiles were stored as classic Kitty overlay runs, which text never modifies, so anything drawn across a placeholder picture (a dialog, a new screen) kept the picture on top of it permanently.

• New PlacementKind.Placeholder with content semantics: the split that printing performs on Sixel runs now takes placeholder runs too (a one-column run simply goes). Classic placements keep overlay behaviour and z-ordering untouched, pinned by a new test.
• Writing a placeholder cell also clears any stale tile another picture left at that cell, since the cell write itself now splits.
• The test asserting overlay behaviour for placeholders encoded the implementation rather than the protocol (kitty itself removes the tile; image.nvim depends on it) and now asserts the removal, with the reasoning in its remarks.

Perf: the only hot-path-adjacent change is the kind test inside SplitPlacementsAt, which flipped from != Sixel to == Kitty — same single compare, and the method only runs on lines that hold placements.

Found from the consumer side: Consolonia's kitty renderer overwrites occluded placeholder cells exactly as the spec prescribes, and the pictures stayed on top of its dialogs.

BufferLine.CopyFrom carries placements and images

Clone already copies them ("the runs are the picture"); CopyFrom silently dropped them. A host that double-buffers frames through pooled line copies (Iciclecreek.Avalonia.Terminal's FrameCapture) therefore could not represent image rows and had to read them live — which, for a screen drawn entirely as kitty Unicode placeholders, was the remaining paint-mid-write tear (a black band sweeping the picture). Replace semantics, like every other field there: a recycled line that once held a picture must not keep showing it. The lists are copied and the images shared — a stored picture is never mutated in place (a retransmission builds a new one), so holders of a copy are safe against later writes.

Consumed by tomlm/Iciclecreek.Avalonia.Terminal#166, which captures image rows only when this fix is present and falls back to live reads against older emulators.

Suite: 2216 passed / 0 failed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CxS1BnzZ6BhuGovMLNtRQH
https://claude.ai/code/session_01XmKfhMXUAy4n3uLDSUBHo8

[github-actions]

Perf comparison — this change, against its base

3 run(s) of each side, alternating on one machine. Allocation is a count and is gated exactly. Time is a measurement, so its gate is derived from the spread this job just observed in itself rather than fixed in advance.

corpus	bytes/char	gen0/Mchar	ns/char	Δ time	noise	gate
scroll-ascii	0.00 → 0.00	0.00 → 0.00	3.49 → 3.48	-0.3%	±1%	4%
sgr-churn	0.00 → 0.00	0.00 → 0.00	9.33 → 9.31	-0.3%	±0%	4%
truecolor	0.00 → 0.00	0.00 → 0.00	9.87 → 9.88	+0.0%	±1%	4%
alt-redraw	0.00 → 0.00	0.00 → 0.00	14.74 → 14.74	+0.0%	±2%	7%
unicode	7.66 → 7.66	0.45 → 0.45	36.52 → 35.32	-3.3%	±1%	4%
flood	0.00 → 0.00	0.00 → 0.00	105.12 → 104.78	-0.3%	±0%	4%

Each corpus is gated at max(4%, 3 × its own noise). A wide noise column means this runner was busy and the timing half of the table should be read as advisory; the allocation half is exact either way.

assemblies measured

• base: XTerm.NET 2.0.2.0 mvid:c3048032-d19f-486a-a7b4-d178e47b981e
• head: XTerm.NET 2.0.2.0 mvid:5d73322b-acc3-4edd-b593-0b33f51dc3ca

---

Perf comparison — cumulative, everything since 2.0.0

3 run(s) of each side, alternating on one machine. Allocation is a count and is gated exactly. Time is a measurement, so its gate is derived from the spread this job just observed in itself rather than fixed in advance.

corpus	bytes/char	gen0/Mchar	ns/char	Δ time	noise	gate
scroll-ascii	0.00 → 0.00	0.00 → 0.00	3.48 → 3.48	+0.1%	±1%	5%
sgr-churn	0.00 → 0.00	0.00 → 0.00	9.26 → 9.31	+0.5%	±1%	5%
truecolor	0.00 → 0.00	0.00 → 0.00	9.86 → 9.88	+0.2%	±1%	5%
alt-redraw	0.00 → 0.00	0.00 → 0.00	14.93 → 14.74	-1.3%	±4%	12%
unicode	7.66 → 7.66	0.45 → 0.45	35.53 → 35.32	-0.6%	±2%	7%
flood	0.00 → 0.00	0.00 → 0.00	105.09 → 104.78	-0.3%	±0%	5%

Each corpus is gated at max(5%, 3 × its own noise). A wide noise column means this runner was busy and the timing half of the table should be read as advisory; the allocation half is exact either way.

assemblies measured

• base: XTerm.NET 2.0.0.0 mvid:a26a50e5-3343-4b31-bada-ce2a03923fe4
• head: XTerm.NET 2.0.2.0 mvid:5d73322b-acc3-4edd-b593-0b33f51dc3ca

[Copilot]

🟡 Changes recommended

There are a couple of newly introduced comments that contradict the actual implementation (and a missing regression test for the new CopyFrom image/placement behavior), which should be corrected before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR aligns Kitty Unicode placeholder tiles with “content” semantics so that overwriting a placeholder cell removes the corresponding tile (matching kitty/image.nvim behavior), while preserving classic Kitty placement overlay/z-index behavior. It also fixes BufferLine.CopyFrom to carry image placement state so line copies don’t silently drop images.

Changes:

• Introduce PlacementKind.Placeholder and treat placeholder-tile placements as content (split/removed on text writes), while leaving classic Kitty placements as overlays.
• Update placeholder writing to emit PlacementKind.Placeholder so buffer write paths can clear/replace tiles correctly.
• Fix BufferLine.CopyFrom to copy placements/images and add/adjust tests covering the intended semantics.

File summaries

File	Description
src/XTerm.NET/InputHandler.KittyGraphics.cs	Marks placeholder-tile placements as Placeholder so overwrites clear tiles.
src/XTerm.NET/Graphics/LinePlacement.cs	Adds PlacementKind.Placeholder with documentation for content semantics.
src/XTerm.NET/Buffer/BufferLine.cs	Updates placement-splitting logic for placeholder tiles; fixes CopyFrom to copy placement/image lists.
src/XTerm.NET.Tests/Graphics/KittyZIndexTests.cs	Adds regression test ensuring classic Kitty placements remain overlays under text.
src/XTerm.NET.Tests/Graphics/KittyPlaceholderTests.cs	Updates placeholder behavior test to assert tile removal on overwrite; adds replacement test.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.