fix: preserve inline image tile stride across resize

This commit is contained in:
陈大猫 committed 2026-10-19 21:51:46 +08:00
1 parent 8b0b7706a3
commit 2ba045c8e7
4 files changed
+348 -1

No files matched your search

+98
View File
@@ -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 };
@@ -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);
}
});
}
+100
View File
@@ -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,<body style='margin:0;background:black'>");
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); });
}