From 3bb7538ce0f479835d6a515e6894918aca4f378f Mon Sep 17 00:00:00 2001
From: Thomas Kosiewski <tk@coder.com>
Date: Mon, 9 Nov 2026 11:51:23 +0000
Subject: [PATCH 1/8] perf: read the viewport once when the replay scans for
 painted graphemes

---
 .../ghosttyWeb/embeddedHarnessHtml.ts         | 21 +++--
 test/integration/renderer-backend.test.ts     | 92 +++++++++++++++++++
 2 files changed, 106 insertions(+), 7 deletions(-)

diff --git a/src/renderer/ghosttyWeb/embeddedHarnessHtml.ts b/src/renderer/ghosttyWeb/embeddedHarnessHtml.ts
index 666368d2..f091acde 100644
--- a/src/renderer/ghosttyWeb/embeddedHarnessHtml.ts
+++ b/src/renderer/ghosttyWeb/embeddedHarnessHtml.ts
@@ -547,24 +547,31 @@ export const EMBEDDED_HARNESS_HTML = `<!doctype html>
         return cells;
       }
 
-      // One grapheme string per viewport cell, '' where getChars() is empty
+      // One grapheme string per viewport cell, '' where the codepoint is 0
       // (blanks and wide-glyph spacers), the same rule as decodeSnapshotCell.
+      // It reads the viewport once: activeBuffer.getLine(row) copies the whole
+      // viewport out of the wasm module for every row, so a loop over the rows
+      // read each cell once per row.
       function getCellGraphemes() {
         const terminal = getReadyTerminal();
         terminal.scrollToBottom();
-        const { cols, rows, activeBuffer, viewportY } =
-          getNormalizedViewportState(terminal);
+        const { cols, rows } = getNormalizedViewportState(terminal);
         const wasmTerm = terminal.wasmTerm;
         invariant(wasmTerm, 'terminal WASM instance is unavailable');
-        const nullCell = activeBuffer.getNullCell();
+        wasmTerm.update();
+        const cells = wasmTerm.getViewport();
+        invariant(
+          cells.length >= rows * cols,
+          'viewport cell count must cover the visible grid',
+        );
         const grid = [];
         for (let row = 0; row < rows; row += 1) {
-          const line = activeBuffer.getLine(viewportY + row);
           const graphemes = [];
           for (let col = 0; col < cols; col += 1) {
-            const cell = line?.getCell(col) ?? nullCell;
             graphemes.push(
-              cell.getChars() === '' ? '' : wasmTerm.getGraphemeString(row, col),
+              cells[row * cols + col].codepoint === 0
+                ? ''
+                : wasmTerm.getGraphemeString(row, col),
             );
           }
           grid.push(graphemes);
diff --git a/test/integration/renderer-backend.test.ts b/test/integration/renderer-backend.test.ts
index 8a1ee507..f580e578 100644
--- a/test/integration/renderer-backend.test.ts
+++ b/test/integration/renderer-backend.test.ts
@@ -1180,6 +1180,98 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
     });
   });
 
+  // The scan of a flush reads the viewport once, and a snapshot reads it row by
+  // row. Both must name the same grapheme in every cell, whatever the screen
+  // holds and however it came to hold it.
+  it('notes the graphemes of every cell as the per-row read of a snapshot names them', async () => {
+    await backend.boot();
+    const { page } = backend as unknown as { page: Page };
+    const noted = new Set<string>();
+    const sizes: string[] = [];
+    // Flushes the chunks, notes their graphemes, and returns the notes so far.
+    const flush = async (chunks: string[]): Promise<string[]> =>
+      page.evaluate(
+        `(async () => {
+          await window.__agentTty.writeBatch(${JSON.stringify(chunks)}, true, 1000);
+          return [...window.__agentTtyPainted.seen];
+        })()`,
+      ) as Promise<string[]>;
+    const readGrids = (): Promise<{ grid: string[][]; cells: string[][] }> =>
+      page.evaluate(
+        `(() => {
+          const snapshot = window.__agentTty.getSnapshot({ includeCells: true });
+          return {
+            grid: window.__agentTty.getCellGraphemes(),
+            cells: snapshot.cells.map((line) => line.cells.map((cell) => cell.char)),
+          };
+        })()`,
+      ) as Promise<{ grid: string[][]; cells: string[][] }>;
+    const check = async (chunks: string[]): Promise<string[][]> => {
+      const painted = await flush(chunks);
+      const { grid, cells } = await readGrids();
+      expect(grid).toEqual(cells);
+      sizes.push(`${String(grid[0]?.length)}x${String(grid.length)}`);
+      for (const grapheme of grid.flat()) {
+        if (grapheme !== '') {
+          noted.add(grapheme);
+        }
+      }
+      expect(new Set(painted)).toEqual(noted);
+      return grid;
+    };
+    const resize = (cols: number, rows: number): Promise<unknown> =>
+      page.evaluate(
+        `window.__agentTty.resize(${String(cols)}, ${String(rows)})`,
+      );
+
+    await resize(80, 24);
+    // Narrow, wide, combining, joined and unassigned glyphs on one screen.
+    const mixed = await check([
+      '\u001b[2J\u001b[Habc \u65e5\u672c\u8a9e e\u0301 \u{1F469}\u200D\u{1F4BB} \u{1F1EF}\u{1F1F5}',
+      '\r\n\u0915\u094D\u0937\u093F \u0378 \ue0b0 a\u0300\u0301 \u{1F44D}\u{1F3FD}',
+    ]);
+    expect(mixed[0]?.slice(0, 5)).toEqual(['a', 'b', 'c', ' ', '\u65e5']);
+    // A wide glyph's trailing spacer cell has no grapheme.
+    expect(mixed[0]?.[5]).toBe('');
+    expect(noted).toContain('e\u0301');
+    expect(noted).toContain('\u{1F469}\u200D\u{1F4BB}');
+    expect(noted).toContain('\u0915\u094D');
+    expect(noted).toContain('\u0937\u093F');
+    expect(noted).toContain('\u0378');
+
+    // Every row changes by scrolling, and no flush writes into a row.
+    const scrolled = await check([
+      Array.from({ length: 40 }, (_, line) => `line ${String(line)}`).join(
+        '\r\n',
+      ),
+    ]);
+    expect(scrolled[0]?.join('').trimEnd()).not.toBe(
+      mixed[0]?.join('').trimEnd(),
+    );
+
+    // The other screen has its own cells and returns the first screen's.
+    await check(['\u001b[?1049h\u001b[2J\u001b[Halt \u{1F600} \u00c5']);
+    await check(['\u001b[?1049l']);
+
+    // The cell pool of ghostty-web grows with the screen and does not shrink,
+    // so the scan must index the viewport by the current width.
+    await resize(120, 40);
+    await check(['\u001b[2J\u001b[Hwide screen \u65e5\u672c']);
+    await resize(40, 10);
+    await check(['\u001b[2J\u001b[Hsmall \u65e5\u672c \u{1F600}']);
+    await resize(100, 30);
+    await check(['\u001b[2J\u001b[Hagain \u{1F1EF}\u{1F1F5}']);
+    expect(sizes).toEqual([
+      '80x24',
+      '80x24',
+      '80x24',
+      '80x24',
+      '120x40',
+      '40x10',
+      '100x30',
+    ]);
+  });
+
   it('allows dispose to be called more than once', async () => {
     await backend.boot();
 

From ba5eb578421f4601c14c9184e900cd932a8e4760 Mon Sep 17 00:00:00 2001
From: Thomas Kosiewski <tk@coder.com>
Date: Mon, 9 Nov 2026 11:54:56 +0000
Subject: [PATCH 2/8] test: scan the viewport in the task of a resize and after
 a shrink

---
 test/integration/renderer-backend.test.ts | 37 +++++++++++++++--------
 1 file changed, 25 insertions(+), 12 deletions(-)

diff --git a/test/integration/renderer-backend.test.ts b/test/integration/renderer-backend.test.ts
index f580e578..d6d0d4dd 100644
--- a/test/integration/renderer-backend.test.ts
+++ b/test/integration/renderer-backend.test.ts
@@ -1196,12 +1196,18 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
           return [...window.__agentTtyPainted.seen];
         })()`,
       ) as Promise<string[]>;
