docs: state what the attach, placement, and icon-name code actually does #353

Merged

natsukium merged 3 commits from docs/issue-349-reference-vs-code into main 2026-09-22 21:48:25 +09:00

Conversation 0 Commits 3 Files changed 3 +20 -16

natsukium commented 2026-09-22 21:15:36 +09:00

Owner

Copy link

Reference-only corrections. Each of the three claims in #349 is resolved the way the triage comment recommends: the reference states what the code does, and no behavior changes.

1. SessionAttach.id_prefix (docs/reference/ipc.md)

The Attach bullet said a prefix that "is not 1-32 hex digits" is refused at decode and that an attach, unlike the Ops verbs, "cannot answer a malformed prefix with NoMatch". Neither holds: attach_target_from_wire (crates/felis-protocol/src/convert/session.rs) builds AttachTarget::Prefix from the wire string unvalidated, and take_attach_handle (crates/felis-daemon/src/serve.rs) resolves it with felis_protocol::session_prefix::resolve_session_prefix, which returns ResolvedId::NoMatch for an empty, overlong, or non-hex prefix. The bullet now says the daemon answers AttachFailure::NoMatch, on the same resolver every Ops prefix field uses.

The unset-target half of the sentence is kept: attach_target_from_wire does answer a missing target with WireError::MissingOneof, pinned by an_attach_naming_no_target_at_all_is_rejected.

No explanation page repeated the old rationale (grep for "hex digits" and "NoMatch" under docs/ finds only unrelated pages).

2. Kitty placement X, Y (docs/reference/protocols/kitty-graphics.md, support-matrix.md)

upsert_placement (crates/felis-daemon/src/graphics.rs) reads c, r, z, C, q, p, and the lowercase source rectangle, and felis_grid::images::Placement has no destination-offset field; uppercase X/Y are read only by a=c frame composition, as the source offset. The "Pixel offset within destination cell" line is gone, replaced by a sentence stating that the offsets parse and are ignored (the image lands at the cell origin) and pointing at the a=c use of the same pair.

The a=p row stays ✅ — the action works — and the Display / lifecycle table gains an X= / Y= row marked ⚠️, which is the legend's marker for consumed without effect.

3. OSC 1 icon name (docs/reference/protocols/support-matrix.md)

crates/felis-grid/src/sink.rs records the icon name and CSI 20 t reports it back on the session's own PTY, but felis.proto has no icon field (only title, which GridTitle and SessionInfo carry) and no client crate consumes one, so nothing is ever displayed. The row moves from ✅ to ⚠️ and names the two halves: recorded and answered by CSI 20 t, not carried to a client.

Verified

• just fmt-check — clean
• just lint — clean
• just prose-check — 0 hits
• just docs-links — 0 errors
• pre-commit (lychee, prose check, treefmt, check-merge-conflicts) — passed on commit

No Rust, proto, config, or CLI surface changed, so just proto / just schema / just golden / just test do not apply.

Closes #349

Reference-only corrections. Each of the three claims in #349 is resolved the way the triage comment recommends: the reference states what the code does, and no behavior changes. ## 1. `SessionAttach.id_prefix` (`docs/reference/ipc.md`) The `Attach` bullet said a prefix that "is not 1-32 hex digits" is refused at decode and that an attach, unlike the `Ops` verbs, "cannot answer a malformed prefix with `NoMatch`". Neither holds: `attach_target_from_wire` (`crates/felis-protocol/src/convert/session.rs`) builds `AttachTarget::Prefix` from the wire string unvalidated, and `take_attach_handle` (`crates/felis-daemon/src/serve.rs`) resolves it with `felis_protocol::session_prefix::resolve_session_prefix`, which returns `ResolvedId::NoMatch` for an empty, overlong, or non-hex prefix. The bullet now says the daemon answers `AttachFailure::NoMatch`, on the same resolver every `Ops` prefix field uses. The unset-target half of the sentence is kept: `attach_target_from_wire` does answer a missing `target` with `WireError::MissingOneof`, pinned by `an_attach_naming_no_target_at_all_is_rejected`. No explanation page repeated the old rationale (grep for "hex digits" and "NoMatch" under `docs/` finds only unrelated pages). ## 2. Kitty placement `X`, `Y` (`docs/reference/protocols/kitty-graphics.md`, `support-matrix.md`) `upsert_placement` (`crates/felis-daemon/src/graphics.rs`) reads `c`, `r`, `z`, `C`, `q`, `p`, and the lowercase source rectangle, and `felis_grid::images::Placement` has no destination-offset field; uppercase `X`/`Y` are read only by `a=c` frame composition, as the source offset. The "Pixel offset within destination cell" line is gone, replaced by a sentence stating that the offsets parse and are ignored (the image lands at the cell origin) and pointing at the `a=c` use of the same pair. The `a=p` row stays ✅ — the action works — and the Display / lifecycle table gains an `X=` / `Y=` row marked ⚠️, which is the legend's marker for consumed without effect. ## 3. OSC 1 icon name (`docs/reference/protocols/support-matrix.md`) `crates/felis-grid/src/sink.rs` records the icon name and `CSI 20 t` reports it back on the session's own PTY, but `felis.proto` has no icon field (only `title`, which `GridTitle` and `SessionInfo` carry) and no client crate consumes one, so nothing is ever displayed. The row moves from ✅ to ⚠️ and names the two halves: recorded and answered by `CSI 20 t`, not carried to a client. ## Verified - `just fmt-check` — clean - `just lint` — clean - `just prose-check` — 0 hits - `just docs-links` — 0 errors - pre-commit (lychee, prose check, treefmt, check-merge-conflicts) — passed on commit No Rust, proto, config, or CLI surface changed, so `just proto` / `just schema` / `just golden` / `just test` do not apply. Closes #349

