From dc6c994038631cb4395c2e008e65019fac25bbb5 Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 11:25:13 -0400
Subject: [PATCH 01/24] Type the cell grid context and round out its text
 attributes

getContext("termdom-cellgrid") is typed to return a
CanvasCellGridContext, in TermDOM's own canvas and, through a global
declaration, in lib.dom's, so no caller casts. The context's canvas is
an HTMLCanvasElement, and its settings read back as their own values.

columns and rows are gone: canvas.width and canvas.height are the
grid's size, as a 2d context reads its canvas's.

textDecoration takes line-through as well as underline, alone or
together, and getCell reports dim, strikethrough and inverse.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/guides/07-images-and-canvas.md | 11 ++---
 examples/canvas.ts                  |  2 +-
 src/index.ts                        | 10 +++++
 src/internal/canvas.ts              | 54 ++++++++++++++--------
 src/internal/dom.ts                 |  8 +++-
 src/internal/framebuffer.ts         |  4 ++
 tests/canvas.test.ts                | 69 ++++++++++++++++++++---------
 7 files changed, 110 insertions(+), 48 deletions(-)

diff --git a/docs/guides/07-images-and-canvas.md b/docs/guides/07-images-and-canvas.md
index 83da6b29d..70a39d84b 100644
--- a/docs/guides/07-images-and-canvas.md
+++ b/docs/guides/07-images-and-canvas.md
@@ -287,13 +287,14 @@ The cell grid context draws cells instead of pixels. The canvas is
 TermDOM's own, so its name carries TermDOM's prefix, as a browser's own
 context types once carried theirs (`"moz-webgl"`, `"webkit-3d"`). Its
 interface is not on `window`. The `@b9g/termdom` package exports it as