-    const readGrids = (): Promise<{ grid: string[][]; cells: string[][] }> =>
+    // The scan reads first, then the snapshot reads the same screen. A script
+    // runs before the scan, in the same task.
+    const readGrids = (
+      script = '',
+    ): Promise<{ grid: string[][]; cells: string[][] }> =>
       page.evaluate(
         `(() => {
+          ${script}
+          const grid = window.__agentTty.getCellGraphemes();
           const snapshot = window.__agentTty.getSnapshot({ includeCells: true });
           return {
-            grid: window.__agentTty.getCellGraphemes(),
+            grid,
             cells: snapshot.cells.map((line) => line.cells.map((cell) => cell.char)),
           };
         })()`,
@@ -1219,12 +1225,18 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
       expect(new Set(painted)).toEqual(noted);
       return grid;
     };
-    const resize = (cols: number, rows: number): Promise<unknown> =>
-      page.evaluate(
-        `window.__agentTty.resize(${String(cols)}, ${String(rows)})`,
+    // The scan runs in the task of the resize, before any frame updates the
+    // render state, as the note after a resize event of a replay does.
+    const resizeAndRead = async (cols: number, rows: number): Promise<void> => {
+      const { grid, cells } = await readGrids(
+        `window.__agentTty.resize(${String(cols)}, ${String(rows)});`,
       );
+      expect(grid).toHaveLength(rows);
+      expect(grid.every((row) => row.length === cols)).toBe(true);
+      expect(grid).toEqual(cells);
+    };
 
-    await resize(80, 24);
+    await resizeAndRead(80, 24);
     // Narrow, wide, combining, joined and unassigned glyphs on one screen.
     const mixed = await check([
       '\u001b[2J\u001b[Habc \u65e5\u672c\u8a9e e\u0301 \u{1F469}\u200D\u{1F4BB} \u{1F1EF}\u{1F1F5}',
@@ -1253,13 +1265,14 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
     await check(['\u001b[?1049h\u001b[2J\u001b[Halt \u{1F600} \u00c5']);
     await check(['\u001b[?1049l']);
 
-    // The cell pool of ghostty-web grows with the screen and does not shrink,
-    // so the scan must index the viewport by the current width.
-    await resize(120, 40);
-    await check(['\u001b[2J\u001b[Hwide screen \u65e5\u672c']);
-    await resize(40, 10);
+    // The cell pool of ghostty-web grows with the screen and does not shrink.
+    // After a shrink its cells past the screen still hold the larger screen,
+    // so the scan must index the viewport by the width of the screen.
+    await resizeAndRead(120, 40);
+    await check(['x'.repeat(120 * 40)]);
+    await resizeAndRead(40, 10);
     await check(['\u001b[2J\u001b[Hsmall \u65e5\u672c \u{1F600}']);
-    await resize(100, 30);
+    await resizeAndRead(100, 30);
     await check(['\u001b[2J\u001b[Hagain \u{1F1EF}\u{1F1F5}']);
     expect(sizes).toEqual([
       '80x24',

From 99c4bac46942e3c7b2ba35d5268df4eff297f76a Mon Sep 17 00:00:00 2001
From: Thomas Kosiewski <tk@coder.com>
Date: Mon, 9 Nov 2026 11:57:46 +0000
Subject: [PATCH 3/8] test: scan the viewport in the task of a write

---
 test/integration/renderer-backend.test.ts | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/test/integration/renderer-backend.test.ts b/test/integration/renderer-backend.test.ts
index d6d0d4dd..cab3f110 100644
--- a/test/integration/renderer-backend.test.ts
+++ b/test/integration/renderer-backend.test.ts
@@ -1265,6 +1265,15 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
     await check(['\u001b[?1049h\u001b[2J\u001b[Halt \u{1F600} \u00c5']);
     await check(['\u001b[?1049l']);
 
+    // A write changes the wasm screen at once, and the render state follows
+    // a frame later. A scan in the task of the write must not read the old
+    // state.
+    const fresh = await readGrids(
+      `void window.__agentTty.write('\\u001b[2J\\u001b[Hsync');`,
+    );
+    expect(fresh.grid[0]?.slice(0, 4)).toEqual(['s', 'y', 'n', 'c']);
+    expect(fresh.grid).toEqual(fresh.cells);
+
     // The cell pool of ghostty-web grows with the screen and does not shrink.
     // After a shrink its cells past the screen still hold the larger screen,
     // so the scan must index the viewport by the width of the screen.

From 823c8aa0899eee012ea20b301b7792dfb41da0f9 Mon Sep 17 00:00:00 2001
From: Thomas Kosiewski <tk@coder.com>
Date: Mon, 9 Nov 2026 12:00:14 +0000
Subject: [PATCH 4/8] perf: leave the render state update to the viewport read

---
 src/renderer/ghosttyWeb/embeddedHarnessHtml.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/renderer/ghosttyWeb/embeddedHarnessHtml.ts b/src/renderer/ghosttyWeb/embeddedHarnessHtml.ts
index f091acde..55f31d38 100644
--- a/src/renderer/ghosttyWeb/embeddedHarnessHtml.ts
+++ b/src/renderer/ghosttyWeb/embeddedHarnessHtml.ts
@@ -558,7 +558,6 @@ export const EMBEDDED_HARNESS_HTML = `<!doctype html>
         const { cols, rows } = getNormalizedViewportState(terminal);
         const wasmTerm = terminal.wasmTerm;
         invariant(wasmTerm, 'terminal WASM instance is unavailable');
-        wasmTerm.update();
         const cells = wasmTerm.getViewport();
         invariant(
           cells.length >= rows * cols,

From 82fd4eaac72a9d924485d26a7b0bc3a00497b572 Mon Sep 17 00:00:00 2001
From: Thomas Kosiewski <tk@coder.com>
Date: Mon, 9 Nov 2026 16:26:51 +0000
Subject: [PATCH 5/8] perf: read the viewport once when a snapshot decodes the
 screen

activeBuffer.getLine(row) re-reads the whole viewport out of the wasm module on every call. decodeVisibleLines and decodeVisibleCells called it once per row, so a snapshot or a wait poll read each cell once per row. They now read the viewport once with wasmTerm.getViewport() and take the text, width, colour and style of a cell from it.
---
 .../ghosttyWeb/embeddedHarnessHtml.ts         | 104 +++++++++++-------
 1 file changed, 67 insertions(+), 37 deletions(-)

diff --git a/src/renderer/ghosttyWeb/embeddedHarnessHtml.ts b/src/renderer/ghosttyWeb/embeddedHarnessHtml.ts
index 55f31d38..fc48ca64 100644
--- a/src/renderer/ghosttyWeb/embeddedHarnessHtml.ts
+++ b/src/renderer/ghosttyWeb/embeddedHarnessHtml.ts
@@ -71,7 +71,7 @@ export const EMBEDDED_HARNESS_HTML = `<!doctype html>
       <div id="terminal"></div>
     </div>
     <script type="module">
-      import { Terminal, init } from '/assets/ghostty-web.js';
+      import { CellFlags, Terminal, init } from '/assets/ghostty-web.js';
 
       const DEFAULT_COLS = 80;
       const DEFAULT_ROWS = 24;
@@ -386,31 +386,64 @@ export const EMBEDDED_HARNESS_HTML = `<!doctype html>
       }
 
       // Width for a single column, used to drop wide-glyph trailing spacers.
-      // getCell() always returns a cell (out-of-range columns synthesize a
-      // blank width-1 cell), so a missing cell is treated as a blank column.
+      function normalizeCellWidth(width) {
+        return Number.isInteger(width) && width >= 0 ? width : 1;
+      }
+
+      // The width of a column of a scrollback line. getCell() always returns a
+      // cell (out-of-range columns synthesize a blank width-1 cell), so a
+      // missing cell is treated as a blank column.
       function readCellWidth(line, col) {
         const cell = line?.getCell(col);
         if (cell === undefined || cell === null) {
           return 1;
         }
-        const width = cell.getWidth();
-        return Number.isInteger(width) && width >= 0 ? width : 1;
+        return normalizeCellWidth(cell.getWidth());
+      }
+
+      // The cells of the visible screen, row by row: the cell of (row, col) is
+      // cells[row * cols + col]. A decode reads them here, once.
+      // activeBuffer.getLine(row) re-reads the whole viewport out of the wasm
+      // module on every call and copies one row of it, so a loop over the rows
+      // read each cell once per row. The pool that getViewport() returns never
+      // shrinks, so it can hold more cells than the screen: the width of the
+      // screen sets the row stride, not the length of the pool. No update() is
+      // needed first: a read in the task of a write or a resize sees the new
+      // screen.
+      function readViewportCells(wasmTerm, cols, rows) {
+        const cells = wasmTerm.getViewport();
+        invariant(
+          cells.length >= rows * cols,
+          'viewport cell count must cover the visible grid',
+        );
+        return cells;
+      }
+
+      // Whether a cell holds a character: the rule of getChars() in
+      // ghostty-web, which gives '' for codepoint 0 (a blank or a wide glyph's
+      // trailing spacer) and for a value that is not a Unicode scalar value.
+      function cellHasChars(cell) {
+        const codepoint = cell.codepoint;
+        return (
+          codepoint !== 0 &&
+          codepoint <= 0x10ffff &&
+          !(codepoint >= 0xd800 && codepoint <= 0xdfff)
+        );
       }
 
       function decodeVisibleLines(terminal) {
         terminal.scrollToBottom();
-        const { cols, rows, activeBuffer, viewportY } =
-          getNormalizedViewportState(terminal);
+        const { cols, rows } = getNormalizedViewportState(terminal);
         const wasmTerm = terminal.wasmTerm;
         invariant(wasmTerm, 'terminal WASM instance is unavailable');
 
+        const viewport = readViewportCells(wasmTerm, cols, rows);
         const visibleLines = [];
         for (let row = 0; row < rows; row += 1) {
-          const line = activeBuffer.getLine(viewportY + row);
           const text = decodeGraphemeLine(
             (col) => ({
               grapheme: wasmTerm.getGraphemeString(row, col),
-              width: readCellWidth(line, col),
+              width: normalizeCellWidth(viewport[row * cols + col].width),
             }),
             cols,
           );
@@ -465,10 +498,13 @@ export const EMBEDDED_HARNESS_HTML = `<!doctype html>
         return \`#\${colorValue.toString(16).padStart(6, '0')}\`;
       }
 
+      function packRgb(red, green, blue) {
+        return (red << 16) | (green << 8) | blue;
+      }
+
+      // cell is a cell of readViewportCells().
       function decodeSnapshotCell(cell, graphemeChar) {
         invariant(cell !== undefined, 'snapshot cell must be defined');
-        const baseChars = cell.getChars();
-        assertStringValue(baseChars, 'snapshot cell char must be a string');
         assertStringValue(
           graphemeChar,
           'snapshot cell grapheme must be a string',
@@ -484,30 +520,31 @@ export const EMBEDDED_HARNESS_HTML = `<!doctype html>
         // cluster so continuation codepoints (emoji ZWJ, NFD combining marks)
         // are not dropped. The Screen Hash sources visibleLines[].text, never
         // cells[], so this asymmetry never reaches the hash.
-        const char = baseChars === '' ? '' : graphemeChar;
+        const char = cellHasChars(cell) ? graphemeChar : '';
 
-        const isInverse = cell.isInverse() === 1;
-        const fgColor = cell.getFgColor();
-        const bgColor = cell.getBgColor();
+        const isInverse = (cell.flags & CellFlags.INVERSE) !== 0;
+        const fgColor = packRgb(cell.fg_r, cell.fg_g, cell.fg_b);
+        const bgColor = packRgb(cell.bg_r, cell.bg_g, cell.bg_b);
 
         return {
           char,
           fg: toHexColor(isInverse ? bgColor : fgColor),
           bg: toHexColor(isInverse ? fgColor : bgColor),
-          ...(cell.isBold() === 1 && { bold: true }),
-          ...(cell.isItalic() === 1 && { italic: true }),
-          ...(cell.isUnderline() === 1 && { underline: true }),
-          ...(cell.isStrikethrough() === 1 && { strikethrough: true }),
+          ...((cell.flags & CellFlags.BOLD) !== 0 && { bold: true }),
+          ...((cell.flags & CellFlags.ITALIC) !== 0 && { italic: true }),
+          ...((cell.flags & CellFlags.UNDERLINE) !== 0 && { underline: true }),
+          ...((cell.flags & CellFlags.STRIKETHROUGH) !== 0 && {
+            strikethrough: true,
+          }),
         };
       }
 
       function decodeVisibleCells(terminal, visibleLines) {
         terminal.scrollToBottom();
-        const { cols, rows, activeBuffer, viewportY } =
-          getNormalizedViewportState(terminal);
+        const { cols, rows } = getNormalizedViewportState(terminal);
         const wasmTerm = terminal.wasmTerm;
         invariant(wasmTerm, 'terminal WASM instance is unavailable');
-        const nullCell = activeBuffer.getNullCell();
+        const viewport = readViewportCells(wasmTerm, cols, rows);
         const cells = [];
 
         invariant(
@@ -522,12 +559,11 @@ export const EMBEDDED_HARNESS_HTML = `<!doctype html>
             \`visible line \${row} row must be a non-negative integer\`,
           );
 
-          const line = activeBuffer.getLine(viewportY + row);
           const rowCells = [];
           for (let col = 0; col < cols; col += 1) {
             rowCells.push(
               decodeSnapshotCell(
-                line?.getCell(col) ?? nullCell,
+                viewport[row * cols + col],
                 wasmTerm.getGraphemeString(row, col),
               ),
             );
@@ -547,30 +583,24 @@ export const EMBEDDED_HARNESS_HTML = `<!doctype html>
         return cells;
       }
 
-      // One grapheme string per viewport cell, '' where the codepoint is 0
-      // (blanks and wide-glyph spacers), the same rule as decodeSnapshotCell.
-      // It reads the viewport once: activeBuffer.getLine(row) copies the whole
-      // viewport out of the wasm module for every row, so a loop over the rows
-      // read each cell once per row.
+      // One grapheme string per viewport cell, '' where the cell has no
+      // character (blanks and wide-glyph spacers), the same rule as
+      // decodeSnapshotCell.
       function getCellGraphemes() {
         const terminal = getReadyTerminal();
         terminal.scrollToBottom();
         const { cols, rows } = getNormalizedViewportState(terminal);
         const wasmTerm = terminal.wasmTerm;
         invariant(wasmTerm, 'terminal WASM instance is unavailable');
-        const cells = wasmTerm.getViewport();
-        invariant(
-          cells.length >= rows * cols,
-          'viewport cell count must cover the visible grid',
-        );
+        const cells = readViewportCells(wasmTerm, cols, rows);
         const grid = [];
         for (let row = 0; row < rows; row += 1) {
           const graphemes = [];
           for (let col = 0; col < cols; col += 1) {
             graphemes.push(
-              cells[row * cols + col].codepoint === 0
-                ? ''
-                : wasmTerm.getGraphemeString(row, col),
+              cellHasChars(cells[row * cols + col])
+                ? wasmTerm.getGraphemeString(row, col)
+                : '',
             );
           }
           grid.push(graphemes);

From 6c9c64ae857b37caf3e7244b9142783f1e8b529c Mon Sep 17 00:00:00 2001
From: Thomas Kosiewski <tk@coder.com>
Date: Mon, 9 Nov 2026 16:41:09 +0000
Subject: [PATCH 6/8] test: compare the snapshot decode with a per-row read of
 the same screen

A snapshot and a wait poll read the viewport once. The new test decodes the same screens with the per-row read that the harness used before and compares the lines, the scrollback, the cells and the text. The scan test now compares with the same per-row read.
---
 test/helpers/perRowDecode.ts              |  77 +++++++++
 test/integration/renderer-backend.test.ts | 202 +++++++++++++++++++++-
 2 files changed, 271 insertions(+), 8 deletions(-)
 create mode 100644 test/helpers/perRowDecode.ts

diff --git a/test/helpers/perRowDecode.ts b/test/helpers/perRowDecode.ts
new file mode 100644
index 00000000..4df8f63b
--- /dev/null
+++ b/test/helpers/perRowDecode.ts
@@ -0,0 +1,77 @@
+// The decode that the ghostty-web harness used before it read the viewport
+// once: every row goes through activeBuffer.getLine(row), which re-reads the
+// whole viewport out of the wasm module. A test runs it against the terminal
+// that the harness decodes and compares the results, so a change in how the
+// harness indexes or interprets the one viewport read shows as a difference.
+//
+// The string is an expression that evaluates to a function in the page. A
+// function value would carry the transpiler's helpers into the page, which
+// does not have them. Call it as
+// (PER_ROW_DECODE)(terminal, includeScrollback) and it returns the payload
+// fields of window.__agentTty.getSnapshot({ includeCells: true }).
+export const PER_ROW_DECODE = `((terminal, includeScrollback) => {
+  terminal.scrollToBottom();
+  const wasmTerm = terminal.wasmTerm;
+  const { cols, rows } = wasmTerm.getDimensions();
+  const buffer = terminal.buffer.active;
+  const top = buffer.length - rows;
+  const nullCell = buffer.getNullCell();
+  const hex = (value) => '#' + value.toString(16).padStart(6, '0');
+  const widthOf = (line, col) => {
+    const width = line?.getCell(col)?.getWidth();
+    return Number.isInteger(width) && width >= 0 ? width : 1;
+  };
+  // A spacer column (width 0) adds nothing, a blank is a NUL that reads as a
+  // space, and only the trailing ASCII spaces of the line go.
+  const textOf = (line, graphemeAt) => {
+    let text = '';
+    for (let col = 0; col < cols; col += 1) {
+      const grapheme = graphemeAt(col);
+      if (widthOf(line, col) !== 0) {
+        text += grapheme === '\\u0000' ? ' ' : grapheme;
+      }
+    }
+    return text.replace(/ +$/, '');
+  };
+  const decodeCell = (cell, grapheme) => {
+    const inverse = cell.isInverse() === 1;
+    const fg = cell.getFgColor();
+    const bg = cell.getBgColor();
+    return {
+      char: cell.getChars() === '' ? '' : grapheme,
+      fg: hex(inverse ? bg : fg),
+      bg: hex(inverse ? fg : bg),
+      ...(cell.isBold() === 1 && { bold: true }),
+      ...(cell.isItalic() === 1 && { italic: true }),
+      ...(cell.isUnderline() === 1 && { underline: true }),
+      ...(cell.isStrikethrough() === 1 && { strikethrough: true }),
+    };
+  };
+  const visibleLines = [];
+  const cells = [];
+  for (let row = 0; row < rows; row += 1) {
+    const line = buffer.getLine(top + row);
+    visibleLines.push({
+      row,
+      text: textOf(line, (col) => wasmTerm.getGraphemeString(row, col)),
+    });
+    cells.push({
+      lineNumber: row,
+      cells: Array.from({ length: cols }, (_, col) =>
+        decodeCell(
+          line?.getCell(col) ?? nullCell,
+          wasmTerm.getGraphemeString(row, col),
+        ),
+      ),
+    });
+  }
+  const scrollbackLines = [];
+  for (let row = 0; includeScrollback && row < top; row += 1) {
+    const line = buffer.getLine(row);
+    scrollbackLines.push({
+      row,
+      text: textOf(line, (col) => wasmTerm.getScrollbackGraphemeString(row, col)),
+    });
+  }
+  return { cols, rows, visibleLines, scrollbackLines, cells };
+})`;
diff --git a/test/integration/renderer-backend.test.ts b/test/integration/renderer-backend.test.ts
index cab3f110..7268d1c5 100644
--- a/test/integration/renderer-backend.test.ts
+++ b/test/integration/renderer-backend.test.ts
@@ -14,6 +14,7 @@ import type {
 } from '../../src/renderer/types.js';
 import { GhosttyWebBackend } from '../../src/renderer/ghosttyWeb/index.js';
 import { probeUsedFonts } from '../../src/renderer/ghosttyWeb/missingGlyphs.js';
+import { PER_ROW_DECODE } from '../helpers/perRowDecode.js';
 
 const PROFILE = resolveProfile('reference-dark');
 const SESSION_ID = 'renderer-backend-integration';
@@ -46,6 +47,22 @@ const PNG_SIGNATURE = Buffer.from([
   0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
 ]);
 
+// The harness decode starts with terminal.scrollToBottom(). Patching it keeps
+// the terminal in globalThis.__decodedTerminal for PER_ROW_DECODE. The string
+// keeps vitest from rewriting the import.
+async function keepDecodedTerminal(page: Page): Promise<void> {
+  await page.evaluate(`(() => {
+    return import('/assets/ghostty-web.js').then(({ Terminal }) => {
+      const scrollToBottom = Terminal.prototype.scrollToBottom;
+      Terminal.prototype.scrollToBottom = function () {
+        globalThis.__decodedTerminal = this;
+        return scrollToBottom.call(this);
+      };
+      window.__agentTty.getVisibleText();
+    });
+  })()`);
+}
+
 function visibleTextFromSnapshot(
   snapshot: Awaited<ReturnType<GhosttyWebBackend['snapshot']>>,
 ): string {
@@ -1180,12 +1197,13 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
     });
   });
 
-  // The scan of a flush reads the viewport once, and a snapshot reads it row by
-  // row. Both must name the same grapheme in every cell, whatever the screen
-  // holds and however it came to hold it.
-  it('notes the graphemes of every cell as the per-row read of a snapshot names them', async () => {
+  // The scan of a flush reads the viewport once. The per-row decode reads it
+  // row by row. Both must name the same grapheme in every cell, whatever the
+  // screen holds and however it came to hold it.
+  it('notes the graphemes of every cell as the per-row read names them', async () => {
     await backend.boot();
     const { page } = backend as unknown as { page: Page };
+    await keepDecodedTerminal(page);
     const noted = new Set<string>();
     const sizes: string[] = [];
     // Flushes the chunks, notes their graphemes, and returns the notes so far.
@@ -1196,8 +1214,8 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
           return [...window.__agentTtyPainted.seen];
         })()`,
       ) as Promise<string[]>;
-    // The scan reads first, then the snapshot reads the same screen. A script
-    // runs before the scan, in the same task.
+    // The scan reads first, then the per-row decode reads the same screen. A
+    // script runs before the scan, in the same task.
     const readGrids = (
       script = '',
     ): Promise<{ grid: string[][]; cells: string[][] }> =>
@@ -1205,10 +1223,10 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
         `(() => {
           ${script}
           const grid = window.__agentTty.getCellGraphemes();
-          const snapshot = window.__agentTty.getSnapshot({ includeCells: true });
+          const reference = (${PER_ROW_DECODE})(globalThis.__decodedTerminal, false);
           return {
             grid,
-            cells: snapshot.cells.map((line) => line.cells.map((cell) => cell.char)),
+            cells: reference.cells.map((line) => line.cells.map((cell) => cell.char)),
           };
         })()`,
       ) as Promise<{ grid: string[][]; cells: string[][] }>;
@@ -1294,6 +1312,174 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
     ]);
   });
 
+  // A snapshot and a wait poll read the viewport once. PER_ROW_DECODE reads it
+  // row by row, as the harness did before. Both must give the same lines,
+  // cells and text for every screen. The harness decodes first in every
+  // comparison, so a read in the task of a write or a resize cannot lean on an
+  // update that the per-row read made.
+  it('decodes the visible lines and cells as the per-row read of the same screen does', async () => {
+    await backend.boot();
+    const { page } = backend as unknown as { page: Page };
+    await keepDecodedTerminal(page);
+    interface Cell {
+      char: string;
+      fg: string;
+      bg: string;
+      bold?: boolean;
+      italic?: boolean;
+      underline?: boolean;
+      strikethrough?: boolean;
+    }
+    interface Decoded {
+      cols: number;
+      rows: number;
+      visibleLines: { row: number; text: string }[];
+      scrollbackLines: { row: number; text: string }[];
+      cells: { lineNumber: number; cells: Cell[] }[];
+    }
+    const flush = async (chunks: string[]): Promise<void> => {
+      await page.evaluate(
+        `window.__agentTty.writeBatch(${JSON.stringify(chunks)}, true)`,
+      );
+    };
+    // Returns the cells of the screen, after the comparison passed. A script
+    // runs before the decodes, in the same task.
+    let scrollbackLength = 0;
+    const compare = async (script = ''): Promise<Cell[][]> => {
+      const { actual, text, expected } = (await page.evaluate(
+        `(() => {
+          ${script}
+          const text = window.__agentTty.getVisibleText();
+          const actual = window.__agentTty.getSnapshot({
+            includeScrollback: true,
+            includeCells: true,
+          });
+          const expected = (${PER_ROW_DECODE})(globalThis.__decodedTerminal, true);
+          return { actual, text, expected };
+        })()`,
+      )) as { actual: Decoded; text: string; expected: Decoded };
+      expect(actual.cols).toBe(expected.cols);
+      expect(actual.rows).toBe(expected.rows);
+      expect(actual.visibleLines).toEqual(expected.visibleLines);
+      expect(actual.scrollbackLines).toEqual(expected.scrollbackLines);
+      scrollbackLength = actual.scrollbackLines.length;
+      expect(actual.cells).toEqual(expected.cells);
+      expect(text).toBe(
+        expected.visibleLines.map((line) => line.text).join('\n'),
+      );
+      return actual.cells.map((line) => line.cells);
+    };
+    const cellAt = (grid: Cell[][], row: number, col: number): Cell => {
+      const cell = grid[row]?.[col];
+      if (cell === undefined) {
+        throw new Error(
+          `the screen has no cell at row ${String(row)} col ${String(col)}`,
+        );
+      }
+      return cell;
+    };
+    const find = (
+      grid: Cell[][],
+      char: string,
+    ): { row: number; col: number } => {
+      for (const [row, line] of grid.entries()) {
+        const col = line.findIndex((cell) => cell.char === char);
+        if (col >= 0) {
+          return { row, col };
+        }
+      }
+      throw new Error(`the screen has no cell with ${JSON.stringify(char)}`);
+    };
+
+    // A blank screen, in the task of a resize that changes nothing.
+    const blank = await compare('window.__agentTty.resize(80, 24);');
+    const blankCell = cellAt(blank, 23, 79);
+    expect(blankCell.char).toBe('');
+
+    // Every style, narrow and wide glyphs, combining marks, joined emoji,
+    // flags, Indic clusters, unassigned and private-use code points, half of a
+    // wide glyph overwritten, and a wide glyph at the last column.
+    await flush([
+      '\u001b[2J\u001b[H',
+      '\u001b[1mbold\u001b[22m \u001b[3mitalic\u001b[23m \u001b[4munder\u001b[24m \u001b[9mstrike\u001b[29m \u001b[2mfaint\u001b[22m\r\n',
+      '\u001b[7minverse\u001b[27m \u001b[7;38;2;10;200;30;48;5;196mxcolour\u001b[0m \u001b[38;5;33;48;2;250;240;5mycolour\u001b[0m\r\n',
+      '\u001b[1;3;4;9;31;44mall\u001b[0m \u65e5\u672c\u8a9e \u001b[1m\u6f22\u5b57\u001b[0m \u{1F469}\u200D\u{1F4BB} \u001b[43me\u0301\u001b[0m\r\n',
+      '\u0915\u094D\u0937\u093F \u0378 \ue0b0 \u{1F1EF}\u{1F1F5} \u{1F44D}\u{1F3FD} \uff21\uff22\r\n',
+      '\u{1F600}\u001b[1Dz  \u001b[5;80H\u65e5\u65e5',
+      '\u001b[7;1H\ttab\t\u001b[5mblink\u001b[25m \u001b[8mhidden\u001b[28m',
+    ]);
+    const mixed = await compare();
+    expect(cellAt(mixed, 0, 0)).toMatchObject({ char: 'b', bold: true });
+    expect(cellAt(mixed, 0, 5)).toMatchObject({ char: 'i', italic: true });
+    expect(cellAt(mixed, 0, 12)).toMatchObject({ char: 'u', underline: true });
+    expect(cellAt(mixed, 0, 18)).toMatchObject({
+      char: 's',
+      strikethrough: true,
+    });
+    // Inverse swaps the two colours.
+    expect(cellAt(mixed, 1, 0)).toMatchObject({
+      char: 'i',
+      fg: blankCell.bg,
+      bg: blankCell.fg,
+    });
+    expect(cellAt(mixed, 1, 8)).toMatchObject({ char: 'x', bg: '#0ac81e' });
+    const wide = find(mixed, '\u65e5');
+    expect(cellAt(mixed, wide.row, wide.col + 1).char).toBe('');
+    expect(find(mixed, '\u{1F469}\u200D\u{1F4BB}').row).toBe(wide.row);
+    expect(find(mixed, 'e\u0301').row).toBe(wide.row);
+    expect(find(mixed, '\u0915\u094D').row).toBe(wide.row + 1);
+
+    // Sixty lines scroll the first screen into the scrollback.
+    await flush([
+      Array.from(
+        { length: 60 },
+        (_, line) =>
+          `line ${String(line)} \u001b[3${String(line % 8)}m\u65e5\u672c\u001b[0m e\u0301 \u001b[1mbold\u001b[0m`,
+      ).join('\r\n'),
+    ]);
+    const scrolled = await compare();
+    expect(scrolled.length).toBe(24);
+    expect(scrollbackLength).toBeGreaterThan(30);
+
+    // The other screen has its own cells and returns the first screen's.
+    await flush([
+      '\u001b[?1049h\u001b[2J\u001b[Halt \u001b[7mscreen\u001b[0m \u{1F600} \u65e5',
+    ]);
+    const alt = await compare();
+    expect(cellAt(alt, 0, 0).char).toBe('a');
+    await flush(['\u001b[?1049l']);
+    await compare();
+
+    // A write changes the wasm screen at once, and the render state follows a
+    // frame later. A decode in the task of the write must not read the old
+    // screen.
+    const fresh = await compare(
+      `void window.__agentTty.write('\\u001b[2J\\u001b[H\\u001b[1;31msync\\u001b[0m \\u65e5');`,
+    );
+    expect(cellAt(fresh, 0, 0)).toMatchObject({ char: 's', bold: true });
+
+    // The cell pool of ghostty-web grows with the screen and does not shrink.
+    // After a shrink its cells past the screen still hold the larger screen,
+    // so the decode must index the viewport by the width of the screen.
+    const sizes: string[] = [];
+    for (const [cols, rows, text] of [
+      [120, 40, '\u001b[1mx\u001b[0m'],
+      [40, 10, '\u65e5y'],
+      [100, 30, '\u001b[7mz\u001b[0m\u{1F600}'],
+      [200, 60, 'w'],
+      [80, 24, '\u0301e'],
+    ] as const) {
+      const resized = await compare(
+        `window.__agentTty.resize(${String(cols)}, ${String(rows)});`,
+      );
+      expect(resized.length).toBe(rows);
+      await flush([`\u001b[2J\u001b[H${text.repeat(cols * rows)}`]);
+      const full = await compare();
+      sizes.push(`${String(full[0]?.length)}x${String(full.length)}`);
+    }
+    expect(sizes).toEqual(['120x40', '40x10', '100x30', '200x60', '80x24']);
+  });
+
   it('allows dispose to be called more than once', async () => {
     await backend.boot();
 

From 1886399c8bee2d9a1b104c5ae4008dc9b24fd153 Mon Sep 17 00:00:00 2001
From: Thomas Kosiewski <tk@coder.com>
Date: Mon, 9 Nov 2026 17:02:33 +0000
Subject: [PATCH 7/8] test: compare the two decodes inside the page

Sending the cells of a large screen to the test took far longer than decoding them. The page compares the two decodes and returns the first difference.
---
 test/integration/renderer-backend.test.ts | 94 +++++++++++++++--------
 1 file changed, 61 insertions(+), 33 deletions(-)

diff --git a/test/integration/renderer-backend.test.ts b/test/integration/renderer-backend.test.ts
index 7268d1c5..5bf64dfd 100644
--- a/test/integration/renderer-backend.test.ts
+++ b/test/integration/renderer-backend.test.ts
@@ -1316,7 +1316,9 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
   // row by row, as the harness did before. Both must give the same lines,
   // cells and text for every screen. The harness decodes first in every
   // comparison, so a read in the task of a write or a resize cannot lean on an
-  // update that the per-row read made.
+  // update that the per-row read made. The page compares the two decodes and
+  // returns the differences: sending the cells of a large screen to the test
+  // costs far more than decoding them.
   it('decodes the visible lines and cells as the per-row read of the same screen does', async () => {
     await backend.boot();
     const { page } = backend as unknown as { page: Page };
@@ -1330,23 +1332,22 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
       underline?: boolean;
       strikethrough?: boolean;
     }
-    interface Decoded {
+    interface Comparison {
       cols: number;
       rows: number;
-      visibleLines: { row: number; text: string }[];
-      scrollbackLines: { row: number; text: string }[];
-      cells: { lineNumber: number; cells: Cell[] }[];
+      scrollbackLength: number;
+      differences: string[];
+      cells: Cell[][];
     }
     const flush = async (chunks: string[]): Promise<void> => {
       await page.evaluate(
         `window.__agentTty.writeBatch(${JSON.stringify(chunks)}, true)`,
       );
     };
-    // Returns the cells of the screen, after the comparison passed. A script
-    // runs before the decodes, in the same task.
-    let scrollbackLength = 0;
-    const compare = async (script = ''): Promise<Cell[][]> => {
-      const { actual, text, expected } = (await page.evaluate(
+    // A script runs before the decodes, in the same task. The result holds the
+    // cells of the top rows of the screen, for the checks of its content.
+    const compare = async (script = '', topRows = 0): Promise<Comparison> => {
+      const comparison = (await page.evaluate(
         `(() => {
           ${script}
           const text = window.__agentTty.getVisibleText();
@@ -1355,19 +1356,48 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
             includeCells: true,
           });
           const expected = (${PER_ROW_DECODE})(globalThis.__decodedTerminal, true);
-          return { actual, text, expected };
+          const canon = (value) =>
+            JSON.stringify(value, (key, item) =>
+              item !== null && typeof item === 'object' && !Array.isArray(item)
+                ? Object.fromEntries(
+                    Object.entries(item).sort(([a], [b]) => (a < b ? -1 : 1)),
+                  )
+                : item,
+            );
+          const firstDifference = (name, left, right) => {
+            if (left.length !== right.length) {
+              return name + ': ' + left.length + ' rows against ' + right.length;
+            }
+            for (let row = 0; row < left.length; row += 1) {
+              if (canon(left[row]) !== canon(right[row])) {
+                return name + ' ' + row + ': ' + canon(left[row]).slice(0, 400) +
+                  ' against ' + canon(right[row]).slice(0, 400);
+              }
+            }
+            return null;
+          };
+          const differences = [
+            actual.cols === expected.cols && actual.rows === expected.rows
+              ? null
+              : 'size',
+            firstDifference('visibleLines', actual.visibleLines, expected.visibleLines),
+            firstDifference('scrollbackLines', actual.scrollbackLines, expected.scrollbackLines),
+            firstDifference('cells', actual.cells, expected.cells),
+            text === expected.visibleLines.map((line) => line.text).join('\\n')
+              ? null
+              : 'text',
+          ].filter((difference) => difference !== null);
+          return {
+            cols: actual.cols,
+            rows: actual.rows,
+            scrollbackLength: actual.scrollbackLines.length,
+            differences,
+            cells: actual.cells.slice(0, ${String(topRows)}).map((line) => line.cells),
+          };
         })()`,
-      )) as { actual: Decoded; text: string; expected: Decoded };
-      expect(actual.cols).toBe(expected.cols);
-      expect(actual.rows).toBe(expected.rows);
-      expect(actual.visibleLines).toEqual(expected.visibleLines);
-      expect(actual.scrollbackLines).toEqual(expected.scrollbackLines);
-      scrollbackLength = actual.scrollbackLines.length;
-      expect(actual.cells).toEqual(expected.cells);
-      expect(text).toBe(
-        expected.visibleLines.map((line) => line.text).join('\n'),
-      );
-      return actual.cells.map((line) => line.cells);
+      )) as Comparison;
+      expect(comparison.differences).toEqual([]);
+      return comparison;
     };
     const cellAt = (grid: Cell[][], row: number, col: number): Cell => {
       const cell = grid[row]?.[col];
@@ -1392,8 +1422,8 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
     };
 
     // A blank screen, in the task of a resize that changes nothing.
-    const blank = await compare('window.__agentTty.resize(80, 24);');
-    const blankCell = cellAt(blank, 23, 79);
+    const blank = await compare('window.__agentTty.resize(80, 24);', 1);
+    const blankCell = cellAt(blank.cells, 0, 79);
     expect(blankCell.char).toBe('');
 
     // Every style, narrow and wide glyphs, combining marks, joined emoji,
@@ -1408,7 +1438,7 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
       '\u{1F600}\u001b[1Dz  \u001b[5;80H\u65e5\u65e5',
       '\u001b[7;1H\ttab\t\u001b[5mblink\u001b[25m \u001b[8mhidden\u001b[28m',
     ]);
-    const mixed = await compare();
+    const mixed = (await compare('', 8)).cells;
     expect(cellAt(mixed, 0, 0)).toMatchObject({ char: 'b', bold: true });
     expect(cellAt(mixed, 0, 5)).toMatchObject({ char: 'i', italic: true });
     expect(cellAt(mixed, 0, 12)).toMatchObject({ char: 'u', underline: true });
@@ -1437,16 +1467,13 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
           `line ${String(line)} \u001b[3${String(line % 8)}m\u65e5\u672c\u001b[0m e\u0301 \u001b[1mbold\u001b[0m`,
       ).join('\r\n'),
     ]);
-    const scrolled = await compare();
-    expect(scrolled.length).toBe(24);
-    expect(scrollbackLength).toBeGreaterThan(30);
+    expect((await compare()).scrollbackLength).toBeGreaterThan(30);
 
     // The other screen has its own cells and returns the first screen's.
     await flush([
       '\u001b[?1049h\u001b[2J\u001b[Halt \u001b[7mscreen\u001b[0m \u{1F600} \u65e5',
     ]);
-    const alt = await compare();
-    expect(cellAt(alt, 0, 0).char).toBe('a');
+    expect(cellAt((await compare('', 1)).cells, 0, 0).char).toBe('a');
     await flush(['\u001b[?1049l']);
     await compare();
 
@@ -1455,8 +1482,9 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
     // screen.
     const fresh = await compare(
       `void window.__agentTty.write('\\u001b[2J\\u001b[H\\u001b[1;31msync\\u001b[0m \\u65e5');`,
+      1,
     );
-    expect(cellAt(fresh, 0, 0)).toMatchObject({ char: 's', bold: true });
+    expect(cellAt(fresh.cells, 0, 0)).toMatchObject({ char: 's', bold: true });
 
     // The cell pool of ghostty-web grows with the screen and does not shrink.
     // After a shrink its cells past the screen still hold the larger screen,
@@ -1472,10 +1500,10 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
       const resized = await compare(
         `window.__agentTty.resize(${String(cols)}, ${String(rows)});`,
       );
-      expect(resized.length).toBe(rows);
+      expect([resized.cols, resized.rows]).toEqual([cols, rows]);
       await flush([`\u001b[2J\u001b[H${text.repeat(cols * rows)}`]);
       const full = await compare();
-      sizes.push(`${String(full[0]?.length)}x${String(full.length)}`);
+      sizes.push(`${String(full.cols)}x${String(full.rows)}`);
     }
     expect(sizes).toEqual(['120x40', '40x10', '100x30', '200x60', '80x24']);
   });

From d252ac32d8841fd955d878422166c293031ae391 Mon Sep 17 00:00:00 2001
From: Thomas Kosiewski <tk@coder.com>
Date: Mon, 9 Nov 2026 17:24:40 +0000
Subject: [PATCH 8/8] test: name a stale viewport width in the decode of a
 write

The row that the write puts on the screen has the spacers of two wide glyphs where the old screen has narrow cells, so a decode that reads the pool of the old screen adds spaces to the line.

docs: note in the ghostty-web README that a decode reads the viewport once
---
 src/renderer/ghosttyWeb/README.md         | 1 +
 test/integration/renderer-backend.test.ts | 9 ++++++---
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/src/renderer/ghosttyWeb/README.md b/src/renderer/ghosttyWeb/README.md
index 668a2464..1a96b873 100644
--- a/src/renderer/ghosttyWeb/README.md
+++ b/src/renderer/ghosttyWeb/README.md
@@ -32,6 +32,7 @@ This directory holds the `ghostty-web` reference renderer. `GhosttyWebBackend` s
 - `replayWithTiming` asserts strictly increasing seqs and non-decreasing timestamps [backend.ts:GhosttyWebBackend.replayWithTiming].
 - `replayWithTiming` waits until each event's place on a schedule built from the recorded gaps: `recorded` keeps them, `accelerated` caps each at `maxGapMs`, and `max-speed` sets them to 0. It measures that schedule with `performance.now()`, so frame holds and bridge calls use up idle time instead of adding to it. In `recorded` and `accelerated` mode it flushes pending output once the next event is at least one frame hold after the batch's first output, unless the replay runs behind the schedule, in which case the batch grows until it catches up. `max-speed` has no schedule to fall behind, so only recorded time ends its flushes. A flush ends at the first event that is at least one frame hold of recorded time after the batch's first output. An event that changes no pixel does not end it: input, marker, run-complete, signal and exit events leave the batch as it is, because a flush at each of them would cost a frame per event. A resize and the end of the replay still end it. `max-speed` also spreads at most `MAX_SPEED_FRAME_BUDGET` (2,400) flushes over the recorded span of the events that it applies: the distance between the first output of a flush and the event that ends it is at least the larger of the frame hold and the span divided by 2,400. So a `max-speed` replay makes about one flush per frame hold of recorded time for a recording shorter than 38 s and at most about 2,400 flushes for a longer one, whatever its number of events. Output that arrives less than that distance after the first output of a flush shares the flush, also when an input or a marker sits between, so a state that the next output of the flush replaces is never painted. A flush waits for one animation frame. `max-speed` holds the frame hold only after the last flush of the replay and before and after a resize, so two flushes that follow each other can paint within one video frame. In `recorded` and `accelerated` mode, every event that changes no pixel ends a flush, and a hold follows every flush. Events with the same timestamp share a flush at any hold, 0 included, because a flush needs at least 1 ms of recorded time [backend.ts:GhosttyWebBackend.replayWithTiming].
 - `writeBatch(chunks, endsFlush, paintedCap)` takes the chunks of one bridge call. A flush that has more than 1000 chunks needs several calls, and ghostty-web paints on every animation frame, so the page holds the chunks of a call that does not end the flush. The call that ends it (`endsFlush`, set by the backend on the last call only) writes every held chunk in one task, so no frame paints a state between two calls, and then resolves after one frame. ghostty-web calls a write callback one animation frame (about 17 ms) after the write, and waiting on every chunk (`write`) cost one frame per output event. `write()` and `resize()` throw while chunks are held. `discardHeldChunks()` drops them: the backend calls it when a flush fails, because `HostRendererManager` keeps the backend and a retry would otherwise meet them. A `paintedCap` that is not null makes the call that ends the flush add the graphemes on the screen to the set that the missing-glyph check of `replayWithTiming` probes, so a flush is one page call. The call returns the message of a failed note and not an error, because a failed note must not fail the flush. In `replayWithTiming`, the chunks of one flush share one video frame [embeddedHarnessHtml.ts:EMBEDDED_HARNESS_HTML].
+- The harness reads the visible screen once per decode, with `wasmTerm.getViewport()`: `getSnapshot`, `getVisibleText` and `getCellGraphemes` each take the text, width, colors and styles of a cell from that one read. In ghostty-web 0.4.0, `activeBuffer.getLine(row)` of a visible row re-reads the whole viewport out of the wasm module, so a loop over the rows would read each cell once per row. The scrollback decode still calls `getLine(row)` per row, because that call reads one scrollback row only [embeddedHarnessHtml.ts:EMBEDDED_HARNESS_HTML]. `test/helpers/perRowDecode.ts` holds the per-row decode that `renderer-backend.test.ts` compares the harness with.
 - `snapshot()` and `screenshot()` throw until `replayTo()` or `replayWithTiming()` has run once and set the initial size. Both replays accept `targetSeq` -1 for an empty Event Log. A replay over zero events sets `lastAppliedSeq` to `targetSeq` [backend.ts:GhosttyWebBackend.snapshot].
 - `missingGlyphs` lists a code point only when a bundled face that lacks it drew it. Chromium draws a cluster with one font: the first stack font that covers all of it, or else the first font of the stack, which is bundled in both built-in profiles and then draws `.notdef` boxes. CDP names the face that drew a probe by its PostScript name, so a family alias or several faces under one family resolve to the right cmap. When one bundled face drew the whole grapheme, every code point that face lacks is listed. A probe with no reported font is judged against every face of the first family. When the grapheme is split over several fonts, each uncovered code point is judged by its own probe, and a mark's probe on its base is compared with a probe of the base alone. Glyphs that a host font draws are not listed. The check runs after the PNG is written, removes its probe spans, and caches each probe text's result for the page, clearing the cache when it would pass `MAX_CACHED_GLYPH_PROBES` (16384) entries. It probes at most `MAX_GLYPH_PROBES` texts and lists at most `MAX_MISSING_GLYPH_CELLS` cells (4096 each). `probeUsedFonts` sends its CDP queries in batches of 256 and stops starting batches after `GLYPH_PROBE_BUDGET_MS` (1000 ms). The result sets `missingGlyphsTruncated` when any of these stops the check early. Family names match without regard to case. A web font whose PostScript name the profile does not bundle fails the check. A failed check is logged at debug level and leaves the field out, so the screenshot still succeeds. `replayWithTiming()` records the viewport graphemes in the page after each output batch and each resize (at most `MAX_CACHED_GLYPH_PROBES`), and the final frame hold judges them once, with the hold as the probe budget, so the check does not lengthen the video. `recordedMissingGlyphs()` returns that result. A failed note or check leaves the record export fields out. A profile whose font stack does not start with a bundled font gets no `missingGlyphs` field [missingGlyphs.ts:probeUsedFonts] [backend.ts:GhosttyWebBackend.screenshot].
 - `screenshot()` requires an absolute `outputPath` whose parent directory exists. It checks that the output is a non-empty PNG with a valid signature and an `IHDR` first chunk [backend.ts:GhosttyWebBackend.screenshot].
diff --git a/test/integration/renderer-backend.test.ts b/test/integration/renderer-backend.test.ts
index 5bf64dfd..72597c32 100644
--- a/test/integration/renderer-backend.test.ts
+++ b/test/integration/renderer-backend.test.ts
@@ -1479,12 +1479,15 @@ describe('GhosttyWebBackend integration', { timeout: 120_000 }, () => {
 
     // A write changes the wasm screen at once, and the render state follows a
     // frame later. A decode in the task of the write must not read the old
-    // screen.
+    // screen. The old screen has narrow cells where the new row has the
+    // spacers of two wide glyphs, so an old width shows as extra spaces.
     const fresh = await compare(
-      `void window.__agentTty.write('\\u001b[2J\\u001b[H\\u001b[1;31msync\\u001b[0m \\u65e5');`,
+      `void window.__agentTty.write('\\u001b[2J\\u001b[H\\u65e5\\u672cabc \\u001b[1;31msync\\u001b[0m');`,
       1,
     );
-    expect(cellAt(fresh.cells, 0, 0)).toMatchObject({ char: 's', bold: true });
+    expect(cellAt(fresh.cells, 0, 0).char).toBe('\u65e5');
+    expect(cellAt(fresh.cells, 0, 1).char).toBe('');
+    expect(cellAt(fresh.cells, 0, 8)).toMatchObject({ char: 's', bold: true });
 
     // The cell pool of ghostty-web grows with the screen and does not shrink.
     // After a shrink its cells past the screen still hold the larger screen,