shaping: round the cell width to the nearest pixel #411

Merged

natsukium merged 1 commit from shaping/round-cell-width into main 2026-09-25 03:01:08 +09:00

Conversation 0 Commits 1 Files changed 3 +68 -12

natsukium commented 2026-09-25 02:43:41 +09:00

Owner

Copy link

What

CellMetrics::from_scaled rounds the cell width to the nearest pixel instead of ceiling it (the .max(1.0) floor stays, so a sub-half-pixel advance still yields a 1 px cell). Height keeps its separate ceil of ascent and descent. docs/explanation/rendering/text-shaping.md "Atlas integration" is rewritten with what kitty actually does, why rounding is safe, the rejected alternatives, why height keeps its rule, and a "Revisit if" trigger. CHANGELOG gains a "Changed" entry, since a window of a given size now holds more columns at the same font.size_px.

Why

The ceil was justified by "kitty ceils the same advance". That holds only on macOS, where kitty ceils CoreText's unhinted advance. On Linux kitty ceils a FreeType advance that hinting has already rounded to a whole pixel, so its effective rule there is round. felis therefore drew 12 px cells where kitty, alacritty and foot draw 11 (issue diagnosis comment has the source walk).

Measured

	advance	felis before	felis after	peers
Linux, DejaVu Sans Mono 14 pt (18.67 px)	11.2383 px (swash; FreeType hinted 11.0)	12	11	kitty, alacritty, foot 11
macOS, Menlo 14 pt (72 dpi)	8.4287 px (CoreText, measured on an M4 Max)	9	8	ghostty, alacritty 8; kitty 9

Menlo on the Mac via CoreText: advance 8.4287, ascent 12.9951, descent 3.3018, leading 0, matching the DejaVu-derived numbers in the diagnosis.

Spill with the new width, measured on felis's own Linux (hinted) raster at 18.67 px in an 11 px cell: ASCII ink reaches at most one column into the neighbor (_ 44% coverage, # 41%, W 36%); nothing reaches further or left of the cell. Backgrounds paint before any glyph and glyph quads are not clipped to the cell, so the spill is drawn over the neighbor.

Height is unchanged (23 px on Linux, matching every peer; 17 px for Menlo on macOS where peers get 16): rounding the descent would reach 16 on macOS but drop Linux to 22.

just check: fmt, clippy, portable, prose, skills, docs-links, deny, proto-compat and release-check pass; nextest 3542/3543 on the full run, the one failure (os_clipboard::tests::write_primary_program_lands_when_program_writes_allowed, a live PRIMARY selection test) and two earlier load flakes in felis-cli / felis-daemon pass in isolation and do not touch shaping.

Closes #404

## What `CellMetrics::from_scaled` rounds the cell width to the nearest pixel instead of ceiling it (the `.max(1.0)` floor stays, so a sub-half-pixel advance still yields a 1 px cell). Height keeps its separate ceil of ascent and descent. `docs/explanation/rendering/text-shaping.md` "Atlas integration" is rewritten with what kitty actually does, why rounding is safe, the rejected alternatives, why height keeps its rule, and a "Revisit if" trigger. CHANGELOG gains a "Changed" entry, since a window of a given size now holds more columns at the same `font.size_px`. ## Why The ceil was justified by "kitty ceils the same advance". That holds only on macOS, where kitty ceils CoreText's unhinted advance. On Linux kitty ceils a FreeType advance that hinting has already rounded to a whole pixel, so its effective rule there is round. felis therefore drew 12 px cells where kitty, alacritty and foot draw 11 (issue diagnosis comment has the source walk). ## Measured | | advance | felis before | felis after | peers | |---|---|---|---|---| | Linux, DejaVu Sans Mono 14 pt (18.67 px) | 11.2383 px (swash; FreeType hinted 11.0) | 12 | 11 | kitty, alacritty, foot 11 | | macOS, Menlo 14 pt (72 dpi) | 8.4287 px (CoreText, measured on an M4 Max) | 9 | 8 | ghostty, alacritty 8; kitty 9 | Menlo on the Mac via CoreText: advance 8.4287, ascent 12.9951, descent 3.3018, leading 0, matching the DejaVu-derived numbers in the diagnosis. Spill with the new width, measured on felis's own Linux (hinted) raster at 18.67 px in an 11 px cell: ASCII ink reaches at most one column into the neighbor (`_` 44% coverage, `#` 41%, `W` 36%); nothing reaches further or left of the cell. Backgrounds paint before any glyph and glyph quads are not clipped to the cell, so the spill is drawn over the neighbor. Height is unchanged (23 px on Linux, matching every peer; 17 px for Menlo on macOS where peers get 16): rounding the descent would reach 16 on macOS but drop Linux to 22. `just check`: fmt, clippy, portable, prose, skills, docs-links, deny, proto-compat and release-check pass; nextest 3542/3543 on the full run, the one failure (`os_clipboard::tests::write_primary_program_lands_when_program_writes_allowed`, a live PRIMARY selection test) and two earlier load flakes in `felis-cli` / `felis-daemon` pass in isolation and do not touch shaping. Closes #404

natsukium added 1 commit 2026-09-25 02:43:41 +09:00

shaping: round the cell width to the nearest pixel ... 73c81c2627

Ceiling the `M` advance was justified as matching kitty, but that holds
only on macOS. On Linux kitty ceils an advance FreeType has already
hinted to a whole pixel, so DejaVu Sans Mono at 14 pt gets 11 px cells
in kitty, alacritty and foot while felis got 12, painting 9% more
pixels per row and fitting fewer columns in the same window. Rounding
gives 11 there and 8 for Menlo at 14 pt on macOS (CoreText advance
8.4287 px, measured on the Mac), matching ghostty and alacritty; only
kitty's macOS path, which ceils CoreText's unhinted advance, stays at 9.

Glyph quads are never clipped to the cell and every background paints
before any glyph, so the ink a rounded-down advance pushes into the
neighbor (under half a pixel unhinted; one column of up to 44% coverage
for DejaVu's hinted `_`, `#` and `W` on Linux) is drawn, not lost. The height
keeps its separate ceil of ascent and descent: rounding the descent
would give macOS peers' 16 px for Menlo but drop DejaVu on Linux to
22 px, one row short of every Linux peer.

Assisted-by: Claude Code

natsukium force-pushed shaping/round-cell-width from 73c81c2627 to 1b7c652df0 2026-09-25 02:44:41 +09:00 Compare

natsukium merged commit b5204672d4 into main 2026-09-25 03:01:08 +09:00

natsukium deleted branch shaping/round-cell-width 2026-09-25 03:01:08 +09:00

natsukium referenced this pull request from a commit 2026-09-25 03:01:09 +09:00

shaping: round the cell width to the nearest pixel (#411)

natsukium referenced this pull request 2026-09-25 04:11:40 +09:00

bench: follow up the 9d1d842f cross-terminal run #405

natsukium referenced this pull request from a commit 2026-09-26 01:13:27 +09:00

docs: republish the macOS benchmarks from a pre-release run at 5c8b9769

natsukium referenced this pull request 2026-09-26 01:13:35 +09:00

docs: republish the macOS benchmarks from a pre-release run at 5c8b9769 #467

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!411

No description provided.