-`CanvasCellGridContext`.
+`CanvasCellGridContext`, and importing the package teaches TypeScript
+that `getContext("termdom-cellgrid")` returns one.
 
 ```ts
 const canvas = document.createElement("canvas");
 canvas.width = 20;
 canvas.height = 3;
-const grid = canvas.getContext("termdom-cellgrid");
+const grid = canvas.getContext("termdom-cellgrid")!;
 grid.fillStyle = "#003366";
 grid.fillRect(0, 0, 20, 3);
 grid.fillStyle = "#ffcc00";
@@ -317,16 +318,16 @@ not the page's borders around the canvas.
 | `lineJoin` | `miter`, the default, or `round`, which curves `strokeRect()`'s corners |
 | `font` | Keywords from the CSS `font` shorthand: `bold`, `italic`, `lighter` |
 | `textAlign` | `left`, `right`, `center`, `start` or `end` |
-| `textDecoration` | `none` or `underline` |
+| `textDecoration` | `none`, or `underline` and `line-through`, alone or together |
 | `fillText(text, x, y, maxWidth?)` | Writes glyphs in the fill color, over the cells' backgrounds. A wide glyph takes two columns |
 | `fillRect(x, y, w, h)` | Fills cells with the fill color as their background. `currentcolor` fills them in inverse video |
 | `clearRect(x, y, w, h)` | Empties cells |
 | `strokeLine(x1, y1, x2, y2)` | A line from one cell to another, both included, along a row or a column. A slanted line draws nothing |
 | `strokeRect(x, y, w, h)` | A box around the cells `w` by `h` from (x, y) |
 | `drawImage(image, ...)` | Draws an image's pixels, two to a cell. Without a size, the image takes its natural size in cells |
-| `getCell(x, y)` | The cell's glyph, colors and attributes, or `null` |
+| `getCell(x, y)` | The cell's `char`, `color` and `background`, and whether it is `bold`, `italic`, `dim`, `underline`, `strikethrough` or `inverse`; `null` for an empty cell |
 | `measureText(text)` | The text's width in columns |
-| `columns`, `rows`, `reset()` | The grid's size, and clearing it |
+| `reset()` | Clears the grid and the settings |
 
 ## Text alone
 
diff --git a/examples/canvas.ts b/examples/canvas.ts
index 3c15667a8..eb0eb3f3a 100644
--- a/examples/canvas.ts
+++ b/examples/canvas.ts
@@ -37,7 +37,7 @@ pixels.style.height = "16px";
 const ctx = pixels.getContext("2d")!;
 
 const grid = (document.getElementById("cells") as HTMLCanvasElement)
-  .getContext("termdom-cellgrid" as "2d") as any;
+  .getContext("termdom-cellgrid")!;
 
 // Conway's Life on the grid, seeded with a glider, blinkers, a toad and
 // an R-pentomino, which keeps changing for a long time.
diff --git a/src/index.ts b/src/index.ts
index 84c0ee5cb..587c3b607 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,5 +1,6 @@
 import "./internal/inspector.ts";
 
+import type {CanvasCellGridContext} from "./internal/canvas.ts";
 import {
 	Cascade,
 	type CellSize,
@@ -79,6 +80,15 @@ export type {
 	TerminalTransport,
 } from "./internal/exchange.ts";
 
+declare global {
+	interface HTMLCanvasElement {
+		getContext(
+			contextId: "termdom-cellgrid",
+			options?: unknown,
+		): CanvasCellGridContext | null;
+	}
+}
+
 // Images decode on the runtime's web Worker, running src/decode-worker.ts,
 // which builds to dist/decode-worker.js beside this file. A runtime with
 // no Worker, as Node is without --experimental-web-worker, and a CommonJS
diff --git a/src/internal/canvas.ts b/src/internal/canvas.ts
index ddf15fa3b..82158a267 100644
--- a/src/internal/canvas.ts
+++ b/src/internal/canvas.ts
@@ -2970,7 +2970,7 @@ export interface CanvasCellGridContext {
 	[kLineStyle]: LineStyle["style"];
 	[kLineJoin]: "miter" | "round";
 	[kFont]: string;
-	[kTextAlign]: string;
+	[kTextAlign]: "start" | "end" | "left" | "right" | "center";
 	[kTextDecoration]: string;
 }
 
@@ -2995,16 +2995,8 @@ export class CanvasCellGridContext {
 		this[kTextDecoration] = "none";
 	}
 
-	get canvas(): object {
-		return this[kGridHost].canvas;
-	}
-
-	get columns(): number {
-		return this[kGridHost].cells().cols;
-	}
-
-	get rows(): number {
-		return this[kGridHost].cells().rows;
+	get canvas(): HTMLCanvasElement {
+		return this[kGridHost].canvas as HTMLCanvasElement;
 	}
 
 	get fillStyle(): string {
@@ -3024,7 +3016,7 @@ export class CanvasCellGridContext {
 	}
 
 	/** A CSS border style: solid, double, dashed, dotted and the rest. */
-	get lineStyle(): string {
+	get lineStyle(): LineStyle["style"] {
 		return this[kLineStyle];
 	}
 
@@ -3036,7 +3028,7 @@ export class CanvasCellGridContext {
 	}
 
 	/** miter, round. A round join curves strokeRect()'s corners. */
-	get lineJoin(): string {
+	get lineJoin(): "miter" | "round" {
 		return this[kLineJoin];
 	}
 
@@ -3055,24 +3047,41 @@ export class CanvasCellGridContext {
 		this[kFont] = String(value);
 	}
 
-	get textAlign(): string {
+	get textAlign(): "start" | "end" | "left" | "right" | "center" {
 		return this[kTextAlign];
 	}
 
 	set textAlign(value: string) {
-		if (["start", "end", "left", "right", "center"].includes(value)) {
+		if (
+			value === "start" ||
+			value === "end" ||
+			value === "left" ||
+			value === "right" ||
+			value === "center"
+		) {
 			this[kTextAlign] = value;
 		}
 	}
 
-	/** none, underline. */
+	/** none, or underline and line-through, alone or together. */
 	get textDecoration(): string {
 		return this[kTextDecoration];
 	}
 
 	set textDecoration(value: string) {
-		if (value === "none" || value === "underline") {
-			this[kTextDecoration] = value;
+		const words = String(value).trim().toLowerCase().split(/\s+/);
+		if (words.length === 1 && words[0] === "none") {
+			this[kTextDecoration] = "none";
+			return;
+		}
+		const lines = new Set(words);
+		if (
+			lines.size === words.length &&
+			words.every((word) => word === "underline" || word === "line-through")
+		) {
+			this[kTextDecoration] = ["underline", "line-through"]
+				.filter((line) => lines.has(line))
+				.join(" ");
 		}
 	}
 
@@ -3137,7 +3146,8 @@ export class CanvasCellGridContext {
 			bold: words.includes("bold") || words.includes("bolder"),
 			italic: words.includes("italic") || words.includes("oblique"),
 			dim: words.includes("lighter"),
-			underline: this[kTextDecoration] === "underline",
+			underline: this[kTextDecoration].includes("underline"),
+			strikethrough: this[kTextDecoration].includes("line-through"),
 		};
 		const {grid} = cells;
 		for (const cluster of clusters) {
@@ -3320,7 +3330,10 @@ export class CanvasCellGridContext {
 		background: string | null;
 		bold: boolean;
 		italic: boolean;
+		dim: boolean;
 		underline: boolean;
+		strikethrough: boolean;
+		inverse: boolean;
 	} | null {
 		const {grid, cols, rows} = this[kGridHost].cells();
 		const col = Math.floor(x);
@@ -3350,7 +3363,10 @@ export class CanvasCellGridContext {
 			background: css(cell.bg),
 			bold: cell.bold,
 			italic: cell.italic,
+			dim: cell.dim,
 			underline: cell.underline,
+			strikethrough: cell.strikethrough,
+			inverse: cell.inverse,
 		};
 	}
 
diff --git a/src/internal/dom.ts b/src/internal/dom.ts
index de6319ba1..0b5e80e19 100644
--- a/src/internal/dom.ts
+++ b/src/internal/dom.ts
@@ -14486,6 +14486,10 @@ class HTMLCanvasElement extends HTMLElement {
 		contextId: "2d",
 		options?: globalThis.CanvasRenderingContext2DSettings,
 	): globalThis.CanvasRenderingContext2D | null;
+	getContext(
+		contextId: "termdom-cellgrid",
+		options?: unknown,
+	): CanvasCellGridContext | null;
 	getContext(
 		contextId: "bitmaprenderer",
 		options?: globalThis.ImageBitmapRenderingContextSettings,
@@ -14502,7 +14506,9 @@ class HTMLCanvasElement extends HTMLElement {
 		contextId: string,
 		options?: any,
 	): globalThis.RenderingContext | null;
-	getContext(contextId: string): globalThis.RenderingContext | null {
+	getContext(
+		contextId: string,
+	): globalThis.RenderingContext | CanvasCellGridContext | null {
 		if (arguments.length < 1) {
 			throw new TypeError("getContext needs a context id");
 		}
diff --git a/src/internal/framebuffer.ts b/src/internal/framebuffer.ts
index e88d4f921..136f25a5d 100644
--- a/src/internal/framebuffer.ts
+++ b/src/internal/framebuffer.ts
@@ -948,6 +948,8 @@ export function readCell(
 	bold: boolean;
 	italic: boolean;
 	underline: boolean;
+	strikethrough: boolean;
+	dim: boolean;
 	inverse: boolean;
 } | null {
 	if (grid.cluster[index] === 0) {
@@ -964,6 +966,8 @@ export function readCell(
 		bold: (attrs & ATTR.Bold) !== 0,
 		italic: (attrs & ATTR.Italic) !== 0,
 		underline: (attrs & (ATTR.Underline | ATTR.DoubleUnderline)) !== 0,
+		strikethrough: (attrs & ATTR.Strikethrough) !== 0,
+		dim: (attrs & ATTR.Dim) !== 0,
 		inverse: (attrs & ATTR.Inverse) !== 0,
 	};
 }
diff --git a/tests/canvas.test.ts b/tests/canvas.test.ts
index 67a8720bd..3fd0c05a2 100644
--- a/tests/canvas.test.ts
+++ b/tests/canvas.test.ts
@@ -77,10 +77,10 @@ test("getContext hands back one context per canvas, and null for the rest", asyn
 	expect(ctx).not.toBeNull();
 	expect(a.getContext("2d")).toBe(ctx);
 	expect(ctx!.canvas).toBe(a);
-	expect(a.getContext("termdom-cellgrid" as "2d")).toBeNull();
+	expect(a.getContext("termdom-cellgrid")).toBeNull();
 	expect(a.getContext("webgl")).toBeNull();
 	expect(b.getContext("bitmaprenderer")).toBeNull();
-	const grid = b.getContext("termdom-cellgrid" as "2d");
+	const grid = b.getContext("termdom-cellgrid");
 	expect(grid).not.toBeNull();
 	expect(b.getContext("2d")).toBeNull();
 	expect(ctx).toBeInstanceOf((dom.window as any).CanvasRenderingContext2D);
@@ -600,9 +600,9 @@ test("a canvas stretched by CSS scales its pixels to the box", async () => {
 // ---------------------------------------------------------------------------
 // cellgrid
 
-function grid(document: Document, id = "g"): any {
+function grid(document: Document, id = "g"): CanvasCellGridContext {
 	return (document.getElementById(id) as HTMLCanvasElement)
-		.getContext("termdom-cellgrid" as "2d");
+		.getContext("termdom-cellgrid")!;
 }
 
 test("a cellgrid canvas is width columns by height rows of cells", async () => {
@@ -612,7 +612,7 @@ test("a cellgrid canvas is width columns by height rows of cells", async () => {
 	await nextFrame(dom);
 	const rect = document.getElementById("g")!.getBoundingClientRect();
 	expect([rect.width, rect.height]).toEqual([12, 3]);
-	expect([ctx.columns, ctx.rows]).toEqual([12, 3]);
+	expect([ctx.canvas.width, ctx.canvas.height]).toEqual([12, 3]);
 	dom.dispose();
 });
 
@@ -645,7 +645,10 @@ test("fillText writes glyphs, fillRect fills backgrounds, clearRect empties", as
 		background: "#003366",
 		bold: true,
 		italic: true,
+		dim: false,
 		underline: false,
+		strikethrough: false,
+		inverse: false,
 	});
 	ctx.clearRect(0, 0, 12, 1);
 	expect(ctx.getCell(1, 0)).toBeNull();
@@ -655,6 +658,34 @@ test("fillText writes glyphs, fillRect fills backgrounds, clearRect empties", as
 	dom.dispose();
 });
 
+test("textDecoration draws underline and line-through, and getCell reads them back", async () => {
+	const {dom, document} =
+		await mount("<canvas id=g width=12 height=1></canvas>");
+	const ctx = grid(document);
+	ctx.textDecoration = "line-through underline";
+	expect(ctx.textDecoration).toBe("underline line-through");
+	ctx.textDecoration = "overline";
+	expect(ctx.textDecoration).toBe("underline line-through");
+	ctx.font = "lighter";
+	ctx.fillText("ab", 0, 0);
+	ctx.textDecoration = "line-through";
+	ctx.font = "";
+	ctx.fillText("c", 2, 0);
+	expect(ctx.getCell(0, 0)).toMatchObject({
+		dim: true,
+		underline: true,
+		strikethrough: true,
+	});
+	expect(ctx.getCell(2, 0)).toMatchObject({
+		dim: false,
+		underline: false,
+		strikethrough: true,
+	});
+	ctx.textDecoration = "none";
+	expect(ctx.textDecoration).toBe("none");
+	dom.dispose();
+});
+
 test("text that runs past the grid is cut, and wide glyphs take two columns", async () => {
 	const {dom, terminal, document} =
 		await mount("<canvas id=g width=6 height=1></canvas>|");
@@ -662,11 +693,11 @@ test("text that runs past the grid is cut, and wide glyphs take two columns", as
 	ctx.fillText("漢字abcdef", 0, 0);
 	await nextFrame(dom);
 	expect(rowText(terminal, 0)).toBe("漢字ab|");
-	expect(ctx.getCell(0, 0).char).toBe("漢");
+	expect(ctx.getCell(0, 0)!.char).toBe("漢");
 	expect(ctx.measureText("漢字a").width).toBe(5);
 	ctx.textAlign = "right";
 	ctx.fillText("Z", 6, 0);
-	expect(ctx.getCell(5, 0).char).toBe("Z");
+	expect(ctx.getCell(5, 0)!.char).toBe("Z");
 	dom.dispose();
 });
 
@@ -715,7 +746,7 @@ test("resizing a cellgrid canvas resizes and clears its grid", async () => {
 	const ctx = grid(document);
 	ctx.fillText("abcd", 0, 0);
 	canvas.width = 8;
-	expect(ctx.columns).toBe(8);
+	expect(ctx.canvas.width).toBe(8);
 	expect(ctx.getCell(0, 0)).toBeNull();
 	await nextFrame(dom);
 	expect(canvas.getBoundingClientRect().width).toBe(8);
@@ -867,7 +898,7 @@ test("strokeRect draws a box and strokeLine joins it as tees", async () => {
 	expect(rowText(terminal, 1)).toBe("│  │ │");
 	expect(rowText(terminal, 2)).toBe("├──┴─┤");
 	expect(rowText(terminal, 3)).toBe("└────┘");
-	expect(ctx.getCell(3, 2).char).toBe("┴");
+	expect(ctx.getCell(3, 2)!.char).toBe("┴");
 	dom.dispose();
 });
 
@@ -935,9 +966,9 @@ test("a cellgrid samples only the cells an image lands on, however large", async
 	source.fillRect(1, 0, 1, 2);
 	const ctx = grid(document);
 	ctx.drawImage(document.getElementById("src"), -1e6 + 2, 0, 2e6, 1e6);
-	expect(ctx.getCell(1, 0).background).toBe("#ff0000");
-	expect(ctx.getCell(2, 0).background).toBe("#0000ff");
-	expect(ctx.getCell(3, 1).background).toBe("#0000ff");
+	expect(ctx.getCell(1, 0)!.background).toBe("#ff0000");
+	expect(ctx.getCell(2, 0)!.background).toBe("#0000ff");
+	expect(ctx.getCell(3, 1)!.background).toBe("#0000ff");
 	dom.dispose();
 });
 
@@ -975,7 +1006,7 @@ test("with graphics off, a canvas has no 2d context and keeps its cellgrid", asy
 	const b = dom.document.createElement("canvas");
 	dom.document.body.append(a, b);
 	expect(a.getContext("2d")).toBeNull();
-	expect(b.getContext("termdom-cellgrid" as "2d")).toBeInstanceOf(
+	expect(b.getContext("termdom-cellgrid")).toBeInstanceOf(
 		CanvasCellGridContext,
 	);
 	dom.dispose();
@@ -1014,9 +1045,7 @@ test("a cell grid clips to a scroller and paints the rows scrolled into view", a
 		"</div><p>below</p>",
 	);
 	const canvas = document.getElementById("c") as HTMLCanvasElement;
-	const grid = canvas.getContext("termdom-cellgrid" as "2d") as unknown as {
-		fillText(text: string, x: number, y: number): void;
-	};
+	const grid = canvas.getContext("termdom-cellgrid")!;
 	for (let row = 0; row < 6; row++) {
 		grid.fillText(`row ${row}`, 0, row);
 	}
@@ -1044,9 +1073,7 @@ test("a cell grid narrower than its columns is cut at its content box", async ()
 		"</canvas>|</p>",
 	);
 	const canvas = document.getElementById("c") as HTMLCanvasElement;
-	const grid = canvas.getContext("termdom-cellgrid" as "2d") as unknown as {
-		fillText(text: string, x: number, y: number): void;
-	};
+	const grid = canvas.getContext("termdom-cellgrid")!;
 	grid.fillText("abcdefghijklmnop", 0, 0);
 	await nextFrame(dom);
 	expect(rowText(terminal, 0)).toBe("abcde|");
@@ -1107,9 +1134,7 @@ test("a cell grid in a scroller shifts with the terminal's scroll", async () =>
 		"<canvas id=c width=10 height=12 style=\"display: block\"></canvas>" +
 		"</div>";
 	const canvas = dom.document.getElementById("c") as HTMLCanvasElement;
-	const grid = canvas.getContext("termdom-cellgrid" as "2d") as unknown as {
-		fillText(text: string, x: number, y: number): void;
-	};
+	const grid = canvas.getContext("termdom-cellgrid")!;
 	for (let row = 0; row < 12; row++) {
 		grid.fillText(`row ${row}`, 0, row);
 	}

From 5315782eec63e99889c5b1a04fc856908ba74130 Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 11:34:15 -0400
Subject: [PATCH 02/24] Build the image decoder as a worker entry, out of the
 package's exports

libuild 0.2.26 builds a src/<name>.worker.ts to dist and leaves it out
of exports, which is what a module loaded by file path from
new URL(..., import.meta.url) needs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 bun.lock                                         | 4 ++--
 docs/guides/06-api.md                            | 3 ---
 docs/guides/07-images-and-canvas.md              | 5 +++--
 package.json                                     | 3 +--
 src/{decode-worker.ts => image-decode.worker.ts} | 0
 src/index.ts                                     | 6 +++---
 src/internal/images.ts                           | 2 +-
 7 files changed, 10 insertions(+), 13 deletions(-)
 rename src/{decode-worker.ts => image-decode.worker.ts} (100%)

diff --git a/bun.lock b/bun.lock
index 0fe767cda..09da77fae 100644
--- a/bun.lock
+++ b/bun.lock
@@ -14,7 +14,7 @@
       "devDependencies": {
         "@b9g/crank": "^0.7.12",
         "@b9g/eslint-config": "^0.1.10",
-        "@b9g/libuild": "^0.2.25",
+        "@b9g/libuild": "^0.2.26",
         "@codemirror/commands": "^6.11.1",
         "@codemirror/lang-javascript": "^6.2.5",
         "@codemirror/language": "^6.12.4",
@@ -61,7 +61,7 @@
 
     "@b9g/eslint-config": ["@b9g/eslint-config@0.1.10", "", { "peerDependencies": { "@eslint/js": ">=9", "@stylistic/eslint-plugin": ">=3", "@typescript-eslint/eslint-plugin": ">=8", "@typescript-eslint/parser": ">=8", "eslint": ">=9", "eslint-plugin-acrocase": ">=0.0.1", "eslint-plugin-crank": ">=0.2.2", "eslint-plugin-esfold": ">=0.1.2" } }, "sha512-5uVBZvX+K4XoGilegJ5/tEH4Mzg5gf+/XdOF6I3QJxTX/5iOoyTuMChIKWHPI3oxBAHzbLHYxFeHoNrp7q2gRQ=="],
 
-    "@b9g/libuild": ["@b9g/libuild@0.2.25", "", { "dependencies": { "@b9g/async-context": "^0.2.1", "commander": "^15.0.0", "esbuild": "^0.28.1", "expect": "^30.4.1", "glob": "^13.0.6", "pretty-format": "^30.4.1" }, "peerDependencies": { "playwright": "^1.40.0", "typescript": "^5.0.0 || ^6.0.0" }, "optionalPeers": ["playwright", "typescript"], "bin": { "libuild": "cli.js" } }, "sha512-gASB1QiejGfe5vIGbp2wwIhMvz4T1ppo9RlmtwI8tpVXld8GqXl/7NliU0HiY5IU3ZqaLDTbiick7BXSkKAJgw=="],
+    "@b9g/libuild": ["@b9g/libuild@0.2.26", "", { "dependencies": { "@b9g/async-context": "^0.2.1", "commander": "^15.0.0", "esbuild": "^0.28.1", "expect": "^30.4.1", "glob": "^13.0.6", "pretty-format": "^30.4.1" }, "peerDependencies": { "playwright": "^1.40.0", "typescript": "^5.0.0 || ^6.0.0" }, "optionalPeers": ["playwright", "typescript"], "bin": { "libuild": "cli.js" } }, "sha512-8eZT6nJ+PL5ILlowL64kBntd+PPrH7DpTJHyWazhL6ik9kQwmQpQFJgVtcu27G4FE0BPqtlSYyJMbLPNVE1KlA=="],
 
     "@babel/code-frame": ["@babel/code-frame@7.29.7", "", { "dependencies": { "@babel/helper-validator-identifier": "^7.29.7", "js-tokens": "^4.0.0", "picocolors": "^1.1.1" } }, "sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw=="],
 
diff --git a/docs/guides/06-api.md b/docs/guides/06-api.md
index 7dac7b513..082d50001 100644
--- a/docs/guides/06-api.md
+++ b/docs/guides/06-api.md
@@ -373,6 +373,3 @@ is a whole server.
 - The types `TermDOMOptions`, `TermDOMEventMap`, `CellSize`,
   `TerminalTransport`, `TerminalCloseInfo`, `TerminalSize`, `ProcessLike`,
   `TTYReadStream`, `TTYWriteStream` and `SSHSessionLike`.
-
-`@b9g/termdom/decode-worker` is the module that decodes images on a
-`Worker`. Programs do not import it.
diff --git a/docs/guides/07-images-and-canvas.md b/docs/guides/07-images-and-canvas.md
index 70a39d84b..fe0e93300 100644
--- a/docs/guides/07-images-and-canvas.md
+++ b/docs/guides/07-images-and-canvas.md
@@ -209,8 +209,9 @@ one does not stall the page. Bun and Deno have one. Node has one from
 thread there. Without a `Worker`, and in a CommonJS build, images decode
 on the page's thread in 16 ms slices, so input and frames go on
 between slices. A decode that takes more than 10 seconds is stopped
-and that image fails; the images behind it still decode. The worker runs
-the package's `@b9g/termdom/decode-worker` module.
+and that image fails; the images behind it still decode. The worker's
+module ships in the package beside its entry, and TermDOM starts it
+itself.
 
 The worker ends a second after its last decode, and when the last
 TermDOM is disposed, so it never keeps a finished program running.
diff --git a/package.json b/package.json
index 5675064dc..38f4d4763 100644
--- a/package.json
+++ b/package.json
@@ -26,7 +26,6 @@
   ],
   "exports": {
     ".": "./src/index.ts",
-    "./decode-worker": "./src/decode-worker.ts",
     "./package.json": "./package.json"
   },
   "files": [
@@ -59,7 +58,7 @@
   "devDependencies": {
     "@b9g/crank": "^0.7.12",
     "@b9g/eslint-config": "^0.1.10",
-    "@b9g/libuild": "^0.2.25",
+    "@b9g/libuild": "^0.2.26",
     "@codemirror/commands": "^6.11.1",
     "@codemirror/lang-javascript": "^6.2.5",
     "@codemirror/language": "^6.12.4",
diff --git a/src/decode-worker.ts b/src/image-decode.worker.ts
similarity index 100%
rename from src/decode-worker.ts
rename to src/image-decode.worker.ts
diff --git a/src/index.ts b/src/index.ts
index 587c3b607..0be85e0c6 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -89,14 +89,14 @@ declare global {
 	}
 }
 
-// Images decode on the runtime's web Worker, running src/decode-worker.ts,
-// which builds to dist/decode-worker.js beside this file. A runtime with
+// Images decode on the runtime's web Worker, running src/image-decode.worker.ts,
+// which builds to dist/image-decode.worker.js beside this file. A runtime with
 // no Worker, as Node is without --experimental-web-worker, and a CommonJS
 // build, which has no import.meta.url, decode on this thread instead.
 setDecodeWorkerURL(
 	typeof import.meta.url === "string"
 		? new URL(
-			`./decode-worker.${import.meta.url.endsWith(".ts") ? "ts" : "js"}`,
+			`./image-decode.worker.${import.meta.url.endsWith(".ts") ? "ts" : "js"}`,
 			import.meta.url,
 		)
 		: null,
diff --git a/src/internal/images.ts b/src/internal/images.ts
index 9d644e931..ef0bad52d 100644
--- a/src/internal/images.ts
+++ b/src/internal/images.ts
@@ -2187,7 +2187,7 @@ let current: WorkerState | null = null;
 let workersWork = true;
 let nextRequest = 0;
 
-/** The module src/decode-worker.ts builds to, which decodes off-thread. */
+/** The module src/image-decode.worker.ts builds to, which decodes off-thread. */
 export function setDecodeWorkerURL(url: URL | null): void {
 	if (current !== null) {
 		endWorker(current);

From e6fe843f8354a0b65501de9a3e1ed10363d3eca8 Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 11:40:11 -0400
Subject: [PATCH 03/24] Style gauges through css-forms-1's pseudo-elements and
 their prefixed aliases

A page styles a progress or meter's track and fill through
::slider-track and ::slider-fill, and a meter's level through
:optimal-value, :low-value and :high-value, as CSS Form Control Styling
specifies. WebKit's ::-webkit-progress-* and ::-webkit-meter-* and
Firefox's ::-moz-progress-bar, ::-moz-meter-bar and :-moz-meter-*
pseudo-classes are aliases, as its section 4.10 asks. The groove takes
the track's color, so ::slider-track colors it.

accent-color no longer colors a progress bar's fill.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                    |  3 +-
 docs/guides/04-styling.md    |  6 ++-
 docs/guides/06-api.md        | 22 +++++++--
 examples/animated.ts         |  3 +-
 examples/progress-bar.ts     |  3 +-
 src/internal/cssom.ts        | 63 +++++++++++-------------
 src/internal/cssselectors.ts | 43 +++++++++++++++++
 src/internal/cssvalues.ts    |  9 ++++
 src/internal/dom.ts          | 22 +++++++--
 src/internal/useragent.ts    | 14 +++---
 tests/widgets.test.ts        | 93 ++++++++++++++++++++++++++++++++----
 11 files changed, 220 insertions(+), 61 deletions(-)

diff --git a/README.md b/README.md
index 5e69c19ab..f0cb317d9 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,8 @@ document.body.innerHTML = `
   <style>
     .card { border: 1px solid #5fafff; padding: 0 1ch; width: 36ch; }
     .title { color: #5fafff; font-weight: bold; }
-    progress { width: 25ch; accent-color: green; }
+    progress { width: 25ch; }
+    progress::slider-fill { color: green; }
     .pct { color: #888; }
   </style>
   <div class="card">
diff --git a/docs/guides/04-styling.md b/docs/guides/04-styling.md
index 2c797ea44..c8b424e25 100644
--- a/docs/guides/04-styling.md
+++ b/docs/guides/04-styling.md
@@ -171,8 +171,10 @@ ranges in `CSS.highlights`. `::placeholder` styles a text control's
 placeholder. `::backdrop` styles what a modal dialog or popover covers.
 A `<select>`'s picker and icon take `::picker(select)` and
 `::picker-icon`, and a `<details>`' content takes `::details-content`.
-A `<progress>` fills with its `accent-color`. `::part()` from a page
-does not reach inside the built-in controls, as in a browser.
+A `<progress>` or `<meter>` takes `::slider-track` and `::slider-fill`,
+and a meter's levels match `:optimal-value`, `:low-value` and
+`:high-value`. `::part()` from a page does not reach inside the
+built-in controls, as in a browser.
 
 ## Default looks
 
diff --git a/docs/guides/06-api.md b/docs/guides/06-api.md
index 082d50001..582c6edfa 100644
--- a/docs/guides/06-api.md
+++ b/docs/guides/06-api.md
@@ -125,6 +125,7 @@ pseudo-elements browsers give them:
 | `<input>` text types, `<textarea>` | `::placeholder` |
 | `<select>` | `::picker(select)`, `::picker-icon` |
 | `<details>` | `::details-content` |
+| `<progress>`, `<meter>` | `::slider-track`, `::slider-fill` |
 
 `::picker(select)` and `::picker-icon` are a customizable `<select>`'s,
 as Chromium ships them.
@@ -134,14 +135,27 @@ select::picker(select) { background-color: #1c1c1c; }
 select::picker-icon { color: gray; }
 ```
 
-A `<progress>` draws its fill in its `accent-color`, as browsers do.
+`::slider-track` and `::slider-fill` are CSS Form Control Styling's
+(css-forms-1). The track holds the fill and shows past it. A meter
+matches `:optimal-value` when its value is in its optimum region,
+`:low-value` below `low`, and `:high-value` above `high`.
 
 ```css
-progress { accent-color: green; }
+progress::slider-fill { color: green; }
+meter:low-value::slider-fill { color: orange; }
 ```
 
-The rest of a control's insides, such as a meter's fill or a button's
-brackets, are TermDOM's own, as they are a browser's: the
+The prefixed names WebKit and Firefox ship work too, as aliases:
+`::-webkit-progress-bar` and `::-webkit-meter-bar` are the track,
+`::-webkit-progress-value`, `::-moz-progress-bar` and `::-moz-meter-bar`
+the fill, `::-webkit-meter-optimum-value`,
+`::-webkit-meter-suboptimum-value` and
+`::-webkit-meter-even-less-good-value` a meter's fill at each level,
+and `:-moz-meter-optimum`, `:-moz-meter-sub-optimum` and
+`:-moz-meter-sub-sub-optimum` the meter at each level.
+
+The rest of a control's insides, such as a button's brackets, are
+TermDOM's own, as they are a browser's: the
 controls are shadow trees inside, and `::part()` does not reach into
 them. TermDOM's own rules come first, so a page's `::placeholder` and the
 rest override them as they would any built-in style.
diff --git a/examples/animated.ts b/examples/animated.ts
index d4b9793fd..2e3911c05 100644
--- a/examples/animated.ts
+++ b/examples/animated.ts
@@ -14,7 +14,8 @@ style.textContent = `
   .spinner { color: green; display: inline; }
   .dots { color: yellow; display: inline; }
   .bar-container { display: flex; flex-direction: row; }
-  .bar { width: 30ch; accent-color: green; }
+  .bar { width: 30ch; }
+  .bar::slider-fill { color: green; }
   .bar-pct { color: white; display: inline; padding-left: 1ch; }
   .braille { color: magenta; display: inline; }
   .clock { color: cyan; display: inline; }
diff --git a/examples/progress-bar.ts b/examples/progress-bar.ts
index 46a38df48..fed20722f 100644
--- a/examples/progress-bar.ts
+++ b/examples/progress-bar.ts
@@ -9,7 +9,8 @@ document.body.innerHTML = `
   <style>
     .card { border: 1px solid #5fafff; padding: 0 1ch; width: 36ch; }
     .title { color: #5fafff; font-weight: bold; }
-    progress { width: 25ch; accent-color: green; }
+    progress { width: 25ch; }
+    progress::slider-fill { color: green; }
     .pct { color: #888; }
   </style>
   <div class="card">
diff --git a/src/internal/cssom.ts b/src/internal/cssom.ts
index 3f31018d1..f3d5cb022 100644
--- a/src/internal/cssom.ts
+++ b/src/internal/cssom.ts
@@ -4864,31 +4864,12 @@ function blockifyDisplay(element: Element | null, display: string): string {
 	return display;
 }
 
-// A progress bar's fill, inside the UA shadow tree of a <progress>.
-function isProgressFill(element: Element | null): boolean {
-	if (element === null) {
-		return false;
-	}
-	const root = element.getRootNode();
-	return isUAShadowTree(root) &&
-		(root as unknown as ShadowRoot).host.tagName === "PROGRESS" &&
-		(element.getAttribute("part") ?? "").split(" ").includes("bar");
-}
-
 // What the cascade leaves, with var() substituted, `currentcolor`
 // replaced by the color it names, and display blockified.
 function resolvePropertyValue(
 	declaration: ComputedStyleDeclaration,
 	property: string,
 ): string {
-	// css-ui-4 §6.1: a <progress> draws in its accent color, when the page
-	// gives it one.
-	if (property === "color" && isProgressFill(declaration[kElement])) {
-		const accent = declaration[kComputedValue]("accent-color");
-		if (accent !== "" && accent.toLowerCase() !== "auto") {
-			return accent;
-		}
-	}
 	const value = resolveCascadedValue(declaration, property);
 	if (property === "font-weight") {
 		return computeFontWeight(declaration[kElement], value);
@@ -7096,19 +7077,34 @@ function unescapeHighlightName(pseudoElement: string): string {
 
 // The pseudo-elements a page styles a built-in control's parts through,
 // by the part names its UA shadow tree gives them. Author shadow trees
-// are not eligible: their parts are theirs to style from inside.
-const PART_PSEUDOS: Readonly<Record<string, Readonly<Record<string, string>>>> =
-	{
-		"*": {
-			placeholder: "::placeholder",
-			selection: "::selection",
-			"details-content": "::details-content",
-		},
-		SELECT: {picker: "::picker(select)", indicator: "::picker-icon"},
-	};
+// are not eligible: their parts are theirs to style from inside. A gauge
+// takes css-forms-1's names, and the prefixed names WebKit and Firefox
+// ship as aliases, as css-forms-1 §4.10 asks.
+const PART_PSEUDOS: Readonly<Record<
+	string,
+	Readonly<Record<string, readonly string[]>>
+>> = {
+	"*": {
+		placeholder: ["::placeholder"],
+		selection: ["::selection"],
+		"details-content": ["::details-content"],
+	},
+	SELECT: {picker: ["::picker(select)"], indicator: ["::picker-icon"]},
+	PROGRESS: {
+		track: ["::slider-track", "::-webkit-progress-bar"],
+		bar: ["::slider-fill", "::-webkit-progress-value", "::-moz-progress-bar"],
+	},
+	METER: {
+		track: ["::slider-track", "::-webkit-meter-bar"],
+		bar: ["::slider-fill", "::-moz-meter-bar"],
+		optimum: ["::-webkit-meter-optimum-value"],
+		suboptimum: ["::-webkit-meter-suboptimum-value"],
+		"even-less-good": ["::-webkit-meter-even-less-good-value"],
+	},
+};
 
 const PART_PSEUDO_NAMES = new Set(
-	Object.values(PART_PSEUDOS).flatMap((names) => Object.values(names)),
+	Object.values(PART_PSEUDOS).flatMap((names) => Object.values(names).flat()),
 );
 
 // True for a pseudo-element the tree needs a node of its own for. The
@@ -9613,10 +9609,9 @@ function getPartPseudos(element: Element, root: Node): string[] {
 	const host = (root as unknown as ShadowRoot).host.tagName;
 	const pseudos: string[] = [];
 	for (const name of part.split(/\s+/)) {
-		const pseudo = PART_PSEUDOS["*"][name] ?? PART_PSEUDOS[host]?.[name];
-		if (pseudo !== undefined) {
-			pseudos.push(pseudo);
-		}
+		pseudos.push(
+			...(PART_PSEUDOS["*"][name] ?? PART_PSEUDOS[host]?.[name] ?? []),
+		);
 	}
 	return pseudos;
 }
diff --git a/src/internal/cssselectors.ts b/src/internal/cssselectors.ts
index 91ad2cc39..fcdb0762c 100644
--- a/src/internal/cssselectors.ts
+++ b/src/internal/cssselectors.ts
@@ -7,6 +7,7 @@ import {
 	getElementChildren,
 	getFirstChildNode,
 	getHeadingLevel,
+	getMeterLevel,
 	getNextSiblingNode,
 	getOpenAssignedSlot,
 	getParentNode,
@@ -34,6 +35,7 @@ import {
 	isHTMLNode,
 	isIndeterminateControl,
 	isInQuirksMode,
+	isMeterValue,
 	isModalDialog,
 	isOpenElement,
 	isPlaceholderShown,
@@ -65,6 +67,9 @@ import {splitOnASCIIWhitespace, toASCIILowercase} from "./text.ts";
 // A selector naming anything else does not parse, which makes
 // `:gibberish` invalid rather than merely unmatched.
 const PSEUDO_CLASSES: ReadonlySet<string> = new Set([
+	"-moz-meter-optimum",
+	"-moz-meter-sub-optimum",
+	"-moz-meter-sub-sub-optimum",
 	"active",
 	"any-link",
 	"autofill",
@@ -93,6 +98,7 @@ const PSEUDO_CLASSES: ReadonlySet<string> = new Set([
 	"host-context",
 	"hover",
 	"in-range",
+	"high-value",
 	"indeterminate",
 	"invalid",
 	"is",
@@ -100,6 +106,7 @@ const PSEUDO_CLASSES: ReadonlySet<string> = new Set([
 	"last-child",
 	"last-of-type",
 	"left",
+	"low-value",
 	"link",
 	"local-link",
 	"modal",
@@ -114,6 +121,7 @@ const PSEUDO_CLASSES: ReadonlySet<string> = new Set([
 	"only-child",
 	"only-of-type",
 	"open",
+	"optimal-value",
 	"optional",
 	"out-of-range",
 	"past",
@@ -144,6 +152,14 @@ const PSEUDO_CLASSES: ReadonlySet<string> = new Set([
 ]);
 
 const PSEUDO_ELEMENTS: ReadonlySet<string> = new Set([
+	"-moz-meter-bar",
+	"-moz-progress-bar",
+	"-webkit-meter-bar",
+	"-webkit-meter-even-less-good-value",
+	"-webkit-meter-optimum-value",
+	"-webkit-meter-suboptimum-value",
+	"-webkit-progress-bar",
+	"-webkit-progress-value",
 	"after",
 	"backdrop",
 	"before",
@@ -166,6 +182,9 @@ const PSEUDO_ELEMENTS: ReadonlySet<string> = new Set([
 	"scroll-marker",
 	"scroll-marker-group",
 	"selection",
+	"slider-fill",
+	"slider-thumb",
+	"slider-track",
 	"slotted",
 	"spelling-error",
 	"target-text",
@@ -203,6 +222,9 @@ export function isLegacyPseudoElement(name: string): boolean {
 }
 
 const ARGUMENTLESS_PSEUDO_CLASSES: ReadonlySet<string> = new Set([
+	"-moz-meter-optimum",
+	"-moz-meter-sub-optimum",
+	"-moz-meter-sub-sub-optimum",
 	"active",
 	"any-link",
 	"autofill",
@@ -226,11 +248,13 @@ const ARGUMENTLESS_PSEUDO_CLASSES: ReadonlySet<string> = new Set([
 	"future",
 	"hover",
 	"in-range",
+	"high-value",
 	"indeterminate",
 	"invalid",
 	"last-child",
 	"last-of-type",
 	"left",
+	"low-value",
 	"link",
 	"local-link",
 	"modal",
@@ -238,6 +262,7 @@ const ARGUMENTLESS_PSEUDO_CLASSES: ReadonlySet<string> = new Set([
 	"only-child",
 	"only-of-type",
 	"open",
+	"optimal-value",
 	"optional",
 	"out-of-range",
 	"past",
@@ -1165,6 +1190,24 @@ function compilePseudoClass(
 		case "indeterminate":
 			compound.tests.push((element) => isIndeterminateControl(element));
 			return;
+		case "low-value":
+			compound.tests.push((element) => isMeterValue(element, "low"));
+			return;
+		case "high-value":
+			compound.tests.push((element) => isMeterValue(element, "high"));
+			return;
+		case "optimal-value":
+		case "-moz-meter-optimum":
+			compound.tests.push((element) => getMeterLevel(element) === "optimum");
+			return;
+		case "-moz-meter-sub-optimum":
+			compound.tests.push((element) => getMeterLevel(element) === "suboptimum");
+			return;
+		case "-moz-meter-sub-sub-optimum":
+			compound.tests.push(
+				(element) => getMeterLevel(element) === "even-less-good",
+			);
+			return;
 		case "placeholder-shown":
 			compound.tests.push((element) => isPlaceholderShown(element));
 			return;
diff --git a/src/internal/cssvalues.ts b/src/internal/cssvalues.ts
index 080905bbf..d1127a644 100644
--- a/src/internal/cssvalues.ts
+++ b/src/internal/cssvalues.ts
@@ -4291,9 +4291,13 @@ function getSelectorSpecificity(selector: CSSTree.SelectorNode): Specificity {
 // descendants when the attribute behind it changes, and no attribute
 // NAME in the selector reveals that.
 const STATE_PSEUDO_CLASSES = new Set([
+	"-moz-meter-optimum",
+	"-moz-meter-sub-optimum",
+	"-moz-meter-sub-sub-optimum",
 	"any-link",
 	"checked",
 	"heading",
+	"high-value",
 	"closed",
 	"default",
 	"defined",
@@ -4303,7 +4307,9 @@ const STATE_PSEUDO_CLASSES = new Set([
 	"indeterminate",
 	"invalid",
 	"link",
+	"low-value",
 	"open",
+	"optimal-value",
 	"optional",
 	"out-of-range",
 	"placeholder-shown",
@@ -4322,12 +4328,15 @@ const STATE_ATTRIBUTES = new Set([
 	"disabled",
 	"headingoffset",
 	"headingreset",
+	"high",
 	"href",
 	"id",
+	"low",
 	"max",
 	"min",
 	"multiple",
 	"open",
+	"optimum",
 	"pattern",
 	"placeholder",
 	"popover",
diff --git a/src/internal/dom.ts b/src/internal/dom.ts
index 0b5e80e19..b35cbbf66 100644
--- a/src/internal/dom.ts
+++ b/src/internal/dom.ts
@@ -18935,7 +18935,7 @@ class HTMLMeterElement extends HTMLElement {
 		const min = this.min;
 		const span = this.max - min;
 		setGaugeFill(bar, span > 0 ? (this.value - min) / span : 0);
-		const barLevel = getMeterLevel(this);
+		const barLevel = getMeterLevel(this)!;
 		const part = `bar ${barLevel}`;
 		if (bar.getAttribute("part") !== part) {
 			bar.setAttribute("part", part);
@@ -18959,8 +18959,11 @@ class HTMLMeterElement extends HTMLElement {
 // where `optimum` sits relative to `low` and `high`. A value in that
 // region is optimum, one region away is suboptimum, and two away is even
 // less good.
-function getMeterLevel(meter: HTMLMeterElement): string {
-	const {low, high, optimum, value} = meter;
+export function getMeterLevel(element: Element): string | null {
+	if (!(element instanceof HTMLMeterElement)) {
+		return null;
+	}
+	const {low, high, optimum, value} = element;
 	if (optimum < low) {
 		if (value < low) {
 			return "optimum";
@@ -18976,6 +18979,19 @@ function getMeterLevel(meter: HTMLMeterElement): string {
 	return value >= low && value <= high ? "optimum" : "suboptimum";
 }
 
+/** css-forms-1's :low-value and :high-value: a meter past a threshold. */
+export function isMeterValue(
+	element: Element,
+	threshold: "low" | "high",
+): boolean {
+	if (!(element instanceof HTMLMeterElement)) {
+		return false;
+	}
+	return threshold === "low"
+		? element.value < element.low
+		: element.value > element.high;
+}
+
 class HTMLModElement extends HTMLElement {
 	declare cite: globalThis.HTMLModElement["cite"];
 	declare dateTime: globalThis.HTMLModElement["dateTime"];
diff --git a/src/internal/useragent.ts b/src/internal/useragent.ts
index 2cf05ab95..40979131d 100644
--- a/src/internal/useragent.ts
+++ b/src/internal/useragent.ts
@@ -157,9 +157,10 @@ export const UA_DOCUMENT_STYLES = `
 `;
 
 // The insides of the built-in controls. A page reaches the ones a browser
-// lets it, through ::placeholder, ::picker(select), ::picker-icon and
-// ::details-content. The rest are this sheet's alone, through ::part(),
-// which reaches no page's rules into a built-in control.
+// lets it, through ::placeholder, ::picker(select), ::picker-icon,
+// ::details-content, and a gauge's ::slider-track and ::slider-fill with
+// their prefixed aliases. The rest are this sheet's alone, through
+// ::part(), which reaches no page's rules into a built-in control.
 //
 // A text field's value and placeholder clip their text, and the render
 // loop sets scrollLeft to follow the caret. A textarea's value text node
@@ -172,7 +173,8 @@ export const UA_DOCUMENT_STYLES = `
 //
 // A gauge's bar is as wide as the fraction filled. The groove follows it
 // in the same clip, so an empty bar still reads as a bar, and an
-// indeterminate progress bar shows only the groove. A meter's bar also
+// indeterminate progress bar shows only the groove. The groove takes the
+// track's color, so ::slider-track colors it. A meter's bar also
 // has the part name of its level against low, high and optimum, so the
 // color is a rule and not a choice the painter makes.
 //
@@ -188,8 +190,8 @@ export const UA_CONTROL_STYLES = `
 
 	details::details-content { display: block; }
 
-	meter::part(track), progress::part(track) { display: inline-block; width: 100%; overflow: hidden; white-space: pre; vertical-align: top; }
-	meter::part(groove), progress::part(groove) { color: #808080; font-weight: lighter; }
+	meter::part(track), progress::part(track) { display: inline-block; width: 100%; overflow: hidden; white-space: pre; vertical-align: top; color: #808080; }
+	meter::part(groove), progress::part(groove) { font-weight: lighter; }
 	meter::part(bar), progress::part(bar) { display: inline-block; overflow: hidden; white-space: pre; vertical-align: top; }
 	progress::part(bar) { color: #5fafff; }
 	meter::part(bar optimum) { color: #5faf5f; }
diff --git a/tests/widgets.test.ts b/tests/widgets.test.ts
index b64927514..a9b6851f7 100644
--- a/tests/widgets.test.ts
+++ b/tests/widgets.test.ts
@@ -495,24 +495,99 @@ test("a control's insides follow a change to what they inherit", async () => {
 	dom.dispose();
 });
 
-test("a progress bar's fill takes its accent-color", async () => {
+test("a progress bar's accent-color leaves its fill alone", async () => {
 	const terminal = new MockProcess({rows: 4, cols: 40});
 	const dom = new TermDOM({transport: terminal.transport});
 	dom.document.body.innerHTML =
-		"<style>.done { accent-color: #00ff00; }</style>" +
-		"<progress class=\"done\" max=\"10\" value=\"10\"></progress>";
+		"<progress style=\"accent-color: #00ff00\" max=\"10\" value=\"10\">" +
+		"</progress>";
 	await nextFrame(dom);
-	expect(terminal.getStaticANSI()).toContain("38;2;0;255;0");
-	dom.document.querySelector("progress")!.style.accentColor = "#ff00ff";
+	expect(terminal.getStaticANSI()).toContain("38;2;95;175;255");
+	dom.dispose();
+});
+
+async function gaugeANSI(html: string): Promise<string> {
+	const terminal = new MockProcess({rows: 4, cols: 40});
+	const dom = new TermDOM({transport: terminal.transport});
+	dom.document.body.innerHTML = html;
+	await nextFrame(dom);
+	const ansi = terminal.getStaticANSI();
+	dom.dispose();
+	return ansi;
+}
+
+test("a page colors a gauge through ::slider-fill and ::slider-track", async () => {
+	const ansi = await gaugeANSI(
+		"<style>" +
+		"progress::slider-fill { color: #010203; }" +
+		"progress::slider-track { color: #040506; }" +
+		"</style>" +
+		"<progress max=\"10\" value=\"5\"></progress>",
+	);
+	expect(ansi).toContain("38;2;1;2;3");
+	expect(ansi).toContain("38;2;4;5;6");
+	expect(ansi).not.toContain("38;2;95;175;255");
+});
+
+test("a meter's levels match :optimal-value, :low-value and :high-value", async () => {
+	const ansi = await gaugeANSI(
+		"<style>" +
+		"meter:optimal-value::slider-fill { color: #000001; }" +
+		"meter:low-value::slider-fill { color: #000002; }" +
+		"meter:high-value::slider-fill { color: #000003; }" +
+		"</style>" +
+		"<meter low=\"3\" high=\"7\" optimum=\"5\" max=\"10\" value=\"5\"></meter>" +
+		"<br><meter low=\"3\" high=\"7\" optimum=\"5\" max=\"10\" value=\"1\"></meter>" +
+		"<br><meter low=\"3\" high=\"7\" optimum=\"5\" max=\"10\" value=\"9\"></meter>",
+	);
+	expect(ansi).toContain("38;2;0;0;1");
+	expect(ansi).toContain("38;2;0;0;2");
+	expect(ansi).toContain("38;2;0;0;3");
+});
+
+test("a meter's level pseudo-classes follow its attributes", async () => {
+	const terminal = new MockProcess({rows: 4, cols: 40});
+	const dom = new TermDOM({transport: terminal.transport});
+	dom.document.body.innerHTML =
+		"<style>meter:low-value::slider-fill { color: #000002; }</style>" +
+		"<meter low=\"3\" high=\"7\" max=\"10\" value=\"5\"></meter>";
 	await nextFrame(dom);
-	expect(terminal.getStaticANSI()).toContain("38;2;255;0;255");
-	dom.document.querySelector("progress")!.style.accentColor = "auto";
-	dom.document.querySelector("progress")!.className = "";
+	expect(terminal.getStaticANSI()).not.toContain("38;2;0;0;2");
+	expect(dom.document.querySelector("meter:low-value")).toBeNull();
+	dom.document.querySelector("meter")!.setAttribute("low", "6");
 	await nextFrame(dom);
-	expect(terminal.getStaticANSI()).toContain("38;2;95;175;255");
+	expect(terminal.getStaticANSI()).toContain("38;2;0;0;2");
+	expect(dom.document.querySelector("meter:low-value")).not.toBeNull();
 	dom.dispose();
 });
 
+test("WebKit's and Firefox's gauge pseudo-elements are aliases", async () => {
+	const webkit = await gaugeANSI(
+		"<style>" +
+		"progress::-webkit-progress-value { color: #000004; }" +
+		"progress::-webkit-progress-bar { color: #000005; }" +
+		"meter::-webkit-meter-optimum-value { color: #000006; }" +
+		"meter::-webkit-meter-even-less-good-value { color: #000007; }" +
+		"</style>" +
+		"<progress max=\"10\" value=\"5\"></progress>" +
+		"<br><meter low=\"3\" high=\"7\" optimum=\"9\" max=\"10\" value=\"9\"></meter>" +
+		"<br><meter low=\"3\" high=\"7\" optimum=\"9\" max=\"10\" value=\"1\"></meter>",
+	);
+	for (const color of ["0;0;4", "0;0;5", "0;0;6", "0;0;7"]) {
+		expect(webkit).toContain(`38;2;${color}`);
+	}
+	const firefox = await gaugeANSI(
+		"<style>" +
+		"progress::-moz-progress-bar { color: #000008; }" +
+		"meter:-moz-meter-sub-optimum::-moz-meter-bar { color: #000009; }" +
+		"</style>" +
+		"<progress max=\"10\" value=\"5\"></progress>" +
+		"<br><meter low=\"3\" high=\"7\" optimum=\"9\" max=\"10\" value=\"5\"></meter>",
+	);
+	expect(firefox).toContain("38;2;0;0;8");
+	expect(firefox).toContain("38;2;0;0;9");
+});
+
 test("a page styles a select's icon through ::picker-icon", async () => {
 	const terminal = new MockProcess({rows: 4, cols: 40});
 	const dom = new TermDOM({transport: terminal.transport});

From 989f0384a2d5ee20524b2743fff5cb171f5788fe Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 12:05:46 -0400
Subject: [PATCH 04/24] Give both canvas contexts a direction, and round the
 cell grid's getCell

The cell grid gains the 2d context's direction: ltr, rtl, or inherit,
the default, which takes the canvas element's direction as the text is
drawn. Right-to-left text is put in display order, as the layout does
for a page's text, and start and end follow it. textAlign defaults to
start, as a 2d context's does.

The 2d context's inherit was read as ltr and its text was written in
logical order; it now resolves and orders the same way.

getCell rounds its coordinates, as every drawing method does, so a
fractional coordinate reads the cell it was drawn to.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/guides/07-images-and-canvas.md |  9 +++-
 src/internal/canvas.ts              | 68 ++++++++++++++++++++++++-----
 src/internal/dom.ts                 |  7 +++
 tests/canvas.test.ts                | 59 +++++++++++++++++++++++++
 4 files changed, 131 insertions(+), 12 deletions(-)

diff --git a/docs/guides/07-images-and-canvas.md b/docs/guides/07-images-and-canvas.md
index fe0e93300..3c4fec7fa 100644
--- a/docs/guides/07-images-and-canvas.md
+++ b/docs/guides/07-images-and-canvas.md
@@ -260,7 +260,8 @@ shows like an image. It implements:
 
 A terminal has no fonts to rasterize, so `fillText()` and
 `strokeText()` draw text as cells over the pixels, at the cell the text
-anchor falls in, with `textAlign` and `textBaseline` applied. Painting
+anchor falls in, with `textAlign`, `textBaseline` and `direction`
+applied. Painting
 over the anchor paints over the text. `measureText()` counts a cell's
 width in pixels for each column. Shadows and `filter` keep their values
 but draw nothing.
@@ -307,6 +308,9 @@ grid.strokeRect(0, 0, 20, 3);
 document.body.append(canvas);
 ```
 
+Coordinates are cells, and fractional ones round to the nearest cell,
+in every method.
+
 Lines are box-drawing glyphs. Where two meet they join in a corner, a
 tee or a cross, as borders do. A canvas's lines join each other but
 not the page's borders around the canvas.
@@ -318,7 +322,8 @@ not the page's borders around the canvas.
 | `lineStyle` | A CSS `border-style`: `solid`, the default, `double`, `dashed`, `dotted` and the rest |
 | `lineJoin` | `miter`, the default, or `round`, which curves `strokeRect()`'s corners |
 | `font` | Keywords from the CSS `font` shorthand: `bold`, `italic`, `lighter` |
-| `textAlign` | `left`, `right`, `center`, `start` or `end` |
+| `textAlign` | `start`, the default, `end`, `left`, `right` or `center` |
+| `direction` | `inherit`, the default, which takes the canvas element's CSS `direction`, or `ltr` or `rtl`. Right-to-left text is drawn in display order, and it decides which side `start` and `end` are |
 | `textDecoration` | `none`, or `underline` and `line-through`, alone or together |
 | `fillText(text, x, y, maxWidth?)` | Writes glyphs in the fill color, over the cells' backgrounds. A wide glyph takes two columns |
 | `fillRect(x, y, w, h)` | Fills cells with the fill color as their background. `currentcolor` fills them in inverse video |
diff --git a/src/internal/canvas.ts b/src/internal/canvas.ts
index 82158a267..98f876ed2 100644
--- a/src/internal/canvas.ts
+++ b/src/internal/canvas.ts
@@ -30,7 +30,7 @@ import {
 	naturalWidthOf,
 	sampleBitmap,
 } from "./images.ts";
-import {getStringWidth, graphemeSegmenter} from "./text.ts";
+import {getStringWidth, graphemeSegmenter, toVisualOrder} from "./text.ts";
 
 // ---------------------------------------------------------------------------
 // What drawImage() and createPattern() take.
@@ -1717,6 +1717,8 @@ interface CanvasHost {
 	changed(): void;
 	// Bitmap pixels per cell, as the canvas is shown, for measureText().
 	pixelsPerCell(): {x: number; y: number};
+	// The canvas element's own direction, which "inherit" takes.
+	direction(): "ltr" | "rtl";
 }
 
 const kHost = Symbol("host");
@@ -2874,7 +2876,11 @@ export class CanvasRenderingContext2D {
 		if (color === null || color.a * this[kState].globalAlpha === 0) {
 			return;
 		}
-		const rtl = this[kState].direction === "rtl";
+		// "inherit" takes the canvas's direction as the text is drawn.
+		const direction = this[kState].direction === "inherit"
+			? this[kHost].direction()
+			: this[kState].direction;
+		const rtl = direction === "rtl";
 		const align = this[kState].textAlign;
 		const resolved = align === "center"
 			? "center"
@@ -2885,7 +2891,10 @@ export class CanvasRenderingContext2D {
 				: "left";
 		const words = this[kState].font.toLowerCase().split(/\s+/);
 		const run: CanvasTextRun = {
-			text: text.replace(/[\t\n\f\r]/g, " "),
+			text: toVisualOrder(
+				text.replace(/[\t\n\f\r]/g, " "),
+				rtl ? "rtl" : "ltr",
+			),
 			x: px,
 			y: py,
 			align: resolved,
@@ -2948,6 +2957,8 @@ interface GridHost {
 	// The canvas's cells, `width` columns by `height` rows.
 	cells(): CellContext;
 	changed(): void;
+	// The canvas element's own direction, which "inherit" takes.
+	direction(): "ltr" | "rtl";
 	// Terminal pixels per cell, for drawing images at their natural size.
 	cellPixels(): {width: number; height: number};
 }
@@ -2961,6 +2972,8 @@ const kLineJoin = Symbol("lineJoin");
 const kFont = Symbol("font");
 const kTextAlign = Symbol("textAlign");
 const kTextDecoration = Symbol("textDecoration");
+const kGridDirection = Symbol("direction");
+const kResolveDirection = Symbol("resolveDirection");
 const kRect = Symbol("rect");
 
 export interface CanvasCellGridContext {
@@ -2972,6 +2985,7 @@ export interface CanvasCellGridContext {
 	[kFont]: string;
 	[kTextAlign]: "start" | "end" | "left" | "right" | "center";
 	[kTextDecoration]: string;
+	[kGridDirection]: "ltr" | "rtl" | "inherit";
 }
 
 /**
@@ -2991,8 +3005,9 @@ export class CanvasCellGridContext {
 		this[kLineStyle] = "solid";
 		this[kLineJoin] = "miter";
 		this[kFont] = "";
-		this[kTextAlign] = "left";
+		this[kTextAlign] = "start";
 		this[kTextDecoration] = "none";
+		this[kGridDirection] = "inherit";
 	}
 
 	get canvas(): HTMLCanvasElement {
@@ -3063,6 +3078,21 @@ export class CanvasCellGridContext {
 		}
 	}
 
+	/**
+	 * ltr, rtl, or inherit, the default, which takes the canvas element's
+	 * direction as the text is drawn. It orders right-to-left text for
+	 * display and decides which side start and end are.
+	 */
+	get direction(): "ltr" | "rtl" | "inherit" {
+		return this[kGridDirection];
+	}
+
+	set direction(value: string) {
+		if (value === "ltr" || value === "rtl" || value === "inherit") {
+			this[kGridDirection] = value;
+		}
+	}
+
 	/** none, or underline and line-through, alone or together. */
 	get textDecoration(): string {
 		return this[kTextDecoration];
@@ -3121,8 +3151,14 @@ export class CanvasCellGridContext {
 			return;
 		}
 		const cells = this[kGridHost].cells();
+		const rtl = this[kResolveDirection]() === "rtl";
 		const clusters = [
-			...graphemeSegmenter.segment(String(text).replace(/[\t\n\f\r]/g, " ")),
+			...graphemeSegmenter.segment(
+				toVisualOrder(
+					String(text).replace(/[\t\n\f\r]/g, " "),
+					rtl ? "rtl" : "ltr",
+				),
+			),
 		]
 			.map((segment) => segment.segment)
 			.filter((cluster) => getStringWidth(cluster) > 0);
@@ -3134,7 +3170,11 @@ export class CanvasCellGridContext {
 		const align = this[kTextAlign];
 		if (align === "center") {
 			col -= Math.floor(width / 2);
-		} else if (align === "right" || align === "end") {
+		} else if (
+			align === "right" ||
+			(align === "end" && !rtl) ||
+			(align === "start" && rtl)
+		) {
 			col -= width;
 		}
 		const row = Math.round(y);
@@ -3238,7 +3278,8 @@ export class CanvasCellGridContext {
 	}
 
 	measureText(text: string): {width: number} {
-		return this[kGridHost].cells().measureText(String(text));
+		return this[kGridHost].cells()
+			.measureText(toVisualOrder(String(text), this[kResolveDirection]()));
 	}
 
 	/**
@@ -3336,8 +3377,8 @@ export class CanvasCellGridContext {
 		inverse: boolean;
 	} | null {
 		const {grid, cols, rows} = this[kGridHost].cells();
-		const col = Math.floor(x);
-		const row = Math.floor(y);
+		const col = Math.round(x);
+		const row = Math.round(y);
 		if (col < 0 || row < 0 || col >= cols || row >= rows) {
 			return null;
 		}
@@ -3377,11 +3418,18 @@ export class CanvasCellGridContext {
 		this[kLineStyle] = "solid";
 		this[kLineJoin] = "miter";
 		this[kFont] = "";
-		this[kTextAlign] = "left";
+		this[kTextAlign] = "start";
 		this[kTextDecoration] = "none";
+		this[kGridDirection] = "inherit";
 		this[kGridHost].changed();
 	}
 
+	[kResolveDirection](): "ltr" | "rtl" {
+		return this[kGridDirection] === "inherit"
+			? this[kGridHost].direction()
+			: this[kGridDirection];
+	}
+
 	[kRect](
 		x: number,
 		y: number,
diff --git a/src/internal/dom.ts b/src/internal/dom.ts
index b35cbbf66..cfddde8bf 100644
--- a/src/internal/dom.ts
+++ b/src/internal/dom.ts
@@ -14542,6 +14542,7 @@ class HTMLCanvasElement extends HTMLElement {
 				canvas: this,
 				bitmap: () => getCanvasBitmap(this),
 				changed,
+				direction: () => getCanvasDirection(this),
 				pixelsPerCell: () => {
 					const attached = getAttachedDocument(this);
 					const rect = attached?.[kLayout].contentRect(this);
@@ -14558,6 +14559,7 @@ class HTMLCanvasElement extends HTMLElement {
 				cells: () => getCanvasGrid(this),
 				changed,
 				cellPixels: () => getImageCellSize(this as unknown as Node),
+				direction: () => getCanvasDirection(this),
 			});
 			// The natural size is now in cells, not pixels.
 			invalidateReplaced(this, true);
@@ -18781,6 +18783,11 @@ function getGaugeGlyphs(host: Element, glyph: string): string {
 	);
 }
 
+// What a canvas context's "inherit" direction resolves to.
+function getCanvasDirection(canvas: Element): "ltr" | "rtl" {
+	return getComputedValue(canvas, "direction") === "rtl" ? "rtl" : "ltr";
+}
+
 // A full-width track that clips, holding a bar whose width is the
 // fraction filled and the groove that shows past it.
 function buildGaugeRoot(
diff --git a/tests/canvas.test.ts b/tests/canvas.test.ts
index 3fd0c05a2..142e81fe2 100644
--- a/tests/canvas.test.ts
+++ b/tests/canvas.test.ts
@@ -562,6 +562,27 @@ test("textAlign centers and right-aligns text on its anchor", async () => {
 	dom.dispose();
 });
 
+test("a 2d context's start follows the canvas's direction, and rtl text draws in visual order", async () => {
+	const {dom, terminal, document} = await mount(
+		"<canvas id=c width=160 height=48 style=\"direction: rtl\"></canvas>",
+	);
+	const ctx = context2d(document);
+	ctx.fillStyle = "#ffffff";
+	ctx.textBaseline = "top";
+	expect(ctx.direction).toBe("inherit");
+	ctx.fillText("end", 160, 0);
+	ctx.direction = "ltr";
+	ctx.fillText("ltr", 0, 16);
+	ctx.direction = "rtl";
+	ctx.textAlign = "left";
+	ctx.fillText("\u05e9\u05dc\u05d5\u05dd!", 0, 32);
+	await nextFrame(dom);
+	expect(rowText(terminal, 0).indexOf("end")).toBe(17);
+	expect(rowText(terminal, 1).indexOf("ltr")).toBe(0);
+	expect(rowText(terminal, 2).trim()).toBe("!\u05dd\u05d5\u05dc\u05e9");
+	dom.dispose();
+});
+
 test("createImageBitmap copies a canvas, and the copy draws", async () => {
 	const {dom, document} =
 		await mount("<canvas id=c width=4 height=4></canvas>");
@@ -686,6 +707,44 @@ test("textDecoration draws underline and line-through, and getCell reads them ba
 	dom.dispose();
 });
 
+test("a cell grid mirrors a 2d context's direction", async () => {
+	const {dom, document} = await mount(
+		"<canvas id=g width=8 height=3 style=\"direction: rtl\"></canvas>",
+	);
+	const ctx = grid(document);
+	expect([ctx.direction, ctx.textAlign]).toEqual(["inherit", "start"]);
+	ctx.fillText("ab", 8, 0);
+	expect(ctx.getCell(6, 0)!.char).toBe("a");
+	ctx.direction = "ltr";
+	ctx.fillText("cd", 0, 1);
+	expect(ctx.getCell(0, 1)!.char).toBe("c");
+	ctx.textAlign = "end";
+	ctx.fillText("e", 8, 1);
+	expect(ctx.getCell(7, 1)!.char).toBe("e");
+	ctx.direction = "rtl";
+	ctx.textAlign = "left";
+	ctx.fillText("\u05e9\u05dc\u05d5\u05dd!", 0, 2);
+	expect([0, 1, 2, 3, 4].map((x) => ctx.getCell(x, 2)!.char).join("")).toBe(
+		"!\u05dd\u05d5\u05dc\u05e9",
+	);
+	ctx.direction = "sideways";
+	expect(ctx.direction).toBe("rtl");
+	ctx.reset();
+	expect(ctx.direction).toBe("inherit");
+	dom.dispose();
+});
+
+test("a cell grid rounds every coordinate, getCell's too", async () => {
+	const {dom, document} =
+		await mount("<canvas id=g width=6 height=2></canvas>");
+	const ctx = grid(document);
+	ctx.fillText("x", 2.5, 0.4);
+	expect(ctx.getCell(3, 0)!.char).toBe("x");
+	expect(ctx.getCell(2.5, 0.4)!.char).toBe("x");
+	expect(ctx.getCell(2.4, 0)).toBeNull();
+	dom.dispose();
+});
+
 test("text that runs past the grid is cut, and wide glyphs take two columns", async () => {
 	const {dom, terminal, document} =
 		await mount("<canvas id=g width=6 height=1></canvas>|");

From d7224199ce467ae24aa2ba7b65289e5a420d5a05 Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 12:16:44 -0400
Subject: [PATCH 05/24] Make the cell grid's settings behave as a 2d context's

- fillStyle and strokeStyle read back serialized as a 2d context's do.
  currentcolor is the canvas element's color as it is set, and the
  defaults are CanvasText, the terminal's own text color; Canvas is its
  background. A translucent fill blends over the cell, and text under
  half opaque draws nothing, as a 2d context's text does.
- font is a CSS font shorthand, parsed, serialized and ignored when
  invalid, and its weight and style make text bold, dim or italic. The
  2d context's font validates the same way.
- save(), restore() and isContextLost().
- maxWidth of zero, less or NaN draws nothing.
- lineJoin takes bevel, drawn as a miter, and lineStyle takes none.
- drawImage normalizes a negative destination size.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/guides/07-images-and-canvas.md |  18 +-
 examples/canvas.ts                  |   6 +-
 src/internal/canvas.ts              | 297 +++++++++++++++++++---------
 src/internal/cssvalues.ts           |  38 ++++
 src/internal/dom.ts                 |   1 +
 tests/canvas.test.ts                | 121 +++++++++++-
 6 files changed, 368 insertions(+), 113 deletions(-)

diff --git a/docs/guides/07-images-and-canvas.md b/docs/guides/07-images-and-canvas.md
index 3c4fec7fa..8c4f0915a 100644
--- a/docs/guides/07-images-and-canvas.md
+++ b/docs/guides/07-images-and-canvas.md
@@ -300,7 +300,7 @@ const grid = canvas.getContext("termdom-cellgrid")!;
 grid.fillStyle = "#003366";
 grid.fillRect(0, 0, 20, 3);
 grid.fillStyle = "#ffcc00";
-grid.font = "bold";
+grid.font = "bold 1px monospace";
 grid.fillText("score: 42", 1, 1);
 grid.strokeStyle = "#5fafff";
 grid.lineJoin = "round";
@@ -317,23 +317,25 @@ not the page's borders around the canvas.
 
 | Member | What it does |
 | --- | --- |
-| `fillStyle` | A CSS color. `currentcolor`, the default, is the terminal's foreground |
+| `fillStyle` | A CSS color, read back as a 2D context reads it. `CanvasText`, the default, is the terminal's own text color and `Canvas` its background. `currentcolor` is the canvas element's `color` when it is set. A translucent fill blends over the cell; text under half opaque draws nothing |
 | `strokeStyle` | The lines' color, the same way |
-| `lineStyle` | A CSS `border-style`: `solid`, the default, `double`, `dashed`, `dotted` and the rest |
-| `lineJoin` | `miter`, the default, or `round`, which curves `strokeRect()`'s corners |
-| `font` | Keywords from the CSS `font` shorthand: `bold`, `italic`, `lighter` |
+| `lineStyle` | A CSS `border-style`: `solid`, the default, `double`, `dashed`, `dotted`, `none` and the rest |
+| `lineJoin` | `miter`, the default, `round`, which curves `strokeRect()`'s corners, or `bevel`, which draws as `miter` |
+| `font` | A CSS `font` shorthand, as a 2D context takes it, such as `"bold 1px monospace"`. Its weight and style make text bold, dim or italic; a cell has no size or family to change. A value the shorthand rejects is ignored |
 | `textAlign` | `start`, the default, `end`, `left`, `right` or `center` |
 | `direction` | `inherit`, the default, which takes the canvas element's CSS `direction`, or `ltr` or `rtl`. Right-to-left text is drawn in display order, and it decides which side `start` and `end` are |
 | `textDecoration` | `none`, or `underline` and `line-through`, alone or together |
-| `fillText(text, x, y, maxWidth?)` | Writes glyphs in the fill color, over the cells' backgrounds. A wide glyph takes two columns |
-| `fillRect(x, y, w, h)` | Fills cells with the fill color as their background. `currentcolor` fills them in inverse video |
+| `save()`, `restore()` | Push and pop the settings above, as a 2D context does |
+| `fillText(text, x, y, maxWidth?)` | Writes glyphs in the fill color, over the cells' backgrounds. A wide glyph takes two columns. Text past `maxWidth` columns is cut, and a `maxWidth` of zero, less, or `NaN` draws nothing |
+| `fillRect(x, y, w, h)` | Fills cells with the fill color as their background. `CanvasText` fills them in inverse video |
 | `clearRect(x, y, w, h)` | Empties cells |
 | `strokeLine(x1, y1, x2, y2)` | A line from one cell to another, both included, along a row or a column. A slanted line draws nothing |
 | `strokeRect(x, y, w, h)` | A box around the cells `w` by `h` from (x, y) |
 | `drawImage(image, ...)` | Draws an image's pixels, two to a cell. Without a size, the image takes its natural size in cells |
 | `getCell(x, y)` | The cell's `char`, `color` and `background`, and whether it is `bold`, `italic`, `dim`, `underline`, `strikethrough` or `inverse`; `null` for an empty cell |
 | `measureText(text)` | The text's width in columns |
-| `reset()` | Clears the grid and the settings |
+| `reset()` | Clears the grid, the settings and the saved settings |
+| `isContextLost()` | Always `false` |
 
 ## Text alone
 
diff --git a/examples/canvas.ts b/examples/canvas.ts
index eb0eb3f3a..534fc231c 100644
--- a/examples/canvas.ts
+++ b/examples/canvas.ts
@@ -138,12 +138,12 @@ function frame(): void {
       }
     }
   }
+  grid.save();
   grid.fillStyle = "#e5c07b";
-  grid.font = "bold";
+  grid.font = "bold 1px monospace";
   grid.textAlign = "right";
   grid.fillText(`gen ${t}`, cols, rows - 1);
-  grid.textAlign = "left";
-  grid.font = "";
+  grid.restore();
   stepLife();
 }
 
diff --git a/src/internal/canvas.ts b/src/internal/canvas.ts
index 98f876ed2..1ab1b3c49 100644
--- a/src/internal/canvas.ts
+++ b/src/internal/canvas.ts
@@ -12,7 +12,13 @@
  * The cellgrid context is for drawing in cells, the way terminal
  * programs draw: one glyph, one color and one background a cell.
  */
-import {parseColor, toCellColor} from "./cssvalues.ts";
+import {
+	getSystemColor,
+	numberFromCSSColor,
+	parseCanvasFont,
+	parseColor,
+	toCellColor,
+} from "./cssvalues.ts";
 import {
 	type CellContext,
 	type CellStyle,
@@ -1849,7 +1855,10 @@ export class CanvasRenderingContext2D {
 	}
 
 	set font(value: string) {
-		this[kState].font = String(value);
+		const font = parseCanvasFont(String(value));
+		if (font !== null) {
+			this[kState].font = font.serialized;
+		}
 	}
 
 	get textAlign(): string {
@@ -2959,33 +2968,59 @@ interface GridHost {
 	changed(): void;
 	// The canvas element's own direction, which "inherit" takes.
 	direction(): "ltr" | "rtl";
+	// The canvas element's color, which currentcolor takes.
+	color(): string;
 	// Terminal pixels per cell, for drawing images at their natural size.
 	cellPixels(): {width: number; height: number};
 }
 
 const kGridHost = Symbol("gridHost");
 
-const kFillStyle = Symbol("fillStyle");
-const kGridStrokeStyle = Symbol("gridStrokeStyle");
-const kLineStyle = Symbol("lineStyle");
-const kLineJoin = Symbol("lineJoin");
-const kFont = Symbol("font");
-const kTextAlign = Symbol("textAlign");
-const kTextDecoration = Symbol("textDecoration");
-const kGridDirection = Symbol("direction");
+const kGridState = Symbol("gridState");
+const kGridStack = Symbol("gridStack");
 const kResolveDirection = Symbol("resolveDirection");
+const kTextColor = Symbol("textColor");
 const kRect = Symbol("rect");
 
+type GridTextAlign = "start" | "end" | "left" | "right" | "center";
+type GridDirection = "ltr" | "rtl" | "inherit";
+type GridLineStyle = LineStyle["style"] | "none";
+type GridLineJoin = "miter" | "round" | "bevel";
+
+interface GridState {
+	fillStyle: string;
+	strokeStyle: string;
+	lineStyle: GridLineStyle;
+	lineJoin: GridLineJoin;
+	font: string;
+	bold: boolean;
+	italic: boolean;
+	dim: boolean;
+	textAlign: GridTextAlign;
+	textDecoration: string;
+	direction: GridDirection;
+}
+
+function defaultGridState(): GridState {
+	return {
+		fillStyle: "canvastext",
+		strokeStyle: "canvastext",
+		lineStyle: "solid",
+		lineJoin: "miter",
+		font: "10px sans-serif",
+		bold: false,
+		italic: false,
+		dim: false,
+		textAlign: "start",
+		textDecoration: "none",
+		direction: "inherit",
+	};
+}
+
 export interface CanvasCellGridContext {
 	[kGridHost]: GridHost;
-	[kFillStyle]: string;
-	[kGridStrokeStyle]: string;
-	[kLineStyle]: LineStyle["style"];
-	[kLineJoin]: "miter" | "round";
-	[kFont]: string;
-	[kTextAlign]: "start" | "end" | "left" | "right" | "center";
-	[kTextDecoration]: string;
-	[kGridDirection]: "ltr" | "rtl" | "inherit";
+	[kGridState]: GridState;
+	[kGridStack]: GridState[];
 }
 
 /**
@@ -2994,20 +3029,15 @@ export interface CanvasCellGridContext {
  * cells' backgrounds, fillRect() fills cells' backgrounds, strokeLine()
  * and strokeRect() draw box-drawing lines that join where they meet,
  * drawImage() draws an image two pixels a cell, and clearRect() empties
- * cells. Coordinates are cells. Colors are any CSS color, and
- * `currentcolor`, the default, is the terminal's own foreground.
+ * cells. Coordinates are cells. Its settings mean what a 2d context's
+ * do, and CanvasText and Canvas, the default colors, are the terminal's
+ * own.
  */
 export class CanvasCellGridContext {
 	constructor(host: GridHost) {
 		this[kGridHost] = host;
-		this[kFillStyle] = "currentcolor";
-		this[kGridStrokeStyle] = "currentcolor";
-		this[kLineStyle] = "solid";
-		this[kLineJoin] = "miter";
-		this[kFont] = "";
-		this[kTextAlign] = "start";
-		this[kTextDecoration] = "none";
-		this[kGridDirection] = "inherit";
+		this[kGridState] = defaultGridState();
+		this[kGridStack] = [];
 	}
 
 	get canvas(): HTMLCanvasElement {
@@ -3015,55 +3045,80 @@ export class CanvasCellGridContext {
 	}
 
 	get fillStyle(): string {
-		return this[kFillStyle];
+		return this[kGridState].fillStyle;
 	}
 
 	set fillStyle(value: string) {
-		this[kFillStyle] = readGridColor(value) ?? this[kFillStyle];
+		const color = readGridColor(value, this[kGridHost]);
+		if (color !== null) {
+			this[kGridState].fillStyle = color;
+		}
 	}
 
 	get strokeStyle(): string {
-		return this[kGridStrokeStyle];
+		return this[kGridState].strokeStyle;
 	}
 
 	set strokeStyle(value: string) {
-		this[kGridStrokeStyle] = readGridColor(value) ?? this[kGridStrokeStyle];
+		const color = readGridColor(value, this[kGridHost]);
+		if (color !== null) {
+			this[kGridState].strokeStyle = color;
+		}
 	}
 
-	/** A CSS border style: solid, double, dashed, dotted and the rest. */
-	get lineStyle(): LineStyle["style"] {
-		return this[kLineStyle];
+	/** A CSS border style: solid, double, dashed, dotted, none and the rest. */
+	get lineStyle(): GridLineStyle {
+		return this[kGridState].lineStyle;
 	}
 
 	set lineStyle(value: string) {
-		const style = LINE_STYLES.find((name) => name === value);
+		const style = value === "none"
+			? "none"
+			: LINE_STYLES.find((name) => name === value);
 		if (style !== undefined) {
-			this[kLineStyle] = style;
+			this[kGridState].lineStyle = style;
 		}
 	}
 
-	/** miter, round. A round join curves strokeRect()'s corners. */
-	get lineJoin(): "miter" | "round" {
-		return this[kLineJoin];
+	/**
+	 * miter, the default, round or bevel. A round join curves
+	 * strokeRect()'s corners; a bevel draws as a miter, the nearest a cell
+	 * comes.
+	 */
+	get lineJoin(): GridLineJoin {
+		return this[kGridState].lineJoin;
 	}
 
 	set lineJoin(value: string) {
-		if (value === "miter" || value === "round") {
-			this[kLineJoin] = value;
+		if (value === "miter" || value === "round" || value === "bevel") {
+			this[kGridState].lineJoin = value;
 		}
 	}
 
-	/** Keywords from the CSS font shorthand: bold, italic, lighter. */
+	/**
+	 * A CSS font shorthand, as a 2d context takes it. Its weight and style
+	 * decide bold, dim and italic; a cell has no size or family to change.
+	 */
 	get font(): string {
-		return this[kFont];
+		return this[kGridState].font;
 	}
 
 	set font(value: string) {
-		this[kFont] = String(value);
+		const font = parseCanvasFont(String(value));
+		if (font === null) {
+			return;
+		}
+		const state = this[kGridState];
+		state.font = font.serialized;
+		const weight = font.longhands["font-weight"];
+		const numeric = Number(weight);
+		state.bold = weight === "bold" || weight === "bolder" || numeric >= 600;
+		state.dim = weight === "lighter" || (numeric > 0 && numeric <= 300);
+		state.italic = font.longhands["font-style"] !== "normal";
 	}
 
-	get textAlign(): "start" | "end" | "left" | "right" | "center" {
-		return this[kTextAlign];
+	get textAlign(): GridTextAlign {
+		return this[kGridState].textAlign;
 	}
 
 	set textAlign(value: string) {
@@ -3074,7 +3129,7 @@ export class CanvasCellGridContext {
 			value === "right" ||
 			value === "center"
 		) {
-			this[kTextAlign] = value;
+			this[kGridState].textAlign = value;
 		}
 	}
 
@@ -3083,25 +3138,25 @@ export class CanvasCellGridContext {
 	 * direction as the text is drawn. It orders right-to-left text for
 	 * display and decides which side start and end are.
 	 */
-	get direction(): "ltr" | "rtl" | "inherit" {
-		return this[kGridDirection];
+	get direction(): GridDirection {
+		return this[kGridState].direction;
 	}
 
 	set direction(value: string) {
 		if (value === "ltr" || value === "rtl" || value === "inherit") {
-			this[kGridDirection] = value;
+			this[kGridState].direction = value;
 		}
 	}
 
 	/** none, or underline and line-through, alone or together. */
 	get textDecoration(): string {
-		return this[kTextDecoration];
+		return this[kGridState].textDecoration;
 	}
 
 	set textDecoration(value: string) {
 		const words = String(value).trim().toLowerCase().split(/\s+/);
 		if (words.length === 1 && words[0] === "none") {
-			this[kTextDecoration] = "none";
+			this[kGridState].textDecoration = "none";
 			return;
 		}
 		const lines = new Set(words);
@@ -3109,22 +3164,35 @@ export class CanvasCellGridContext {
 			lines.size === words.length &&
 			words.every((word) => word === "underline" || word === "line-through")
 		) {
-			this[kTextDecoration] = ["underline", "line-through"]
+			this[kGridState].textDecoration = ["underline", "line-through"]
 				.filter((line) => lines.has(line))
 				.join(" ");
 		}
 	}
 
+	save(): void {
+		this[kGridStack].push({...this[kGridState]});
+	}
+
+	restore(): void {
+		const state = this[kGridStack].pop();
+		if (state !== undefined) {
+			this[kGridState] = state;
+		}
+	}
+
+	isContextLost(): boolean {
+		return false;
+	}
+
 	fillRect(x: number, y: number, w: number, h: number): void {
 		const rect = this[kRect](x, y, w, h);
-		const color = toGridColor(this[kFillStyle]);
-		if (rect === null || color === undefined) {
+		const fill = toGridFill(this[kGridState].fillStyle);
+		if (rect === null || fill === undefined) {
 			return;
 		}
 		const [x0, y0, x1, y1] = rect;
-		// The terminal's foreground as a background is its inverse.
-		this[kGridHost].cells()
-			.drawRect(x0, y0, x1 - x0, y1 - y0, color ?? "inverse");
+		this[kGridHost].cells().drawRect(x0, y0, x1 - x0, y1 - y0, fill);
 		this[kGridHost].changed();
 	}
 
@@ -3146,8 +3214,8 @@ export class CanvasCellGridContext {
 		if (!isFiniteAll(x, y)) {
 			return;
 		}
-		const color = toGridColor(this[kFillStyle]);
-		if (color === undefined) {
+		const color = this[kTextColor](this[kGridState].fillStyle);
+		if (color === undefined || (maxWidth !== undefined && !(maxWidth > 0))) {
 			return;
 		}
 		const cells = this[kGridHost].cells();
@@ -3167,7 +3235,8 @@ export class CanvasCellGridContext {
 			0,
 		);
 		let col = Math.round(x);
-		const align = this[kTextAlign];
+		const state = this[kGridState];
+		const align = state.textAlign;
 		if (align === "center") {
 			col -= Math.floor(width / 2);
 		} else if (
@@ -3179,15 +3248,14 @@ export class CanvasCellGridContext {
 		}
 		const row = Math.round(y);
 		const limit = maxWidth !== undefined && Number.isFinite(maxWidth)
-			? col + Math.max(0, Math.floor(maxWidth))
+			? col + Math.floor(maxWidth)
 			: Infinity;
-		const words = this[kFont].toLowerCase().split(/\s+/);
 		const base: CellStyle = {
-			bold: words.includes("bold") || words.includes("bolder"),
-			italic: words.includes("italic") || words.includes("oblique"),
-			dim: words.includes("lighter"),
-			underline: this[kTextDecoration].includes("underline"),
-			strikethrough: this[kTextDecoration].includes("line-through"),
+			bold: state.bold,
+			italic: state.italic,
+			dim: state.dim,
+			underline: state.textDecoration.includes("underline"),
+			strikethrough: state.textDecoration.includes("line-through"),
 		};
 		const {grid} = cells;
 		for (const cluster of clusters) {
@@ -3232,12 +3300,13 @@ export class CanvasCellGridContext {
 		if (!isFiniteAll(x1, y1, x2, y2)) {
 			return;
 		}
-		const color = toGridColor(this[kGridStrokeStyle]);
-		if (color === undefined) {
+		const color = this[kTextColor](this[kGridState].strokeStyle);
+		const style = this[kGridState].lineStyle;
+		if (color === undefined || style === "none" || style === "hidden") {
 			return;
 		}
 		const [a, b, c, d] = [x1, y1, x2, y2].map(Math.round);
-		const line: LineStyle = {style: this[kLineStyle], color};
+		const line: LineStyle = {style, color};
 		const cells = this[kGridHost].cells();
 		if (b === d) {
 			cells.drawLine(Math.min(a, c), b, Math.max(a, c) + 1, b, {
@@ -3256,13 +3325,19 @@ export class CanvasCellGridContext {
 	/** A box on the cells `w` by `h` from (x, y), in strokeStyle and lineStyle. */
 	strokeRect(x: number, y: number, w: number, h: number): void {
 		const rect = this[kRect](x, y, w, h);
-		const color = toGridColor(this[kGridStrokeStyle]);
-		if (rect === null || color === undefined) {
+		const color = this[kTextColor](this[kGridState].strokeStyle);
+		const style = this[kGridState].lineStyle;
+		if (
+			rect === null ||
+			color === undefined ||
+			style === "none" ||
+			style === "hidden"
+		) {
 			return;
 		}
 		const [x0, y0, x1, y1] = rect;
-		const side: LineStyle = {style: this[kLineStyle], color};
-		const corner = this[kLineJoin] === "round" ? "round" : undefined;
+		const side: LineStyle = {style, color};
+		const corner = this[kGridState].lineJoin === "round" ? "round" : undefined;
 		this[kGridHost].cells()
 			.drawBox(x0, y0, x1 - x0, y1 - y0, {
 				top: side,
@@ -3316,6 +3391,16 @@ export class CanvasCellGridContext {
 		if (!isFiniteAll(sx, sy, sw, sh, dx, dy, dw, dh)) {
 			return;
 		}
+		// A negative size is the same rectangle measured from its other
+		// edge, as a 2d context normalizes it.
+		if (dw < 0) {
+			dx += dw;
+			dw = -dw;
+		}
+		if (dh < 0) {
+			dy += dh;
+			dh = -dh;
+		}
 		const cols = Math.round(dw);
 		const rows = Math.round(dh);
 		if (cols <= 0 || rows <= 0) {
@@ -3413,21 +3498,29 @@ export class CanvasCellGridContext {
 
 	reset(): void {
 		this[kGridHost].cells().grid.clear();
-		this[kFillStyle] = "currentcolor";
-		this[kGridStrokeStyle] = "currentcolor";
-		this[kLineStyle] = "solid";
-		this[kLineJoin] = "miter";
-		this[kFont] = "";
-		this[kTextAlign] = "start";
-		this[kTextDecoration] = "none";
-		this[kGridDirection] = "inherit";
+		this[kGridState] = defaultGridState();
+		this[kGridStack] = [];
 		this[kGridHost].changed();
 	}
 
 	[kResolveDirection](): "ltr" | "rtl" {
-		return this[kGridDirection] === "inherit"
-			? this[kGridHost].direction()
-			: this[kGridDirection];
+		const {direction} = this[kGridState];
+		return direction === "inherit" ? this[kGridHost].direction() : direction;
+	}
+
+	// A kept color as a glyph's color: a cell color, null for the
+	// terminal's own text color, or undefined for one too transparent to
+	// show, as a 2d context's text under half opaque does not.
+	[kTextColor](value: string): number | null | undefined {
+		const system = getSystemColor(value);
+		if (system !== null) {
+			return system.cell === 0 ? null : system.cell;
+		}
+		const color = parseCanvasColor(value)!;
+		if (color.a < 0.5) {
+			return undefined;
+		}
+		return toCellColor((color.r << 16) | (color.g << 8) | color.b);
 	}
 
 	[kRect](
@@ -3451,28 +3544,38 @@ export class CanvasCellGridContext {
 	}
 }
 
-// A color as the grid context keeps it, serialized, or null when the
-// value is not a color.
-function readGridColor(value: string): string | null {
+// A color as the grid context keeps it: a system color's keyword, the
+// rest serialized as a 2d context reads them back, or null when the value
+// is not a color. currentcolor is the canvas element's color as it is set.
+function readGridColor(value: string, host: GridHost): string | null {
 	const text = String(value).trim().toLowerCase();
 	if (text === "currentcolor") {
-		return "currentcolor";
+		return readGridColor(host.color(), host);
+	}
+	if (getSystemColor(text) !== null) {
+		return text;
 	}
 	const color = parseCanvasColor(text);
 	return color === null ? null : serializeColor(color);
 }
 
-// A kept color as a cell color: null for the terminal's foreground, or
-// undefined for a transparent one, which draws nothing.
-function toGridColor(value: string): number | null | undefined {
-	if (value === "currentcolor") {
-		return null;
+// A kept color as a cell's background. A system color the terminal fills
+// in is its own background, or its text color through inverse video. A
+// translucent color blends over what the cell shows. Undefined for a
+// transparent one, which fills nothing.
+function toGridFill(value: string): number | "default" | "inverse" | undefined {
+	const system = getSystemColor(value);
+	if (system !== null) {
+		if (system.cell !== 0) {
+			return system.cell;
+		}
+		return system.background ? "default" : "inverse";
 	}
 	const color = parseCanvasColor(value)!;
 	if (color.a === 0) {
 		return undefined;
 	}
-	return toCellColor((color.r << 16) | (color.g << 8) | color.b);
+	return numberFromCSSColor(value);
 }
 
 /**
diff --git a/src/internal/cssvalues.ts b/src/internal/cssvalues.ts
index d1127a644..e4087b320 100644
--- a/src/internal/cssvalues.ts
+++ b/src/internal/cssvalues.ts
@@ -718,6 +718,22 @@ const BACKGROUND_SYSTEM_COLORS = new Set([
 	"window",
 ]);
 
+/**
+ * A system color keyword's cell color, and whether one the terminal fills
+ * in stands for its background rather than its text. Null for anything
+ * that is not a system color.
+ */
+export function getSystemColor(
+	value: string,
+): {cell: number; background: boolean} | null {
+	const keyword = value.trim().toLowerCase();
+	const cell = SYSTEM_COLORS[keyword];
+	if (cell === undefined) {
+		return null;
+	}
+	return {cell, background: BACKGROUND_SYSTEM_COLORS.has(keyword)};
+}
+
 /**
  * A system color as a page reads it back: rgb(), as a browser gives it.
  * One the terminal fills in reads as black or white, whichever the
@@ -1503,6 +1519,28 @@ function matchesProperty(property: string, text: string): boolean {
  * initial value, the font-variant ones among them. Null for a system font
  * or a value that does not parse.
  */
+/**
+ * A CSS font shorthand as a canvas keeps it: the value serialized without
+ * its line height, as HTML's canvas font attribute reads back, and the
+ * longhands it sets. Null for a value the shorthand grammar rejects.
+ */
+export function parseCanvasFont(
+	value: string,
+): {serialized: string; longhands: Record<string, string>} | null {
+	const longhands = expandFont(splitComponents(value));
+	if (longhands === null) {
+		return null;
+	}
+	const words = [
+		longhands["font-style"],
+		longhands["font-variant-caps"],
+		longhands["font-weight"],
+		longhands["font-stretch"],
+	].filter((word) => word !== "normal");
+	words.push(longhands["font-size"], longhands["font-family"]);
+	return {serialized: words.join(" "), longhands};
+}
+
 function expandFont(tokens: string[]): Record<string, string> | null {
 	if (tokens.length === 1 && SYSTEM_FONTS.has(tokens[0].toLowerCase())) {
 		return null;
diff --git a/src/internal/dom.ts b/src/internal/dom.ts
index cfddde8bf..6d7bd7da2 100644
--- a/src/internal/dom.ts
+++ b/src/internal/dom.ts
@@ -14559,6 +14559,7 @@ class HTMLCanvasElement extends HTMLElement {
 				cells: () => getCanvasGrid(this),
 				changed,
 				cellPixels: () => getImageCellSize(this as unknown as Node),
+				color: () => getComputedValue(this, "color"),
 				direction: () => getCanvasDirection(this),
 			});
 			// The natural size is now in cells, not pixels.
diff --git a/tests/canvas.test.ts b/tests/canvas.test.ts
index 142e81fe2..bb7bcece1 100644
--- a/tests/canvas.test.ts
+++ b/tests/canvas.test.ts
@@ -644,10 +644,10 @@ test("fillText writes glyphs, fillRect fills backgrounds, clearRect empties", as
 	ctx.fillStyle = "#003366";
 	ctx.fillRect(0, 0, 12, 1);
 	ctx.fillStyle = "#ffcc00";
-	ctx.font = "bold italic";
+	ctx.font = "bold italic 10px monospace";
 	ctx.fillText("score: 42", 1, 0);
-	ctx.fillStyle = "currentcolor";
-	ctx.font = "";
+	ctx.fillStyle = "canvastext";
+	ctx.font = "10px monospace";
 	ctx.fillText("plain", 0, 2);
 	await nextFrame(dom);
 	expect(rowText(terminal, 0).trimEnd()).toBe(" score: 42");
@@ -687,10 +687,10 @@ test("textDecoration draws underline and line-through, and getCell reads them ba
 	expect(ctx.textDecoration).toBe("underline line-through");
 	ctx.textDecoration = "overline";
 	expect(ctx.textDecoration).toBe("underline line-through");
-	ctx.font = "lighter";
+	ctx.font = "lighter 10px monospace";
 	ctx.fillText("ab", 0, 0);
 	ctx.textDecoration = "line-through";
-	ctx.font = "";
+	ctx.font = "10px monospace";
 	ctx.fillText("c", 2, 0);
 	expect(ctx.getCell(0, 0)).toMatchObject({
 		dim: true,
@@ -745,6 +745,117 @@ test("a cell grid rounds every coordinate, getCell's too", async () => {
 	dom.dispose();
 });
 
+test("a cell grid's font is a CSS font shorthand, as a 2d context's is", async () => {
+	const {dom, document} =
+		await mount("<canvas id=g width=8 height=1></canvas>");
+	const ctx = grid(document);
+	expect(ctx.font).toBe("10px sans-serif");
+	ctx.font = "bold";
+	expect(ctx.font).toBe("10px sans-serif");
+	ctx.font = "italic 700 12px/2 monospace";
+	expect(ctx.font).toBe("italic 700 12px monospace");
+	ctx.fillText("a", 0, 0);
+	expect(ctx.getCell(0, 0)).toMatchObject({bold: true, italic: true});
+	ctx.font = "300 1px monospace";
+	ctx.fillText("b", 1, 0);
+	expect(ctx.getCell(1, 0)).toMatchObject({bold: false, dim: true});
+	dom.dispose();
+});
+
+test("a 2d context ignores a font the shorthand grammar rejects", async () => {
+	const {dom, document} =
+		await mount("<canvas id=c width=8 height=8></canvas>");
+	const ctx = context2d(document);
+	ctx.font = "banana";
+	expect(ctx.font).toBe("10px sans-serif");
+	ctx.font = "bold 16px/1.5 monospace";
+	expect(ctx.font).toBe("bold 16px monospace");
+	dom.dispose();
+});
+
+test("a cell grid's colors: currentcolor, the terminal's own, and translucent fills", async () => {
+	const {dom, terminal, document} = await mount(
+		"<canvas id=g width=6 height=3 style=\"color: #102030\"></canvas>",
+	);
+	const ctx = grid(document);
+	expect([
+		ctx.fillStyle,
+		ctx.strokeStyle,
+	]).toEqual(["canvastext", "canvastext"]);
+	ctx.fillStyle = "currentcolor";
+	expect(ctx.fillStyle).toBe("#102030");
+	ctx.fillText("a", 0, 0);
+	expect(ctx.getCell(0, 0)!.color).toBe("#102030");
+	ctx.fillStyle = "CanvasText";
+	expect(ctx.fillStyle).toBe("canvastext");
+	ctx.fillText("b", 1, 0);
+	expect(ctx.getCell(1, 0)!.color).toBeNull();
+	ctx.fillStyle = "rgb(255 0 0 / 0.3)";
+	expect(ctx.fillStyle).toBe("rgba(255, 0, 0, 0.3)");
+	ctx.fillText("c", 2, 0);
+	expect(ctx.getCell(2, 0)).toBeNull();
+	ctx.fillStyle = "#ffffff";
+	ctx.fillRect(0, 1, 6, 1);
+	ctx.fillStyle = "rgba(0, 0, 0, 0.5)";
+	ctx.fillRect(0, 1, 3, 1);
+	await nextFrame(dom);
+	const shaded = cell(terminal, 0, 1).bg;
+	expect(shaded).not.toBe(0xffffff);
+	expect(shaded).not.toBe(0);
+	expect(cell(terminal, 4, 1).bg).toBe(0xffffff);
+	ctx.fillStyle = "Canvas";
+	ctx.fillRect(0, 2, 1, 1);
+	ctx.fillStyle = "CanvasText";
+	ctx.fillRect(1, 2, 1, 1);
+	expect(ctx.getCell(1, 2)!.inverse).toBe(true);
+	dom.dispose();
+});
+
+test("a cell grid saves and restores its settings, and reports no context loss", async () => {
+	const {dom, document} =
+		await mount("<canvas id=g width=4 height=1></canvas>");
+	const ctx = grid(document);
+	ctx.fillStyle = "#ff0000";
+	ctx.textAlign = "center";
+	ctx.save();
+	ctx.fillStyle = "#00ff00";
+	ctx.textAlign = "right";
+	ctx.font = "bold 1px monospace";
+	ctx.restore();
+	expect([ctx.fillStyle, ctx.textAlign, ctx.font])
+		.toEqual(["#ff0000", "center", "10px sans-serif"]);
+	ctx.restore();
+	expect(ctx.fillStyle).toBe("#ff0000");
+	expect(ctx.isContextLost()).toBe(false);
+	dom.dispose();
+});
+
+test("a cell grid follows a 2d context on maxWidth, lineJoin, lineStyle and drawImage's sizes", async () => {
+	const {dom, document} = await mount(
+		"<canvas id=g width=6 height=4></canvas><canvas id=src width=2 height=2></canvas>",
+	);
+	const ctx = grid(document);
+	ctx.fillText("nan", 0, 0, Number.NaN);
+	ctx.fillText("neg", 0, 0, -1);
+	expect(ctx.getCell(0, 0)).toBeNull();
+	ctx.fillText("abc", 0, 0, 2);
+	expect([ctx.getCell(1, 0)!.char, ctx.getCell(2, 0)]).toEqual(["b", null]);
+	ctx.lineJoin = "bevel";
+	expect(ctx.lineJoin).toBe("bevel");
+	ctx.lineStyle = "none";
+	expect(ctx.lineStyle).toBe("none");
+	ctx.strokeRect(0, 1, 3, 2);
+	expect(ctx.getCell(0, 1)).toBeNull();
+	const source = (document.getElementById("src") as HTMLCanvasElement)
+		.getContext("2d")!;
+	source.fillStyle = "#ff0000";
+	source.fillRect(0, 0, 2, 2);
+	ctx.drawImage(document.getElementById("src")!, 6, 4, -1, -1);
+	expect(ctx.getCell(5, 3)!.background).toBe("#ff0000");
+	expect(() => ctx.drawImage({}, 0, 0)).toThrow(TypeError);
+	dom.dispose();
+});
+
 test("text that runs past the grid is cut, and wide glyphs take two columns", async () => {
 	const {dom, terminal, document} =
 		await mount("<canvas id=g width=6 height=1></canvas>|");

From b462d9607d03b12dcb3e9ebc12e660c8497553eb Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 00:04:56 -0400
Subject: [PATCH 06/24] Run the canvas and images examples on the site

images.ts reads a file: URL with node:fs's readFileSync, which the
site's sandbox provides, and its broken image is described as the alt
text it shows.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015Bw3yEu4cfkuDkaZ3RSy4D
---
 examples/images.ts             | 7 ++++---
 website/src/models/examples.ts | 2 ++
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/examples/images.ts b/examples/images.ts
index e713987a5..df3525176 100644
--- a/examples/images.ts
+++ b/examples/images.ts
@@ -1,4 +1,4 @@
-import {readFile} from "node:fs/promises";
+import {readFileSync} from "node:fs";
 import {pathToFileURL} from "node:url";
 
 import {TermDOM} from "@b9g/termdom";
@@ -20,8 +20,9 @@ const term = new TermDOM({
 });
 term.addEventListener("fetch", (event) => {
   if (event.request.url.startsWith("file:")) {
+    const url = new URL(event.request.url);
     event.respondWith(
-      readFile(new URL(event.request.url)).then((bytes) => new Response(bytes)),
+      Promise.resolve().then(() => new Response(readFileSync(url))),
     );
   }
 });
@@ -87,7 +88,7 @@ document.body.innerHTML = `
         <img class="box" style="object-fit: cover">
       </div>
     </div>
-    <p>A broken image is a box with its alt text: <img src="missing.png" alt="no cover art"></p>
+    <p>A broken image shows its alt text: <img src="missing.png" alt="no cover art"></p>
   </div>
 `;
 
diff --git a/website/src/models/examples.ts b/website/src/models/examples.ts
index 77a30b7f4..fee791082 100644
--- a/website/src/models/examples.ts
+++ b/website/src/models/examples.ts
@@ -28,6 +28,7 @@ const RUNNABLE = [
 	"animated",
 	"bar-chart",
 	"borders",
+	"canvas",
 	"chat",
 	"codemirror",
 	"commit-editor",
@@ -40,6 +41,7 @@ const RUNNABLE = [
 	"hacker-news",
 	"highlights",
 	"hover",
+	"images",
 	"lists",
 	"markdown",
 	"password",

From df1775e4aac3b0a5ae5aa3f4f0197a64a4544494 Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 12:33:54 -0400
Subject: [PATCH 07/24] Say that a cell grid canvas wants its width and height
 set

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/guides/07-images-and-canvas.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/guides/07-images-and-canvas.md b/docs/guides/07-images-and-canvas.md
index 8c4f0915a..7e161bd08 100644
--- a/docs/guides/07-images-and-canvas.md
+++ b/docs/guides/07-images-and-canvas.md
@@ -285,7 +285,9 @@ Drawing repaints the canvas on the next frame. No DOM change is needed.
 ### `"termdom-cellgrid"`
 
 The cell grid context draws cells instead of pixels. The canvas is
-`width` columns by `height` rows, and that is its natural size. It is
+`width` columns by `height` rows, and that is its natural size. Set
+both: without them a canvas is HTML's default 300 by 150, which here
+is 300 columns by 150 rows. It is
 TermDOM's own, so its name carries TermDOM's prefix, as a browser's own
 context types once carried theirs (`"moz-webgl"`, `"webkit-3d"`). Its
 interface is not on `window`. The `@b9g/termdom` package exports it as

From 5552bf6130158a9545f083e151c9efe46f5540fc Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 13:10:05 -0400
Subject: [PATCH 08/24] Lay a canvas out at width by height CSS pixels whatever
 its context

A canvas's width and height are unitless, and HTML lays the canvas out
at that many CSS pixels. Under the unit cell a CSS pixel is a cell, so
there they are cells, for a 2d canvas as for a cell grid, and with
cellSize set they are pixels. Asking for a context no longer changes a
canvas's size: a 2d canvas under the unit cell was measured against
the terminal's cell, as an image is, and a cell grid switched to
counting its attributes as cells.

Under the unit cell, width and height default to 38 and 9, the cells
HTML's 300 by 150 pixels fill at 8 by 16 pixels a cell, so a bare
canvas is not 300 columns wide.

A cell grid holds the cells its canvas's box holds, reported as cols
and rows, so CSS sizes it exactly in any mode. When the box changes
size, the cells that still fit keep what was drawn, as a terminal keeps
its screen when its window is resized.

Images keep measuring their pixels against the terminal's cell under
the unit cell.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/guides/07-images-and-canvas.md |  32 ++++--
 examples/canvas.ts                  |   5 +-
 src/internal/canvas.ts              |  14 ++-
 src/internal/dom.ts                 |  73 +++++++++----
 src/internal/htmlreflection.ts      |   8 +-
 src/internal/images.ts              |  10 +-
 src/internal/replaced.ts            |  44 +++++---
 tests/canvas.test.ts                | 159 +++++++++++++++++++++++-----
 8 files changed, 273 insertions(+), 72 deletions(-)

diff --git a/docs/guides/07-images-and-canvas.md b/docs/guides/07-images-and-canvas.md
index 7e161bd08..933d4f5a5 100644
--- a/docs/guides/07-images-and-canvas.md
+++ b/docs/guides/07-images-and-canvas.md
@@ -236,12 +236,28 @@ a cell grid stops at 2^22 cells.
 
 ## `<canvas>`
 
+A canvas is laid out at `width` by `height` CSS pixels, as HTML sizes
+it, whichever context it gets. Under the default unit cell a CSS pixel
+is a cell, so `<canvas width="40" height="10">` is 40 columns by 10
+rows. With the `cellSize` option set, they are pixels, and a canvas
+covers the cells its pixels fill. CSS sizes a canvas like any element.
+
+Without the attributes, a canvas is HTML's 300 by 150 pixels. Under the
+unit cell, `width` and `height` default to 38 and 9 instead, the cells
+300 by 150 pixels fill at 8 by 16 pixels a cell, so a bare canvas is
+about the size it would be in pixels.
+
+Images keep their own rule: an image's pixels are its file's, so under
+the unit cell it is measured against the terminal's cell, not one cell
+a pixel.
+
 `getContext()` takes two context types.
 
 ### `"2d"`
 
-The 2D context draws pixels into a bitmap, `width` by `height`, which
-shows like an image. It implements:
+The 2D context draws pixels into a bitmap, `width` by `height`, scaled
+to the canvas's box. A cell shows two pixels, one above the other, so a
+bitmap twice as tall as its box in cells shows every pixel. It implements:
 
 - rectangles, paths (lines, arcs, ellipses, Bézier curves, `arcTo`,
   `roundRect`), `Path2D` with SVG path data, filling with the `nonzero`
@@ -284,10 +300,13 @@ Drawing repaints the canvas on the next frame. No DOM change is needed.
 
 ### `"termdom-cellgrid"`
 
-The cell grid context draws cells instead of pixels. The canvas is
-`width` columns by `height` rows, and that is its natural size. Set
-both: without them a canvas is HTML's default 300 by 150, which here
-is 300 columns by 150 rows. It is
+The cell grid context draws cells instead of pixels: as many as the
+canvas's box holds, which `cols` and `rows` report. Under the unit cell
+that is `width` by `height`. In any mode, CSS sizes it exactly:
+`width: 40ch; height: 10ch` holds 40 by 10 cells. When the box changes
+size, the cells that still fit keep what was drawn, and the new ones
+are empty, as a terminal keeps its screen when its window is resized;
+a `ResizeObserver` on the canvas tells a script to draw again. It is
 TermDOM's own, so its name carries TermDOM's prefix, as a browser's own
 context types once carried theirs (`"moz-webgl"`, `"webkit-3d"`). Its
 interface is not on `window`. The `@b9g/termdom` package exports it as
@@ -319,6 +338,7 @@ not the page's borders around the canvas.
 
 | Member | What it does |
 | --- | --- |
+| `cols`, `rows` | The cells the canvas's box holds |
 | `fillStyle` | A CSS color, read back as a 2D context reads it. `CanvasText`, the default, is the terminal's own text color and `Canvas` its background. `currentcolor` is the canvas element's `color` when it is set. A translucent fill blends over the cell; text under half opaque draws nothing |
 | `strokeStyle` | The lines' color, the same way |
 | `lineStyle` | A CSS `border-style`: `solid`, the default, `double`, `dashed`, `dotted`, `none` and the rest |
diff --git a/examples/canvas.ts b/examples/canvas.ts
index 534fc231c..5a3f51408 100644
--- a/examples/canvas.ts
+++ b/examples/canvas.ts
@@ -33,7 +33,7 @@ document.body.innerHTML = `
 // in cells with CSS and its pixels stretch to fit.
 const pixels = document.getElementById("pixels") as HTMLCanvasElement;
 pixels.style.width = "40ch";
-pixels.style.height = "16px";
+pixels.style.height = "16ch";
 const ctx = pixels.getContext("2d")!;
 
 const grid = (document.getElementById("cells") as HTMLCanvasElement)
@@ -41,8 +41,7 @@ const grid = (document.getElementById("cells") as HTMLCanvasElement)
 
 // Conway's Life on the grid, seeded with a glider, blinkers, a toad and
 // an R-pentomino, which keeps changing for a long time.
-const cols = 30;
-const rows = 16;
+const {cols, rows} = grid;
 let life = Array.from({length: rows}, () => new Array(cols).fill(false));
 for (const [x, y] of [
   [1, 0],
diff --git a/src/internal/canvas.ts b/src/internal/canvas.ts
index 1ab1b3c49..a91191092 100644
--- a/src/internal/canvas.ts
+++ b/src/internal/canvas.ts
@@ -3024,8 +3024,8 @@ export interface CanvasCellGridContext {
 }
 
 /**
- * getContext("termdom-cellgrid"): the canvas as `width` columns by `height`
- * rows of cells. fillText() writes glyphs in the fill color over the
+ * getContext("termdom-cellgrid"): the canvas as the cells its box holds,
+ * `cols` by `rows`. fillText() writes glyphs in the fill color over the
  * cells' backgrounds, fillRect() fills cells' backgrounds, strokeLine()
  * and strokeRect() draw box-drawing lines that join where they meet,
  * drawImage() draws an image two pixels a cell, and clearRect() empties
@@ -3044,6 +3044,16 @@ export class CanvasCellGridContext {
 		return this[kGridHost].canvas as HTMLCanvasElement;
 	}
 
+	/** The columns the canvas's box holds. */
+	get cols(): number {
+		return this[kGridHost].cells().cols;
+	}
+
+	/** The rows the canvas's box holds. */
+	get rows(): number {
+		return this[kGridHost].cells().rows;
+	}
+
 	get fillStyle(): string {
 		return this[kGridState].fillStyle;
 	}
diff --git a/src/internal/dom.ts b/src/internal/dom.ts
index 6d7bd7da2..e22274096 100644
--- a/src/internal/dom.ts
+++ b/src/internal/dom.ts
@@ -13902,8 +13902,13 @@ function installReflection(prototype: object, spec: ReflectSpec): void {
 			break;
 		}
 		case "unsigned-long": {
-			const fallback = spec.fallback ?? 0;
+			const fallbackFor = (element: Element): number =>
+				spec.unitFallback !== undefined &&
+				getCellSize(element as unknown as Node) === UNIT_CELL
+					? spec.unitFallback
+					: (spec.fallback ?? 0);
 			get = function (this: Element): number {
+				const fallback = fallbackFor(this);
 				const value = this.getAttribute(attribute);
 				let parsed = value === null ? null : parseNonNegativeInteger(value);
 				if (parsed !== null && parsed > 2147483647) {
@@ -13933,7 +13938,7 @@ function installReflection(prototype: object, spec: ReflectSpec): void {
 				}
 				this.setAttribute(
 					attribute,
-					String(number > 2147483647 ? fallback : number),
+					String(number > 2147483647 ? fallbackFor(this) : number),
 				);
 			};
 			break;
@@ -14420,11 +14425,12 @@ function invalidateReplaced(element: Element, reflow: boolean): void {
 }
 
 /**
- * <canvas>: "2d" draws pixels, shown two to a cell, and "termdom-cellgrid"
- * draws cells, `width` columns by `height` rows. A 2d canvas shows at
- * its pixel size over the terminal's cell size, as an image does. The
- * other context types (webgl, webgpu, bitmaprenderer) are null, as they
- * are in a browser that cannot create them.
+ * <canvas>: laid out at `width` by `height` CSS pixels whatever its
+ * context, so where a CSS pixel is a cell those are cells. "2d" draws
+ * that many pixels, shown two to a cell and scaled to the box, and
+ * "termdom-cellgrid" draws as many cells as the box holds. The other
+ * context types (webgl, webgpu, bitmaprenderer) are null, as they are in
+ * a browser that cannot create them.
  */
 class HTMLCanvasElement extends HTMLElement {
 	declare height: globalThis.HTMLCanvasElement["height"];
@@ -14447,7 +14453,10 @@ class HTMLCanvasElement extends HTMLElement {
 			if (this[kCanvasContext] instanceof CanvasCellGridContext) {
 				return {
 					kind: "grid",
-					grid: getCanvasGrid(this).grid,
+					width: this.width,
+					height: this.height,
+					fit: (cols: number, rows: number) =>
+						fitCanvasGrid(this, cols, rows).grid,
 					version: this[kCanvasVersion],
 				};
 			}
@@ -14562,8 +14571,6 @@ class HTMLCanvasElement extends HTMLElement {
 				color: () => getComputedValue(this, "color"),
 				direction: () => getCanvasDirection(this),
 			});
-			// The natural size is now in cells, not pixels.
-			invalidateReplaced(this, true);
 		} else {
 			return null;
 		}
@@ -14663,16 +14670,46 @@ function getCanvasBitmap(canvas: HTMLCanvasElement): Bitmap {
 	return bitmap;
 }
 
+// The cells a cellgrid canvas's box holds: its content box as last laid
+// out, or before any layout its natural size, `width` by `height` CSS
+// pixels over the page's cell size.
 function getCanvasGrid(canvas: HTMLCanvasElement): CellContext {
-	const fits = canvas.width * canvas.height <= GRID_CELL_LIMIT;
-	const cols = fits ? canvas.width : 0;
-	const rows = fits ? canvas.height : 0;
-	let cells = canvas[kCanvasGrid];
-	if (cells === null || cells.cols !== cols || cells.rows !== rows) {
-		cells =
-			canvas[kCanvasGrid] =
-			new CellContext(new CellGrid(rows, cols), rows, cols, 0);
+	const rect = getAttachedDocument(canvas)?.[kLayout].contentRect(canvas);
+	if (rect) {
+		return fitCanvasGrid(
+			canvas,
+			Math.round(rect.width),
+			Math.round(rect.height),
+		);
+	}
+	const cell = getCellSize(canvas as unknown as Node);
+	return fitCanvasGrid(
+		canvas,
+		Math.round(canvas.width / cell.width),
+		Math.round(canvas.height / cell.height),
+	);
+}
+
+// The grid at a size, keeping the cells that still fit when its box
+// changes size, as a terminal keeps its screen when its window does.
+function fitCanvasGrid(
+	canvas: HTMLCanvasElement,
+	cols: number,
+	rows: number,
+): CellContext {
+	if (cols * rows > GRID_CELL_LIMIT) {
+		cols = 0;
+		rows = 0;
+	}
+	const previous = canvas[kCanvasGrid];
+	if (previous !== null && previous.cols === cols && previous.rows === rows) {
+		return previous;
+	}
+	const cells = new CellContext(new CellGrid(rows, cols), rows, cols, 0);
+	if (previous !== null) {
+		cells.drawGrid(previous.grid, 0, 0);
 	}
+	canvas[kCanvasGrid] = cells;
 	return cells;
 }
 
diff --git a/src/internal/htmlreflection.ts b/src/internal/htmlreflection.ts
index 63526559b..6ba0259ff 100644
--- a/src/internal/htmlreflection.ts
+++ b/src/internal/htmlreflection.ts
@@ -19,6 +19,9 @@ export interface ReflectSpec {
 	// A number's value when the attribute is absent or unparsable.
 	fallback?: number;
 
+	// The fallback instead where a CSS pixel is a cell.
+	unitFallback?: number;
+
 	keywords?: readonly string[];
 
 	missing?: string;
@@ -217,8 +220,9 @@ const HAND_REFLECTIONS: Readonly<Record<string, readonly ReflectSpec[]>> = {
 		popoverTargetAction(),
 	],
 	HTMLCanvasElement: [
-		ulong("width", "width", 300),
-		ulong("height", "height", 150),
+		// HTML's 300 by 150 pixels over an 8 by 16 cell.
+		ulong("width", "width", 300, {unitFallback: 38}),
+		ulong("height", "height", 150, {unitFallback: 9}),
 	],
 	HTMLDialogElement: [
 		keyword(
diff --git a/src/internal/images.ts b/src/internal/images.ts
index ef0bad52d..cb95cd189 100644
--- a/src/internal/images.ts
+++ b/src/internal/images.ts
@@ -2036,7 +2036,15 @@ export type ReplacedContent =
 	} |
 	// A canvas not drawn on yet: its size, and nothing to paint.
 	{kind: "blank"; width: number; height: number} |
-	{kind: "grid"; grid: CellGrid; version: number} |
+	{
+		kind: "grid";
+		// The canvas's width and height attributes, in CSS pixels.
+		width: number;
+		height: number;
+		// The grid resized to the cells its box holds.
+		fit(cols: number, rows: number): CellGrid;
+		version: number;
+	} |
 	{kind: "text"; text: string; loading: boolean} |
 	null;
 
diff --git a/src/internal/replaced.ts b/src/internal/replaced.ts
index 327502e94..3e6bdabbc 100644
--- a/src/internal/replaced.ts
+++ b/src/internal/replaced.ts
@@ -8,12 +8,15 @@
  * size over the page's cell size. Under the default unit cell, where a
  * CSS pixel is a cell, that would be one cell per pixel, so the image
  * takes the screen's cell size instead, which the terminal reports
- * (XTWINOPS 16) and which is guessed at 8 by 16 until it does. A
- * cellgrid canvas is already in cells.
+ * (XTWINOPS 16) and which is guessed at 8 by 16 until it does. A canvas
+ * is `width` by `height` CSS pixels, as HTML sizes it, over the page's
+ * cell size, whatever its context: where a CSS pixel is a cell, those
+ * are cells.
  */
 import {type CanvasTextRun, halfBlockCell} from "./canvas.ts";
 import {
 	getBoxModel,
+	getCellSize,
 	getComputedValue,
 	getImageCellSize,
 	toCellLength,
@@ -67,15 +70,12 @@ export function getNaturalSize(
 	if (content === null) {
 		return null;
 	}
-	if (content.kind === "grid") {
-		return {width: content.grid.cols, height: content.grid.rows};
-	}
 	if (content.kind === "text") {
 		// The alt text on one line inside a border, or an empty cell
 		// inside one when there is none.
 		return {width: Math.max(1, textWidth(content.text)) + 2, height: 3};
 	}
-	const {width, height} = content.kind === "blank"
+	const {width, height} = content.kind === "blank" || content.kind === "grid"
 		? content
 		: {
 			width: naturalWidthOf(content.bitmap),
@@ -84,7 +84,7 @@ export function getNaturalSize(
 	if (width === 0 || height === 0) {
 		return {width: 0, height: 0};
 	}
-	const cell = getImageCellSize(element as unknown as Node);
+	const cell = getPixelCellSize(element);
 	return {
 		width: Math.max(1, Math.round(width / cell.width)),
 		height: Math.max(1, Math.round(height / cell.height)),
@@ -99,10 +99,7 @@ export function getNaturalRatio(
 	if (content === null || content.kind === "text") {
 		return NaN;
 	}
-	if (content.kind === "grid") {
-		return content.grid.rows > 0 ? content.grid.cols / content.grid.rows : NaN;
-	}
-	const {width, height} = content.kind === "blank"
+	const {width, height} = content.kind === "blank" || content.kind === "grid"
 		? content
 		: {
 			width: naturalWidthOf(content.bitmap),
@@ -111,10 +108,19 @@ export function getNaturalRatio(
 	if (width === 0 || height === 0) {
 		return NaN;
 	}
-	const cell = getImageCellSize(element as unknown as Node);
+	const cell = getPixelCellSize(element);
 	return (width / cell.width) / (height / cell.height);
 }
 
+// What one of the element's pixels is measured against: the page's cell
+// for a canvas, whose pixels are CSS pixels, and for an image the
+// screen's cell where a CSS pixel is a cell.
+function getPixelCellSize(element: Element): {width: number; height: number} {
+	return element.localName === "canvas"
+		? getCellSize(element as unknown as Node)
+		: getImageCellSize(element as unknown as Node);
+}
+
 function textWidth(text: string): number {
 	let width = 0;
 	for (const char of text) {
@@ -459,14 +465,15 @@ const settledGrids = new WeakMap<CellGrid, {version: number; grid: CellGrid}>();
 // drawn, kept until the canvas draws again.
 function getSettledGrid(
 	content: Extract<ReplacedContent, {kind: "grid"}>,
+	source: CellGrid,
 ): CellGrid {
-	const cached = settledGrids.get(content.grid);
+	const cached = settledGrids.get(source);
 	if (cached?.version === content.version) {
 		return cached.grid;
 	}
-	const grid = content.grid.clone();
+	const grid = source.clone();
 	settleBorders(grid);
-	settledGrids.set(content.grid, {version: content.version, grid});
+	settledGrids.set(source, {version: content.version, grid});
 	return grid;
 }
 
@@ -531,7 +538,12 @@ export function renderReplaced(
 		if (content.kind === "text") {
 			drawPlaceholder(content.text, left, top, cols, rows, ctx, style);
 		} else if (content.kind === "grid") {
-			ctx.drawGrid(getSettledGrid(content), left, top, style);
+			ctx.drawGrid(
+				getSettledGrid(content, content.fit(cols, rows)),
+				left,
+				top,
+				style,
+			);
 		} else if (cols * rows * 2 <= MAX_IMAGE_PIXELS) {
 			// Past the limit the pixels a box samples are more than an image
 			// may hold, and like a canvas past it, the box shows nothing.
diff --git a/tests/canvas.test.ts b/tests/canvas.test.ts
index bb7bcece1..45153a393 100644
--- a/tests/canvas.test.ts
+++ b/tests/canvas.test.ts
@@ -45,15 +45,20 @@ function rowText(terminal: MockProcess, row: number): string {
 		.translateToString(true);
 }
 
+// A cell of 8 by 16 CSS pixels, where a canvas's pixels are pixels.
+const PIXELS = {width: 8, height: 16};
+
 async function mount(
 	html: string,
 	cols = 40,
 	rows = 12,
+	cellSize?: {width: number; height: number},
 ): Promise<{dom: TermDOM; terminal: MockProcess; document: Document}> {
 	const terminal = new MockProcess({cols, rows});
 	const dom = new TermDOM({
 		transport: terminal.transport,
 		csp: "img-src data: https:",
+		cellSize,
 	});
 	dom.document.body.innerHTML = html;
 	await nextFrame(dom);
@@ -89,18 +94,50 @@ test("getContext hands back one context per canvas, and null for the rest", asyn
 	dom.dispose();
 });
 
-test("a canvas is 300 by 150 pixels until sized, and sizes in cells from them", async () => {
+test("a canvas is width by height CSS pixels, which are cells under the unit cell", async () => {
+	const {dom, document} = await mount(
+		"<canvas id=c></canvas><canvas id=d width=16 height=4></canvas>",
+	);
+	const canvas = document.getElementById("c") as HTMLCanvasElement;
+	// HTML's 300 by 150 pixels over an 8 by 16 cell.
+	expect([canvas.width, canvas.height]).toEqual([38, 9]);
+	const bare = canvas.getBoundingClientRect();
+	expect([bare.width, bare.height]).toEqual([38, 9]);
+	const sized = document.getElementById("d")!.getBoundingClientRect();
+	expect([sized.width, sized.height]).toEqual([16, 4]);
+	dom.dispose();
+});
+
+test("a canvas is 300 by 150 pixels by default where a CSS pixel is a pixel", async () => {
 	const {dom, document} = await mount(
 		"<canvas id=c></canvas><canvas id=d width=16 height=32></canvas>",
+		40,
+		12,
+		PIXELS,
 	);
 	const canvas = document.getElementById("c") as HTMLCanvasElement;
-	expect(canvas.width).toBe(300);
-	expect(canvas.height).toBe(150);
-	// 300 / 8 rounds to 38 and 150 / 16 to 9.
-	expect(canvas.getBoundingClientRect().width).toBe(38);
-	expect(canvas.getBoundingClientRect().height).toBe(9);
+	expect([canvas.width, canvas.height]).toEqual([300, 150]);
+	const bare = canvas.getBoundingClientRect();
+	expect([bare.width / 8, bare.height / 16]).toEqual([38, 9]);
 	const small = document.getElementById("d")!.getBoundingClientRect();
-	expect([small.width, small.height]).toEqual([2, 2]);
+	expect([small.width / 8, small.height / 16]).toEqual([2, 2]);
+	dom.dispose();
+});
+
+test("a canvas lays out the same whichever context it gets", async () => {
+	const {dom, document} = await mount(
+		"<canvas id=a width=12 height=3></canvas><canvas id=b width=12 height=3></canvas>",
+	);
+	const a = document.getElementById("a") as HTMLCanvasElement;
+	const b = document.getElementById("b") as HTMLCanvasElement;
+	const before = a.getBoundingClientRect();
+	a.getContext("2d");
+	b.getContext("termdom-cellgrid");
+	await nextFrame(dom);
+	for (const canvas of [a, b]) {
+		const rect = canvas.getBoundingClientRect();
+		expect([rect.width, rect.height]).toEqual([before.width, before.height]);
+	}
 	dom.dispose();
 });
 
@@ -124,8 +161,12 @@ test("fillRect fills pixels, and fillStyle reads back as HTML serializes it", as
 });
 
 test("drawing repaints the canvas's cells without any DOM change", async () => {
-	const {dom, terminal, document} =
-		await mount("<canvas id=c width=16 height=32></canvas>");
+	const {dom, terminal, document} = await mount(
+		"<canvas id=c width=16 height=32></canvas>",
+		40,
+		12,
+		PIXELS,
+	);
 	const ctx = context2d(document);
 	ctx.fillStyle = "#ff0000";
 	ctx.fillRect(0, 0, 16, 8);
@@ -478,8 +519,12 @@ test("toDataURL and toBlob encode PNG", async () => {
 });
 
 test("setting width or height clears the canvas and resets its state", async () => {
-	const {dom, document} =
-		await mount("<canvas id=c width=8 height=8></canvas>");
+	const {dom, document} = await mount(
+		"<canvas id=c width=8 height=8></canvas>",
+		40,
+		12,
+		PIXELS,
+	);
 	const canvas = document.getElementById("c") as HTMLCanvasElement;
 	const ctx = canvas.getContext("2d")!;
 	ctx.fillStyle = "#ff0000";
@@ -491,7 +536,7 @@ test("setting width or height clears the canvas and resets its state", async ()
 	expect(ctx.getTransform().isIdentity).toBe(true);
 	canvas.height = 48;
 	await nextFrame(dom);
-	expect(canvas.getBoundingClientRect().height).toBe(3);
+	expect(canvas.getBoundingClientRect().height / 16).toBe(3);
 	dom.dispose();
 });
 
@@ -523,8 +568,12 @@ test("hit testing: isPointInPath and isPointInStroke, with Path2D", async () =>
 });
 
 test("fillText draws text as cells over the pixels", async () => {
-	const {dom, terminal, document} =
-		await mount("<canvas id=c width=80 height=32></canvas>");
+	const {dom, terminal, document} = await mount(
+		"<canvas id=c width=80 height=32></canvas>",
+		40,
+		12,
+		PIXELS,
+	);
 	const ctx = context2d(document);
 	ctx.fillStyle = "#202020";
 	ctx.fillRect(0, 0, 80, 32);
@@ -547,8 +596,12 @@ test("fillText draws text as cells over the pixels", async () => {
 });
 
 test("textAlign centers and right-aligns text on its anchor", async () => {
-	const {dom, terminal, document} =
-		await mount("<canvas id=c width=160 height=48></canvas>");
+	const {dom, terminal, document} = await mount(
+		"<canvas id=c width=160 height=48></canvas>",
+		40,
+		12,
+		PIXELS,
+	);
 	const ctx = context2d(document);
 	ctx.fillStyle = "#ffffff";
 	ctx.textBaseline = "top";
@@ -565,6 +618,9 @@ test("textAlign centers and right-aligns text on its anchor", async () => {
 test("a 2d context's start follows the canvas's direction, and rtl text draws in visual order", async () => {
 	const {dom, terminal, document} = await mount(
 		"<canvas id=c width=160 height=48 style=\"direction: rtl\"></canvas>",
+		40,
+		12,
+		PIXELS,
 	);
 	const ctx = context2d(document);
 	ctx.fillStyle = "#ffffff";
@@ -856,6 +912,54 @@ test("a cell grid follows a 2d context on maxWidth, lineJoin, lineStyle and draw
 	dom.dispose();
 });
 
+test("a cell grid holds the cells its canvas's box holds", async () => {
+	const {dom, document} = await mount(
+		"<canvas id=a width=96 height=48></canvas>" +
+		"<canvas id=b style=\"width: 12ch; height: 3ch\"></canvas>",
+		40,
+		12,
+		PIXELS,
+	);
+	const a = (document.getElementById("a") as HTMLCanvasElement)
+		.getContext("termdom-cellgrid")!;
+	const b = (document.getElementById("b") as HTMLCanvasElement)
+		.getContext("termdom-cellgrid")!;
+	expect([a.cols, a.rows]).toEqual([12, 3]);
+	expect([b.cols, b.rows]).toEqual([12, 3]);
+	dom.dispose();
+});
+
+test("a cell grid knows its size before layout", async () => {
+	const {dom, document} = await mount("");
+	const canvas = document.createElement("canvas");
+	canvas.width = 20;
+	canvas.height = 5;
+	const grid = canvas.getContext("termdom-cellgrid")!;
+	expect([grid.cols, grid.rows]).toEqual([20, 5]);
+	grid.fillText("detached", 0, 0);
+	expect(grid.getCell(0, 0)!.char).toBe("d");
+	dom.dispose();
+});
+
+test("a cell grid keeps what still fits when its box changes size", async () => {
+	const {dom, terminal, document} = await mount(
+		"<canvas id=g width=10 height=2 style=\"width: 10ch; height: 2ch\"></canvas>",
+	);
+	const canvas = document.getElementById("g") as HTMLCanvasElement;
+	const grid = canvas.getContext("termdom-cellgrid")!;
+	grid.fillText("0123456789", 0, 0);
+	canvas.style.width = "4ch";
+	await nextFrame(dom);
+	expect([grid.cols, grid.rows]).toEqual([4, 2]);
+	expect(rowText(terminal, 0)).toBe("0123");
+	canvas.style.width = "8ch";
+	await nextFrame(dom);
+	expect(grid.cols).toBe(8);
+	expect(grid.getCell(3, 0)!.char).toBe("3");
+	expect(grid.getCell(4, 0)).toBeNull();
+	dom.dispose();
+});
+
 test("text that runs past the grid is cut, and wide glyphs take two columns", async () => {
 	const {dom, terminal, document} =
 		await mount("<canvas id=g width=6 height=1></canvas>|");
@@ -1034,10 +1138,14 @@ test("gradients interpolate their colors and alpha without premultiplying", asyn
 });
 
 test("a canvas too large to allocate lays out and draws nothing", async () => {
-	const {dom, document} =
-		await mount("<canvas id=c width=60000 height=60000></canvas>");
+	const {dom, document} = await mount(
+		"<canvas id=c width=60000 height=60000></canvas>",
+		40,
+		12,
+		PIXELS,
+	);
 	const canvas = document.getElementById("c") as HTMLCanvasElement;
-	expect(canvas.getBoundingClientRect().width).toBe(7500);
+	expect(canvas.getBoundingClientRect().width / 8).toBe(7500);
 	const ctx = canvas.getContext("2d")!;
 	ctx.fillRect(0, 0, 10, 10);
 	expect(canvas.toDataURL()).toBe("data:,");
@@ -1186,9 +1294,12 @@ test("with graphics off, a canvas has no 2d context and keeps its cellgrid", asy
 // overflow, scrolled or not, and by its own content box.
 test("a 2d canvas clips to a scroller and paints the rows scrolled into view", async () => {
 	const {dom, terminal, document} = await mount(
-		"<div id=s style=\"height: 2px; overflow: hidden\">" +
+		"<div id=s style=\"height: 2ch; overflow: hidden\">" +
 		"<canvas id=c width=8 height=64 style=\"display: block\"></canvas>" +
 		"</div><p>below</p>",
+		40,
+		12,
+		PIXELS,
 	);
 	const ctx = context2d(document);
 	const bands = ["#ff0000", "#00ff00", "#0000ff", "#ffffff"];
@@ -1200,7 +1311,7 @@ test("a 2d canvas clips to a scroller and paints the rows scrolled into view", a
 	expect(cell(terminal, 0, 0).bg).toBe(0xff0000);
 	expect(cell(terminal, 0, 1).bg).toBe(0x00ff00);
 	expect(rowText(terminal, 2)).toBe("below");
-	document.getElementById("s")!.scrollTop = 2;
+	document.getElementById("s")!.scrollTop = 2 * 16;
 	await nextFrame(dom);
 	expect(cell(terminal, 0, 0).bg).toBe(0x0000ff);
 	expect(cell(terminal, 0, 1).bg).toBe(0xffffff);
@@ -1271,10 +1382,10 @@ test("a 2d canvas wider than a box that clips it paints nothing past the box", a
 test("a 2d canvas in a scroller shifts with the terminal's scroll", async () => {
 	const terminal = new MockProcess({cols: 40, rows: 12});
 	const written = captureRawOutput(terminal);
-	const dom = new TermDOM({transport: terminal.transport});
+	const dom = new TermDOM({transport: terminal.transport, cellSize: PIXELS});
 	await dom.attach();
 	dom.document.body.innerHTML =
-		"<div id=s style=\"height: 6px; overflow: hidden\">" +
+		"<div id=s style=\"height: 6ch; overflow: hidden\">" +
 		"<canvas id=c width=8 height=192 style=\"display: block\"></canvas>" +
 		"</div>";
 	const ctx = context2d(dom.document);
@@ -1285,7 +1396,7 @@ test("a 2d canvas in a scroller shifts with the terminal's scroll", async () =>
 	}
 	await nextFrame(dom);
 	const before = written().length;
-	dom.document.getElementById("s")!.scrollTop = 1;
+	dom.document.getElementById("s")!.scrollTop = 16;
 	await nextFrame(dom);
 	expect(written().slice(before)).toContain("\x1b[1;6r");
 	for (let row = 0; row < 6; row++) {

From d5d7f7d053fa70ac5015c42ea70caa0dda6ba55d Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 13:14:45 -0400
Subject: [PATCH 09/24] Export ColorDepth, the numbers and names colorDepth
 takes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/guides/06-api.md | 10 +++++-----
 src/index.ts          | 16 +++++++++++-----
 2 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/docs/guides/06-api.md b/docs/guides/06-api.md
index 582c6edfa..2de2a3a5c 100644
--- a/docs/guides/06-api.md
+++ b/docs/guides/06-api.md
@@ -68,10 +68,10 @@ Options:
   (default) uses the best way the terminal has, `"cells"` draws them two
   to a cell in half blocks, and `"none"` draws none: images show their `alt` text and
   `getContext("2d")` returns `null`.
-- `colorDepth?: "auto" | 24 | 8 | 4` — the colors the terminal shows,
-  in the bits `screen.colorDepth` reports. With `"auto"` (default),
-  TermDOM asks the terminal. `"rgb"`, `"256"` and `"ansi"` name 24, 8
-  and 4. Any other value throws a `TypeError`. See "Color depth" in the
+- `colorDepth?: "auto" | ColorDepth` — the colors the terminal shows:
+  `24`, `8` or `4`, the bits `screen.colorDepth` reports, or `"rgb"`,
+  `"256"` or `"ansi"`, the same three by name. With `"auto"` (default),
+  TermDOM asks the terminal. Any other value throws a `TypeError`. See "Color depth" in the
   styling guide.
 
 TermDOM reads no environment variables. What the terminal can say, it is
@@ -384,6 +384,6 @@ is a whole server.
   `"fetch"` event.
 - `CanvasCellGridContext`, the class behind a canvas's
   `"termdom-cellgrid"` context.
-- The types `TermDOMOptions`, `TermDOMEventMap`, `CellSize`,
+- The types `TermDOMOptions`, `TermDOMEventMap`, `CellSize`, `ColorDepth`,
   `TerminalTransport`, `TerminalCloseInfo`, `TerminalSize`, `ProcessLike`,
   `TTYReadStream`, `TTYWriteStream` and `SSHSessionLike`.
diff --git a/src/index.ts b/src/index.ts
index 0be85e0c6..d34accb64 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -37,8 +37,8 @@ import {
 	type Window,
 } from "./internal/dom.ts";
 import {
-	type ColorDepth,
 	DEFAULT_ROWS,
+	type ColorDepth as EmittedColorDepth,
 	Exchange,
 	type TerminalCloseInfo,
 	type TerminalResizeEvent,
@@ -161,10 +161,16 @@ export interface TermDOMOptions {
 	 * tmux, which converts 24-bit color for the terminal it runs in, and 8
 	 * otherwise.
 	 */
-	colorDepth?: "auto" | 24 | 8 | 4 | ColorDepth;
+	colorDepth?: "auto" | ColorDepth;
 }
 
-const COLOR_DEPTHS = new Map<unknown, ColorDepth>([
+/**
+ * A color depth: `24`, `8` or `4`, the bits `screen.colorDepth` reports,
+ * or `"rgb"`, `"256"` or `"ansi"`, the same three by name.
+ */
+export type ColorDepth = 24 | 8 | 4 | EmittedColorDepth;
+
+const COLOR_DEPTHS = new Map<unknown, EmittedColorDepth>([
 	[24, "rgb"],
 	[8, "256"],
 	[4, "ansi"],
@@ -175,7 +181,7 @@ const COLOR_DEPTHS = new Map<unknown, ColorDepth>([
 
 function toColorDepth(
 	option: TermDOMOptions["colorDepth"],
-): ColorDepth | undefined {
+): EmittedColorDepth | undefined {
 	if (option === undefined || option === "auto") {
 		return undefined;
 	}
@@ -311,7 +317,7 @@ export interface TermDOM {
 	[kMouseReportingEnabled]: boolean;
 	[kHoverReportingEnabled]: boolean;
 	[kTransport]: TerminalTransport;
-	[kColorDepth]: ColorDepth | undefined;
+	[kColorDepth]: EmittedColorDepth | undefined;
 	[kExchange]: Exchange;
 	// Resolves once the session is established and the first frame written.
 	[kAttachReady]: Promise<void>;

From 34c75d3f3b3b9ccd39766bea8a399d46e70c94a5 Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 13:16:11 -0400
Subject: [PATCH 10/24] Take the progress bar's ::part styling out of the
 launch post's demo

A page's ::part() does not reach inside a built-in control, as in a
browser, and the demo does not need the colors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 website/content/blog/2026-09-22-introducing-termdom.md | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/website/content/blog/2026-09-22-introducing-termdom.md b/website/content/blog/2026-09-22-introducing-termdom.md
index fe56247cc..57b88b763 100644
--- a/website/content/blog/2026-09-22-introducing-termdom.md
+++ b/website/content/blog/2026-09-22-introducing-termdom.md
@@ -29,8 +29,6 @@ document.body.innerHTML = `
     .card { border: 1px solid #5fafff; padding: 0 1ch; width: 36ch; }
     .title { color: #5fafff; font-weight: bold; }
     progress { width: 25ch; }
-    progress::part(bar) { color: green; }
-    progress::part(groove) { color: #444; }
   </style>
   <div class="card">
     <div class="title">Installing</div>
@@ -92,7 +90,7 @@ the terminal.
 
 - **Stylesheets.** CSS from `<style>` elements and `style` attributes
   cascades and inherits as in the browser, translated to ANSI color and
-  text decoration. Modern color syntax, gradients, and `::part` all work.
+  text decoration. Modern color syntax and gradients work.
 - **Layout.** The box model, flexbox, grid, and tables, computed in whole
   cells, with margins, borders, and padding. `position: absolute`,
   `fixed`, and `sticky` do what they do on the web.

From b894232febb863f1bebc7f784a76a74d7a5fa393 Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 13:44:16 -0400
Subject: [PATCH 11/24] Take colorScheme as a TermDOM option, dispose
 asynchronously only, and make canvas contexts only through getContext

- colorScheme, what the program knows of the terminal's background, is
  an option of TermDOM beside colorDepth, not a member of
  TerminalTransport or an option of transportFromProcess and
  transportFromSSH.
- A TermDOM disposes through Symbol.asyncDispose, so await using waits
  for the restores as dispose() does. Symbol.dispose is gone: a
  disposal that writes to a terminal cannot promise it is done when it
  returns.
- new CanvasRenderingContext2D() and new CanvasCellGridContext() throw
  Illegal constructor, as a browser's contexts do, so no internal type
  is in their published signatures. A 2d context's pixels a cell before
  layout follow the canvas's size, not an image's.
- A delayed transition's test waits half a second, not 60 ms, so a
  frame that runs late on Bun no longer ends the delay early.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/guides/06-api.md         | 14 ++++++--------
 src/index.ts                  | 18 +++++++++++++++---
 src/internal/canvas.ts        | 32 +++++++++++++++++++++++++++++---
 src/internal/dom.ts           |  8 +++++---
 src/internal/exchange.ts      | 23 +++++++++--------------
 tests/canvas.test.ts          |  4 ++++
 tests/color-rendering.test.ts |  3 ++-
 tests/document-mode.test.ts   | 10 ++++++----
 tests/media-queries.test.ts   |  6 ++----
 tests/transitions.test.ts     |  2 +-
 10 files changed, 79 insertions(+), 41 deletions(-)

diff --git a/docs/guides/06-api.md b/docs/guides/06-api.md
index 2de2a3a5c..512430aef 100644
--- a/docs/guides/06-api.md
+++ b/docs/guides/06-api.md
@@ -73,6 +73,10 @@ Options:
   `"256"` or `"ansi"`, the same three by name. With `"auto"` (default),
   TermDOM asks the terminal. Any other value throws a `TypeError`. See "Color depth" in the
   styling guide.
+- `colorScheme?: "light" | "dark"` — whether the terminal's background
+  is light or dark, where the program knows. It holds until the
+  terminal answers TermDOM's question about its background, and stands
+  when the terminal gives no answer. Light without either.
 
 TermDOM reads no environment variables. What the terminal can say, it is
 asked, and the rest is an option.
@@ -222,8 +226,8 @@ continues; `window.close()` is the quit. Returns a promise that resolves
 when every queued restore has reached the transport; await it before
 writing further output. The process transport also restores
 shell-critical modes synchronously, so a caller that exits without
-awaiting still leaves the shell usable. `using term = new TermDOM()`
-disposes on scope exit.
+awaiting still leaves the shell usable. `await using term = new TermDOM()`
+disposes on scope exit and waits for it.
 
 ## `installGlobals(term)`
 
@@ -276,9 +280,6 @@ interface TerminalTransport {
 	readonly cols: number; // live: always the current size
 	readonly rows: number;
 	readonly interactive: boolean; // false: plain line output (a pipe)
-	// Optional. Whether the terminal's background is dark, where the
-	// program knows. The terminal's own answer replaces it.
-	readonly colorScheme?: "light" | "dark";
 	// Optional. Takes an error's text somewhere the frame does not share;
 	// true when it did. The engine keeps what it cannot place and prints
 	// it below the document at the end.
@@ -323,8 +324,6 @@ const term = new TermDOM({transport: transportFromProcess(process)});
 - `options.sharesScreen` — overrides `sharesScreen`, which defaults to
   true for the global process (it sits below a shell) and false for
   anything else.
-- `options.colorScheme` — `"light"` or `"dark"`, for the frames before
-  the terminal reports its background.
 
 The wrapper owns all process-level behavior: raw mode, `SIGWINCH` →
 `resizes`, signals → `closed`, `stdout.isTTY` → `interactive`, `stderr`
@@ -358,7 +357,6 @@ new ssh2.Server({hostKeys: [hostKey]}, (client) => {
   does not depend on ssh2.
 - `options.sharesScreen` — defaults to true: the client's shell is above
   the `ssh` command, so the document anchors below it.
-- `options.colorScheme` — as for `transportFromProcess`.
 
 The transport accepts the session's pty request and takes its size, or
 80×24 without one. It accepts the shell request, and `ready` resolves
diff --git a/src/index.ts b/src/index.ts
index d34accb64..9b976b71c 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -162,6 +162,14 @@ export interface TermDOMOptions {
 	 * otherwise.
 	 */
 	colorDepth?: "auto" | ColorDepth;
+
+	/**
+	 * Whether the terminal's background is light or dark, where the
+	 * program knows. It holds until the terminal answers TermDOM's
+	 * question about its background, and is the answer when the terminal
+	 * gives none. Light without either.
+	 */
+	colorScheme?: "light" | "dark";
 }
 
 /**
@@ -445,6 +453,7 @@ export class TermDOM extends EventTarget {
 			this[kLayout],
 			this[kCascade],
 			this[kFramebuffer],
+			options.colorScheme,
 		);
 
 		// The framebuffer measures widths over the exchange's probe channel.
@@ -741,9 +750,12 @@ export class TermDOM extends EventTarget {
 		return this[kExchange].write(output);
 	}
 
-	/** `using dom = new TermDOM()` tears down on scope exit. */
-	[Symbol.dispose](): void {
-		this.dispose();
+	/**
+	 * `await using term = new TermDOM()` disposes on scope exit and waits
+	 * for the restores, as dispose() does.
+	 */
+	[Symbol.asyncDispose](): Promise<void> {
+		return this.dispose();
 	}
 
 	/**
diff --git a/src/internal/canvas.ts b/src/internal/canvas.ts
index a91191092..6f6a54a07 100644
--- a/src/internal/canvas.ts
+++ b/src/internal/canvas.ts
@@ -1743,6 +1743,31 @@ const kPaint = Symbol("paint");
 const kDropText = Symbol("dropText");
 const kDrawText = Symbol("drawText");
 
+// The host getContext() is making a context for. A context made any other
+// way has none, and its constructor is illegal, as a browser's is.
+let constructingHost: CanvasHost | GridHost | null = null;
+
+function takeHost<T extends CanvasHost | GridHost>(): T {
+	const host = constructingHost;
+	constructingHost = null;
+	if (host === null) {
+		throw new TypeError("Illegal constructor");
+	}
+	return host as T;
+}
+
+/** A canvas's 2d context, as getContext("2d") makes it. */
+export function createContext2D(host: CanvasHost): CanvasRenderingContext2D {
+	constructingHost = host;
+	return new CanvasRenderingContext2D();
+}
+
+/** A canvas's cell grid context, as getContext("termdom-cellgrid") makes it. */
+export function createCellGridContext(host: GridHost): CanvasCellGridContext {
+	constructingHost = host;
+	return new CanvasCellGridContext();
+}
+
 export interface CanvasRenderingContext2D {
 	[kHost]: CanvasHost;
 	[kText]: CanvasTextRun[];
@@ -1752,7 +1777,8 @@ export interface CanvasRenderingContext2D {
 }
 
 export class CanvasRenderingContext2D {
-	constructor(host: CanvasHost) {
+	constructor() {
+		const host = takeHost<CanvasHost>();
 		this[kText] = [];
 		this[kState] = defaultState();
 		this[kStack] = [];
@@ -3034,8 +3060,8 @@ export interface CanvasCellGridContext {
  * own.
  */
 export class CanvasCellGridContext {
-	constructor(host: GridHost) {
-		this[kGridHost] = host;
+	constructor() {
+		this[kGridHost] = takeHost<GridHost>();
 		this[kGridState] = defaultGridState();
 		this[kGridStack] = [];
 	}
diff --git a/src/internal/dom.ts b/src/internal/dom.ts
index e22274096..ddf909be3 100644
--- a/src/internal/dom.ts
+++ b/src/internal/dom.ts
@@ -15,6 +15,8 @@ import {
 	CanvasRenderingContext2D,
 	canvasToPNG,
 	clearCanvasText,
+	createCellGridContext,
+	createContext2D,
 	createImageBitmapFrom,
 	getCanvasText,
 	ImageBitmap,
@@ -14547,7 +14549,7 @@ class HTMLCanvasElement extends HTMLElement {
 			if (getAttachedDocument(this)?.[kGraphics] === "none") {
 				return null;
 			}
-			this[kCanvasContext] = new CanvasRenderingContext2D({
+			this[kCanvasContext] = createContext2D({
 				canvas: this,
 				bitmap: () => getCanvasBitmap(this),
 				changed,
@@ -14558,12 +14560,12 @@ class HTMLCanvasElement extends HTMLElement {
 					if (rect && rect.width > 0 && rect.height > 0) {
 						return {x: this.width / rect.width, y: this.height / rect.height};
 					}
-					const cell = getImageCellSize(this as unknown as Node);
+					const cell = getCellSize(this as unknown as Node);
 					return {x: cell.width, y: cell.height};
 				},
 			});
 		} else if (id === "termdom-cellgrid") {
-			this[kCanvasContext] = new CanvasCellGridContext({
+			this[kCanvasContext] = createCellGridContext({
 				canvas: this,
 				cells: () => getCanvasGrid(this),
 				changed,
diff --git a/src/internal/exchange.ts b/src/internal/exchange.ts
index 616f073c9..2d426844e 100644
--- a/src/internal/exchange.ts
+++ b/src/internal/exchange.ts
@@ -35,12 +35,6 @@ export interface TerminalTransport {
 	readonly cols: number;
 	readonly rows: number;
 
-	/**
-	 * Whether the terminal's background is dark, where the program knows.
-	 * The terminal's own answer, when it gives one, replaces it.
-	 */
-	readonly colorScheme?: "light" | "dark";
-
 	/**
 	 * Chunks are strings, so code points never split. Escape sequences may
 	 * split, and the exchange reassembles them.
@@ -864,6 +858,7 @@ const kHasDetectedAnchor = Symbol("hasDetectedAnchor");
 const kCursorDetectionPromise = Symbol("cursorDetectionPromise");
 const kDSRSequence = Symbol("dsrSequence");
 const kColorScheme = Symbol("colorScheme");
+const kStatedColorScheme = Symbol("statedColorScheme");
 const kTerminalBackground = Symbol("terminalBackground");
 const kPendingReplies = Symbol("pendingReplies");
 
@@ -927,6 +922,7 @@ export interface Exchange {
 	// names its mode, so neither takes the other's reply.
 	[kPendingReplies]: PendingReply[];
 	[kColorScheme]: "light" | "dark" | null;
+	[kStatedColorScheme]: "light" | "dark" | undefined;
 	[kTerminalBackground]: number | null;
 	// The BDSM state the terminal reported before we touched it.
 	[kPriorBidiMode]: number | null;
@@ -955,8 +951,10 @@ export class Exchange extends EventTarget {
 		layout: Layout,
 		styles: Cascade,
 		framebuffer: Framebuffer,
+		colorScheme?: "light" | "dark",
 	) {
 		super();
+		this[kStatedColorScheme] = colorScheme;
 		const interactive = transport.interactive;
 		this[kWriter] = null;
 		this[kReader] = null;
@@ -1012,11 +1010,11 @@ export class Exchange extends EventTarget {
 
 	/**
 	 * Whether the terminal's background is light or dark: what the terminal
-	 * said, or before it has, what the transport knows, and light without
+	 * said, or before it has, what the program stated, and light without
 	 * either.
 	 */
 	get colorScheme(): "light" | "dark" {
-		return this[kColorScheme] ?? this[kTransport].colorScheme ?? "light";
+		return this[kColorScheme] ?? this[kStatedColorScheme] ?? "light";
 	}
 
 	/**
@@ -2290,9 +2288,8 @@ export const DEFAULT_ROWS = 24;
 export function transportFromProcess(
 	proc: ProcessLike = process as unknown as ProcessLike,
 	// The global process sits below a shell. A mock or relay owns its
-	// screen. What the caller passes is used as given, and the rest is
-	// asked of the terminal, never read from the environment.
-	options: {sharesScreen?: boolean; colorScheme?: "light" | "dark"} = {},
+	// screen.
+	options: {sharesScreen?: boolean} = {},
 ): TerminalTransport {
 	const sharesScreen =
 		options.sharesScreen ?? proc === (process as unknown as ProcessLike);
@@ -2476,7 +2473,6 @@ export function transportFromProcess(
 			stderr.write(text + "\n");
 			return true;
 		},
-		colorScheme: options.colorScheme,
 		ready: Promise.resolve(),
 		readable,
 		writable,
@@ -2540,7 +2536,7 @@ export function transportFromSSH(
 	session: SSHSessionLike,
 	// The client's shell sits above the ssh command, as a local one does
 	// above a program, so the document anchors below it.
-	options: {sharesScreen?: boolean; colorScheme?: "light" | "dark"} = {},
+	options: {sharesScreen?: boolean} = {},
 ): TerminalTransport {
 	let cols = DEFAULT_COLS;
 	let rows = DEFAULT_ROWS;
@@ -2619,7 +2615,6 @@ export function transportFromSSH(
 		},
 		sharesScreen: options.sharesScreen ?? true,
 		interactive: true,
-		colorScheme: options.colorScheme,
 		ready,
 		readable: new ReadableStream<string>({
 			start(controller) {
diff --git a/tests/canvas.test.ts b/tests/canvas.test.ts
index 45153a393..daf9211b4 100644
--- a/tests/canvas.test.ts
+++ b/tests/canvas.test.ts
@@ -91,6 +91,10 @@ test("getContext hands back one context per canvas, and null for the rest", asyn
 	expect(ctx).toBeInstanceOf((dom.window as any).CanvasRenderingContext2D);
 	expect(grid).toBeInstanceOf(CanvasCellGridContext);
 	expect("CanvasCellGridContext" in dom.window).toBe(false);
+	// Only getContext() makes a context, as in a browser.
+	expect(() => new CanvasCellGridContext()).toThrow(TypeError);
+	expect(() => new (dom.window as any).CanvasRenderingContext2D())
+		.toThrow(TypeError);
 	dom.dispose();
 });
 
diff --git a/tests/color-rendering.test.ts b/tests/color-rendering.test.ts
index 9d81136e5..a1e223cd6 100644
--- a/tests/color-rendering.test.ts
+++ b/tests/color-rendering.test.ts
@@ -357,7 +357,8 @@ test("black paints black, and unstyled text the terminal's own color", async ()
 	for (const scheme of ["light", "dark"] as const) {
 		const terminal = new MockProcess({rows: 4, cols: 20});
 		const dom = new TermDOM({
-			transport: {...terminal.transport, colorScheme: scheme},
+			transport: terminal.transport,
+			colorScheme: scheme,
 		});
 		const {document} = dom;
 		document.body.innerHTML =
diff --git a/tests/document-mode.test.ts b/tests/document-mode.test.ts
index 3a22cfd8c..5ad5eba8b 100644
--- a/tests/document-mode.test.ts
+++ b/tests/document-mode.test.ts
@@ -384,16 +384,18 @@ test("the seal pays out the rows the region painted, not body's own box", async
 	dom.dispose();
 });
 
-test("[Symbol.dispose] tears down, so `using` works", () => {
+test("[Symbol.asyncDispose] disposes, so `await using` works", async () => {
 	const terminal = new MockProcess({rows: 10, cols: 30});
 	const dom = new TermDOM({transport: terminal.sharedTransport});
 	dom.document.body.innerHTML = "<div>hi</div>";
+	expect(Symbol.dispose in dom).toBe(false);
 
-	// The explicit-resource-management hook delegates to dispose().
-	dom[Symbol.dispose]();
+	// The explicit-resource-management hook is dispose().
+	await dom[Symbol.asyncDispose]();
+	expect(dom.document.visibilityState).toBe("hidden");
 
 	// Idempotent with an explicit dispose(); tearing down twice is safe.
-	expect(() => dom.dispose()).not.toThrow();
+	await dom.dispose();
 });
 
 test(":fullscreen matches the element the stack holds", async () => {
diff --git a/tests/media-queries.test.ts b/tests/media-queries.test.ts
index 051d14329..d698f47e3 100644
--- a/tests/media-queries.test.ts
+++ b/tests/media-queries.test.ts
@@ -131,11 +131,9 @@ test("a dark terminal background is prefers-color-scheme: dark from the first fr
 	termdom.dispose();
 });
 
-test("the environment's background stands until the terminal says otherwise", async () => {
+test("the program's stated background stands until the terminal says otherwise", async () => {
 	const proc = new MockProcess({cols: 20, rows: 5});
-	const termdom = new TermDOM({
-		transport: {...proc.transport, colorScheme: "dark"},
-	});
+	const termdom = new TermDOM({transport: proc.transport, colorScheme: "dark"});
 	expect(matches(termdom, "(prefers-color-scheme: dark)")).toBe(true);
 	termdom.dispose();
 
diff --git a/tests/transitions.test.ts b/tests/transitions.test.ts
index 19af05430..b6e86456d 100644
--- a/tests/transitions.test.ts
+++ b/tests/transitions.test.ts
@@ -216,7 +216,7 @@ test("the transition longhands serialize from the shorthand", async () => {
 test("a delayed transition holds its start value, then runs", async () => {
 	const {dom, document, window} = attached(
 		"<style>#box { width: 10px; height: 1px; " +
-		"transition: width 0.05s steps(1, jump-both) 0.06s; }" +
+		"transition: width 0.05s steps(1, jump-both) 0.5s; }" +
 		"</style><div id='box'></div>",
 	);
 	await nextFrame(dom);

From b9d70ac4448e05602228ff1fc9b8be8046da992e Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 13:49:55 -0400
Subject: [PATCH 12/24] Take the transport only from the constructor

attach() no longer takes a transport to swap in before the first
attach. The constructor's transport does nothing until attach(), and a
transport that is not ready yet resolves ready when it is, so binding
late needed nothing more, and the rebind path served only this.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/guides/06-api.md    |  5 +----
 src/index.ts             | 27 ++++-----------------------
 src/internal/exchange.ts | 16 ----------------
 tests/termdom.test.ts    | 32 +++-----------------------------
 4 files changed, 8 insertions(+), 72 deletions(-)

diff --git a/docs/guides/06-api.md b/docs/guides/06-api.md
index 512430aef..876edac60 100644
--- a/docs/guides/06-api.md
+++ b/docs/guides/06-api.md
@@ -182,7 +182,7 @@ term.addEventListener("fetch", (event) => {
 A load `csp` blocks fires `securitypolicyviolation` at its element
 instead. The images guide has both.
 
-### `term.attach(transport?)`
+### `term.attach()`
 
 Puts the terminal in raw mode, starts input handling, mouse reporting,
 and bracketed paste, and paints whatever the document holds. Idempotent;
@@ -197,9 +197,6 @@ until `dispose()`, and `"hidden"` after. It is also `"hidden"` while the
 wheel has been handed to the terminal's scrollback, until the next
 keystroke. `visibilitychange` fires on each change.
 
-Passing a transport rebinds the instance to it, only before the first
-attach.
-
 ### `term.renderANSI(html?)`
 
 Returns the whole document as an ANSI string at the terminal's width:
diff --git a/src/index.ts b/src/index.ts
index 9b976b71c..6577707f5 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -523,32 +523,13 @@ export class TermDOM extends EventTarget {
 	}
 
 	/**
-	 * Takes over the terminal: starts the session, sends the startup queries,
-	 * enables mouse reporting. Passing a transport rebinds to it and
-	 * re-derives everything that depends on the terminal. Only allowed before
-	 * the first attach.
+	 * Takes over the terminal the constructor was given: starts the
+	 * session, sends the startup queries, enables mouse reporting.
 	 */
-	attach(transport: TerminalTransport = this[kTransport]): Promise<void> {
-		const rebinding = transport !== this[kTransport];
-		if (this[kLifecycle] === "disposed") {
-			return this[kAttachReady];
-		}
-		if (isAttached(this)) {
-			if (rebinding) {
-				throw new Error(
-					"attach(): cannot re-attach a live TermDOM to a different " +
-					"transport; attach once, before the first render.",
-				);
-			}
+	attach(): Promise<void> {
+		if (this[kLifecycle] === "disposed" || isAttached(this)) {
 			return this[kAttachReady];
 		}
-		// Re-derive everything that comes from the transport. Only before the
-		// first frame.
-		if (rebinding) {
-			this[kTransport] = transport;
-			this[kFramebuffer].rebind(this[kColorDepth] ?? "256");
-			this[kExchange].rebind(transport);
-		}
 		// Resolves when the first frame has been written. The negotiations'
 		// silence timeouts must not delay that.
 		this[kLifecycle] = "attaching";
diff --git a/src/internal/exchange.ts b/src/internal/exchange.ts
index 2d426844e..b425a2a7c 100644
--- a/src/internal/exchange.ts
+++ b/src/internal/exchange.ts
@@ -1156,22 +1156,6 @@ export class Exchange extends EventTarget {
 		return this[kLastWrite];
 	}
 
-	/**
-	 * Only before the session starts. It cannot change terminals under its
-	 * readers.
-	 */
-	rebind(transport: TerminalTransport): void {
-		if (this[kStarted]) {
-			throw new Error("rebind(): the session has already started");
-		}
-		this[kTransport] = transport;
-		this[kInteractive] = transport.interactive;
-		this[kAnchorDetectionEnabled] =
-			transport.sharesScreen && transport.interactive;
-		this[kWidths] = createWidthProbes(transport.interactive);
-		terminalResized(this, transport.cols, transport.rows);
-	}
-
 	start(input: Input): void {
 		if (this[kStarted]) {
 			return;
diff --git a/tests/termdom.test.ts b/tests/termdom.test.ts
index c36c3909b..b188bfb8b 100644
--- a/tests/termdom.test.ts
+++ b/tests/termdom.test.ts
@@ -390,39 +390,13 @@ test("exiting fullscreen restores a coherent document frame", async () => {
 	dom.dispose();
 });
 
-test("a headless TermDOM binds its terminal at attach(), re-deriving size", async () => {
-	// Construct with no process -- the global process stands in until attach.
-	const dom = new TermDOM();
-
-	// Rebind to a specific terminal before the first render: its size, not the
-	// stand-in's, must reach the document (window.innerWidth and layout).
-	const terminal = new MockProcess({rows: 12, cols: 50});
-	dom.attach(terminal.transport);
-	dom.document.body.innerHTML = "<p>bound late</p>";
-	await nextFrame(dom);
-
-	expect(dom.window.innerWidth).toBe(50);
-	expect(dom.window.innerHeight).toBe(12);
-	expect(terminal.getPlainText()).toContain("bound late");
-
-	dom.dispose();
-});
-
-test("attach() is idempotent for its process but rejects a different one", async () => {
+test("attach() is idempotent", async () => {
 	const terminal = new MockProcess({rows: 8, cols: 40});
 	const dom = new TermDOM({transport: terminal.transport});
 
-	dom.attach(); // first attach
-
+	const first = dom.attach();
 	await new Promise((r) => setTimeout(r, 0));
-	dom.attach(); // same transport -> no-op, no throw
-	await new Promise((r) => setTimeout(r, 0));
-	dom.attach(terminal.transport); // still the same transport -> no-op
-
-	// Re-attaching a live instance to a different terminal is not supported.
-	expect(() =>
-		dom.attach(new MockProcess({rows: 5, cols: 5}).transport),
-	).toThrow(/different transport/);
+	expect(dom.attach()).toBe(first);
 
 	dom.dispose();
 });

From 34f133408226d3e80e18510c83f4c5b693296010 Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 13:51:49 -0400
Subject: [PATCH 13/24] Leave document.close()'s scrollback behavior out of the
 guides

It stays as it is for now, undocumented, until document.open(), write()
and close() are worked out for the scrollback.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/guides/02-rendering.md | 6 ------
 docs/guides/06-api.md       | 2 --
 2 files changed, 8 deletions(-)

diff --git a/docs/guides/02-rendering.md b/docs/guides/02-rendering.md
index 00393af6d..795ed7a04 100644
--- a/docs/guides/02-rendering.md
+++ b/docs/guides/02-rendering.md
@@ -44,12 +44,6 @@ region and prints the whole document once more as plain output, so the
 final state sits in the scrollback like the output of any other command,
 and the shell prompt returns below it.
 
-`document.close()` does the same thing without ending the program: the
-document is written into the scrollback and sealed. The next mutation
-starts a fresh document below it, on a new starting row. A program that
-prints a sequence of reports, one after another, can build each as a
-document and close it.
-
 ### Resizing
 
 When the terminal is resized, the engine asks for the cursor position
diff --git a/docs/guides/06-api.md b/docs/guides/06-api.md
index 876edac60..cd4d07da7 100644
--- a/docs/guides/06-api.md
+++ b/docs/guides/06-api.md
@@ -85,8 +85,6 @@ asked, and the rest is an option.
 
 `document` is a `Document`. Setting `document.title` sets the terminal
 window title; the previous title is restored on `dispose()`.
-`document.close()` writes the document into the scrollback and seals
-it, and the next mutation starts a fresh document below it.
 
 `window` has the DOM interfaces and event constructors, and these members
 are wired to the terminal:

From b016ef8c752df0b1a0b8b3f6b123b7f5c2639bcf Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 13:59:29 -0400
Subject: [PATCH 14/24] Leave the cell grid overload off the internal canvas
 class

It made getContext drift from lib.dom's. Importing the package declares
the overload on lib.dom's HTMLCanvasElement, which is where callers'
types come from.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/internal/dom.ts | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/src/internal/dom.ts b/src/internal/dom.ts
index ddf909be3..3ffdbc8ab 100644
--- a/src/internal/dom.ts
+++ b/src/internal/dom.ts
@@ -14497,10 +14497,6 @@ class HTMLCanvasElement extends HTMLElement {
 		contextId: "2d",
 		options?: globalThis.CanvasRenderingContext2DSettings,
 	): globalThis.CanvasRenderingContext2D | null;
-	getContext(
-		contextId: "termdom-cellgrid",
-		options?: unknown,
-	): CanvasCellGridContext | null;
 	getContext(
 		contextId: "bitmaprenderer",
 		options?: globalThis.ImageBitmapRenderingContextSettings,

From fc3f0895316244e8c3b52a1e310e39e7efde42f9 Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 14:06:43 -0400
Subject: [PATCH 15/24] Exit with the status a shell expects

window.close() closes with 1 once the page has let an exception escape,
and 0 otherwise; Ctrl-C's close is an interrupt, 130. A SIGINT, SIGHUP
or SIGTERM sent to the process ends it with 128 plus the signal's
number, where it ended with 0. The hint that a blocked load prints is
not an error and does not change the status.

The API guide said a keydown listener could keep Ctrl-C from closing;
Ctrl-C never reaches keydown, and a beforeunload listener is what keeps
the session.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/guides/06-api.md    | 13 +++++---
 src/index.ts             | 22 +++++++++++--
 src/internal/exchange.ts | 32 +++++++++++++------
 tests/attach.test.ts     | 68 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 120 insertions(+), 15 deletions(-)

diff --git a/docs/guides/06-api.md b/docs/guides/06-api.md
index cd4d07da7..0b629b404 100644
--- a/docs/guides/06-api.md
+++ b/docs/guides/06-api.md
@@ -109,10 +109,15 @@ are wired to the terminal:
 - `navigator.userActivation` — `hasBeenActive` and `isActive`
 - `MutationObserver`, `ResizeObserver`, `IntersectionObserver` — entries
   are delivered per rendered frame
-- `close()` — quit: flush the final frame to scrollback, restore terminal
-  modes, dispose, and call `transport.close({status: 0})`, which exits the
-  process on the default transport. Ctrl-C calls this as its default
-  action; a `keydown` listener that calls `preventDefault()` overrides it.
+- `close()` — quit: fire `beforeunload`, then flush the final frame to
+  scrollback, restore terminal modes, dispose, and call
+  `transport.close({status})`, which exits the process on the default
+  transport. A `beforeunload` listener that calls `preventDefault()`
+  keeps the session. Ctrl-C calls `close()`; it does not reach `keydown`.
+  The status is 130 when Ctrl-C closed the window, as a shell reports an
+  interrupt, 1 when the page let an exception escape, and 0 otherwise.
+  On the default transport, a `SIGINT`, `SIGHUP` or `SIGTERM` sent to the
+  process ends it with 130, 129 or 143.
 
 Anything not listed behaves as the DOM and CSSOM standards specify,
 without terminal wiring.
diff --git a/src/index.ts b/src/index.ts
index 6577707f5..cdf072144 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -282,6 +282,7 @@ const FRAME_INTERVAL_MS = 16;
 // Errors the page let escape that no log could take live. Printed below
 // the document when the session ends.
 const kHeldErrors = Symbol("heldErrors");
+const kErrored = Symbol("errored");
 // Held errors handed to the output queue whose write has not finished.
 const kUnwrittenErrors = Symbol("unwrittenErrors");
 const HELD_ERROR_LIMIT = 50;
@@ -309,6 +310,7 @@ export interface TermDOM {
 	[kFlowPainted]: boolean;
 	[kLastFrameAt]: number;
 	[kHeldErrors]: string[];
+	[kErrored]: boolean;
 	[kUnwrittenErrors]: string | null;
 	// Timestamps observer entries.
 	[kRenderCount]: number;
@@ -363,6 +365,7 @@ export class TermDOM extends EventTarget {
 		this[kFlowPainted] = false;
 		this[kLastFrameAt] = -Infinity;
 		this[kHeldErrors] = [];
+		this[kErrored] = false;
 		this[kUnwrittenErrors] = null;
 		this[kRenderCount] = 0;
 		this[kFirstFrame] = null;
@@ -470,7 +473,10 @@ export class TermDOM extends EventTarget {
 				answerRequest(this, document, request, context, requestPolicy),
 			loadSignal: this[kLoads].signal,
 			render: () => render(this),
-			reportUncaught: (error) => reportUncaught(this, error),
+			reportUncaught: (error) => {
+				this[kErrored] = true;
+				reportUncaught(this, error);
+			},
 		});
 		// The document had no size until it was attached, so an @media rule
 		// in the markup was read against a zero-width viewport. Attaching is
@@ -806,6 +812,18 @@ export class TermDOM extends EventTarget {
 	}
 }
 
+/**
+ * How the session ended, as an exit status: 130 when Ctrl-C closed it, as
+ * a shell reports an interrupt, 1 when the page let an exception escape,
+ * and 0 otherwise.
+ */
+function getExitStatus(termDOM: TermDOM): number {
+	if (termDOM[kExchange].interrupted) {
+		return 130;
+	}
+	return termDOM[kErrored] ? 1 : 0;
+}
+
 /**
  * An exception the page let escape, once the window's error event has
  * not handled it. A browser would log it to the console and go on. The
@@ -932,7 +950,7 @@ function closeTermDOM(termDOM: TermDOM): void {
 		}
 		await termDOM.dispose();
 		if (live) {
-			termDOM[kTransport].close({status: 0});
+			termDOM[kTransport].close({status: getExitStatus(termDOM)});
 		}
 	})();
 }
diff --git a/src/internal/exchange.ts b/src/internal/exchange.ts
index b425a2a7c..c486e9d8b 100644
--- a/src/internal/exchange.ts
+++ b/src/internal/exchange.ts
@@ -858,6 +858,7 @@ const kHasDetectedAnchor = Symbol("hasDetectedAnchor");
 const kCursorDetectionPromise = Symbol("cursorDetectionPromise");
 const kDSRSequence = Symbol("dsrSequence");
 const kColorScheme = Symbol("colorScheme");
+const kInterrupted = Symbol("interrupted");
 const kStatedColorScheme = Symbol("statedColorScheme");
 const kTerminalBackground = Symbol("terminalBackground");
 const kPendingReplies = Symbol("pendingReplies");
@@ -922,6 +923,7 @@ export interface Exchange {
 	// names its mode, so neither takes the other's reply.
 	[kPendingReplies]: PendingReply[];
 	[kColorScheme]: "light" | "dark" | null;
+	[kInterrupted]: boolean;
 	[kStatedColorScheme]: "light" | "dark" | undefined;
 	[kTerminalBackground]: number | null;
 	// The BDSM state the terminal reported before we touched it.
@@ -968,6 +970,7 @@ export class Exchange extends EventTarget {
 		this[kCursorDetectionPromise] = null;
 		this[kPendingReplies] = [];
 		this[kColorScheme] = null;
+		this[kInterrupted] = false;
 		this[kTerminalBackground] = null;
 		this[kPriorBidiMode] = null;
 		this[kGraphemeClustersNegotiated] = false;
@@ -1003,6 +1006,11 @@ export class Exchange extends EventTarget {
 		return this[kTransportClosed];
 	}
 
+	/** Whether Ctrl-C closed the window. */
+	get interrupted(): boolean {
+		return this[kInterrupted];
+	}
+
 	/** The terminal's background as packed RGB, once it has said. */
 	get terminalBackground(): number | null {
 		return this[kTerminalBackground];
@@ -2007,10 +2015,14 @@ function routeItems(session: Exchange, items: WireItem[]): void {
 		switch (item.kind) {
 			case "key":
 				// Raw mode delivers Ctrl-C as data. Closing is the window's
-				// decision.
+				// decision, and a close it allows is an interrupt.
 				if (item.ctrlKey && item.key === "c") {
 					flushKeys();
+					session[kInterrupted] = true;
 					session[kWindow].close();
+					if (!session[kWindow].closed) {
+						session[kInterrupted] = false;
+					}
 					break;
 				}
 				keys.push(item);
@@ -2371,20 +2383,22 @@ export function transportFromProcess(
 				// A SIGINT here is an external kill, since raw mode delivers
 				// Ctrl-C as data. Close, then exit once the session has
 				// disposed.
-				const closeOn = (signal: ProcessSignal, exitAfter: boolean) => {
+				// A process a signal ends exits with 128 plus the signal's
+				// number, as a shell reports it.
+				const closeOn = (signal: ProcessSignal, status: number | null) => {
 					const listener = () => {
-						closedResolve({});
-						if (exitAfter) {
-							setImmediate(() => proc.exit(0));
+						closedResolve({status: status ?? undefined});
+						if (status !== null) {
+							setImmediate(() => proc.exit(status));
 						}
 					};
 					signalListeners.push([signal, listener]);
 					proc.on(signal, listener);
 				};
-				closeOn("SIGINT", true);
-				closeOn("SIGTERM", true);
-				closeOn("SIGHUP", true);
-				closeOn("exit", false);
+				closeOn("SIGINT", 130);
+				closeOn("SIGTERM", 143);
+				closeOn("SIGHUP", 129);
+				closeOn("exit", null);
 			},
 			cancel: disengage,
 			// The default high-water mark would pull at construction and take
diff --git a/tests/attach.test.ts b/tests/attach.test.ts
index 1f4404fb2..73f569b3f 100644
--- a/tests/attach.test.ts
+++ b/tests/attach.test.ts
@@ -393,6 +393,74 @@ test("Ctrl-C fires beforeunload, and a listener can keep the session", async ()
 	expect(watched.closes()).toBe(1);
 });
 
+// A transport that records the exit status each close asks for.
+function statusRecordingTransport(terminal: MockProcess): {
+	transport: any;
+	statuses: Array<number | undefined>;
+} {
+	const base = terminal.transport;
+	const statuses: Array<number | undefined> = [];
+	return {
+		transport: {
+			...base,
+			cols: base.cols,
+			rows: base.rows,
+			close: (info?: {status?: number}) => {
+				statuses.push(info?.status);
+			},
+		},
+		statuses,
+	};
+}
+
+test("window.close() exits 0, or 1 once the page let an error escape", async () => {
+	for (const fail of [false, true]) {
+		const terminal = new MockProcess({cols: 40, rows: 10});
+		const recorded = statusRecordingTransport(terminal);
+		const dom = new TermDOM({transport: recorded.transport});
+		await dom.attach();
+		if (fail) {
+			dom.document.body.addEventListener("go", () => {
+				throw new Error("escaped");
+			});
+			dom.document.body.dispatchEvent(new dom.window.Event("go"));
+		}
+		dom.window.close();
+		await until(() => recorded.statuses.length === 1);
+		expect(recorded.statuses).toEqual([fail ? 1 : 0]);
+	}
+});
+
+test("Ctrl-C exits 130, as a shell reports an interrupt", async () => {
+	const terminal = new MockProcess({cols: 40, rows: 10});
+	const recorded = statusRecordingTransport(terminal);
+	const dom = new TermDOM({transport: recorded.transport});
+	await dom.attach();
+	(terminal.stdin as any).emit("data", Buffer.from("\x03"));
+	await until(() => recorded.statuses.length === 1);
+	expect(recorded.statuses).toEqual([130]);
+});
+
+test("a signal ends the process with 128 plus its number", async () => {
+	for (const [signal, status] of [
+		["SIGINT", 130],
+		["SIGTERM", 143],
+		["SIGHUP", 129],
+	] as const) {
+		const terminal = new MockProcess({cols: 40, rows: 10});
+		const codes: number[] = [];
+		terminal.exit = ((code?: number) => {
+			codes.push(code ?? 0);
+		}) as never;
+		const dom = new TermDOM({transport: terminal.transport});
+		await dom.attach();
+		terminal.emit(signal);
+		await until(() => codes.length > 0);
+		expect(codes[0]).toBe(status);
+		await dom.dispose();
+	}
+});
+
 test("BeforeUnloadEvent is the interface a browser exposes", async () => {
 	const terminal = new MockProcess({cols: 40, rows: 10});
 	const watched = closeCountingTransport(terminal);

From 4f9ad6b99cb2cc3e72b62843426ad0ba8b80e09c Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 14:18:11 -0400
Subject: [PATCH 16/24] Scroll with the keys a browser scrolls with, and move
 through a radio group with the arrows

A keydown nothing canceled scrolls, as in a browser: the arrows a row,
PageUp, PageDown and Space a page, keeping one row of the last in view,
and Home and End to an edge. The nearest scroller around the focus that
can go that way takes the key, and the document otherwise. Keys a field,
a select or editable content takes, and Space on a button, do not
scroll.

The arrows move to the previous or next radio of a group, checking it
and wrapping at the ends.

The git-log, tree, hacker-news, markdown and solitaire examples cancel
the keys they handle, as they would in a browser.

Part of #84.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 examples/git-log.ts              |   2 +
 examples/hacker-news.ts          |   7 ++
 examples/markdown.ts             |   7 +-
 examples/solitaire.ts            |  11 ++
 examples/tree.ts                 |   2 +
 src/internal/dom.ts              |  18 ++++
 src/internal/input.ts            |  67 +++++++++++++
 tests/keyboard-scrolling.test.ts | 166 +++++++++++++++++++++++++++++++
 8 files changed, 279 insertions(+), 1 deletion(-)
 create mode 100644 tests/keyboard-scrolling.test.ts

diff --git a/examples/git-log.ts b/examples/git-log.ts
index b8269ff19..6517113d7 100644
--- a/examples/git-log.ts
+++ b/examples/git-log.ts
@@ -173,6 +173,8 @@ document.addEventListener("keydown", (event: Event) => {
   } else {
     return;
   }
+  // The arrows would also scroll the document, as in a browser.
+  event.preventDefault();
   refresh();
 });
 
diff --git a/examples/hacker-news.ts b/examples/hacker-news.ts
index 5210ab04a..c6ac8c066 100644
--- a/examples/hacker-news.ts
+++ b/examples/hacker-news.ts
@@ -604,8 +604,15 @@ window.addEventListener("resize", () => {
   refresh();
 });
 
+// Keys this page handles that would also scroll the document, as in a
+// browser.
+const SCROLL_KEYS = new Set(["ArrowUp", "ArrowDown", " ", "PageUp", "PageDown"]);
+
 document.addEventListener("keydown", (event: Event) => {
   const key = (event as KeyboardEvent).key;
+  if (SCROLL_KEYS.has(key)) {
+    event.preventDefault();
+  }
   if (key === "q") {
     term.window.close();
     return;
diff --git a/examples/markdown.ts b/examples/markdown.ts
index b696c0139..8b6a03595 100644
--- a/examples/markdown.ts
+++ b/examples/markdown.ts
@@ -252,7 +252,12 @@ const bindings: Record<string, () => void> = {
   G: () => window.scrollBy(0, height()),
 };
 document.addEventListener("keydown", (event: Event) => {
-  bindings[(event as KeyboardEvent).key]?.();
+  const binding = bindings[(event as KeyboardEvent).key];
+  if (binding) {
+    // The keys it binds would also scroll the document, as in a browser.
+    event.preventDefault();
+    binding();
+  }
 });
 // The wheel and the keys above both move the document; the scroll event
 // is where every move ends up.
diff --git a/examples/solitaire.ts b/examples/solitaire.ts
index 8e9c92c35..99c1f1b20 100644
--- a/examples/solitaire.ts
+++ b/examples/solitaire.ts
@@ -1232,6 +1232,17 @@ function *App(this: Context) {
 
   const onkeydown = (event: KeyboardEvent): void => {
     const key = event.key;
+    // The game's keys, not the document's scrolling.
+    if (
+      key === " " ||
+      key.startsWith("Arrow") ||
+      key === "PageUp" ||
+      key === "PageDown" ||
+      key === "Home" ||
+      key === "End"
+    ) {
+      event.preventDefault();
+    }
     if (menu) {
       // While the seed field has focus, letters and digits belong to it;
       // Enter still deals. Tab and Escape leave it, and Tab goes no
diff --git a/examples/tree.ts b/examples/tree.ts
index 469e72a23..dc3449775 100644
--- a/examples/tree.ts
+++ b/examples/tree.ts
@@ -220,6 +220,8 @@ document.addEventListener("keydown", (event: Event) => {
   } else {
     return;
   }
+  // The arrows would also scroll the document, as in a browser.
+  event.preventDefault();
   refresh();
 });
 
diff --git a/src/internal/dom.ts b/src/internal/dom.ts
index 3ffdbc8ab..f54f1ce83 100644
--- a/src/internal/dom.ts
+++ b/src/internal/dom.ts
@@ -17267,6 +17267,24 @@ export class HTMLInputElement extends HTMLElement {
 			// the same reason the readline chords edit.
 				if (key === " " || key === "Enter") {
 					this.click();
+					return;
+				}
+				// The arrows move to the previous or next radio of the group, as
+				// a browser's do, checking it and wrapping at the ends.
+				const step = key === "ArrowUp" || key === "ArrowLeft"
+					? -1
+					: key === "ArrowDown" || key === "ArrowRight" ? 1 : 0;
+				if (this.type === "radio" && step !== 0) {
+					event.preventDefault();
+					const group = getRadioGroup(this).filter(
+						(radio) => radio === this || !isActuallyDisabled(radio),
+					);
+					const next = group[(group.indexOf(this) + step + group.length) %
+						group.length];
+					if (next !== this) {
+						next.focus();
+						next.click();
+					}
 				}
 				return;
 			}
diff --git a/src/internal/input.ts b/src/internal/input.ts
index fe3b3f2f2..3ac1cf3c2 100644
--- a/src/internal/input.ts
+++ b/src/internal/input.ts
@@ -992,6 +992,64 @@ function scrollByWheel(input: Input, target: Element, deltaY: number): boolean {
 	return false;
 }
 
+// Elements whose own keys a scrolling key would take: controls that edit,
+// step or pick with them, and editable content.
+function takesKeys(element: Element): boolean {
+	const tag = element.tagName;
+	return (
+		tag === "INPUT" ||
+		tag === "TEXTAREA" ||
+		tag === "SELECT" ||
+		getEditingHost(element) !== null
+	);
+}
+
+/**
+ * A browser's scrolling keys, as the default action of a keydown nothing
+ * canceled: the arrows a row, PageUp, PageDown and Space a page, Home and
+ * End to an edge. They move the nearest scroller around the focus that can
+ * go that way, and the document otherwise. A page keeps one row of the
+ * last in view.
+ */
+function scrollByKey(input: Input, target: Element, key: string): void {
+	const direction = key === "ArrowUp" || key === "PageUp" || key === "Home"
+		? -1
+		: key === "ArrowDown" || key === "PageDown" || key === " " || key === "End"
+			? 1
+			: 0;
+	if (direction === 0) {
+		return;
+	}
+	const document = input[kDocument];
+	const edge = key === "Home" || key === "End";
+	const page = key === "PageUp" || key === "PageDown" || key === " ";
+	const scroller = getWheelScroller(input, target, direction, "top");
+	if (scroller) {
+		const rowPx = pxFromCells(1, true, document);
+		if (edge) {
+			scroller.scrollTop = direction < 0 ? 0 : scroller.scrollHeight;
+		} else {
+			const rows = page
+				? Math.max(1, Math.round(scroller.clientHeight / rowPx) - 1)
+				: 1;
+			scroller.scrollTop += direction * rows * rowPx;
+		}
+		requestRender(document);
+		return;
+	}
+	if (document.fullscreenElement !== null) {
+		return;
+	}
+	const top = input[kFramebuffer].scrollTop;
+	const rows = page ? Math.max(1, input[kFramebuffer].rows - 1) : 1;
+	scrollDocumentTo(
+		document,
+		edge
+			? (direction < 0 ? 0 : Number.MAX_SAFE_INTEGER)
+			: top + direction * rows,
+	);
+}
+
 /**
  * What a multi-click selects in a text control: a word, the line in a
  * textarea, or an input's whole value. A password's word is its whole
@@ -1345,6 +1403,15 @@ function dispatchKey(input: Input, stroke: WireKey): void {
 
 		// A control's own editing ran above, and claimed its keys.
 		const activation = getKeyboardActivation(targetElement);
+		if (
+			!ctrlKey &&
+			!altKey &&
+			!metaKey &&
+			!(keyName === " " && activation?.space) &&
+			!takesKeys(targetElement)
+		) {
+			scrollByKey(input, targetElement, keyName);
+		}
 		if (activation) {
 			if (
 				(keyName === "Enter" && activation.enter) ||
diff --git a/tests/keyboard-scrolling.test.ts b/tests/keyboard-scrolling.test.ts
new file mode 100644
index 000000000..3a7fba8c4
--- /dev/null
+++ b/tests/keyboard-scrolling.test.ts
@@ -0,0 +1,166 @@
+/**
+ * The keys a browser scrolls with, as the default action of a keydown
+ * nothing canceled: the arrows a row, PageUp, PageDown and Space a page,
+ * Home and End to an edge. They move the nearest scroller around the
+ * focus that can go that way, and the document otherwise, and leave keys
+ * a control or editable content takes alone.
+ */
+import {expect, test} from "@b9g/libuild/test";
+
+import {TermDOM} from "../src/index.ts";
+import {MockProcess, nextFrame, until} from "./test-utils.js";
+
+const KEYS: Record<string, string> = {
+	ArrowUp: "\x1b[A",
+	ArrowDown: "\x1b[B",
+	PageUp: "\x1b[5~",
+	PageDown: "\x1b[6~",
+	Home: "\x1b[H",
+	End: "\x1b[F",
+	" ": " ",
+};
+
+async function press(terminal: MockProcess, key: string): Promise<void> {
+	terminal.stdin.simulateResponse(KEYS[key]);
+	await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+async function longDocument(): Promise<{terminal: MockProcess; dom: TermDOM}> {
+	const terminal = new MockProcess({cols: 20, rows: 10});
+	const dom = new TermDOM({transport: terminal.transport});
+	dom.document.body.innerHTML = Array.from(
+		{length: 40},
+		(_, i) => `<div>row ${i}</div>`,
+	).join("");
+	await dom.attach();
+	await nextFrame(dom);
+	return {terminal, dom};
+}
+
+test("the arrows, the page keys, Space, Home and End scroll the document", async () => {
+	const {terminal, dom} = await longDocument();
+	const {window} = dom;
+	await press(terminal, "ArrowDown");
+	await until(() => window.scrollY === 1);
+	await press(terminal, "PageDown");
+	await until(() => window.scrollY === 10);
+	await press(terminal, " ");
+	await until(() => window.scrollY === 19);
+	await press(terminal, "ArrowUp");
+	await until(() => window.scrollY === 18);
+	await press(terminal, "End");
+	await until(() => window.scrollY === 30);
+	await press(terminal, "PageUp");
+	await until(() => window.scrollY === 21);
+	await press(terminal, "Home");
+	await until(() => window.scrollY === 0);
+	expect(window.scrollY).toBe(0);
+	await dom.dispose();
+});
+
+test("a canceled keydown scrolls nothing", async () => {
+	const {terminal, dom} = await longDocument();
+	let seen = 0;
+	dom.document.addEventListener("keydown", (event) => {
+		seen++;
+		event.preventDefault();
+	});
+	await press(terminal, "ArrowDown");
+	await press(terminal, "PageDown");
+	await until(() => seen === 2);
+	await nextFrame(dom);
+	expect(dom.window.scrollY).toBe(0);
+	await dom.dispose();
+});
+
+test("the nearest scroller around the focus takes the keys first", async () => {
+	const terminal = new MockProcess({cols: 20, rows: 10});
+	const dom = new TermDOM({transport: terminal.transport});
+	const {document} = dom;
+	document.body.innerHTML =
+		"<div id=box tabindex=0 style=\"height: 4px; overflow: auto\">" +
+		Array.from({length: 12}, (_, i) => `<div>line ${i}</div>`).join("") +
+		"</div>" +
+		Array.from({length: 30}, (_, i) => `<div>row ${i}</div>`).join("");
+	await dom.attach();
+	const box = document.getElementById("box")!;
+	box.focus();
+	await nextFrame(dom);
+	await press(terminal, "ArrowDown");
+	await until(() => box.scrollTop === 1);
+	await press(terminal, "PageDown");
+	await until(() => box.scrollTop === 4);
+	await press(terminal, "End");
+	await until(() => box.scrollTop === 8);
+	// At its end, the box lets the next key go to the document.
+	await press(terminal, "ArrowDown");
+	await until(() => dom.window.scrollY === 1);
+	expect(box.scrollTop).toBe(8);
+	await dom.dispose();
+});
+
+test("keys a field or editable content takes do not scroll", async () => {
+	const {terminal, dom} = await longDocument();
+	const {document} = dom;
+	const field = document.createElement("input");
+	const note = document.createElement("div");
+	note.contentEditable = "true";
+	note.textContent = "note";
+	document.body.prepend(field, note);
+	for (const target of [field, note]) {
+		target.focus();
+		await nextFrame(dom);
+		await press(terminal, "End");
+		await press(terminal, " ");
+		await press(terminal, "ArrowDown");
+		await nextFrame(dom);
+		expect(dom.window.scrollY).toBe(0);
+	}
+	await dom.dispose();
+});
+
+test("Space on a button presses it rather than scrolling", async () => {
+	const {terminal, dom} = await longDocument();
+	const {document} = dom;
+	const button = document.createElement("button");
+	button.textContent = "go";
+	let clicks = 0;
+	button.addEventListener("click", () => clicks++);
+	document.body.prepend(button);
+	button.focus();
+	await nextFrame(dom);
+	await press(terminal, " ");
+	await until(() => clicks === 1);
+	await nextFrame(dom);
+	expect(dom.window.scrollY).toBe(0);
+	await dom.dispose();
+});
+
+test("the arrows move through a radio group, checking and wrapping", async () => {
+	const terminal = new MockProcess({cols: 20, rows: 10});
+	const dom = new TermDOM({transport: terminal.transport});
+	const {document} = dom;
+	document.body.innerHTML =
+		"<input type=radio name=size value=s checked>" +
+		"<input type=radio name=size value=m disabled>" +
+		"<input type=radio name=size value=l>" +
+		"<input type=radio name=other value=x>";
+	await dom.attach();
+	const radios = [...document.querySelectorAll("input")] as HTMLInputElement[];
+	const changes: string[] = [];
+	for (const radio of radios) {
+		radio.addEventListener("change", () => changes.push(radio.value));
+	}
+	radios[0].focus();
+	await nextFrame(dom);
+	await press(terminal, "ArrowDown");
+	await until(() => radios[2].checked);
+	expect(document.activeElement).toBe(radios[2]);
+	await press(terminal, "ArrowDown");
+	await until(() => radios[0].checked);
+	await press(terminal, "ArrowUp");
+	await until(() => radios[2].checked);
+	expect(changes).toEqual(["l", "s", "l"]);
+	expect(radios[3].checked).toBe(false);
+	await dom.dispose();
+});

From 8d18b5df96b4dc805d420b01f4db9ae819da5de6 Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 14:22:53 -0400
Subject: [PATCH 17/24] Suspend on Ctrl+Z, as a shell's job control does

Ctrl+Z hands the terminal back, stops the program, and takes the
terminal again when the shell continues it. A document in flow is
written into the scrollback first, so the shell's lines land below it
and the document starts again under them; a fullscreen one leaves the
alternate screen and comes back to it. The document is hidden while
suspended, with visibilitychange on each edge, as a backgrounded tab
reports. Like Ctrl+C, Ctrl+Z is not a key and cannot be canceled.

A transport suspends through an optional suspend(). The process
transport leaves raw mode and sends itself SIGTSTP, which raw mode
keeps the terminal from sending, and goes on at SIGCONT. Where a
transport has no suspend(), over SSH and on Windows, Ctrl+Z is an
ordinary key.

Part of #84.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/index.ts             |  50 ++++++++++++++++++
 src/internal/exchange.ts |  77 ++++++++++++++++++++++++++-
 tests/suspend.test.ts    | 110 +++++++++++++++++++++++++++++++++++++++
 3 files changed, 236 insertions(+), 1 deletion(-)
 create mode 100644 tests/suspend.test.ts

diff --git a/src/index.ts b/src/index.ts
index cdf072144..372513286 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -283,6 +283,7 @@ const FRAME_INTERVAL_MS = 16;
 // the document when the session ends.
 const kHeldErrors = Symbol("heldErrors");
 const kErrored = Symbol("errored");
+const kSuspended = Symbol("suspended");
 // Held errors handed to the output queue whose write has not finished.
 const kUnwrittenErrors = Symbol("unwrittenErrors");
 const HELD_ERROR_LIMIT = 50;
@@ -311,6 +312,7 @@ export interface TermDOM {
 	[kLastFrameAt]: number;
 	[kHeldErrors]: string[];
 	[kErrored]: boolean;
+	[kSuspended]: boolean;
 	[kUnwrittenErrors]: string | null;
 	// Timestamps observer entries.
 	[kRenderCount]: number;
@@ -366,6 +368,7 @@ export class TermDOM extends EventTarget {
 		this[kLastFrameAt] = -Infinity;
 		this[kHeldErrors] = [];
 		this[kErrored] = false;
+		this[kSuspended] = false;
 		this[kUnwrittenErrors] = null;
 		this[kRenderCount] = 0;
 		this[kFirstFrame] = null;
@@ -526,6 +529,11 @@ export class TermDOM extends EventTarget {
 				closeTermDOM(this);
 			}
 		});
+		exchange.addEventListener("suspend", (event) => {
+			if (event.target === exchange) {
+				void suspendTermDOM(this);
+			}
+		});
 	}
 
 	/**
@@ -812,6 +820,48 @@ export class TermDOM extends EventTarget {
 	}
 }
 
+/**
+ * Ctrl+Z: hand the terminal back, stop until the shell continues the
+ * program, and take it again. The document is hidden meanwhile, as a
+ * backgrounded tab is. A document in flow is written into the
+ * scrollback, so the shell's lines land below it and the document starts
+ * again under them; a fullscreen one leaves the alternate screen and
+ * comes back to it.
+ */
+async function suspendTermDOM(termDOM: TermDOM): Promise<void> {
+	const suspend = termDOM[kTransport].suspend;
+	if (
+		suspend === undefined ||
+		termDOM[kLifecycle] !== "attached" ||
+		termDOM[kSuspended]
+	) {
+		return;
+	}
+	termDOM[kSuspended] = true;
+	setDocumentVisible(termDOM.document, false);
+	const fullscreen = isFullscreen(termDOM);
+	if (!fullscreen && termDOM[kRenderCount] > 0) {
+		flushDocument(termDOM);
+		termDOM[kSealed] = true;
+	}
+	termDOM[kExchange].releaseModes();
+	await termDOM[kExchange].flush();
+	await suspend.call(termDOM[kTransport]);
+	termDOM[kSuspended] = false;
+	if (termDOM[kLifecycle] !== "attached") {
+		return;
+	}
+	termDOM[kExchange].reclaimModes();
+	if (termDOM.document.title) {
+		void termDOM[kExchange].setTitle(termDOM.document.title);
+	}
+	if (fullscreen) {
+		termDOM[kFramebuffer].repaintAll();
+	}
+	setDocumentVisible(termDOM.document, true);
+	void render(termDOM);
+}
+
 /**
  * How the session ended, as an exit status: 130 when Ctrl-C closed it, as
  * a shell reports an interrupt, 1 when the page let an exception escape,
diff --git a/src/internal/exchange.ts b/src/internal/exchange.ts
index c486e9d8b..43e374165 100644
--- a/src/internal/exchange.ts
+++ b/src/internal/exchange.ts
@@ -76,6 +76,14 @@ export interface TerminalTransport {
 	/** Hangup, disconnect, process exit. */
 	readonly closed: Promise<TerminalCloseInfo>;
 
+	/**
+	 * Stops the program as a shell's job control does, and resolves when it
+	 * continues. The engine hands the terminal back before it calls this
+	 * and takes it again after. Absent where nothing can suspend the
+	 * program, and Ctrl+Z is then an ordinary key.
+	 */
+	suspend?(): Promise<void>;
+
 	/**
 	 * window.close()'s last act, after the engine has flushed and disposed. A
 	 * transport that owns its medium ends it. One that does not (an embedded
@@ -1136,6 +1144,33 @@ export class Exchange extends EventTarget {
 		void this.write(output);
 	}
 
+	/**
+	 * Resets every engaged mode without forgetting it, so the terminal is
+	 * the shell's while the program is suspended.
+	 */
+	releaseModes(): void {
+		for (const name of MODE_RESTORE_ORDER) {
+			if (this[kEngagedModes].has(name)) {
+				void this.write(MODE_SPELLINGS[name].reset);
+			}
+		}
+		if (this[kPriorBidiMode] === 1) {
+			void this.write(BIDI_IMPLICIT);
+		}
+	}
+
+	/** Sets every engaged mode again once a suspended program continues. */
+	reclaimModes(): void {
+		if (this[kPriorBidiMode] === 1) {
+			void this.write(BIDI_EXPLICIT);
+		}
+		for (const name of MODE_RESTORE_ORDER) {
+			if (this[kEngagedModes].has(name)) {
+				void this.write(MODE_SPELLINGS[name].set);
+			}
+		}
+	}
+
 	restoreEngagedModes(): void {
 		for (const name of MODE_RESTORE_ORDER) {
 			if (this[kEngagedModes].delete(name)) {
@@ -2016,6 +2051,16 @@ function routeItems(session: Exchange, items: WireItem[]): void {
 			case "key":
 				// Raw mode delivers Ctrl-C as data. Closing is the window's
 				// decision, and a close it allows is an interrupt.
+				// Ctrl+Z suspends, where the transport can, and is no key either.
+				if (
+					item.ctrlKey &&
+					item.key === "z" &&
+					session[kTransport].suspend !== undefined
+				) {
+					flushKeys();
+					session.dispatchEvent(new Event("suspend"));
+					break;
+				}
 				if (item.ctrlKey && item.key === "c") {
 					flushKeys();
 					session[kInterrupted] = true;
@@ -2202,7 +2247,8 @@ export interface TTYReadStream {
 	setEncoding?(encoding?: string): this;
 }
 
-type ProcessSignal = "SIGWINCH" | "SIGINT" | "SIGTERM" | "SIGHUP" | "exit";
+type ProcessSignal =
+	"SIGWINCH" | "SIGINT" | "SIGTERM" | "SIGHUP" | "SIGCONT" | "exit";
 
 export interface ProcessLike {
 	stdin?: TTYReadStream;
@@ -2211,6 +2257,10 @@ export interface ProcessLike {
 	on(event: ProcessSignal, listener: () => void): unknown;
 	removeListener?(event: ProcessSignal, listener: () => void): unknown;
 	exit(code?: number): never;
+	// For suspending: the process stops itself with SIGTSTP.
+	pid?: number;
+	platform?: string;
+	kill?(pid: number, signal: string): unknown;
 }
 
 // An app that exits without disposing would strand the shell with no
@@ -2471,6 +2521,31 @@ export function transportFromProcess(
 			stderr.write(text + "\n");
 			return true;
 		},
+		// Job control stops a process with SIGTSTP, which raw mode keeps the
+		// terminal from sending, so the process sends it to itself. Windows
+		// has no such signal.
+		suspend:
+			proc.kill === undefined ||
+			proc.pid === undefined ||
+			(proc.platform ?? process.platform) === "win32"
+				? undefined
+				: () => new Promise<void>((resolve) => {
+					const stdin = proc.stdin;
+					if (!engaged || stdin === undefined) {
+						resolve();
+						return;
+					}
+					stdin.setRawMode?.(false);
+					stdin.pause();
+					const onContinue = () => {
+						proc.removeListener?.("SIGCONT", onContinue);
+						stdin.setRawMode?.(true);
+						stdin.resume();
+						resolve();
+					};
+					proc.on("SIGCONT", onContinue);
+					proc.kill!(proc.pid!, "SIGTSTP");
+				}),
 		ready: Promise.resolve(),
 		readable,
 		writable,
diff --git a/tests/suspend.test.ts b/tests/suspend.test.ts
new file mode 100644
index 000000000..03aa7e0aa
--- /dev/null
+++ b/tests/suspend.test.ts
@@ -0,0 +1,110 @@
+/**
+ * Ctrl+Z suspends the program as a shell's job control does: the engine
+ * hands the terminal back, the transport stops the process until the shell
+ * continues it, and the engine takes the terminal again. The document is
+ * hidden meanwhile. Where the transport cannot suspend, Ctrl+Z is a key.
+ */
+import {expect, test} from "@b9g/libuild/test";
+
+import {TermDOM} from "../src/index.ts";
+import {captureRawOutput, MockProcess, nextFrame, until} from "./test-utils.js";
+
+const CTRL_Z = "\x1a";
+const PASTE_ON = "\x1b[?2004h";
+const PASTE_OFF = "\x1b[?2004l";
+
+test("Ctrl+Z hands the terminal back, suspends, and takes it again", async () => {
+	const terminal = new MockProcess({cols: 30, rows: 8});
+	const written = captureRawOutput(terminal);
+	let resume!: () => void;
+	let suspends = 0;
+	const transport = {
+		...terminal.transport,
+		cols: terminal.transport.cols,
+		rows: terminal.transport.rows,
+		suspend: () => {
+			suspends++;
+			return new Promise<void>((resolve) => {
+				resume = resolve;
+			});
+		},
+	};
+	const dom = new TermDOM({transport});
+	const {document} = dom;
+	document.body.innerHTML = "<p>work in progress</p>";
+	await dom.attach();
+	await nextFrame(dom);
+	const states: string[] = [];
+	document.addEventListener("visibilitychange", () => {
+		states.push(document.visibilityState);
+	});
+	const before = written().length;
+
+	terminal.stdin.simulateResponse(CTRL_Z);
+	await until(() => suspends === 1);
+	expect(document.visibilityState).toBe("hidden");
+	const handedBack = written().slice(before);
+	expect(handedBack).toContain(PASTE_OFF);
+	expect(handedBack).toContain("work in progress");
+	const resumedAt = written().length;
+
+	resume();
+	await until(() => document.visibilityState === "visible");
+	await until(() => written().slice(resumedAt).includes("work in progress"));
+	expect(written().slice(resumedAt)).toContain(PASTE_ON);
+	expect(states).toEqual(["hidden", "visible"]);
+	await dom.dispose();
+});
+
+test("Ctrl+Z is an ordinary key where the transport cannot suspend", async () => {
+	const terminal = new MockProcess({cols: 30, rows: 8});
+	const transport = {
+		...terminal.transport,
+		cols: terminal.transport.cols,
+		rows: terminal.transport.rows,
+		suspend: undefined,
+	};
+	const dom = new TermDOM({transport});
+	await dom.attach();
+	const keys: string[] = [];
+	dom.document.addEventListener("keydown", (event) => {
+		const key = event as KeyboardEvent;
+		keys.push(`${key.ctrlKey ? "ctrl+" : ""}${key.key}`);
+	});
+	terminal.stdin.simulateResponse(CTRL_Z);
+	await until(() => keys.length === 1);
+	expect(keys).toEqual(["ctrl+z"]);
+	await dom.dispose();
+});
+
+test("the process transport stops itself with SIGTSTP and goes on at SIGCONT", async () => {
+	const terminal = new MockProcess({cols: 30, rows: 8});
+	const sent: Array<[number, string]> = [];
+	const raw: boolean[] = [];
+	Object.assign(terminal, {
+		pid: 4242,
+		platform: "linux",
+		kill: (pid: number, signal: string) => {
+			sent.push([pid, signal]);
+		},
+	});
+	const setRawMode = terminal.stdin.setRawMode.bind(terminal.stdin);
+	terminal.stdin.setRawMode = (mode: boolean) => {
+		raw.push(mode);
+		return setRawMode(mode);
+	};
+	const dom = new TermDOM({transport: terminal.transport});
+	await dom.attach();
+	await nextFrame(dom);
+	raw.length = 0;
+
+	terminal.stdin.simulateResponse(CTRL_Z);
+	await until(() => sent.length === 1);
+	expect(sent).toEqual([[4242, "SIGTSTP"]]);
+	expect(raw).toEqual([false]);
+
+	terminal.emit("SIGCONT");
+	await until(() => dom.document.visibilityState === "visible");
+	expect(raw).toEqual([false, true]);
+	await dom.dispose();
+});

From 1cd951e7514c64e62111363dcbfc9d0eff7571cf Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 14:23:42 -0400
Subject: [PATCH 18/24] Document the scrolling keys, radio arrows, Ctrl+Z and
 suspend()

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/guides/05-events-and-input.md | 22 ++++++++++++++++++++--
 docs/guides/06-api.md              | 10 ++++++++--
 2 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/docs/guides/05-events-and-input.md b/docs/guides/05-events-and-input.md
index f9c80efff..0f189d0dc 100644
--- a/docs/guides/05-events-and-input.md
+++ b/docs/guides/05-events-and-input.md
@@ -49,7 +49,15 @@ byte. These limits apply to every terminal application:
   second action instead.
 - `Enter` is the byte for `Ctrl+M` and `Tab` for `Ctrl+I`; the named key
   is what you get, and those chords never arrive.
-- `Ctrl+C` is the interrupt; it never reaches the document.
+- `Ctrl+C` is the interrupt; it never reaches the document. It calls
+  `window.close()`, and a `beforeunload` listener that calls
+  `preventDefault()` keeps the session.
+- `Ctrl+Z` suspends the program, as a shell's job control does, and
+  never reaches the document either. The terminal is handed back and
+  `document.visibilityState` is `"hidden"` until the shell continues the
+  program with `fg`; a document in flow starts again below the shell's
+  lines. Over SSH, and on Windows, where nothing can suspend the program,
+  `Ctrl+Z` is an ordinary key.
 - `Ctrl+L` redraws the screen, as it does in a shell, unless a `keydown`
   listener calls `preventDefault()`.
 - `Ctrl+Shift+letter` is indistinguishable from `Ctrl+letter`.
@@ -156,7 +164,8 @@ field.addEventListener("input", updatePreview);
 `::placeholder` styles a field's placeholder. The caret is the real terminal cursor, and IME composition
 works: CJK input methods compose in the field. `<input type="password">`
 masks its value. A `<textarea>` scrolls to keep its caret in view. A number input takes float syntax only, and ArrowUp and
-ArrowDown step it within `min` and `max`.
+ArrowDown step it within `min` and `max`. The arrows move a radio's
+check to the previous or next radio of its group, wrapping at the ends.
 
 `new FormData(form)` builds the form's entry list: every submittable
 control it owns, in tree order, by the rule its kind has. Submitting a
@@ -297,6 +306,15 @@ pane.scrollTop += 5;
 element.scrollIntoView();
 ```
 
+The keys scroll as a browser's do, as the default action of a `keydown`
+no listener canceled: ArrowUp and ArrowDown a row, PageUp, PageDown and
+Space a page, keeping one row of the last in view, and Home and End to
+an edge. The nearest box around the focused element that can scroll
+that way takes the key, and the document otherwise. Keys a field, a
+`<select>` or editable content takes, and Space on a button, do not
+scroll. A program that uses those keys itself calls `preventDefault()`,
+as it would in a browser.
+
 `scroll` fires on the box, or on the document for the document scroll,
 and `scrollend` follows once scrolling stops. `window.scrollY` reports
 the document position, clamped to the end as soon as it is set.
diff --git a/docs/guides/06-api.md b/docs/guides/06-api.md
index 0b629b404..db0bc2d01 100644
--- a/docs/guides/06-api.md
+++ b/docs/guides/06-api.md
@@ -293,6 +293,10 @@ interface TerminalTransport {
 	readonly resizes: ReadableStream<{cols: number; rows: number}>;
 	readonly ready: Promise<void>; // established; Promise.resolve() if born so
 	readonly closed: Promise<TerminalCloseInfo>; // the terminal went away
+	// Optional. Stops the program as a shell's job control does, and
+	// resolves when it continues; the engine hands the terminal back before
+	// and takes it again after. Without it, Ctrl+Z is an ordinary key.
+	suspend?(): Promise<void>;
 	// Ends the medium if the transport owns it (the process transport exits
 	// the process); a no-op otherwise.
 	close(info?: TerminalCloseInfo): void;
@@ -327,8 +331,10 @@ const term = new TermDOM({transport: transportFromProcess(process)});
 
 The wrapper owns all process-level behavior: raw mode, `SIGWINCH` →
 `resizes`, signals → `closed`, `stdout.isTTY` → `interactive`, `stderr`
-when it is not a terminal → `logError`, and an exit hook that restores
-the cursor if the app exits without disposing.
+when it is not a terminal → `logError`, `suspend()` by leaving raw
+mode and sending the process `SIGTSTP` until `SIGCONT` (not on Windows),
+and an exit hook that restores the cursor if the app exits without
+disposing.
 
 ## `transportFromSSH(session, options?)`
 

From e1b02fcede434ec4a18cd8206befda8ecbc37640 Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 14:33:17 -0400
Subject: [PATCH 19/24] Fold a long line in the hacker-news example

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 examples/hacker-news.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/examples/hacker-news.ts b/examples/hacker-news.ts
index c6ac8c066..91627c61d 100644
--- a/examples/hacker-news.ts
+++ b/examples/hacker-news.ts
@@ -606,7 +606,8 @@ window.addEventListener("resize", () => {
 
 // Keys this page handles that would also scroll the document, as in a
 // browser.
-const SCROLL_KEYS = new Set(["ArrowUp", "ArrowDown", " ", "PageUp", "PageDown"]);
+const SCROLL_KEYS =
+  new Set(["ArrowUp", "ArrowDown", " ", "PageUp", "PageDown"]);
 
 document.addEventListener("keydown", (event: Event) => {
   const key = (event as KeyboardEvent).key;

From 2863e1e1389107d4ec9945a1d5272d159df495fc Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 14:41:07 -0400
Subject: [PATCH 20/24] Report an exception a window timer or microtask lets
 escape

window.setTimeout(), setInterval() and queueMicrotask() hand the
runtime a callback that reports an exception the way a listener's is
reported, through the window's error event and then the transport's
log, and the page goes on, as in a browser. They were the runtime's own,
whose exceptions ended the process.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/guides/05-events-and-input.md |  7 +++--
 src/internal/dom.ts                | 26 +++++++++++++++---
 tests/errors.test.ts               | 43 ++++++++++++++++++++++++++++++
 3 files changed, 71 insertions(+), 5 deletions(-)

diff --git a/docs/guides/05-events-and-input.md b/docs/guides/05-events-and-input.md
index 0f189d0dc..a13b38ccc 100644
--- a/docs/guides/05-events-and-input.md
+++ b/docs/guides/05-events-and-input.md
@@ -228,8 +228,11 @@ spellcheck.
 ## Errors
 
 An exception that escapes a listener, an event handler attribute, an
-observer callback, or a frame callback is reported as a browser reports
-it. The window hears a cancelable `error` event first:
+observer callback, a frame callback, or a callback given to
+`window.setTimeout()`, `setInterval()` or `queueMicrotask()` is reported
+as a browser reports it. (A bare `setTimeout()` is the runtime's own,
+even after `installGlobals()`, and an exception from it ends the
+program; call the window's.) The window hears a cancelable `error` event first:
 
 ```ts
 window.addEventListener("error", (event) => {
diff --git a/src/internal/dom.ts b/src/internal/dom.ts
index f54f1ce83..2f9a14f34 100644
--- a/src/internal/dom.ts
+++ b/src/internal/dom.ts
@@ -36265,16 +36265,36 @@ const platform = {
 // frames, the clipboard) as it mounts the document.
 function buildWindow(document: Document): Window {
 	const window = new Window(document) as unknown as Record<string, unknown>;
+	// HTML reports an exception a timer or a microtask lets escape, as it
+	// does a listener's, and the page goes on. The runtime's own would end
+	// the process.
+	const guard = (handler: unknown, args: unknown[]): unknown =>
+		typeof handler !== "function"
+			? handler
+			: () => {
+				try {
+					(handler as (...args: unknown[]) => void)(...args);
+				} catch (error) {
+					reportError(error, document);
+				}
+			};
 	Object.assign(window, platform, {
 		// The platform's DOMException, which is the one the DOM and the CSSOM
 		// throw. A caller's `instanceof DOMException` has to match the class
 		// the engine builds its errors from.
 		DOMException: PlatformDOMException,
-		setTimeout: globalThis.setTimeout.bind(globalThis),
+		setTimeout: (handler: unknown, timeout?: number, ...args: unknown[]) =>
+			globalThis.setTimeout(guard(handler, args) as () => void, timeout),
 		clearTimeout: globalThis.clearTimeout.bind(globalThis),
-		setInterval: globalThis.setInterval.bind(globalThis),
+		setInterval: (handler: unknown, timeout?: number, ...args: unknown[]) =>
+			globalThis.setInterval(guard(handler, args) as () => void, timeout),
 		clearInterval: globalThis.clearInterval.bind(globalThis),
-		queueMicrotask: globalThis.queueMicrotask.bind(globalThis),
+		queueMicrotask: (callback: unknown) => {
+			if (typeof callback !== "function") {
+				throw new TypeError("queueMicrotask needs a function");
+			}
+			globalThis.queueMicrotask(guard(callback, []) as () => void);
+		},
 		atob: globalThis.atob.bind(globalThis),
 		btoa: globalThis.btoa.bind(globalThis),
 		fetch: globalThis.fetch.bind(globalThis),
diff --git a/tests/errors.test.ts b/tests/errors.test.ts
index 8577c92d3..3fc55643a 100644
--- a/tests/errors.test.ts
+++ b/tests/errors.test.ts
@@ -118,6 +118,49 @@ test("a frame callback's exception does not stop the frames", async () => {
 	await dom.dispose();
 });
 
+test("a timer's or a microtask's exception is reported, and the page goes on", async () => {
+	const terminal = new MockProcess({rows: 8, cols: 40});
+	const dom = attached(terminal);
+	const {window} = dom;
+	const seen: string[] = [];
+	window.addEventListener("error", (event) => {
+		seen.push((event as ErrorEvent).message);
+		event.preventDefault();
+	});
+	await nextFrame(dom);
+	window.setTimeout((word: string) => {
+		throw new Error(word);
+	}, 0, "timeout");
+	let ticks = 0;
+	const interval = window.setInterval(() => {
+		ticks++;
+		if (ticks <= 2) {
+			throw new Error(`interval ${ticks}`);
+		}
+		window.clearInterval(interval);
+	}, 1);
+	window.queueMicrotask(() => {
+		throw new Error("microtask");
+	});
+	await new Promise((resolve) => setTimeout(resolve, 60));
+	expect(seen.sort()).toEqual([
+		"interval 1",
+		"interval 2",
+		"microtask",
+		"timeout",
+	]);
+	expect(ticks).toBe(3);
+	// A cleared timer still clears.
+	let fired = false;
+	const timer = window.setTimeout(() => {
+		fired = true;
+	}, 5);
+	window.clearTimeout(timer);
+	await new Promise((resolve) => setTimeout(resolve, 20));
+	expect(fired).toBe(false);
+	await dom.dispose();
+});
+
 test("an observer's exception is reported and the observer goes on", async () => {
 	const terminal = new MockProcess({rows: 8, cols: 40});
 	const dom = attached(terminal);

From ff0fbb263b38c4b7a4e629b709f0af8fcbe5d5bf Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 14:56:40 -0400
Subject: [PATCH 21/24] Install the window's globals over the runtime's, and
 report unhandled rejections while installed

installGlobals() puts each of the window's names on globalThis, the
runtime's included, so the process reads as the window does: a bare
setTimeout() reports what it lets escape, and navigator, localStorage
and, on Bun and Deno, addEventListener and alert are the window's.
Uninstalling puts back each name's own descriptor. The runtime's event
classes stay its own: on Bun and Deno its event targets accept only its
own events, and the document accepts them as well.

While installed, a promise rejected with no handler fires
unhandledrejection on the window, as a PromiseRejectionEvent, and one
no listener cancels is reported as an uncaught exception, where the
runtime would end the process. Deno fires its own event at the window
first; a promise the window has heard about is not fired again.

The window's timers call the runtime's own, kept from when the module
loaded, so they do not call themselves once installed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/guides/05-events-and-input.md |   8 +-
 docs/guides/06-api.md              |  43 ++++-----
 scripts/lib-dom-exact.ts           | 142 ++++++++++++++++-------------
 src/index.ts                       | 103 +++++++++++++++++----
 src/internal/dom.ts                |  72 +++++++++++++--
 tests/install-globals.test.ts      |  93 +++++++++++++++++--
 6 files changed, 337 insertions(+), 124 deletions(-)

diff --git a/docs/guides/05-events-and-input.md b/docs/guides/05-events-and-input.md
index a13b38ccc..d6fbe93c7 100644
--- a/docs/guides/05-events-and-input.md
+++ b/docs/guides/05-events-and-input.md
@@ -230,9 +230,11 @@ spellcheck.
 An exception that escapes a listener, an event handler attribute, an
 observer callback, a frame callback, or a callback given to
 `window.setTimeout()`, `setInterval()` or `queueMicrotask()` is reported
-as a browser reports it. (A bare `setTimeout()` is the runtime's own,
-even after `installGlobals()`, and an exception from it ends the
-program; call the window's.) The window hears a cancelable `error` event first:
+as a browser reports it. A bare `setTimeout()` is the runtime's own
+unless `installGlobals()` has put the window's in its place, and an
+exception from the runtime's ends the program. With the globals
+installed, a promise rejected with no handler fires
+`unhandledrejection` on the window and is reported the same way. The window hears a cancelable `error` event first:
 
 ```ts
 window.addEventListener("error", (event) => {
diff --git a/docs/guides/06-api.md b/docs/guides/06-api.md
index db0bc2d01..e9c22c71a 100644
--- a/docs/guides/06-api.md
+++ b/docs/guides/06-api.md
@@ -233,10 +233,12 @@ disposes on scope exit and waits for it.
 
 Defines the window's names on `globalThis`, for code that reads
 `document`, `window`, `Element`, `getSelection` and the like as globals:
-React, Vue, Svelte, CodeMirror. Only names the runtime lacks are
-defined, so Node's `Event`, `fetch` and `navigator` stay Node's, and in a
-browser nothing changes. Methods are bound to the window, and other
-properties read and write through to it, so `scrollY` stays current.
+React, Vue, Svelte, CodeMirror. The process then reads as the window
+does. A name the runtime defines too, such as `setTimeout`,
+`navigator`, `localStorage` or, on Bun and Deno, `addEventListener` and
+`alert`, is the window's until uninstalled. Methods are bound to the
+window, and other properties read and write through to it, so `scrollY`
+stays current.
 
 ```ts
 import {installGlobals, TermDOM} from "@b9g/termdom";
@@ -245,29 +247,22 @@ const term = new TermDOM();
 const uninstall = installGlobals(term);
 ```
 
-It returns a function that removes what it defined. One TermDOM's
+It returns a function that puts back what was there. One TermDOM's
 globals can be installed at a time; calling it again before uninstalling
 throws.
 
-Some runtimes have window-like globals of their own, and those stay the
-runtime's. A bare call to one of these reaches the runtime, not the
-TermDOM, so write `window.` before it:
-
-| Name | Runtime that has its own |
-| --- | --- |
-| `addEventListener`, `removeEventListener`, `dispatchEvent` | Bun, Deno |
-| `postMessage` | Bun |
-| `close` (it exits Deno) | Deno |
-| `location`, `name`, `closed` | Deno |
-| `alert`, `confirm`, `prompt`, `self`, `onerror` | Bun, Deno |
-| `localStorage`, `sessionStorage` | Node, Deno |
-
-Events made with the runtime's `Event` or `CustomEvent` reach the
-document's listeners, and the document's events are instances of the
-runtime's `Event`. What a terminal does not have, such as `indexedDB`
-or `caches`, is not installed, so `typeof indexedDB` is `"undefined"`
-and feature detection takes its fallback. Uninstalling leaves any name
-that other code has redefined since.
+The runtime's event classes, `Event`, `EventTarget`, `CustomEvent`,
+`ErrorEvent` and `MessageEvent`, stay its own: on Bun and Deno the
+runtime's own event targets accept only its own events, and the
+document accepts them too, so they serve both. What a terminal does not
+have, such as `indexedDB` or `caches`, is not installed, so feature
+detection takes its fallback.
+
+While installed, a promise rejected with no handler is the page's: it
+fires `unhandledrejection` on the window, and one no listener cancels is
+reported as an uncaught exception is, where the runtime would end the
+process. Uninstalling leaves any name that other code has redefined
+since.
 
 ## `TerminalTransport`
 
diff --git a/scripts/lib-dom-exact.ts b/scripts/lib-dom-exact.ts
index 03419e041..7a0b952c2 100644
--- a/scripts/lib-dom-exact.ts
+++ b/scripts/lib-dom-exact.ts
@@ -14,116 +14,124 @@ type Identical<A, B> =
 // a subclass that adds no member of its own would otherwise be structurally
 // indistinguishable from its base, and a platform type would match the
 // smallest class of ours it happens to satisfy.
-type Map0<T> = Identical<T, DOM.Event> extends true
-	? globalThis.Event
-	: Identical<T, DOM.CustomEvent> extends true
-		? globalThis.CustomEvent
-		: Identical<T, DOM.BeforeUnloadEvent> extends true
-			? globalThis.BeforeUnloadEvent
-			: Identical<T, DOM.ErrorEvent> extends true
-				? globalThis.ErrorEvent
-				: Identical<T, DOM.MessageEvent> extends true
-					? globalThis.MessageEvent
-					: Identical<T, DOM.HashChangeEvent> extends true
-						? globalThis.HashChangeEvent
-						: Identical<T, DOM.StorageEvent> extends true
-							? globalThis.StorageEvent
-							: Identical<T, DOM.UIEvent> extends true
-								? globalThis.UIEvent
-								: Identical<T, DOM.MouseEvent> extends true
-									? globalThis.MouseEvent
-									: Identical<T, DOM.FocusEvent> extends true
-										? globalThis.FocusEvent
-										: Identical<T, DOM.KeyboardEvent> extends true
-											? globalThis.KeyboardEvent
-											: Identical<T, DOM.CompositionEvent> extends true
-												? globalThis.CompositionEvent
-												: Identical<T, DOM.TextEvent> extends true
-													? globalThis.TextEvent
-													: Identical<T, DOM.InputEvent> extends true
-														? globalThis.InputEvent
-														: Identical<T, DOM.FileList> extends true
-															? globalThis.FileList
-															: Identical<T, DOM.DataTransferItem> extends true
-																? globalThis.DataTransferItem
+type Map0<T> = Identical<T, DOM.PromiseRejectionEvent> extends true
+	? globalThis.PromiseRejectionEvent
+	: Identical<T, DOM.Event> extends true
+		? globalThis.Event
+		: Identical<T, DOM.CustomEvent> extends true
+			? globalThis.CustomEvent
+			: Identical<T, DOM.BeforeUnloadEvent> extends true
+				? globalThis.BeforeUnloadEvent
+				: Identical<T, DOM.ErrorEvent> extends true
+					? globalThis.ErrorEvent
+					: Identical<T, DOM.MessageEvent> extends true
+						? globalThis.MessageEvent
+						: Identical<T, DOM.HashChangeEvent> extends true
+							? globalThis.HashChangeEvent
+							: Identical<T, DOM.StorageEvent> extends true
+								? globalThis.StorageEvent
+								: Identical<T, DOM.UIEvent> extends true
+									? globalThis.UIEvent
+									: Identical<T, DOM.MouseEvent> extends true
+										? globalThis.MouseEvent
+										: Identical<T, DOM.FocusEvent> extends true
+											? globalThis.FocusEvent
+											: Identical<T, DOM.KeyboardEvent> extends true
+												? globalThis.KeyboardEvent
+												: Identical<T, DOM.CompositionEvent> extends true
+													? globalThis.CompositionEvent
+													: Identical<T, DOM.TextEvent> extends true
+														? globalThis.TextEvent
+														: Identical<T, DOM.InputEvent> extends true
+															? globalThis.InputEvent
+															: Identical<T, DOM.FileList> extends true
+																? globalThis.FileList
 																: Identical<
 																	T,
-																	DOM.DataTransferItemList
+																	DOM.DataTransferItem
 																> extends true
-																	? globalThis.DataTransferItemList
-																	: Identical<T, DOM.DataTransfer> extends true
-																		? globalThis.DataTransfer
+																	? globalThis.DataTransferItem
+																	: Identical<
+																		T,
+																		DOM.DataTransferItemList
+																	> extends true
+																		? globalThis.DataTransferItemList
 																		: Identical<
 																			T,
-																			DOM.ClipboardEvent
+																			DOM.DataTransfer
 																		> extends true
-																			? globalThis.ClipboardEvent
+																			? globalThis.DataTransfer
 																			: Identical<
 																				T,
-																				DOM.TransitionEvent
+																				DOM.ClipboardEvent
 																			> extends true
-																				? globalThis.TransitionEvent
+																				? globalThis.ClipboardEvent
 																				: Identical<
 																					T,
-																					DOM.AnimationEvent
+																					DOM.TransitionEvent
 																				> extends true
-																					? globalThis.AnimationEvent
+																					? globalThis.TransitionEvent
 																					: Identical<
 																						T,
-																						DOM.WheelEvent
+																						DOM.AnimationEvent
 																					> extends true
-																						? globalThis.WheelEvent
+																						? globalThis.AnimationEvent
 																						: Identical<
 																							T,
-																							DOM.PointerEvent
+																							DOM.WheelEvent
 																						> extends true
-																							? globalThis.PointerEvent
+																							? globalThis.WheelEvent
 																							: Identical<
 																								T,
-																								DOM.DragEvent
+																								DOM.PointerEvent
 																							> extends true
-																								? globalThis.DragEvent
+																								? globalThis.PointerEvent
 																								: Identical<
 																									T,
-																									DOM.EventTarget
+																									DOM.DragEvent
 																								> extends true
-																									? globalThis.EventTarget
+																									? globalThis.DragEvent
 																									: Identical<
 																										T,
-																										DOM.Node
+																										DOM.EventTarget
 																									> extends true
-																										? globalThis.Node
+																										? globalThis.EventTarget
 																										: Identical<
 																											T,
-																											DOM.MutationRecord
+																											DOM.Node
 																										> extends true
-																											? globalThis.MutationRecord
+																											? globalThis.Node
 																											: Identical<
 																												T,
-																												DOM.MutationObserver
+																												DOM.MutationRecord
 																											> extends true
-																												? globalThis.MutationObserver
+																												? globalThis.MutationRecord
 																												: Identical<
 																													T,
-																													DOM.NodeList
+																													DOM.MutationObserver
 																												> extends true
-																													? globalThis.NodeList
+																													? globalThis.MutationObserver
 																													: Identical<
 																														T,
-																														DOM.HTMLCollection
+																														DOM.NodeList
 																													> extends true
-																														? globalThis.HTMLCollection
+																														? globalThis.NodeList
 																														: Identical<
 																															T,
-																															DOM.HTMLAllCollection
+																															DOM.HTMLCollection
 																														> extends true
-																															? globalThis.HTMLAllCollection
+																															? globalThis.HTMLCollection
 																															: Identical<
 																																T,
-																																DOM.DOMTokenList
+																																DOM.HTMLAllCollection
 																															> extends true
-																																? globalThis.DOMTokenList
-																																: Map1<T>;
+																																? globalThis.HTMLAllCollection
+																																: Identical<
+																																	T,
+																																	DOM.DOMTokenList
+																																> extends true
+																																	? globalThis.DOMTokenList
+																																	: Map1<T>;
 type Map1<T> = Identical<T, DOM.CharacterData> extends true
 	? globalThis.CharacterData
 	: Identical<T, DOM.Text> extends true
@@ -659,6 +667,10 @@ export type MessageEventDrift = Drift<
 	globalThis.MessageEvent
 >;
 export type ErrorEventDrift = Drift<DOM.ErrorEvent, globalThis.ErrorEvent>;
+export type PromiseRejectionEventDrift = Drift<
+	DOM.PromiseRejectionEvent,
+	globalThis.PromiseRejectionEvent
+>;
 export type HashChangeEventDrift = Drift<
 	DOM.HashChangeEvent,
 	globalThis.HashChangeEvent
diff --git a/src/index.ts b/src/index.ts
index 372513286..1cf393ac2 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1452,6 +1452,17 @@ function renderStaticHTML(
 	return renderStatic(renderer, lineEnding);
 }
 
+// The runtime's event classes stay its own. Its EventTargets take only
+// its own events on Bun and Deno, and the document takes them too, so
+// they serve both.
+const RUNTIME_EVENT_CLASSES = new Set([
+	"Event",
+	"EventTarget",
+	"CustomEvent",
+	"ErrorEvent",
+	"MessageEvent",
+]);
+
 // Shared by every copy of this module a process loads, so two copies
 // cannot each install a TermDOM's globals.
 const kGlobalsInstalled = Symbol.for("@b9g/termdom.globalsInstalled");
@@ -1459,11 +1470,14 @@ const kGlobalsInstalled = Symbol.for("@b9g/termdom.globalsInstalled");
 /**
  * Defines the window's names on globalThis, for code that reaches for
  * `document`, `window`, `Element` or `requestAnimationFrame` as globals
- * the way browser code does: frameworks, editors, DOM libraries. Names
- * the runtime defines already are left alone, so Node's `Event` and
- * `fetch` stay Node's, and in a browser nothing changes. Methods are
- * bound to the window and other properties read through to it, so
- * `scrollY` stays current. Returns a function that removes them again.
+ * the way browser code does: frameworks, editors, DOM libraries. The
+ * process then reads as the window does, so a name the runtime defines
+ * too, such as `setTimeout` or `navigator`, is the window's until
+ * uninstalled. The runtime's event classes stay its own. A promise
+ * rejected with no handler fires unhandledrejection on the window and is
+ * reported, where the runtime would end the process. Methods are bound to the window and other
+ * properties read through to it, so `scrollY` stays current. Returns a
+ * function that puts back what was there.
  */
 export function installGlobals(termDOM: TermDOM): () => void {
 	const global = globalThis as Record<string | symbol, unknown>;
@@ -1471,14 +1485,24 @@ export function installGlobals(termDOM: TermDOM): () => void {
 		throw new Error("TermDOM's globals are already installed.");
 	}
 	const window = termDOM.window as unknown as Record<string, unknown>;
-	const installed = new Map<string, PropertyDescriptor>();
+	// Each name's own descriptor on globalThis before, or undefined where
+	// it had none, beside the descriptor put in its place.
+	const installed = new Map<
+		string,
+		{ours: PropertyDescriptor; before: PropertyDescriptor | undefined}
+	>();
 	for (
 		let object: object | null = window;
 		object && object !== Object.prototype;
 		object = Object.getPrototypeOf(object)
 	) {
 		for (const name of Object.getOwnPropertyNames(object)) {
-			if (name === "constructor" || name in globalThis) {
+			if (
+				name === "constructor" ||
+				name === "globalThis" ||
+				installed.has(name) ||
+				(RUNTIME_EVENT_CLASSES.has(name) && name in globalThis)
+			) {
 				continue;
 			}
 			const value = Object.getOwnPropertyDescriptor(object, name)!.value;
@@ -1491,13 +1515,18 @@ export function installGlobals(termDOM: TermDOM): () => void {
 				};
 			} else {
 				// What a terminal does not have, such as indexedDB, throws when
-				// read. Left undefined, `typeof indexedDB` finds it missing, as
-				// feature detection expects.
+				// read. Not installed, `typeof indexedDB` finds it missing, as
+				// feature detection expects, or finds the runtime's.
+				let current: unknown;
 				try {
-					void window[name];
+					current = window[name];
 				} catch (_err) {
 					continue;
 				}
+				// The window's own value is the runtime's already.
+				if (current === global[name]) {
+					continue;
+				}
 				descriptor = {
 					get: () => window[name],
 					set: (next) => {
@@ -1506,10 +1535,45 @@ export function installGlobals(termDOM: TermDOM): () => void {
 					configurable: true,
 				};
 			}
-			Object.defineProperty(globalThis, name, descriptor);
-			installed.set(name, descriptor);
+			const before = Object.getOwnPropertyDescriptor(globalThis, name);
+			try {
+				Object.defineProperty(globalThis, name, descriptor);
+			} catch (_err) {
+				// A runtime's global it does not let be redefined stays its own.
+				continue;
+			}
+			installed.set(name, {ours: descriptor, before});
 		}
 	}
+	// The process is the page's now, so a promise it rejects with no
+	// handler is reported as a browser reports one, with unhandledrejection
+	// on the window, and the program goes on, where a runtime would end it.
+	// Deno fires its own unhandledrejection at the global, which is the
+	// window's now, before it calls the process's listeners, so a promise
+	// the window has heard about is reported without firing again.
+	const heard = new WeakSet<object>();
+	const hear = (event: Event) => {
+		const promise = (event as PromiseRejectionEvent).promise;
+		if (promise instanceof Object) {
+			heard.add(promise);
+		}
+	};
+	termDOM.window.addEventListener("unhandledrejection", hear);
+	const onRejection = (reason: unknown, promise: Promise<unknown>) => {
+		if (!heard.has(promise)) {
+			const event = new termDOM.window.PromiseRejectionEvent(
+				"unhandledrejection",
+				{promise, reason, cancelable: true},
+			);
+			dispatchAsUserAgent(termDOM.window, event);
+			if (event.defaultPrevented) {
+				return;
+			}
+		}
+		termDOM[kErrored] = true;
+		reportUncaught(termDOM, reason);
+	};
+	process.on("unhandledRejection", onRejection);
 	global[kGlobalsInstalled] = true;
 	let uninstalled = false;
 	return () => {
@@ -1517,15 +1581,22 @@ export function installGlobals(termDOM: TermDOM): () => void {
 			return;
 		}
 		uninstalled = true;
+		process.removeListener("unhandledRejection", onRejection);
+		termDOM.window.removeEventListener("unhandledrejection", hear);
 		// A name something else has since redefined is that code's now.
-		for (const [name, ours] of installed) {
+		for (const [name, {ours, before}] of installed) {
 			const current = Object.getOwnPropertyDescriptor(globalThis, name);
 			if (
-				current !== undefined &&
-				current.get === ours.get &&
-				current.value === ours.value
+				current === undefined ||
+				current.get !== ours.get ||
+				current.value !== ours.value
 			) {
+				continue;
+			}
+			if (before === undefined) {
 				delete global[name];
+			} else {
+				Object.defineProperty(globalThis, name, before);
 			}
 		}
 		delete global[kGlobalsInstalled];
diff --git a/src/internal/dom.ts b/src/internal/dom.ts
index 2f9a14f34..62657b2d0 100644
--- a/src/internal/dom.ts
+++ b/src/internal/dom.ts
@@ -1725,6 +1725,43 @@ Object.defineProperty(ErrorEvent.prototype, Symbol.toStringTag, {
 	configurable: true,
 });
 
+const kRejectedPromise = Symbol("rejected promise");
+const kRejectionReason = Symbol("rejection reason");
+
+interface PromiseRejectionEvent {
+	[kRejectedPromise]: Promise<unknown>;
+	[kRejectionReason]: unknown;
+}
+
+/** HTML's unhandledrejection and rejectionhandled events. */
+class PromiseRejectionEvent extends Event {
+	constructor(type: string, eventInitDict: PromiseRejectionEventInit) {
+		super(type, eventInitDict);
+		const init = toDictionary<PromiseRejectionEventInit>(
+			eventInitDict,
+			"A promise rejection event init",
+		);
+		if (!(init.promise instanceof Object)) {
+			throw new TypeError("A promise rejection event needs its promise");
+		}
+		this[kRejectedPromise] = init.promise;
+		this[kRejectionReason] = init.reason;
+	}
+
+	get promise(): Promise<any> {
+		return this[kRejectedPromise];
+	}
+
+	get reason(): any {
+		return this[kRejectionReason];
+	}
+}
+
+Object.defineProperty(PromiseRejectionEvent.prototype, Symbol.toStringTag, {
+	value: "PromiseRejectionEvent",
+	configurable: true,
+});
+
 const kMessageData = Symbol("message data");
 const kOrigin = Symbol("origin");
 const kLastEventId = Symbol("last event id");
@@ -35248,6 +35285,7 @@ export class Window extends EventTarget {
 	declare UIEvent: typeof globalThis.UIEvent;
 	declare MouseEvent: typeof globalThis.MouseEvent;
 	declare ErrorEvent: typeof globalThis.ErrorEvent;
+	declare PromiseRejectionEvent: typeof globalThis.PromiseRejectionEvent;
 	declare PointerEvent: typeof globalThis.PointerEvent;
 	declare WheelEvent: typeof globalThis.WheelEvent;
 	declare KeyboardEvent: typeof globalThis.KeyboardEvent;
@@ -36222,6 +36260,7 @@ const platform = {
 	KeyboardEvent,
 	Location,
 	ErrorEvent,
+	PromiseRejectionEvent,
 	MathMLElement,
 	MessageEvent,
 	MouseEvent,
@@ -36263,6 +36302,20 @@ const platform = {
 // A window starts with its interfaces and the timers any script expects
 // to find. The display fills in the rest (sizing, scrolling, animation
 // frames, the clipboard) as it mounts the document.
+// The runtime's own, as the module found them. installGlobals() puts the
+// window's in their place, and the window's call these.
+const runtime = {
+	setTimeout: globalThis.setTimeout,
+	clearTimeout: globalThis.clearTimeout,
+	setInterval: globalThis.setInterval,
+	clearInterval: globalThis.clearInterval,
+	queueMicrotask: globalThis.queueMicrotask,
+	atob: globalThis.atob,
+	btoa: globalThis.btoa,
+	fetch: globalThis.fetch,
+	structuredClone: globalThis.structuredClone,
+};
+
 function buildWindow(document: Document): Window {
 	const window = new Window(document) as unknown as Record<string, unknown>;
 	// HTML reports an exception a timer or a microtask lets escape, as it
@@ -36284,21 +36337,21 @@ function buildWindow(document: Document): Window {
 		// the engine builds its errors from.
 		DOMException: PlatformDOMException,
 		setTimeout: (handler: unknown, timeout?: number, ...args: unknown[]) =>
-			globalThis.setTimeout(guard(handler, args) as () => void, timeout),
-		clearTimeout: globalThis.clearTimeout.bind(globalThis),
+			runtime.setTimeout(guard(handler, args) as () => void, timeout),
+		clearTimeout: runtime.clearTimeout.bind(globalThis),
 		setInterval: (handler: unknown, timeout?: number, ...args: unknown[]) =>
-			globalThis.setInterval(guard(handler, args) as () => void, timeout),
-		clearInterval: globalThis.clearInterval.bind(globalThis),
+			runtime.setInterval(guard(handler, args) as () => void, timeout),
+		clearInterval: runtime.clearInterval.bind(globalThis),
 		queueMicrotask: (callback: unknown) => {
 			if (typeof callback !== "function") {
 				throw new TypeError("queueMicrotask needs a function");
 			}
-			globalThis.queueMicrotask(guard(callback, []) as () => void);
+			runtime.queueMicrotask(guard(callback, []) as () => void);
 		},
-		atob: globalThis.atob.bind(globalThis),
-		btoa: globalThis.btoa.bind(globalThis),
-		fetch: globalThis.fetch.bind(globalThis),
-		structuredClone: globalThis.structuredClone.bind(globalThis),
+		atob: runtime.atob.bind(globalThis),
+		btoa: runtime.btoa.bind(globalThis),
+		fetch: runtime.fetch.bind(globalThis),
+		structuredClone: runtime.structuredClone.bind(globalThis),
 	});
 	// HTML's legacy factory: new Image(width, height) is an <img> in this
 	// window's document.
@@ -36398,6 +36451,7 @@ export type {
 	MessageEvent,
 	HashChangeEvent,
 	ErrorEvent,
+	PromiseRejectionEvent,
 	StorageEvent,
 	UIEvent,
 	MouseEvent,
diff --git a/tests/install-globals.test.ts b/tests/install-globals.test.ts
index 4d0cc7d34..02248c914 100644
--- a/tests/install-globals.test.ts
+++ b/tests/install-globals.test.ts
@@ -23,20 +23,68 @@ test("installGlobals defines the window's names the runtime lacks", () => {
 	}
 });
 
-test("installGlobals leaves the runtime's own globals alone", () => {
+test("installGlobals puts the window's names over the runtime's, and uninstalling puts them back", () => {
 	const term = new TermDOM();
-	const event = global.Event;
-	const fetch = global.fetch;
+	const names = [
+		"Event",
+		"FormData",
+		"setTimeout",
+		"queueMicrotask",
+		"navigator",
+	];
+	const before = names.map((name) =>
+		Object.getOwnPropertyDescriptor(globalThis, name),
+	);
 	const uninstall = installGlobals(term);
 	try {
-		expect(global.Event).toBe(event);
-		expect(global.fetch).toBe(fetch);
+		expect(global.FormData).toBe(term.window.FormData);
+		expect(global.navigator).toBe(term.window.navigator);
+		// The runtime's event classes stay, and serve the document too.
+		expect(Object.getOwnPropertyDescriptor(globalThis, "Event"))
+			.toEqual(before[0]);
+		const p = term.document.createElement("p");
+		let heard = 0;
+		p.addEventListener("ping", () => heard++);
+		p.dispatchEvent(new global.Event("ping"));
+		expect(heard).toBe(1);
+		// The window's timers still run, and report what they let escape.
+		let ran = false;
+		global.queueMicrotask(() => {
+			ran = true;
+		});
+		return Promise.resolve().then(() => {
+			expect(ran).toBe(true);
+		});
+	} finally {
+		uninstall();
+		term.dispose();
+		names.forEach((name, i) => {
+			expect(Object.getOwnPropertyDescriptor(globalThis, name)).toEqual(
+				before[i],
+			);
+		});
+	}
+});
+
+test("the runtime's own EventTargets and events go on working", () => {
+	const RuntimeEventTarget = EventTarget;
+	const term = new TermDOM();
+	const uninstall = installGlobals(term);
+	try {
+		const target = new RuntimeEventTarget();
+		let heard = 0;
+		target.addEventListener("ping", () => heard++);
+		target.dispatchEvent(new global.Event("ping"));
+		expect(heard).toBe(1);
+		const controller = new AbortController();
+		let aborted = 0;
+		controller.signal.addEventListener("abort", () => aborted++);
+		controller.abort();
+		expect(aborted).toBe(1);
 	} finally {
 		uninstall();
 		term.dispose();
 	}
-	expect(global.Event).toBe(event);
-	expect(global.fetch).toBe(fetch);
 });
 
 test("installed properties read and write through to the window", () => {
@@ -111,3 +159,34 @@ test("the installed state is shared by every copy of the module", () => {
 	}
 	expect(Symbol.for("@b9g/termdom.globalsInstalled") in globalThis).toBe(false);
 });
+
+test("while installed, an unhandled rejection fires unhandledrejection and is reported", () => {
+	const term = new TermDOM();
+	const listeners = process.listenerCount("unhandledRejection");
+	const uninstall = installGlobals(term);
+	expect(process.listenerCount("unhandledRejection")).toBe(listeners + 1);
+	const heard: unknown[] = [];
+	const listener = (event: Event) => {
+		const rejection = event as PromiseRejectionEvent;
+		heard.push(rejection.reason);
+		expect(rejection.promise).toBeInstanceOf(Promise);
+		expect(rejection.cancelable).toBe(true);
+		event.preventDefault();
+	};
+	term.window.addEventListener("unhandledrejection", listener);
+	const reason = new Error("nobody caught me");
+	const promise = Promise.resolve();
+	try {
+		// The listener installGlobals added, called as the runtime calls it.
+		// Emitting the event would reach the test runner's own listener too.
+		const ours = process.listeners("unhandledRejection").at(-1)!;
+		ours(reason, promise);
+		expect(heard).toEqual([reason]);
+	} finally {
+		uninstall();
+	}
+	// Uninstalled, the runtime's own handling is back.
+	expect(process.listenerCount("unhandledRejection")).toBe(listeners);
+	term.window.removeEventListener("unhandledrejection", listener);
+	term.dispose();
+});

From 50d03c80315a299aadd1397b107a8d84f2bd77b9 Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 15:13:42 -0400
Subject: [PATCH 22/24] Bind the runtime's timers the window wraps to the
 global

A browser's setTimeout, queueMicrotask and the rest throw Illegal
invocation when called on anything but the global, and the window's
wrappers called them on the object that kept them, so the site's
sandbox broke for the canvas and CodeMirror examples.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 src/internal/dom.ts | 31 ++++++++++++++++---------------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/src/internal/dom.ts b/src/internal/dom.ts
index 62657b2d0..b4280722f 100644
--- a/src/internal/dom.ts
+++ b/src/internal/dom.ts
@@ -36304,16 +36304,17 @@ const platform = {
 // frames, the clipboard) as it mounts the document.
 // The runtime's own, as the module found them. installGlobals() puts the
 // window's in their place, and the window's call these.
+// Bound, since a browser's throws when called on anything but its global.
 const runtime = {
-	setTimeout: globalThis.setTimeout,
-	clearTimeout: globalThis.clearTimeout,
-	setInterval: globalThis.setInterval,
-	clearInterval: globalThis.clearInterval,
-	queueMicrotask: globalThis.queueMicrotask,
-	atob: globalThis.atob,
-	btoa: globalThis.btoa,
-	fetch: globalThis.fetch,
-	structuredClone: globalThis.structuredClone,
+	setTimeout: globalThis.setTimeout.bind(globalThis),
+	clearTimeout: globalThis.clearTimeout.bind(globalThis),
+	setInterval: globalThis.setInterval.bind(globalThis),
+	clearInterval: globalThis.clearInterval.bind(globalThis),
+	queueMicrotask: globalThis.queueMicrotask.bind(globalThis),
+	atob: globalThis.atob.bind(globalThis),
+	btoa: globalThis.btoa.bind(globalThis),
+	fetch: globalThis.fetch.bind(globalThis),
+	structuredClone: globalThis.structuredClone.bind(globalThis),
 };
 
 function buildWindow(document: Document): Window {
@@ -36338,20 +36339,20 @@ function buildWindow(document: Document): Window {
 		DOMException: PlatformDOMException,
 		setTimeout: (handler: unknown, timeout?: number, ...args: unknown[]) =>
 			runtime.setTimeout(guard(handler, args) as () => void, timeout),
-		clearTimeout: runtime.clearTimeout.bind(globalThis),
+		clearTimeout: runtime.clearTimeout,
 		setInterval: (handler: unknown, timeout?: number, ...args: unknown[]) =>
 			runtime.setInterval(guard(handler, args) as () => void, timeout),
-		clearInterval: runtime.clearInterval.bind(globalThis),
+		clearInterval: runtime.clearInterval,
 		queueMicrotask: (callback: unknown) => {
 			if (typeof callback !== "function") {
 				throw new TypeError("queueMicrotask needs a function");
 			}
 			runtime.queueMicrotask(guard(callback, []) as () => void);
 		},
-		atob: runtime.atob.bind(globalThis),
-		btoa: runtime.btoa.bind(globalThis),
-		fetch: runtime.fetch.bind(globalThis),
-		structuredClone: runtime.structuredClone.bind(globalThis),
+		atob: runtime.atob,
+		btoa: runtime.btoa,
+		fetch: runtime.fetch,
+		structuredClone: runtime.structuredClone,
 	});
 	// HTML's legacy factory: new Image(width, height) is an <img> in this
 	// window's document.

From 855d4512788e19c02c1a10b742f3903869091c25 Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 15:19:46 -0400
Subject: [PATCH 23/24] Say what a server holding many sessions owns itself

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/guides/06-api.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/guides/06-api.md b/docs/guides/06-api.md
index e9c22c71a..d84713426 100644
--- a/docs/guides/06-api.md
+++ b/docs/guides/06-api.md
@@ -374,6 +374,19 @@ To serve an app to real users, an OpenSSH `Match` block with
 [`examples/ssh.ts`](https://github.com/bikeshaving/termdom/blob/main/examples/ssh.ts)
 is a whole server.
 
+A server that holds many sessions in one process gives each its own
+`TermDOM`, and an exception a session's listeners, timers or frames let
+escape is reported to that session's window and log. Two things stay
+the server's, because the process has only one of each:
+
+- Globals. `installGlobals()` puts one window on `globalThis`, so a
+  server passes each session's `document` to its framework instead, as
+  React's `createRoot(term.document.body)` takes it.
+- Promise rejections no one handles. The runtime decides what one does,
+  and Node ends the process, with every session in it. A server that
+  should outlive one session's mistake listens for them itself, with
+  `process.on("unhandledRejection", ...)`.
+
 ## Other exports
 
 `TermDOM`, `installGlobals`, `transportFromProcess` and

From 33ea68ec92b4bd4ac45b3b6c29db56a29f3fb5fb Mon Sep 17 00:00:00 2001
From: Brian Kim <briankimpossible@gmail.com>
Date: Fri, 9 Oct 2026 15:25:18 -0400
Subject: [PATCH 24/24] Keep the runtime's localStorage and sessionStorage
 under installGlobals()

Where the runtime defines them, they stay its own, as its event classes
do: Deno's, and Node's given --localstorage-file, keep what is stored
between runs, where the window's keep it in memory. On Bun and Node 20,
which have none, the window's are installed. Only whether the name is
there is asked, since reading Node's when it has no storage file prints
an ExperimentalWarning, which installing the globals did.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/guides/06-api.md         | 10 +++++++---
 src/index.ts                  | 17 +++++++++++------
 tests/install-globals.test.ts | 29 +++++++++++++++++++++++++++++
 3 files changed, 47 insertions(+), 9 deletions(-)

diff --git a/docs/guides/06-api.md b/docs/guides/06-api.md
index d84713426..c0f90608c 100644
--- a/docs/guides/06-api.md
+++ b/docs/guides/06-api.md
@@ -235,8 +235,8 @@ Defines the window's names on `globalThis`, for code that reads
 `document`, `window`, `Element`, `getSelection` and the like as globals:
 React, Vue, Svelte, CodeMirror. The process then reads as the window
 does. A name the runtime defines too, such as `setTimeout`,
-`navigator`, `localStorage` or, on Bun and Deno, `addEventListener` and
-`alert`, is the window's until uninstalled. Methods are bound to the
+`navigator` or, on Bun and Deno, `addEventListener` and `alert`, is the
+window's until uninstalled. Methods are bound to the
 window, and other properties read and write through to it, so `scrollY`
 stays current.
 
@@ -254,7 +254,11 @@ throws.
 The runtime's event classes, `Event`, `EventTarget`, `CustomEvent`,
 `ErrorEvent` and `MessageEvent`, stay its own: on Bun and Deno the
 runtime's own event targets accept only its own events, and the
-document accepts them too, so they serve both. What a terminal does not
+document accepts them too, so they serve both. So do `localStorage` and
+`sessionStorage` where the runtime has them: Deno's, and Node's given
+`--localstorage-file`, keep what is stored between runs, where the
+window's keep it in memory. On Bun and Node 20, which have none, the
+window's are installed. What a terminal does not
 have, such as `indexedDB` or `caches`, is not installed, so feature
 detection takes its fallback.
 
diff --git a/src/index.ts b/src/index.ts
index 1cf393ac2..bfdbf0226 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1452,15 +1452,20 @@ function renderStaticHTML(
 	return renderStatic(renderer, lineEnding);
 }
 
-// The runtime's event classes stay its own. Its EventTargets take only
-// its own events on Bun and Deno, and the document takes them too, so
-// they serve both.
-const RUNTIME_EVENT_CLASSES = new Set([
+// Names that stay the runtime's wherever it has them. Its event classes:
+// its EventTargets take only its own events on Bun and Deno, and the
+// document takes them too, so they serve both. Its storage: Deno's, and
+// Node's given --localstorage-file, persist where the window's do not,
+// and reading Node's when it has none prints a warning, so only whether
+// the name is there is asked.
+const RUNTIME_KEPT = new Set([
 	"Event",
 	"EventTarget",
 	"CustomEvent",
 	"ErrorEvent",
 	"MessageEvent",
+	"localStorage",
+	"sessionStorage",
 ]);
 
 // Shared by every copy of this module a process loads, so two copies
@@ -1473,7 +1478,7 @@ const kGlobalsInstalled = Symbol.for("@b9g/termdom.globalsInstalled");
  * the way browser code does: frameworks, editors, DOM libraries. The
  * process then reads as the window does, so a name the runtime defines
  * too, such as `setTimeout` or `navigator`, is the window's until
- * uninstalled. The runtime's event classes stay its own. A promise
+ * uninstalled. The runtime's event classes and storage stay its own. A promise
  * rejected with no handler fires unhandledrejection on the window and is
  * reported, where the runtime would end the process. Methods are bound to the window and other
  * properties read through to it, so `scrollY` stays current. Returns a
@@ -1501,7 +1506,7 @@ export function installGlobals(termDOM: TermDOM): () => void {
 				name === "constructor" ||
 				name === "globalThis" ||
 				installed.has(name) ||
-				(RUNTIME_EVENT_CLASSES.has(name) && name in globalThis)
+				(RUNTIME_KEPT.has(name) && name in globalThis)
 			) {
 				continue;
 			}
diff --git a/tests/install-globals.test.ts b/tests/install-globals.test.ts
index 02248c914..1ebaaec85 100644
--- a/tests/install-globals.test.ts
+++ b/tests/install-globals.test.ts
@@ -190,3 +190,32 @@ test("while installed, an unhandled rejection fires unhandledrejection and is re
 	term.window.removeEventListener("unhandledrejection", listener);
 	term.dispose();
 });
+
+test("the runtime's storage stays where it has one, and the window's fills in where it has none", () => {
+	const had = {
+		localStorage: "localStorage" in globalThis,
+		sessionStorage: "sessionStorage" in globalThis,
+	};
+	const before = {
+		localStorage: Object.getOwnPropertyDescriptor(globalThis, "localStorage"),
+		sessionStorage: Object.getOwnPropertyDescriptor(
+			globalThis,
+			"sessionStorage",
+		),
+	};
+	const term = new TermDOM();
+	const uninstall = installGlobals(term);
+	try {
+		for (const name of ["localStorage", "sessionStorage"] as const) {
+			if (had[name]) {
+				expect(Object.getOwnPropertyDescriptor(globalThis, name))
+					.toEqual(before[name]);
+			} else {
+				expect(global[name]).toBe(term.window[name]);
+			}
+		}
+	} finally {
+		uninstall();
+		term.dispose();
+	}
+});