# fix\(web\): the terminal cursor no longer leaves faint lines when it blinks off · PR \#21641 · pingdotgg/t3code [View on GitCafe](https://git.cafe/pingdotgg/t3code/pull/21641) Repository: [pingdotgg/t3code](https://git.cafe/pingdotgg/t3code) Visibility: public State: open Source repository: Unavailable fork Source branch: fix/11402-terminal-cursor-fringe Target branch: main Head commit: d1cc00b55b7cc906be9b39ae2d63a6ce01a4c914 [Discussion and reviews](https://git.cafe/pingdotgg/t3code/pull/21641) [Commits](https://git.cafe/pingdotgg/t3code/pull/21641/commits?format=markdown) [Files changed](https://git.cafe/pingdotgg/t3code/pull/21641/diffs?format=markdown) ## Description --- ## Problem At a fractional device pixel ratio the integrated terminal's cursor leaves two faint lines at the top and bottom of its cell when it blinks off (https://git.cafe/pingdotgg/t3code/issues/11402). On a Mac that happens after View > Zoom In in the desktop app (one step gives a ratio of about 2.19) or with browser zoom on web; elsewhere at a 125% or 150% display scale. Row edges then fall partway through device pixels, so the row's background repaint only partly covers the cursor's edge pixels and blends over them instead of replacing them. ## Change `renderGhosttySnapshot` in `apps/web/src/terminal/ghostty/renderer.ts` puts each row's top and bottom on whole device pixels, using the canvas transform's scale, and draws the row's background, selection, text clip, solid Powerline separators (https://git.cafe/pingdotgg/t3code/pulls/5607) and the cursor with that snapped height. Neighbouring rows share an exact edge, so repainting a row replaces every pixel it drew. At a whole-number ratio, such as the default 2 on a Retina display, nothing moves. The mocked context in `surface.test.ts` gets a `getTransform` stub. ## Scope and approval https://git.cafe/pingdotgg/t3code/issues/11402 is a triaged bug; the [triage](https://github.com/pingdotgg/t3code/issues/11402#issuecomment-5644760015) suggests "snap row/cursor Y to the device pixel grid" with an offscreen-canvas pixel test. When closing https://git.cafe/pingdotgg/t3code/pulls/11620, @juliusmarminge [invited a smaller version](https://github.com/pingdotgg/t3code/pull/11620#issuecomment-5739392661): "If you want to send that smaller version with an offscreen-canvas pixel test at a fractional origin, that would be welcome." This rebuilds @Lucenx9's https://git.cafe/pingdotgg/t3code/pulls/11424 (the same snapping) on current `main`, as its [closing comment](https://github.com/pingdotgg/t3code/pull/11424#issuecomment-6104981205) suggested, with a real-canvas test in place of the mocked one. One correction to the triage: on `main` the row origin is always a whole CSS pixel (`clientHeight` and the cell height are integers), so the fractional edges come from the device pixel ratio. Snapping only the origin in `surface.ts` would leave every later row between device pixels, which is why the snap is per row and why the test uses a fractional canvas transform. Web and desktop share this renderer; the triage notes mobile's native terminal does not use it. ## Verification - New `renderer.browser.test.ts` draws on a real Chromium canvas at 1.25x and 2.2x for the bar, block, underline and hollow cursors: cursor on, then off, then a count of the pixels that are not the background. On `main` all 8 fail, leaving 6 to 36 pixels (2.2x block: 36, an 18-pixel line at the top and the bottom of the cell); with the change all 8 pass with 0. A second case draws a separator, then repaints only its row without it: with https://git.cafe/pingdotgg/t3code/pulls/5607's unsnapped height it leaves 1 pixel below the row at both ratios, with the change 0. `surface.test.ts`: 28 passed. `vp lint`, `vp fmt --check` and the web typecheck are clean. - Real app: the dev desktop app from this branch on a fresh `.t3` with a throwaway project, light theme, terminal focused at an idle prompt. I set the ratio to 2.2 over CDP (`Emulation.setDeviceMetricsOverride`), close to the 2.19 one Zoom In step gives, since the menu's Zoom In can't be driven from the automation. The terminal canvas region was exported every 100 ms for 3 s (exact canvas pixels, not a screen capture): | | blink-off frames | pixels left in the cursor cell, every off frame | | --- | --- | --- | | `main` | 15 | 36 (device rows 8 and 48, 18 each) | | this branch | 15 | 0 | At the default ratio of 2 this branch also leaves 0 in all 14 off frames. Cursor off at 2.2x, before (6x, nearest neighbour): ![Before: two faint lines stay where the cursor was](https://github.com/tiliakoos/t3code/releases/download/pr-11402-evidence/before-cursor-off.png) After: ![After: the cell is clear](https://github.com/tiliakoos/t3code/releases/download/pr-11402-evidence/after-cursor-off.png) Blinking, before on the left and after on the right (4x): ![Blinking, before left and after right](https://github.com/tiliakoos/t3code/releases/download/pr-11402-evidence/blink-before-after.gif) - Not checked: Windows or Linux at a fractional display scale (same renderer and arithmetic), and the Zoom In menu item itself. Not changed: horizontal edges, which only matter for a cursor or separator at either end of a row, where it meets the row repaint's own edge; the issue reports the top and bottom lines. Claude Opus 5.5 via T3 Code Fixes #11402 GitCafe: https://git.cafe/pingdotgg/t3code/issues/11402 ## Evidence Maintainer captures of the real web app's integrated terminal. **Before** is `main` at [`8d3b061121`](https://github.com/pingdotgg/t3code/commit/8d3b061121fe65669d5d43d011b48cd3027a4108). **After** is this branch's head [`2a5ca7fae5`](https://github.com/pingdotgg/t3code/commit/2a5ca7fae59e7ad59caaceb32822f72d7d16a608) with that `main` merged in locally (`a1c2f1e5f3`). The branch is on a fork, so that merge was not pushed: **the branch still needs a merge of `main`** (205 commits behind). Between before and after, only the three files in this PR differ. Environment for every capture: chromium-headless-shell 148.0.7778.96 (Playwright 1.60.0), CSS viewport 1280×800, zoom 100%. The device pixel ratio is set with CDP `Emulation.setDeviceMetricsOverride` `deviceScaleFactor`, not browser zoom, so the layout is identical at every ratio. The terminal uses the default font family at 11 px (15 px rows, so row edges fall on fractional device pixels) and runs `bash --norc --noprofile`. Each dev server ran on its own isolated state. The number in each row is how many pixels that differ from the background remain in the cursor cell (±1 device px) on a blink-off frame, read from the canvas right after an on→off transition. Each sheet shows the zoomed before and after cursor cell, a zero-threshold cell diff, and the whole panel before and after with a zero-threshold panel diff. | row | DPR | theme | cursor | before | after | sheet | | --- | --- | --- | --- | --- | --- | --- | | S1 | 1 | dark | block, off | 0 | 0 (whole panel identical) | [S1](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/908b8bd3306d07e4/S1-sheet.png) | | S2 | 1.25 | dark | block, off | 11 | 0 | [S2](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/5d0a011d58c40dd7/S2-sheet.png) | | S3 | 1.5 | dark | block, off | 11 | 0 | [S3](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/e560335cf9d3f399/S3-sheet.png) | | S4 | 2 | dark | block, off | 0 | 0 (whole panel identical) | [S4](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/f58b5cde5633399e/S4-sheet.png) | | S5 | 2.2 | dark | block, off | 34 | 0 | [S5](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/f3b7a1026bdf4d83/S5-sheet.png) | | S6 | 1.25 | light | block, off | 9 | 0 | [S6](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/dfd43a431e4e6633/S6-sheet.png) | | S7 | 2.2 | light | block, off | 32 | 0 | [S7](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/0871fb3c65aba893/S7-sheet.png) | | S8 | 1.25 | dark | bar, off | 5 | 0 | [S8](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/3187466ef54b154a/S8-sheet.png) | | S9 | 2.2 | dark | bar, off | 14 | 0 | [S9](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/ef761d120f542069/S9-sheet.png) | | S10 | 1.25 | dark | block, on | solid | solid | [S10](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/7314f3af8e9ee687/S10-sheet.png) | | S11 | 2.2 | dark | block, on | solid | solid, starts 1 device px lower | [S11](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/2c17c283b5ba8b24/S11-sheet.png) | Cursor off at 2.2, dark (S5). Before leaves lines at the top and bottom of the cell; after leaves nothing: ![S5: at DPR 2.2, before leaves two lines in the cursor cell when the cursor blinks off; after the cell is clear](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/f3b7a1026bdf4d83/S5-sheet.png) Recordings are about 6 s each, roughly 6 blink cycles at 500 ms on and 500 ms off, with before on the left and after on the right. They are canvas frames copied on every animation frame and upscaled nearest-neighbour. The two halves come from separate sessions, so their blink phases are up to 0.5 s apart. In each off phase at 1.25 and 1.5, the left half keeps a one-device-pixel line at the bottom of the cell; at 2.2 it keeps lines at the top and bottom. The right half's cell is empty. At DPR 1 and 2 both halves stay clean. - [R1 DPR 1, dark, block](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/48c6807a6177c381/R1-before-vs-after-dpr1-dark-block.mp4) - [R2 DPR 1.25, dark, block](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/382d20f416444db4/R2-before-vs-after-dpr1.25-dark-block.mp4) - [R3 DPR 1.5, dark, block](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/0ebda405f32a8d44/R3-before-vs-after-dpr1.5-dark-block.mp4) - [R4 DPR 2, dark, block](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/1c436cd13b96eafa/R4-before-vs-after-dpr2-dark-block.mp4) - [R5 DPR 2.2, dark, block](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/2d73964e43cb3d3b/R5-before-vs-after-dpr2.2-dark-block.mp4) - [R6 DPR 1.25, light, block](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/daca6835a2fecb15/R6-before-vs-after-dpr1.25-light-block.mp4) - [R7 DPR 2.2, light, block](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/9125c038a6375649/R7-before-vs-after-dpr2.2-light-block.mp4) - [R8 DPR 1.25, dark, bar](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/d35b2620b68cad70/R8-before-vs-after-dpr1.25-dark-bar.mp4) - [P1 DPR 1.25, dark, cursor on a Powerline separator](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/4bcab38c61d6ecea/P1-before-vs-after-dpr1.25-dark-powerline.mp4) What else changed: - At DPR 1 and 2, no pixel in the whole panel differs. - At fractional ratios on `main`, the dark theme shows faint full-width seams at row boundaries, 2/255 or less from the background. This branch removes them, which is why the whole-panel diffs there count 11k to 40k pixels. - No glyph pixel differs in any row. - The visible cursor block can move by up to 1 device px. At 2.2 it starts 1 px lower and is still solid. - A handful of single pixels at the panel's edge or padding corner differ by 1 to 8 levels. Driver: [capture.mjs](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/44e166036e4ee17f/capture.mjs), [compose.mjs](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/a153dbaa9da26e02/compose.mjs), [pair.mjs](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/f871720fe5bbea90/pair.mjs). Raw PNGs and JSON: [raw-captures-21641.tar.gz](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/3c7d35a60837f86d/raw-captures-21641.tar.gz). Fixture matrix: [matrix.md](https://gh-file-drop-api-prod-mi5fy3sowv63ufte.pinglabs.workers.dev/f/64233a925d058be5/matrix.md).
Verification log - **Proof audit, pass 1** (matrix derived from the diff): blink rows are recordings and cursor-off frames are stills. It found that the bug needs row edges on fractional device pixels, so the captures use an 11 px terminal font. The cursor shape comes from the terminal's escape codes; the app has no setting for it. - **Proof audit, pass 2: SUFFICIENT.** The SHAs match, and `8d3b061121..a1c2f1e5f3` touches only the three PR files. Every still's cursor-cell count was recomputed from the raw PNGs and matches. All 8 block and bar recordings show the fringe in 7 of 7 off frames on `main` at a fractional ratio and in 0 of 7 on this branch; at DPR 1 and 2, both show 0. The auditor rebuilt S5 from the driver on fresh isolated servers: after was 0, before was 34, and both whole panels came out pixel-identical to the stored captures. - **Tests** on the local merge `a1c2f1e5f3`: `surface.test.ts` passes 28/28. `renderer.browser.test.ts` (real canvas, Chromium) passes 10/10, and all 10 fail with `main`'s `renderer.ts` swapped in. - **CI** on head `2a5ca7fae5`: every check succeeded, including Build and Typecheck, Lint, Test Web and the Test Server shards. GitHub's merge-conflict check against the current base was still pending. CI has not run on a `main` merge, because none is pushed. - **Not verified:** - Underline cursor (optional in the matrix). - Bar cursor in light theme at 2.2. Its parts are covered by S9, R8 and S7. - Hollow unfocused cursor. It never blinks, so it can't show this bug. - A remnant specific to an erased Powerline separator: not reproduced on `main`; only the generic row seam shows. - Desktop app with View > Zoom In, and a real HiDPI display. The ratio was emulated in headless Chromium. - Windows and Linux fractional display scaling. - Captured and audited by Claude Opus 5.5 via Claude Code in T3 Code. - **Code review** on head `d1cc00b55b` (read-only, both reviewers run in parallel). Both agree that snapping row tops to device pixels (`renderer.ts` `rowTop`) is the right and minimal fix for the top and bottom lines. They found no regression in selection, wide characters, Powerline glyphs, theme changes or resize. The per-blink cost is one `getTransform()` per render, which is negligible. Nothing outside `apps/web` is touched. - Reviewer A, Claude Sonnet 5.5: **MERGE**. It calls the column-0 edge (below) a pre-existing follow-up, not a blocker. - Reviewer B, Claude Opus 5.5: **FIX_FIRST**. The same fringe still appears on the vertical edge when the cursor is in column 0, because the cursor and the row fill both start at `padding` = 4 CSS px, which is 8.76 device px at a 2.19 ratio. The last column's right edge has the same problem. The tests miss it because they use `cursorX: 1`, and at 1.25 the padding lands on a whole pixel. Suggested fix: fill the row background across the full canvas width, or snap the x edges too, and add a `cursorX: 0` test case. - Minor: underline and strikethrough decorations still use `metrics.height`. That stays within one device pixel and inside the row.