From 2ba045c8e70e1fd05798ddf6f956756db966e2d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=88=E5=A4=A7=E7=8C=AB?= <16399091+binaricat@users.noreply.github.com> Date: Mon, 19 Oct 2026 21:51:46 +0800 Subject: [PATCH] fix: preserve inline image tile stride across resize --- package.json | 3 +- scripts/patch-xterm-image-tile-stride.cjs | 98 ++++++++++++ .../patch-xterm-image-tile-stride.test.cjs | 148 ++++++++++++++++++ scripts/xterm-image-resize.live.test.cjs | 100 ++++++++++++ 4 files changed, 348 insertions(+), 1 deletion(-) create mode 100644 scripts/patch-xterm-image-tile-stride.cjs create mode 100644 scripts/patch-xterm-image-tile-stride.test.cjs create mode 100644 scripts/xterm-image-resize.live.test.cjs diff --git a/package.json b/package.json index 86b17715e..e8dd3b3d3 100644 --- a/package.json +++ b/package.json @@ -42,7 +42,7 @@ "pack:linux": "npm run build && cross-env NODE_OPTIONS=--disable-warning=DEP0190 electron-builder --config electron-builder.config.cjs --linux --publish=never", "pack:linux-x64": "npm run build && cross-env npm_config_arch=x64 NODE_OPTIONS=--disable-warning=DEP0190 electron-builder --config electron-builder.config.cjs --linux --x64 --publish=never", "pack:linux-arm64": "npm run build && cross-env npm_config_arch=arm64 NODE_OPTIONS=--disable-warning=DEP0190 electron-builder --config electron-builder.config.cjs --linux --arm64 --publish=never", - "postinstall": "patch-package && node scripts/patch-xterm-macos-column-selection.cjs && node scripts/patch-xterm-foreground-intense.cjs && electron-builder install-app-deps && node scripts/rebuildPatchedNodePty.cjs && node scripts/patch-xterm-webgl-atlas.cjs", + "postinstall": "patch-package && node scripts/patch-xterm-macos-column-selection.cjs && node scripts/patch-xterm-foreground-intense.cjs && node scripts/patch-xterm-image-tile-stride.cjs && electron-builder install-app-deps && node scripts/rebuildPatchedNodePty.cjs && node scripts/patch-xterm-webgl-atlas.cjs", "rebuild": "electron-builder install-app-deps", "tool:cli": "node electron/cli/netcatty-tool-cli.cjs", "generate:capability-tools": "node scripts/generate-capability-tools.cjs", @@ -68,6 +68,7 @@ "test:ssh-mfa-models:live": "SSH_MFA_LIVE=1 node --test electron/bridges/sshMfaModels.live.test.cjs", "test:local-file-drag:electron": "electron scripts/local-file-drag.live.test.cjs", "test:tray-panel-layout": "electron scripts/tray-panel-layout.live.test.cjs", + "test:xterm-image-resize": "electron scripts/xterm-image-resize.live.test.cjs", "test:xterm-foreground-intense": "electron scripts/xterm-foreground-intense.live.test.cjs", "test:terminal-background-rendering": "electron scripts/terminal-background-rendering.live.test.cjs", "test:xterm-webgl-overflow": "electron scripts/xterm-webgl-atlas-overflow.live.test.cjs", diff --git a/scripts/patch-xterm-image-tile-stride.cjs b/scripts/patch-xterm-image-tile-stride.cjs new file mode 100644 index 000000000..90ccaf608 --- /dev/null +++ b/scripts/patch-xterm-image-tile-stride.cjs @@ -0,0 +1,98 @@ +#!/usr/bin/env node +/* global process, console */ +"use strict"; + +const fs = require("node:fs"); +const path = require("node:path"); + +const EXPECTED_VERSION = "0.10.0-beta.292"; + +// ImageStorage.addImage assigns tile IDs using ceil(orig.width/origCellSize.width). +// Keep that stride for draw, extractTile and viewportResize. Recomputing it from +// the rescaled canvas can add a column: ceil(400 * 9.51 / 10) / 9.51 > 40. +// DOM cell widths can change fractionally on window resize, shifting each image +// row one more tile and producing diagonal corruption (Netcatty #3746). +// Local pinned-version workaround pending an upstream release, not a merged +// upstream backport. The open draft uses the same original-grid principle: +// https://github.com/xtermjs/xterm.js/issues/5861 +// https://github.com/xtermjs/xterm.js/pull/6145 +// Patch both runtime bundles using the existing install-time patch pattern. +const PATCHES = [ + { + file: "lib/addon-image.js", + original: "const n=e.actual,h=Math.ceil(n.width/o),", + replacement: "const n=e.actual,h=Math.ceil(e.orig.width/e.origCellSize.width),", + }, + { + file: "lib/addon-image.js", + original: "const s=e.actual,o=Math.ceil(s.width/A),", + replacement: "const s=e.actual,o=Math.ceil(e.orig.width/e.origCellSize.width),", + }, + { + file: "lib/addon-image.js", + original: "const h=Math.ceil(((null===(t=n.actual)||void 0===t?void 0:t.width)||0)/n.actualCellSize.width);", + replacement: "const h=Math.ceil(((null===(t=n.orig)||void 0===t?void 0:t.width)||0)/n.origCellSize.width);", + }, + { + file: "lib/addon-image.mjs", + original: "let h=t.actual,g=Math.ceil(h.width/o),", + replacement: "let h=t.actual,g=Math.ceil(t.orig.width/t.origCellSize.width),", + }, + { + file: "lib/addon-image.mjs", + original: "let a=t.actual,n=Math.ceil(a.width/A),", + replacement: "let a=t.actual,n=Math.ceil(t.orig.width/t.origCellSize.width),", + }, + { + file: "lib/addon-image.mjs", + original: "let h=Math.ceil((d.actual?.width||0)/d.actualCellSize.width);", + replacement: "let h=Math.ceil((d.orig?.width||0)/d.origCellSize.width);", + }, +]; + +function patchImageSource(source, patch) { + const originalCount = source.split(patch.original).length - 1; + const patchedCount = source.split(patch.replacement).length - 1; + if (originalCount === 1 && patchedCount === 0) { + return { source: source.replace(patch.original, patch.replacement), changed: true }; + } + if (originalCount === 0 && patchedCount === 1) return { source, changed: false }; + throw new Error( + `${patch.file}: unexpected image-tile-stride patch shape ` + + `(original=${originalCount}, patched=${patchedCount})`, + ); +} + +function patchInstalledImage(root = process.cwd()) { + const base = path.resolve(root, "node_modules/@xterm/addon-image"); + const version = JSON.parse(fs.readFileSync(path.join(base, "package.json"), "utf8")).version; + if (version !== EXPECTED_VERSION) { + throw new Error(`unsupported @xterm/addon-image version ${version}; expected ${EXPECTED_VERSION}`); + } + // Validate both complete bundles before writing either one. + const files = new Map(); + let changed = 0; + for (const patch of PATCHES) { + const source = files.get(patch.file) ?? fs.readFileSync(path.join(base, patch.file), "utf8"); + const result = patchImageSource(source, patch); + files.set(patch.file, result.source); + if (result.changed) changed++; + } + if (changed) { + for (const [file, source] of files) fs.writeFileSync(path.join(base, file), source); + fs.rmSync(path.resolve(root, "node_modules/.vite"), { recursive: true, force: true }); + } + return { changed, checked: PATCHES.length }; +} + +if (require.main === module) { + try { + const result = patchInstalledImage(); + console.log(`[patch-xterm-image-tile-stride] changed=${result.changed} checked=${result.checked}`); + } catch (error) { + console.error(`[patch-xterm-image-tile-stride] ERROR: ${error.message}`); + process.exitCode = 1; + } +} + +module.exports = { EXPECTED_VERSION, PATCHES, patchImageSource, patchInstalledImage }; diff --git a/scripts/patch-xterm-image-tile-stride.test.cjs b/scripts/patch-xterm-image-tile-stride.test.cjs new file mode 100644 index 000000000..b5f5fed6f --- /dev/null +++ b/scripts/patch-xterm-image-tile-stride.test.cjs @@ -0,0 +1,148 @@ +"use strict"; +const assert = require("node:assert/strict"); +const fs = require("node:fs"); +const os = require("node:os"); +const path = require("node:path"); +const test = require("node:test"); +const { pathToFileURL } = require("node:url"); +const { EXPECTED_VERSION, PATCHES, patchImageSource, patchInstalledImage } = require("./patch-xterm-image-tile-stride.cjs"); + +for (const patch of PATCHES) { + test(`${patch.file}: ${patch.original.slice(0, 24)} patches once and rejects drift`, () => { + const first = patchImageSource(`before;${patch.original}after`, patch); + assert.equal(first.changed, true); + assert.equal(first.source, `before;${patch.replacement}after`); + assert.deepEqual(patchImageSource(first.source, patch), { source: first.source, changed: false }); + for (const source of ["upstream changed", patch.original.repeat(2), patch.replacement.repeat(2), patch.original + patch.replacement]) { + assert.throws(() => patchImageSource(source, patch), /unexpected image-tile-stride patch shape/); + } + }); +} + +function fixture(t) { + const root = fs.mkdtempSync(path.join(os.tmpdir(), "netcatty-image-stride-")); + t.after(() => fs.rmSync(root, { recursive: true, force: true })); + const base = path.join(root, "node_modules/@xterm/addon-image"); + fs.mkdirSync(path.join(base, "lib"), { recursive: true }); + fs.writeFileSync(path.join(base, "package.json"), JSON.stringify({ version: EXPECTED_VERSION })); + for (const file of new Set(PATCHES.map(p => p.file))) { + fs.writeFileSync(path.join(base, file), PATCHES.filter(p => p.file === file).map(p => p.original).join("\n")); + } + return { root, base }; +} + +test("install patches both bundles, invalidates Vite cache and is idempotent", t => { + const { root, base } = fixture(t); + const cache = path.join(root, "node_modules/.vite"); + fs.mkdirSync(cache); + assert.deepEqual(patchInstalledImage(root), { changed: 6, checked: 6 }); + assert.equal(fs.existsSync(cache), false); + for (const patch of PATCHES) assert.ok(fs.readFileSync(path.join(base, patch.file), "utf8").includes(patch.replacement)); + assert.deepEqual(patchInstalledImage(root), { changed: 0, checked: 6 }); +}); + +test("install fails closed on a changed version or bundle before writing anything", t => { + const { root, base } = fixture(t); + const cjs = path.join(base, "lib/addon-image.js"); + const original = fs.readFileSync(cjs, "utf8"); + fs.writeFileSync(path.join(base, "package.json"), JSON.stringify({ version: "future" })); + assert.throws(() => patchInstalledImage(root), /unsupported @xterm\/addon-image version/); + assert.equal(fs.readFileSync(cjs, "utf8"), original); + fs.writeFileSync(path.join(base, "package.json"), JSON.stringify({ version: EXPECTED_VERSION })); + fs.writeFileSync(path.join(base, "lib/addon-image.mjs"), "upstream changed"); + assert.throws(() => patchInstalledImage(root), /unexpected image-tile-stride patch shape/); + assert.equal(fs.readFileSync(cjs, "utf8"), original); +}); + +// Exercise the installed addon itself, not a copy of its stride expression. +// Canvas calls are captured so these regressions also run in the normal Node suite. +function canvas(width, height) { + const calls = []; + const element = { width, height, calls, remove() {} }; + element.getContext = () => ({ canvas: element, drawImage: (...args) => calls.push(args), clearRect() {} }); + return element; +} + +function setup(ImageAddon, { imageWidth = 400, cellWidth = 10, cols = 80, layer = "top" } = {}) { + const event = () => ({ dispose() {} }); + const lines = Array.from({ length: 24 }, () => ({ + _data: new Uint32Array(100 * 3), _extendedAttrs: {}, + getBg(x) { return this._data[x * 3 + 2]; }, + })); + const cell = { width: cellWidth, height: 20 }; + const buffer = { x: 0, y: 0, ybase: 0, lines: { get: y => lines[y], length: lines.length } }; + const term = { + cols, rows: 24, dimensions: { css: { cell } }, + _core: { + open() {}, buffer, + _coreBrowserService: { window: { document: { createElement: () => canvas(0, 0) } } }, + optionsService: { onOptionChange: event }, + _inputHandler: { onRequestReset: event, _dirtyRowTracker: { markDirty() {} }, lineFeed: () => buffer.y++ }, + }, + parser: { registerCsiHandler: event, registerEscHandler: event }, + buffer: { active: { type: "normal" }, onBufferChange: event }, + onRender: event, onResize: event, + registerMarker: () => ({ onDispose() {}, dispose() {} }), + }; + const addon = new ImageAddon({ enableSizeReports: false, sixelSupport: false, iipSupport: false, kittySupport: false }); + addon.activate(term); + const image = canvas(imageWidth, 400); + const imageId = addon._storage.addImage(image, { scrolling: true, layer, zIndex: 0, cursorPos: "vt340" }); + const spec = addon._storage._images.get(imageId); + const output = canvas(1000, 480); + addon._renderer._layers.set(layer, output.getContext("2d")); + return { addon, cell, spec, output, lines }; +} + +for (const format of ["js", "mjs"]) { + const loadAddon = async () => { + const file = path.resolve(__dirname, `../node_modules/@xterm/addon-image/lib/addon-image.${format}`); + return format === "js" ? require(file) : import(pathToFileURL(file).href); + }; + for (const layer of ["top", "bottom"]) { + test(`${format}: ${layer} image rows and extracted tiles keep their original stride through repeated resizes`, async () => { + const { ImageAddon } = await loadAddon(); + for (const options of [{}, { imageWidth: 397 }, { imageWidth: 384, cellWidth: 9.6 }]) { + const { addon, cell, spec, output, lines } = setup(ImageAddon, { ...options, layer }); + const stride = Math.ceil(spec.orig.width / spec.origCellSize.width); + assert.equal(stride, 40); + assert.equal(lines[1]._extendedAttrs[0].tileId, stride); + const originalWidth = cell.width; + for (const width of [originalWidth, 9.51, 10.02, 12, 8.73, originalWidth]) { + cell.width = width; + for (const tileId of [40, 41, 79, 80, 799]) { + addon._renderer.draw(spec, tileId, 3, 2); + const [, sx, sy, , , dx, dy] = output.calls.at(-1); + assert.equal(sx, Math.floor((tileId % stride) * width), `draw x: tile=${tileId}, width=${width}`); + assert.equal(sy, Math.floor(tileId / stride) * cell.height, `draw y: tile=${tileId}, width=${width}`); + assert.equal(dx, Math.floor(3 * width)); + assert.equal(dy, 2 * cell.height); + const tile = addon._renderer.extractTile(spec, tileId); + assert.equal(tile.calls[0][1], sx, "extractTile uses the same source column as draw"); + assert.equal(tile.calls[0][2], sy, "extractTile uses the same source row as draw"); + } + addon._renderer.draw(spec, stride, 0, 1, stride); + assert.equal(output.calls.at(-1)[1], 0, "batched second row starts at the left edge"); + assert.equal(output.calls.at(-1)[2], cell.height); + } + assert.equal(spec.actual, spec.orig, "restoring cell metrics restores the original image"); + } + }); + } + + test(`${format}: viewport growth after rescaling does not append the next image row`, async () => { + const { ImageAddon } = await loadAddon(); + for (const cols of [20, 40]) { + const { addon, cell, spec, lines } = setup(ImageAddon, { cols }); + cell.width = 9.51; + addon._renderer.draw(spec, 0, 0, 0); + assert.equal(spec.actual.width, 381, "rescaled integer canvas would incorrectly imply 41 columns"); + addon._storage.viewportResize({ cols: 50, rows: 24 }); + for (let row = 0; row < 20; row++) { + for (let col = 0; col < 40; col++) assert.equal(lines[row]._extendedAttrs[col].tileId, row * 40 + col); + assert.equal(lines[row]._extendedAttrs[40], undefined, "must stop at the original row boundary"); + } + assert.equal(spec.tileCount, 800); + } + }); +} diff --git a/scripts/xterm-image-resize.live.test.cjs b/scripts/xterm-image-resize.live.test.cjs new file mode 100644 index 000000000..987d5de24 --- /dev/null +++ b/scripts/xterm-image-resize.live.test.cjs @@ -0,0 +1,100 @@ +"use strict"; +/* global process, __dirname, console, document, requestAnimationFrame */ +if (!process.versions.electron) { + require("node:test")("inline image pixels stay aligned across terminal resizes", { + skip: "run with Electron to exercise real DOM and canvas rendering", + }, () => {}); +} else { + const { app, BrowserWindow } = require("electron"); + const fs = require("node:fs"); + const path = require("node:path"); + const esbuild = require("esbuild"); + const temp = require("../electron/bridges/tempDirBridge.cjs"); + const root = path.resolve(__dirname, ".."); + const userData = fs.mkdtempSync(`${temp.getTempFilePath("image-resize")}-`); + app.setPath("userData", userData); + app.on("window-all-closed", () => {}); + let win; + const cleanup = code => { + win?.destroy(); + fs.rmSync(userData, { recursive: true, force: true }); + app.exit(code); + }; + + async function exercise({ Terminal, ImageAddon }) { + const check = (actual, expected, label) => { + if (JSON.stringify(actual) !== JSON.stringify(expected)) { + throw new Error(`${label}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`); + } + }; + const host = document.createElement("div"); + document.body.appendChild(host); + const term = new Terminal({ cols: 40, rows: 18, fontFamily: "monospace", fontSize: 16, cursorBlink: false, allowProposedApi: true }); + term.open(host); + const addon = new ImageAddon({ sixelSupport: false, iipSupport: false, kittySupport: false }); + term.loadAddon(addon); + const render = async () => { + term.refresh(0, term.rows - 1); + await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))); + }; + await render(); + const originalCell = { ...addon._renderer.cellSize }; + const source = document.createElement("canvas"); + source.width = Math.round(originalCell.width * 40); + source.height = Math.round(originalCell.height * 8); + check(Math.ceil(source.width / originalCell.width), 40, "fixture covers 40 image columns"); + const context = source.getContext("2d"); + const color = (col, row) => [32 + (col % 7) * 32, 32 + row * 24, 192, 255]; + for (let row = 0; row < 8; row++) { + for (let col = 0; col < 40; col++) { + const [r, g, b] = color(col, row); + context.fillStyle = `rgb(${r},${g},${b})`; + context.fillRect(Math.floor(col * originalCell.width), Math.floor(row * originalCell.height), Math.ceil(originalCell.width), Math.ceil(originalCell.height)); + } + } + // Insert once into the real terminal buffer. All subsequent frames must use + // the original tile IDs, just like an image already printed by any protocol. + const id = addon._storage.addImage(source, { scrolling: true, layer: "top", zIndex: 0, cursorPos: "vt340" }); + const spec = addon._storage._images.get(id); + const samples = []; + let roundedStrideChanged = false; + for (const cols of [40, 53, 67, 91, 40, 53, 40]) { + term.resize(cols, 18); + await render(); + const cell = addon._renderer.cellSize; + const badStride = Math.ceil(spec.actual.width / cell.width); + roundedStrideChanged ||= badStride !== 40; + const output = host.querySelector(".xterm-image-layer-top").getContext("2d"); + for (const row of [0, 1, 2, 7]) { + for (const col of [0, 1, 5, 20, 38]) { + const pixel = [...output.getImageData(Math.floor((col + 0.5) * cell.width), Math.floor((row + 0.5) * cell.height), 1, 1).data]; + check(pixel, color(col, row), `canvas pixel at cols=${cols}, cell=${col},${row}`); + const tile = addon.extractTileAtBufferCell(col, row); + const extracted = [...tile.getContext("2d").getImageData(Math.floor(tile.width / 2), Math.floor(tile.height / 2), 1, 1).data]; + check(extracted, color(col, row), `extracted tile at cols=${cols}, cell=${col},${row}`); + } + } + samples.push({ cols, cellWidth: cell.width, canvasWidth: spec.actual.width, roundedStride: badStride }); + } + check(roundedStrideChanged, true, "exercise fractional cell widths that triggered the regression"); + term.dispose(); + host.remove(); + return { samples, pixelChecks: 280, repeatedResizes: true }; + } + + void app.whenReady().then(async () => { + const bundle = esbuild.buildSync({ + stdin: { + contents: 'export { Terminal } from "@xterm/xterm"; export { ImageAddon } from "@xterm/addon-image";', + resolveDir: root, + }, + bundle: true, format: "iife", globalName: "ImageResizeTest", platform: "browser", write: false, + }).outputFiles[0].text; + win = new BrowserWindow({ show: true, width: 1000, height: 600, webPreferences: { backgroundThrottling: false } }); + await win.loadURL("data:text/html,"); + await win.webContents.insertCSS(fs.readFileSync(require.resolve("@xterm/xterm/css/xterm.css"), "utf8")); + const result = await win.webContents.executeJavaScript(`${bundle}\n(${exercise.toString()})(ImageResizeTest)`); + console.log("IMAGE_RESIZE_RENDERING_OK", JSON.stringify(result)); + cleanup(0); + }).catch(error => { console.error(error); cleanup(1); }); +}