graphics: stack equal-z Kitty images in kitty's order, live and across reattach #168

Merged

natsukium merged 2 commits from graphics/equal-z-order into main 2026-10-18 17:15:58 +09:00

Conversation 0 Commits 2 Files changed 33 +715 -60

natsukium commented 2026-10-18 14:56:50 +09:00

Owner

Copy link

Closes #155.

kitty stacks equal-z images by (z, image internal id, ref internal id). felis stacked them by the order the client heard of each placement. That inverts kitty's order when a newer image is placed first, and a reattach could reorder them again.

The order can't be rebuilt from message order. The live outbox collapses a re-sent image to its last transmission. A put under the p= of a placement of the other kind keeps kitty's ref, but felis removes and re-adds it. So the daemon now ships both numbers at protocol minor 2:

• ImageNew.serial: the store's existing creation serial. A re-send keeps it; a delete gives it up.
• ImagePlacement.serial: the sequence number a placement was first inserted under. It is kept through a same-key replace, an anonymous rekey, and a virtual↔direct conversion. A dump without it backfills from the dumped sequence numbers, so DUMP_VERSION is unchanged.

The shared layout sorts by (z, image rank, direct before placeholder, placement serial). A minor-1 daemon sends neither number; the client then falls back to first-arrival image rank and shadow order.

Two choices were made on purpose:

• Placeholder vs. direct placement of the same image: placeholders stay above. In kitty this pair is ordered by render timing.
• Placeholder cells with placement id 0: which virtual placement they resolve to is unchanged. kitty's "first" is hash-map iteration order.

Both are explained in the explanation doc and the commit body.

Tests: layout ordering units, Placements serial invariants plus the proptest model, client-shadow rank, live put serials through the dispatcher, and an end-to-end check that live and rehydrated shadows draw the same kitty order. Mutating either serial path makes the end-to-end check fail. just check and just check-windows pass locally.

Reviewed with pi (sol): the design passed at round 4 and the implementation at round 1. The two non-blocking implementation notes (CHANGELOG wording, conversion-round-trip test plus fuzz seeds) are addressed in the second commit.

Closes #155. kitty stacks equal-z images by `(z, image internal id, ref internal id)`. felis stacked them by the order the client heard of each placement. That inverts kitty's order when a newer image is placed first, and a reattach could reorder them again. The order can't be rebuilt from message order. The live outbox collapses a re-sent image to its last transmission. A put under the `p=` of a placement of the other kind keeps kitty's ref, but felis removes and re-adds it. So the daemon now ships both numbers at **protocol minor 2**: - `ImageNew.serial`: the store's existing creation serial. A re-send keeps it; a delete gives it up. - `ImagePlacement.serial`: the sequence number a placement was first inserted under. It is kept through a same-key replace, an anonymous rekey, and a virtual↔direct conversion. A dump without it backfills from the dumped sequence numbers, so `DUMP_VERSION` is unchanged. The shared layout sorts by `(z, image rank, direct before placeholder, placement serial)`. A minor-1 daemon sends neither number; the client then falls back to first-arrival image rank and shadow order. Two choices were made on purpose: - **Placeholder vs. direct placement of the same image:** placeholders stay above. In kitty this pair is ordered by render timing. - **Placeholder cells with placement id 0:** which virtual placement they resolve to is unchanged. kitty's "first" is hash-map iteration order. Both are explained in the explanation doc and the commit body. Tests: layout ordering units, `Placements` serial invariants plus the proptest model, client-shadow rank, live put serials through the dispatcher, and an end-to-end check that live and rehydrated shadows draw the same kitty order. Mutating either serial path makes the end-to-end check fail. `just check` and `just check-windows` pass locally. Reviewed with pi (sol): the design passed at round 4 and the implementation at round 1. The two non-blocking implementation notes (CHANGELOG wording, conversion-round-trip test plus fuzz seeds) are addressed in the second commit.

natsukium added 2 commits 2026-10-18 14:56:50 +09:00

protocol, grid, daemon, client-core, docs: stack equal-z images in kitty's order ... ad9a666768

kitty draws overlapping equal-z images by the internal ids it gives an
image and a ref at creation, so the older image sits under the newer
one. felis stacked them by the order the client heard of each placement,
which inverts that whenever a newer image is placed first, and a
reattach could reorder them again.

The order cannot be rebuilt from message order. The live outbox
collapses an image sent twice in one drain to its last transmission, so
a re-sent older image's header arrives after a newer one; and a put
under the p= of a placement of the other kind keeps kitty's ref while
felis removes and re-adds it, which a rehydrate replaying every direct
placement before every virtual one cannot restore. So the daemon ships
both numbers at protocol minor 2: ImageNew.serial is the store's
existing creation serial, which a re-send keeps and a delete forfeits,
and ImagePlacement.serial is the sequence number a placement was first
inserted under, kept through a same-key replace, an anonymous rekey,
and a virtual/direct conversion. Virtual placements keep their own
serial daemon-side so a later conversion inherits it; the client never
sorts them. A dump without placement serials backfills them from the
sequence numbers every released dump carries, so DUMP_VERSION stays.

