Skip to content

Commit afed9cf

Browse files
donjor-agent[bot]donjor
authored andcommitted
fix(web): draw sprite glyphs with Ghostty's own rasterizer via wasm
## What Changed Sprite glyphs now come from Ghostty's own rasterizer, not a hand-written TypeScript port. - **Sidecar:** `ghostty-sprite.wasm` - **Source:** pinned `src/font/sprite` plus z2d - **Gate:** every Ghostty sprite golden must match - **Provenance:** wasm embeds its Ghostty revision ### Runtime - **Simple shapes:** cached paths, any colour - **Intricate shapes:** tinted image, bounded - **Kept:** device-pixel snapping, shared fill grid - **Deleted:** five hand-written shape modules ### Numbers | Measure | Value | | --- | --- | | Golden pages | 36/36 exact, 4,340 glyphs | | Runtime sprite TS | 300 lines, was 964 | | Wasm size | 204.7 kB, 74.4 kB gzip | | z2d vector length | 4: same speed as 16, 127 kB smaller | | Raster cost (spike) | ~0.005 ms per glyph, then cached | | Reproducible | same sha256 across two builds | ## Why The TS port from #1309 fixed seams, but it was about 1,000 lines to keep in step with Ghostty by hand. It also covered only box, block, Braille, and Powerline. The wasm runs Ghostty's code at our pin, so coverage matches Ghostty: - **Added:** branch glyphs from `U+F5D0` - **Added:** sextants and octants - **Added:** legacy computing supplement - **Added:** Ghostty's geometric shapes - **Pin bumps:** rebuild; the gate catches drift Until the wasm loads, or if it fails, sprite codepoints fall back to the font. ## UI Changes Web terminal at DPR 1.5: box, blocks, shades, Braille, Powerline pills, branch, sextant, octant, geometric. ![after-wasm.png](https://github.com/user-attachments/assets/b47303ba-1eee-45ab-b72c-736b4ffe529a) Zoomed 4x, nearest-neighbour: ![after-zoom.png](https://github.com/user-attachments/assets/dcc7b481-5581-473d-9bdf-09d533423e1a) Same session, same cell (DPR 2, 25 px line height): #1309 left, this PR right. ![before-after.png](https://github.com/user-attachments/assets/a3941ece-be2d-4c62-99ec-6dd96810eca6) - **Same:** box, blocks, Braille, Powerline - **Same:** sextant, octant, geometric - **Fixed:** branch glyphs were tofu - **Fixed:** legacy computing now fills the cell ## Performance Full-screen redraw, 160×48 cells at DPR 1.5, in the T3 preview; warm median ms per frame. | Scene | TS port | first wasm push | this PR | | --- | --- | --- | --- | | Status line mix, 4 colours | 12.2 | 11.9 | 8.7 | | Braille, 16-band gradient | 15.3 | 3,870 | 6.0 | | Braille, 48-band gradient | 14.3 | not run | 5.9 | | Intricate glyphs, per-cell truecolor | 11.4 | not run | 123.2 | - **Regression:** first push tinted per colour - **Cause:** gradients overflowed the tint cache - **Effect:** every cell re-rasterized each frame - **Fix:** one path per alpha, filled in any colour - **Parity:** 0 pixel diff over 1,085 glyphs - **Residual:** intricate truecolor screen, ~8 fps ## Checklist - [x] This PR is small and focused - [x] I explained what changed and why - [x] I included before/after screenshots for any UI changes - [ ] I included a video for animation/interaction changes (n/a: no motion) ### Checks | Command | Result | | --- | --- | | `bash scripts/build-libghostty-wasm.sh` | exit 0, 36/36 golden pages | | `vp test run` sprite + renderer fork tests | exit 0, 13 passed | | `vp run typecheck` (web) | exit 0 | | `vp lint` (changed files) | exit 0 | | `vp run build` (web) | exit 0 | | `vp run fork:ci` | exit 0, scripts 644 passed | Claude Opus 5.5 via Claude Code in T3 Code. ## Fork trailers Fork-Domain: upstream-fixes Fork-Tier: bugfix Fork-Upstreamable: yes Co-authored-by: donjor <[email protected]>
1 parent 56bb6f0 commit afed9cf

21 files changed

Lines changed: 760 additions & 1070 deletions