natsukium added 1 commit 2026-09-22 21:15:36 +09:00

docs: state what the attach, placement, and icon-name code actually does ... a2d38c7798

Three reference claims outran the implementation. Before the surfaces
freeze, the reference has to be the thing a non-Rust implementer can
build against, so each claim now names the behavior that ships.

An attach's `id_prefix` is not validated at decode: `convert/session.rs`
passes it through and the daemon resolves it with the same
`resolve_session_prefix` every `Ops` verb uses, which answers a
malformed prefix `NoMatch`. The old text argued the opposite as a
deliberate fail-closed design, but a prefix no lowercase-hex id can
start with is already unmatchable, and one resolver for every prefix
field is the property worth keeping.

`upsert_placement` never reads the destination pixel offsets and
`felis_grid::images::Placement` has nowhere to put them, so a producer
that sends `a=p` with `X=`/`Y=` gets the image at the cell origin.
Applying them needs a wire field and renderer work, which is an
additive change after the freeze, not a pre-freeze one.

OSC 1 records an icon name that feeds the `CSI 20 t` reply and stops
there: no `GridMsg` arm carries it, so no client shows it. The check
mark claimed a user-visible effect the wire cannot produce.

Closes #349

Assisted-by: Claude Code

natsukium added 1 commit 2026-09-22 21:21:32 +09:00

docs: state that the attach prefix is normalized before it is judged ... 6ebfa59618

The resolver strips an optional 0x and lowercases before validating, so
an uppercase or 0x-prefixed prefix resolves; the previous wording implied
raw hex digits were required.

natsukium added 1 commit 2026-09-22 21:25:04 +09:00

docs: rewrap the attach prefix bullet to the formatter's width ... be6b0ab700

Assisted-by: Claude Code

natsukium merged commit 8b19df58be into main 2026-09-22 21:48:25 +09:00

natsukium deleted branch docs/issue-349-reference-vs-code 2026-09-22 21:48:25 +09:00

natsukium referenced this pull request from a commit 2026-09-22 21:48:25 +09:00

docs: state what the attach, placement, and icon-name code actually does (#353)

Commenting is not possible because the repository is archived.

Reviewers

No reviewers

Labels

Clear labels   

priority/P0

Must be resolved before the v0.1.0 tag

  

priority/P1

Must be settled before the first public contract freezes

  

priority/P2

Explicitly deferred until after v0.1.0

  

release/v0.1.0

Work tracked for the first tagged release

  

status/blocked

Cannot start now: waits on an upstream release, another issue, or a recorded revisit trigger

  

status/planned

Triaged with a source-grounded plan and a passed pi review; ready to implement

  

type/bug

Shipped behavior that contradicts the docs or the code's own intent; needs a product code change

  

type/design

An open scope or trade-off question; needs a recorded decision in the owning explanation doc before code

  

type/test-gap

Documented or reviewed behavior that no test pins; usually split from a review finding, needs no product code change

  

type/tracker

Parent issue that tracks child work

No labels

priority/P0

priority/P1

priority/P2

release/v0.1.0

status/blocked

status/planned

type/bug

type/design

type/test-gap

type/tracker

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

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

natsukium/felis!353

No description provided.