Guaranteeing an arrival order instead was rejected: it would move a
collapsed transmission back to its first position, where frame and
show-frame markers queued between the two transmissions name frames the
moved one does not carry, and it makes message order an untyped
contract.

The layout sorts by (z, image rank, direct before placeholder,
placement serial). kitty orders a placeholder against a direct
placement of the same image by when the row last rendered, which no
mirror can know; placeholders stay above, as before. A minor-1 daemon
sends neither number, and the client then falls back to first-arrival
image rank and shadow order.

Which virtual placement a cell naming no placement resolves to is left
alone: kitty's "first" is the iteration order of a hash map, not
creation order.

Closes #155

Assisted-by: Claude Code

daemon, fuzz: pin the serial a placement keeps through a round trip to virtual ... 7ec7bd0782

The equal-z change kept a placement's serial when a put turns it to the
other kind, but only the virtual-to-direct direction went through the
dispatcher in a test. A direct placement turned virtual and back must
keep its first serial too, as kitty keeps the ref the whole time. The
two seeds give the body fuzzer an ImageNew and an ImagePlacement that
carry the new fields.

The changelog entry now says images stack by creation rather than
transmission order, since a re-sent image keeps its place.

Assisted-by: Claude Code

natsukium added 1 commit 2026-10-18 15:10:54 +09:00

Merge remote-tracking branch 'origin/main' into graphics/equal-z-order ... d56b1f1039

# Conflicts:
#	CHANGELOG.md
#	docs/reference/ipc.md

natsukium force-pushed graphics/equal-z-order from d56b1f1039 to fcacefd6d1 2026-10-18 15:17:29 +09:00 Compare

natsukium scheduled this pull request to auto merge when all checks succeed 2026-10-18 15:20:27 +09:00

natsukium merged commit b7d6c468f9 into main 2026-10-18 17:15:58 +09:00

natsukium deleted branch graphics/equal-z-order 2026-10-18 17:15:58 +09:00

natsukium referenced this pull request from a commit 2026-10-18 17:15:58 +09:00

Merge pull request 'graphics: stack equal-z Kitty images in kitty's order, live and across reattach' (#168) from graphics/equal-z-order into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

Area/ci

CI workflows (.forgejo/workflows/)

  

Area/cli

felis-cli crate, the felis front-door binary

  

Area/client

felis-client crate, the winit GUI frontend

  

Area/client-core

felis-client-core crate, shadow screen, config, connect_or_spawn_daemon

  

Area/daemon

felis-daemon crate, session pool, IPC server

  

Area/deps

Dependency bumps

  

Area/docs

Documentation tree when no narrower area fits

  

Area/grid

felis-grid crate, cells, scrollback, image store

  

Area/manual

User-facing docs: tutorials, how-to, user-facing reference pages

  

Area/nix

Nix flake, home-manager module, package definitions

  

Area/protocol

felis-protocol crate, felis.proto, frame layout, version constants

  

Area/pty

felis-pty crate, PTY backends

  

Area/render

felis-render-wgpu crate, GPU pipeline, atlas

  

Area/shaping

felis-shaping crate, swash shaper, font fallback

  

Area/skills

Agent skills (skills/felis, .agents/skills/)

  

Area/transport

felis-transport crate, framing, socket/pipe, SSH carrier

  

Area/vt

felis-vt crate, VT parser, dispatch

  

Compat/Breaking

Breaking change that won't be backward compatible

  

Kind/Bug

Something is not working

  

Kind/Documentation

Documentation changes

  

Kind/Enhancement

Improve existing functionality

  

Kind/Feature

New functionality

  

Kind/Performance

Throughput, latency, or memory cost

  

Kind/Security

This is security issue

  

Kind/Testing

Issue or pull request related to testing

  

perf-regression-accepted

Passes the instruction-count bench gate for an intended cost; state why in a PR comment

  

Reviewed

Confirmed

Issue has been confirmed

  

Reviewed

Duplicate

This issue or pull request already exists

  

Reviewed

Invalid

Invalid issue

  

Reviewed

Won't Fix

This issue won't be fixed

  

Status

Blocked

Something is blocking this issue or pull request

  

Status

Need More Info

Feedback is required to reproduce issue or to continue work

  

Status

Upstream

Waiting on a change in an upstream project

No labels

Area/ci

Area/cli

Area/client

Area/client-core

Area/daemon

Area/deps

Area/docs

Area/grid

Area/manual

Area/nix

Area/protocol

Area/pty

Area/render

Area/shaping

Area/skills

Area/transport

Area/vt

Compat/Breaking

Kind/Bug

Kind/Documentation

Kind/Enhancement

Kind/Feature

Kind/Performance

Kind/Security

Kind/Testing

perf-regression-accepted

Reviewed

Confirmed

Reviewed

Duplicate

Reviewed

Invalid

Reviewed

Won't Fix

Status

Blocked

Status

Need More Info

Status

Upstream

Milestone

Clear milestone

No items

No milestone

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

felis-terminal/felis!168

No description provided.