‎apps/web/scripts/build-libghostty-wasm.sh‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,3 +121,60 @@ cp "${build_root}/bin/ghostty-vt.wasm" "${VENDOR_DIR}/ghostty-vt.wasm"
121121
-femit-bin="${VENDOR_DIR}/ghostty-write-pty.wasm"
122122
chmod 0644 "${VENDOR_DIR}/ghostty-write-pty.wasm"
123123
log "wrote ${VENDOR_DIR}/ghostty-vt.wasm"
124+
125+
# Box drawing, block, Powerline, and other cell-filling glyphs come from
126+
# Ghostty's own sprite rasterizer (src/font/sprite), built as a sidecar module.
127+
# The real src/font/main.zig drags the web_canvas font backend into any wasm
128+
# build, so a copy of the pinned src/ gets a stub font root instead.
129+
zon_dependency_field() {
130+
sed -n "/\.$1 = \.{/,/}/p" "${GHOSTTY_SOURCE_DIR}/build.zig.zon" \
131+
| sed -n "s/.*\.$2 = \"\(.*\)\".*/\1/p"
132+
}
133+
134+
z2d_url="$(zon_dependency_field z2d url)"
135+
z2d_hash="$(zon_dependency_field z2d hash)"
136+
[[ -n "${z2d_url}" && -n "${z2d_hash}" ]] || die "z2d dependency missing from build.zig.zon"
137+
log "fetching z2d ${z2d_hash}"
138+
fetched_hash="$("${GHOSTTY_ZIG}" fetch "${z2d_url}")"
139+
[[ "${fetched_hash}" == "${z2d_hash}" ]] || \
140+
die "z2d hash mismatch: build.zig.zon has ${z2d_hash}, fetched ${fetched_hash}"
141+
zig_cache_dir="$("${GHOSTTY_ZIG}" env | sed -n 's/.*\.global_cache_dir = "\(.*\)".*/\1/p')"
142+
z2d_dir="${zig_cache_dir}/p/${z2d_hash}"
143+
[[ -f "${z2d_dir}/src/z2d.zig" ]] || die "z2d source not found at ${z2d_dir}"
144+
145+
sprite_root="${build_root}/sprite"
146+
cp -R "${GHOSTTY_SOURCE_DIR}/src" "${sprite_root}"
147+
cp "${SCRIPT_DIR}/ghostty-sprite-font.zig" "${sprite_root}/font/main.zig"
148+
cp "${SCRIPT_DIR}/ghostty-sprite.zig" "${sprite_root}/t3_sprite.zig"
149+
# Vector length 4 halves the module against z2d's default of 16; sprite output
150+
# is pixel-identical because the golden check below still passes.
151+
printf 'pub const vector_length: u32 = 4;\n' > "${build_root}/z2d_options.zig"
152+
# The pinned revision is embedded so the artifact names its own provenance.
153+
printf 'pub const ghostty_revision = "%s";\n' "${GHOSTTY_REVISION}" \
154+
> "${build_root}/t3_sprite_options.zig"
155+
156+
log "building ghostty-sprite.wasm"
157+
(
158+
cd "${sprite_root}"
159+
"${GHOSTTY_ZIG}" build-exe \
160+
-target wasm32-freestanding \
161+
-O ReleaseSmall \
162+
-fno-entry \
163+
-rdynamic \
164+
-fstrip \
165+
--dep z2d \
166+
--dep t3_sprite_options \
167+
-Mroot=t3_sprite.zig \
168+
--dep z2d_options \
169+
-Mz2d="${z2d_dir}/src/z2d.zig" \
170+
-Mz2d_options="${build_root}/z2d_options.zig" \
171+
-Mt3_sprite_options="${build_root}/t3_sprite_options.zig" \
172+
-femit-bin="${VENDOR_DIR}/ghostty-sprite.wasm"
173+
)
174+
chmod 0644 "${VENDOR_DIR}/ghostty-sprite.wasm"
175+
176+
require_cmd node
177+
node "${SCRIPT_DIR}/check-ghostty-sprite-goldens.ts" \
178+
"${VENDOR_DIR}/ghostty-sprite.wasm" \
179+
"${GHOSTTY_SOURCE_DIR}/src/font/sprite/testdata"
180+
log "wrote ${VENDOR_DIR}/ghostty-sprite.wasm"
Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
// @effect-diagnostics nodeBuiltinImport:off - build-time check run by build-libghostty-wasm.sh.
2+
/**
3+
* Diffs ghostty-sprite.wasm against Ghostty's own sprite golden images
4+
* (src/font/sprite/testdata at the pinned revision). Each PNG is a 16x16 grid
5+
* of padded cells for one 256-codepoint page at one metric set; the wasm must
6+
* reproduce every page pixel for pixel.
7+
*
8+
* Usage: node check-ghostty-sprite-goldens.ts <ghostty-sprite.wasm> <testdata-dir>
9+
*/
10+
import * as NodeFS from "node:fs";
11+
import * as NodePath from "node:path";
12+
import * as NodeZlib from "node:zlib";
13+
14+
interface SpriteExports {
15+
readonly memory: WebAssembly.Memory;
16+
readonly t3_sprite_has: (codepoint: number) => number;
17+
readonly t3_sprite_render: (
18+
codepoint: number,
19+
cellWidth: number,
20+
cellHeight: number,
21+
thickness: number,
22+
span: number,
23+
) => number;
24+
}
25+
26+
// Metric sets from Ghostty's "sprite face render all sprites" test, keyed by
27+
// the golden file suffix: cell width, ascent, descent, box thickness.
28+
const METRIC_SETS: Record<string, readonly [number, number, number, number]> = {
29+
"18x36+4": [18, 30, 6, 4],
30+
"12x24+3": [12, 20, 4, 3],
31+
"11x21+2": [11, 19, 2, 2],
32+
"9x17+1": [9, 15, 2, 1],
33+
};
34+
35+
function paeth(a: number, b: number, c: number): number {
36+
const p = a + b - c;
37+
const pa = Math.abs(p - a);
38+
const pb = Math.abs(p - b);
39+
const pc = Math.abs(p - c);
40+
return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
41+
}
42+
43+
// Decodes the only PNG shape z2d writes for alpha8 surfaces: 8-bit grayscale,
44+
// non-interlaced.
45+
function decodeGrayPng(buffer: Buffer): { width: number; height: number; pixels: Uint8Array } {
46+
const width = buffer.readUInt32BE(16);
47+
const height = buffer.readUInt32BE(20);
48+
if (buffer[24] !== 8 || buffer[25] !== 0 || buffer[28] !== 0) {
49+
throw new Error("expected an 8-bit grayscale, non-interlaced PNG");
50+
}
51+
const chunks: Buffer[] = [];
52+
for (let offset = 8; offset < buffer.length;) {
53+
const length = buffer.readUInt32BE(offset);
54+
if (buffer.toString("ascii", offset + 4, offset + 8) === "IDAT") {
55+
chunks.push(buffer.subarray(offset + 8, offset + 8 + length));
56+
}
57+
offset += 12 + length;
58+
}
59+
const raw = NodeZlib.inflateSync(Buffer.concat(chunks));
60+
const pixels = new Uint8Array(width * height);
61+
for (let y = 0; y < height; y += 1) {
62+
const filter = raw[y * (width + 1)];
63+
for (let x = 0; x < width; x += 1) {
64+
const a = x > 0 ? pixels[y * width + x - 1]! : 0;
65+
const b = y > 0 ? pixels[(y - 1) * width + x]! : 0;
66+
const c = x > 0 && y > 0 ? pixels[(y - 1) * width + x - 1]! : 0;
67+
const predictor =
68+
filter === 1
69+
? a
70+
: filter === 2
71+
? b
72+
: filter === 3
73+
? (a + b) >> 1
74+
: filter === 4
75+
? paeth(a, b, c)
76+
: 0;
77+
pixels[y * width + x] = (raw[y * (width + 1) + 1 + x]! + predictor) & 0xff;
78+
}
79+
}
80+
return { width, height, pixels };
81+
}
82+
83+
const [wasmPath, testdataDir] = process.argv.slice(2);
84+
if (!wasmPath || !testdataDir) {
85+
console.error("usage: node check-ghostty-sprite-goldens.ts <ghostty-sprite.wasm> <testdata-dir>");
86+
process.exit(2);
87+
}
88+
89+
const { instance } = await WebAssembly.instantiate(NodeFS.readFileSync(wasmPath));
90+
const sprite = instance.exports as unknown as SpriteExports;
91+
92+
let failedPages = 0;
93+
let renderedGlyphs = 0;
94+
const pages = NodeFS.readdirSync(testdataDir)
95+
.filter((file) => file.endsWith(".png"))
96+
.toSorted();
97+
for (const file of pages) {
98+
const match = /^U\+([0-9A-F]+)\.\.\.U\+[0-9A-F]+-(\d+x\d+\+\d+)\.png$/.exec(file);
99+
const metrics = match ? METRIC_SETS[match[2]!] : undefined;
100+
if (!match || !metrics) throw new Error(`unrecognized golden file: ${file}`);
101+
const [cellWidth, ascent, descent, thickness] = metrics;
102+
const cellHeight = ascent + descent;
103+
const golden = decodeGrayPng(NodeFS.readFileSync(NodePath.join(testdataDir, file)));
104+
const paddedWidth = cellWidth + 2 * Math.floor(cellWidth / 4);
105+
const paddedHeight = cellHeight + 2 * Math.floor(cellHeight / 4);
106+
const actual = new Uint8Array(golden.width * golden.height);
107+
const failedGlyphs: string[] = [];
108+
for (let index = 0; index < 256; index += 1) {
109+
const codepoint = Number.parseInt(match[1]!, 16) + index;
110+
if (!sprite.t3_sprite_has(codepoint)) continue;
111+
const pointer = sprite.t3_sprite_render(codepoint, cellWidth, cellHeight, thickness, 1);
112+
if (pointer === 0) {
113+
failedGlyphs.push(`${codepoint.toString(16)}(render failed)`);
114+
continue;
115+
}
116+
renderedGlyphs += 1;
117+
const cell = new Uint8Array(sprite.memory.buffer, pointer, paddedWidth * paddedHeight);
118+
const originX = (index % 16) * paddedWidth;
119+
const originY = Math.floor(index / 16) * paddedHeight;
120+
for (let y = 0; y < paddedHeight; y += 1) {
121+
actual.set(
122+
cell.subarray(y * paddedWidth, (y + 1) * paddedWidth),
123+
(originY + y) * golden.width + originX,
124+
);
125+
}
126+
}
127+
// Compare whole pages so golden pixels in cells we left blank also fail.
128+
let differingPixels = 0;
129+
for (let index = 0; index < actual.length; index += 1) {
130+
if (actual[index] !== golden.pixels[index]) differingPixels += 1;
131+
}
132+
const ok = failedGlyphs.length === 0 && differingPixels === 0;
133+
if (!ok) failedPages += 1;
134+
console.log(
135+
`${ok ? "ok " : "FAIL"} ${file}${differingPixels ? ` differing-px=${differingPixels}` : ""}${failedGlyphs.length ? ` ${failedGlyphs.join(",")}` : ""}`,
136+
);
137+
}
138+
139+
console.log(
140+
`[sprite-goldens] pages=${pages.length} failed=${failedPages} glyphs=${renderedGlyphs}`,
141+
);
142+
if (pages.length === 0 || failedPages > 0) process.exit(1);
Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
//! Replaces Ghostty's src/font/main.zig in the sprite build. The real root
2+
//! force-references the web_canvas font backend on wasm, which lib-vt never
3+
//! builds; the sprite face needs only these declarations.
4+
pub const Atlas = @import("Atlas.zig");
5+
pub const Glyph = @import("Glyph.zig");
6+
pub const Metrics = @import("Metrics.zig");
7+
pub const sprite = @import("sprite.zig");
8+
pub const Presentation = enum(u1) { text = 0, emoji = 1 };
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
//! wasm exports over Ghostty's sprite face, built by build-libghostty-wasm.sh
2+
//! from the pinned Ghostty src/ tree. Renders one codepoint into an uncropped,
3+
//! padded alpha8 buffer matching Ghostty's golden-test layout:
4+
//! (w + 2*(w/4)) x (h + 2*(h/4)), with the cell at offset (w/4, h/4).
5+
const std = @import("std");
6+
const font = @import("font/main.zig");
7+
const Face = font.sprite.Face;
8+
const options = @import("t3_sprite_options");
9+
10+
// Freestanding has no stderr or threads: drop logs, trap on panic.
11+
pub const std_options: std.Options = .{ .logFn = noLog };
12+
pub const panic = std.debug.no_panic;
13+
fn noLog(comptime _: std.log.Level, comptime _: @TypeOf(.x), comptime _: []const u8, _: anytype) void {}
14+
15+
const alloc = std.heap.wasm_allocator;
16+
var out: []u8 = &.{};
17+
18+
/// The pinned Ghostty revision this module was built from, NUL-terminated.
19+
export fn t3_sprite_revision() [*:0]const u8 {
20+
return options.ghostty_revision;
21+
}
22+
23+
export fn t3_sprite_has(cp: u32) bool {
24+
const face: Face = .{ .metrics = undefined };
25+
return face.hasCodepoint(cp, null);
26+
}
27+
28+
/// Returns a pointer to the padded alpha buffer, valid until the next call,
29+
/// or 0 when `cp` is not a sprite or rendering failed. Codepoint sprites read
30+
/// only cell width, cell height, and box thickness, so no baseline is needed.
31+
export fn t3_sprite_render(cp: u32, cell_w: u32, cell_h: u32, thickness: u32, span: u32) usize {
32+
return render(cp, cell_w, cell_h, thickness, span) catch 0;
33+
}
34+
35+
fn render(cp: u32, cell_w: u32, cell_h: u32, thickness: u32, span: u32) !usize {
36+
if (!t3_sprite_has(cp) or cell_w == 0 or cell_h == 0) return 0;
37+
const metrics: font.Metrics = .calc(.{
38+
.px_per_em = 16,
39+
.cell_width = @floatFromInt(cell_w),
40+
.ascent = @floatFromInt(cell_h),
41+
.descent = 0,
42+
.line_gap = 0.0,
43+
.underline_thickness = @floatFromInt(thickness),
44+
.strikethrough_thickness = @floatFromInt(thickness),
45+
});
46+
const w = metrics.cell_width * @max(span, 1);
47+
const h = metrics.cell_height;
48+
const pad_x = w / 4;
49+
const pad_y = h / 4;
50+
const out_w = w + 2 * pad_x;
51+
const out_h = h + 2 * pad_y;
52+
53+
var atlas = try font.Atlas.init(alloc, @max(out_w, out_h) + 4, .grayscale);
54+
defer atlas.deinit(alloc);
55+
const face: Face = .{ .metrics = metrics };
56+
const glyph = try face.renderGlyph(alloc, &atlas, cp, .{
57+
.grid_metrics = metrics,
58+
.cell_width = @intCast(@max(span, 1)),
59+
});
60+
61+
const len = out_w * out_h;
62+
if (out.len != len) {
63+
alloc.free(out);
64+
out = try alloc.alloc(u8, len);
65+
}
66+
@memset(out, 0);
67+
// Undo renderGlyph's crop: offset_x = clip_left - pad_x and
68+
// offset_y = height + clip_bottom - pad_y, so clip_top = h + pad_y - offset_y.
69+
const left: u32 = @intCast(glyph.offset_x + @as(i32, @intCast(pad_x)));
70+
const top: u32 = @intCast(@as(i32, @intCast(h + pad_y)) - glyph.offset_y);
71+
for (0..glyph.height) |y| {
72+
const src = atlas.data[(glyph.atlas_y + y) * atlas.size + glyph.atlas_x ..][0..glyph.width];
73+
@memcpy(out[(top + y) * out_w + left ..][0..glyph.width], src);
74+
}
75+
return @intFromPtr(out.ptr);
76+
}

‎apps/web/src/terminal/ghostty/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ It is intentionally not an xterm compatibility layer.
77
- `ghostty-write-pty.wasm` is a 112-byte callback trampoline for terminal-generated PTY replies.
88
- `core.ts` owns per-terminal Ghostty handles and translates the C ABI into render snapshots.
99
- `renderer.ts` batches backgrounds and style runs into a Canvas 2D frame.
10+
- `sprite/` draws box drawing, block, Powerline, and other cell-filling glyphs from
11+
`ghostty-sprite.wasm`, Ghostty's own sprite rasterizer, so they tile at any line height.
1012
- `surface.ts` owns browser input, IME, selection, scrolling, sizing, links, and cursor blinking.
1113
- `fonts/` vendors the symbols-only Nerd Font (MIT) the surface registers lazily, so
1214
prompt glyphs render without a locally installed Nerd Font.
@@ -16,4 +18,4 @@ It is intentionally not an xterm compatibility layer.
1618
in its build info and the ABI test verifies it against mobile's `VERSION`.
1719

1820
Keep browser behavior here and terminal transport in the existing client runtime. Do not add React
19-
state to the render loop. Both WASM artifacts are ordinary read-only assets, not executables.
21+
state to the render loop. The WASM artifacts are ordinary read-only assets, not executables.

0 commit comments

Comments
 (0)