Merge branch 'master' into image-ext

addons/addon-webgl/src/GlyphRenderer.ts

@@ -100,6 +100,8 @@ export class GlyphRenderer extends Disposable {
   private readonly _attributesBuffer: WebGLBuffer;
 
   private _atlas: ITextureAtlas | undefined;
+  private _lastSeenPageLayoutVersion: number = -1;
+  private _pageOverflowWarned: boolean = false;
   private _activeBuffer: number = 0;
   private readonly _vertices: IVertices = {
     count: 0,
@@ -213,8 +215,19 @@ export class GlyphRenderer extends Disposable {
     this.handleResize();
   }
 
+  /**
+   * Call when a frame is being drawn. Returns whether the full model must be rebuilt before
+   * rendering this frame because the atlas page layout changed since this renderer last drew.
+   */
   public beginFrame(): boolean {
-    return this._atlas ? this._atlas.beginFrame() : true;
+    if (!this._atlas) {
+      return true;
+    }
+    if (this._atlas.pageLayoutVersion !== this._lastSeenPageLayoutVersion) {
+      this._lastSeenPageLayoutVersion = this._atlas.pageLayoutVersion;
+      return true;
+    }
+    return false;
   }
 
   public updateCell(x: number, y: number, code: number, bg: number, fg: number, ext: number, chars: string, width: number, lastBg: number): void {
@@ -363,7 +376,13 @@ export class GlyphRenderer extends Disposable {
     // Bind the atlas page texture if they have changed. AtlasPage.version is globally
     // monotonic, so a page object swap at the same index (which happens after a page merge)
     // is detected by the same comparison.
-    for (let i = 0; i < this._atlas.pages.length; i++) {
+    // Clamp defensively in case the atlas unexpectedly exceeds texture capacity.
+    const pageCount = Math.min(this._atlas.pages.length, this._atlasTextures.length);
+    if (this._atlas.pages.length > this._atlasTextures.length && !this._pageOverflowWarned) {
+      this._pageOverflowWarned = true;
+      this._logService.warn(`Atlas page count (${this._atlas.pages.length}) exceeds the renderer's texture capacity (${this._atlasTextures.length}), some glyphs will not render correctly`);
+    }
+    for (let i = 0; i < pageCount; i++) {
       if (this._atlas.pages[i].version !== this._atlasTextures[i].version) {
         this._bindAtlasPageTexture(gl, this._atlas, i);
       }
@@ -375,6 +394,7 @@ export class GlyphRenderer extends Disposable {
 
   public setAtlas(atlas: ITextureAtlas): void {
     this._atlas = atlas;
+    this._lastSeenPageLayoutVersion = -1;
     this.invalidateAtlasTextures();
   }
 

addons/addon-webgl/src/TextureAtlas.ts

@@ -132,12 +132,8 @@ export class TextureAtlas implements ITextureAtlas {
     }
   }
 
-  private _requestClearModel = false;
-  public beginFrame(): boolean {
-    const result = this._requestClearModel;
-    this._requestClearModel = false;
-    return result;
-  }
+  private _pageLayoutVersion = 0;
+  public get pageLayoutVersion(): number { return this._pageLayoutVersion; }
 
   public clearTexture(): void {
     if (this._pages[0].currentRow.x === 0 && this._pages[0].currentRow.y === 0) {
@@ -149,6 +145,11 @@ export class TextureAtlas implements ITextureAtlas {
     this._cacheMap.clear();
     this._cacheMapCombined.clear();
     this._didWarmUp = false;
+
+    // Invalidate renderer models so all texture pages are refreshed. The atlas may be shared, in
+    // which case the clearing renderer has cleared only its own model and every other owner still
+    // holds texture coords into the rows just wiped.
+    this._pageLayoutVersion++;
   }
 
   private _createNewPage(): AtlasPage {
@@ -184,6 +185,8 @@ export class TextureAtlas implements ITextureAtlas {
       // Only proceed with merge if we have exactly 4 same-sized pages. If not, we cannot
       // effectively reduce page count and merging would cause issues.
       if (mergingPages.length < 4 || mergingPages.some(p => p.canvas.width !== mergingPages[0].canvas.width)) {
+        // Evict instead of adding a page beyond the renderer's texture capacity.
+        this._evictAllPages();
         const newPage = new AtlasPage(this._document, this._textureSize);
         this._pages.push(newPage);
         this._activePages.push(newPage);
@@ -206,8 +209,8 @@ export class TextureAtlas implements ITextureAtlas {
       // Add the new merged page to the end
       this.pages.push(mergedPage);
 
-      // Request the model to be cleared to refresh all texture pages.
-      this._requestClearModel = true;
+      // Invalidate renderer models so all texture pages are refreshed.
+      this._pageLayoutVersion++;
       this._onAddTextureAtlasCanvas.fire(mergedPage.canvas);
     }
 
@@ -258,6 +261,23 @@ export class TextureAtlas implements ITextureAtlas {
     }
   }
 
+  private _evictAllPages(): void {
+    const startTime = performance.now();
+    const pageCount = this._pages.length;
+    for (const page of this._pages) {
+      this._onRemoveTextureAtlasCanvas.fire(page.canvas);
+      page.canvas.remove();
+    }
+    this._pages.length = 0;
+    this._activePages.length = 0;
+    this._overflowSizePage = undefined;
+    this._cacheMap.clear();
+    this._cacheMapCombined.clear();
+    this._didWarmUp = false;
+    this._pageLayoutVersion++;
+    this._logService.debug(`Evicted ${pageCount} WebGL atlas pages in ${(performance.now() - startTime).toFixed(2)}ms`);
+  }
+
   public getRasterizedGlyphCombinedChar(chars: string, bg: number, fg: number, ext: number, restrictToCellHeight: boolean, domContainer: HTMLElement | undefined): IRasterizedGlyph {
     return this._getFromCacheMap(this._cacheMapCombined, chars, bg, fg, ext, restrictToCellHeight, domContainer);
   }
@@ -815,11 +835,15 @@ export class TextureAtlas implements ITextureAtlas {
       // Create a new page for oversized glyphs as they come up
       if (rasterizedGlyph.size.x > this._textureSize) {
         if (!this._overflowSizePage) {
+          // Make room for the oversized page without exceeding texture capacity.
+          if (TextureAtlas.maxAtlasPages && this._pages.length >= TextureAtlas.maxAtlasPages) {
+            this._evictAllPages();
+          }
           this._overflowSizePage = new AtlasPage(this._document, this._config.deviceMaxTextureSize);
           this.pages.push(this._overflowSizePage);
 
-          // Request the model to be cleared to refresh all texture pages.
-          this._requestClearModel = true;
+          // Invalidate renderer models so all texture pages are refreshed.
+          this._pageLayoutVersion++;
           this._onAddTextureAtlasCanvas.fire(this._overflowSizePage.canvas);
         }
         activePage = this._overflowSizePage;

addons/addon-webgl/src/Types.ts

@@ -68,10 +68,12 @@ export interface ITextureAtlas extends IDisposable {
   warmUp(): void;
 
   /**
-   * Call when a frame is being drawn, this will return true if the atlas was cleared to make room
-   * for a new set of glyphs.
+   * Incremented whenever cached glyph texture page mappings may be stale, such as after atlas page
+   * merges or overflow page creation. Renderers compare this against their own last-seen value and
+   * rebuild their model when it changes; a shared atlas can have many renderers, so this must not
+   * be a consume-once flag.
    */
-  beginFrame(): boolean;
+  readonly pageLayoutVersion: number;
 
   /**
    * Clear all glyphs from the texture atlas.

addons/addon-webgl/test/WebglAtlasOverflow.test.ts

@@ -0,0 +1,481 @@
+/**
+ * Copyright (c) 2025 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { IImage32, decodePng } from '@lunapaint/png-codec';
+import test, { expect } from '@playwright/test';
+import type { Terminal, ITerminalInitOnlyOptions, ITerminalOptions } from '@xterm/xterm';
+import type { IWebglAddonOptions, WebglAddon } from '@xterm/addon-webgl';
+import { ITestContext, createTestContext, openTerminal } from '../../../test/playwright/TestUtils';
+
+type CellSignature = number[];
+type TestTerminalConstructor = new (options?: ITerminalOptions & ITerminalInitOnlyOptions) => ITestTerminal;
+type TestWebglAddonConstructor = new (options?: IWebglAddonOptions) => ITestWebglAddon;
+
+interface ITestTextureAtlasConstructor {
+  maxAtlasPages: number | undefined;
+  maxTextureSize: number | undefined;
+}
+
+interface ITestAtlasPage {
+  canvas: HTMLCanvasElement;
+}
+
+interface ITestTextureAtlas {
+  constructor: ITestTextureAtlasConstructor;
+  pages: ITestAtlasPage[];
+  pageLayoutVersion: number;
+  _overflowSizePage?: ITestAtlasPage;
+  _textureSize: number;
+}
+
+interface ITestGlyphRenderer {
+  _atlasTextures: unknown[];
+}
+
+interface ITestRenderer {
+  _charAtlas?: ITestTextureAtlas;
+  _glyphRenderer?: {
+    value?: ITestGlyphRenderer;
+  };
+  dimensions: {
+    device: {
+      cell: {
+        width: number;
+      };
+    };
+  };
+}
+
+interface ITestRenderService {
+  _renderer?: {
+    value?: ITestRenderer;
+  };
+}
+
+interface ITestTerminal extends Terminal {
+  _core?: {
+    _renderService?: ITestRenderService;
+  };
+}
+
+interface ITestWebglAddon extends WebglAddon {
+  _renderer?: ITestRenderer;
+}
+
+interface IAtlasEventStats {
+  removals: number;
+  maxPages: number;
+}
+
+interface ITestWindow extends Window {
+  Terminal: TestTerminalConstructor;
+  WebglAddon: TestWebglAddonConstructor;
+  term: ITestTerminal;
+  termB?: ITestTerminal;
+  addon?: ITestWebglAddon;
+  addonB?: ITestWebglAddon;
+  atlasEventStats?: IAtlasEventStats;
+}
+
+interface IAtlasLimits {
+  maxAtlasPages: number;
+  maxTextureSize: number;
+}
+
+interface IAtlasState {
+  pages: number;
+  atlasTextures: number;
+  pageLayoutVersion: number;
+  overflowPageCreated: boolean;
+  removals: number;
+  maxPages: number;
+}
+
+const NORMAL_HEADER = ' NORMAL_REF_0123456789';
+const POST_EVICTION_TEXT = ' AFTER_EVICTION_0123456789';
+const NORMAL_HEADER_COLS = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+const POST_EVICTION_COLS = [2, 3, 4, 5, 6, 7, 8, 9, 10, 11];
+const TERM_B_SELECTOR = '#terminal-container-b .xterm-screen';
+const TERM_SELECTOR = '#terminal-container .xterm-screen';
+
+async function loadWebglStrict(ctx: ITestContext): Promise<void> {
+  await ctx.page.evaluate(() => {
+    const w = window as unknown as ITestWindow;
+    w.addon = new w.WebglAddon({ preserveDrawingBuffer: true });
+    w.term.loadAddon(w.addon);
+  });
+  const isWebglRenderer = await ctx.page.evaluate(() => {
+    const w = window as unknown as ITestWindow;
+    return !!w.addon && w.term._core?._renderService?._renderer?.value === w.addon._renderer;
+  });
+  expect(isWebglRenderer, 'WebGL renderer must be active').toBe(true);
+}
+
+async function createTerminalB(ctx: ITestContext, cols: number): Promise<void> {
+  await ctx.page.evaluate(columnCount => {
+    const w = window as unknown as ITestWindow;
+    w.termB?.dispose();
+    document.getElementById('terminal-container-b')?.remove();
+    const element = document.createElement('div');
+    element.id = 'terminal-container-b';
+    document.body.appendChild(element);
+    w.termB = new w.Terminal({ cols: columnCount, rows: 24, allowProposedApi: true });
+    w.termB.open(element);
+    w.addonB = new w.WebglAddon({ preserveDrawingBuffer: true });
+    w.termB.loadAddon(w.addonB);
+  }, cols);
+}
+
+async function writeToBAndWaitForRender(ctx: ITestContext, data: string): Promise<void> {
+  await ctx.page.evaluate(value => new Promise<void>(resolve => {
+    const w = window as unknown as ITestWindow;
+    if (!w.termB) {
+      throw new Error('Terminal B must be created before writing to it');
+    }
+    const disposable = w.termB.onRender(() => {
+      disposable.dispose();
+      resolve();
+    });
+    w.termB.write(value);
+  }), data);
+}
+
+async function writeAndWaitForRender(ctx: ITestContext, data: string): Promise<void> {
+  const renderPromise = new Promise<void>(resolve => {
+    const disposable = ctx.proxy.onRender(() => {
+      disposable.dispose();
+      resolve();
+    });
+  });
+  await ctx.proxy.write(data);
+  await renderPromise;
+}
+
+async function refreshAndWaitForRender(ctx: ITestContext, terminal: 'term' | 'termB'): Promise<void> {
+  await ctx.page.evaluate(name => new Promise<void>(resolve => {
+    const w = window as unknown as ITestWindow;
+    const term = w[name];
+    if (!term) {
+      throw new Error(`${name} must exist before refreshing it`);
+    }
+    const disposable = term.onRender(() => {
+      disposable.dispose();
+      resolve();
+    });
+    term.refresh(0, term.rows - 1);
+  }), terminal);
+}
+
+async function configureAtlasLimits(ctx: ITestContext): Promise<IAtlasLimits> {
+  const limits = await ctx.page.evaluate(() => {
+    const w = window as unknown as ITestWindow;
+    const atlas = w.term._core?._renderService?._renderer?.value?._charAtlas;
+    if (!atlas || atlas.constructor.maxAtlasPages === undefined || atlas.constructor.maxTextureSize === undefined) {
+      return undefined;
+    }
+    const result = {
+      maxAtlasPages: atlas.constructor.maxAtlasPages,
+      maxTextureSize: atlas.constructor.maxTextureSize
+    };
+    atlas.constructor.maxAtlasPages = 4;
+    atlas.constructor.maxTextureSize = 512;
+    return result;
+  });
+  expect(limits, 'TextureAtlas limits must be initialized').toBeDefined();
+  return limits!;
+}
+
+async function restoreAtlasLimits(ctx: ITestContext, limits: IAtlasLimits | undefined): Promise<void> {
+  if (!limits) {
+    return;
+  }
+  await ctx.page.evaluate(original => {
+    const w = window as unknown as ITestWindow;
+    const atlas = w.term._core?._renderService?._renderer?.value?._charAtlas;
+    if (atlas) {
+      atlas.constructor.maxAtlasPages = original.maxAtlasPages;
+      atlas.constructor.maxTextureSize = original.maxTextureSize;
+    }
+  }, limits);
+}
+
+async function installAtlasEventStats(ctx: ITestContext): Promise<void> {
+  const installed = await ctx.page.evaluate(() => {
+    const w = window as unknown as ITestWindow;
+    const atlas = w.term._core?._renderService?._renderer?.value?._charAtlas;
+    if (!atlas || !w.addon) {
+      return false;
+    }
+    const stats: IAtlasEventStats = {
+      removals: 0,
+      maxPages: atlas.pages.length
+    };
+    w.atlasEventStats = stats;
+    w.addon.onAddTextureAtlasCanvas(() => {
+      stats.maxPages = Math.max(stats.maxPages, atlas.pages.length);
+    });
+    w.addon.onRemoveTextureAtlasCanvas(() => stats.removals++);
+    return true;
+  });
+  expect(installed, 'atlas event tracking must be installed').toBe(true);
+}
+
+async function getAtlasState(ctx: ITestContext): Promise<IAtlasState> {
+  const state = await ctx.page.evaluate(() => {
+    const w = window as unknown as ITestWindow;
+    const renderer = w.term._core?._renderService?._renderer?.value;
+    const atlas = renderer?._charAtlas;
+    const glyphRenderer = renderer?._glyphRenderer?.value;
+    const stats = w.atlasEventStats;
+    if (!atlas || !glyphRenderer || !stats) {
+      return undefined;
+    }
+    return {
+      pages: atlas.pages.length,
+      atlasTextures: glyphRenderer._atlasTextures.length,
+      pageLayoutVersion: atlas.pageLayoutVersion,
+      overflowPageCreated: !!atlas._overflowSizePage,
+      removals: stats.removals,
+      maxPages: stats.maxPages
+    };
+  });
+  expect(state, 'atlas state must be available').toBeDefined();
+  return state!;
+}
+
+function generateUniqueGlyphFlood(count: number, cols: number, offset: number): string {
+  const base = 0x4E00;
+  const range = 0x9FFF - base;
+  const perRow = Math.max(1, Math.floor(cols / 2));
+  let result = '';
+  for (let i = 0; i < count; i++) {
+    result += String.fromCodePoint(base + ((offset + i) % range));
+    if ((i + 1) % perRow === 0 && i + 1 < count) {
+      result += '\r\n';
+    }
+  }
+  return result;
+}
+
+async function captureRowSignatures(ctx: ITestContext, selector: string, cols: number, row: number, sampleCols: number[], debugName: string): Promise<CellSignature[]> {
+  const screenshotOptions = process.env.DEBUG ? { path: `out-esbuild-test/playwright/${debugName}.png` } : undefined;
+  const buffer = await ctx.page.locator(selector).screenshot(screenshotOptions);
+  const frame = {
+    cols,
+    rows: 24,
+    decoded: (await decodePng(new Uint8Array(buffer), { force32: true })).image
+  };
+  return sampleCols.map(col => cellSignature(frame, col, row));
+}
+
+function cellSignature(frame: { cols: number, rows: number, decoded: IImage32 }, col: number, row: number): CellSignature {
+  const grid = 4;
+  const data = frame.decoded.data;
+  const imageWidth = frame.decoded.width;
+  const cellWidth = frame.decoded.width / frame.cols;
+  const cellHeight = frame.decoded.height / frame.rows;
+  const x0 = (col - 1) * cellWidth;
+  const y0 = (row - 1) * cellHeight;
+  const sums = new Array<number>(grid * grid * 4).fill(0);
+  const counts = new Array<number>(grid * grid).fill(0);
+  const startX = Math.max(0, Math.floor(x0));
+  const startY = Math.max(0, Math.floor(y0));
+  const endX = Math.min(frame.decoded.width, Math.ceil(x0 + cellWidth));
+  const endY = Math.min(frame.decoded.height, Math.ceil(y0 + cellHeight));
+
+  for (let y = startY; y < endY; y++) {
+    const gy = Math.min(grid - 1, Math.max(0, Math.floor(((y - y0) / cellHeight) * grid)));
+    for (let x = startX; x < endX; x++) {
+      const gx = Math.min(grid - 1, Math.max(0, Math.floor(((x - x0) / cellWidth) * grid)));
+      const sub = gy * grid + gx;
+      const i = (y * imageWidth + x) * 4;
+      sums[sub * 4] += data[i];
+      sums[sub * 4 + 1] += data[i + 1];
+      sums[sub * 4 + 2] += data[i + 2];
+      sums[sub * 4 + 3] += data[i + 3];
+      counts[sub]++;
+    }
+  }
+
+  const signature = new Array<number>(grid * grid * 4).fill(0);
+  for (let sub = 0; sub < counts.length; sub++) {
+    if (counts[sub] > 0) {
+      signature[sub * 4] = sums[sub * 4] / counts[sub];
+      signature[sub * 4 + 1] = sums[sub * 4 + 1] / counts[sub];
+      signature[sub * 4 + 2] = sums[sub * 4 + 2] / counts[sub];
+      signature[sub * 4 + 3] = sums[sub * 4 + 3] / counts[sub];
+    }
+  }
+  return signature;
+}
+
+function signatureDiff(actual: CellSignature, reference: CellSignature): number {
+  let diff = 0;
+  for (let i = 0; i < actual.length; i++) {
+    diff = Math.max(diff, Math.abs(actual[i] - reference[i]));
+  }
+  return diff;
+}
+
+function expectSignatureMatches(actual: CellSignature, reference: CellSignature, message: string): void {
+  const diff = signatureDiff(actual, reference);
+  expect(diff, `${message}; max channel diff ${diff}`).toBeLessThanOrEqual(14);
+}
+
+test.describe('atlas page overflow (#6038)', () => {
+  test.skip(({ browserName }) => browserName !== 'chromium');
+  test.describe.configure({ timeout: 90000 });
+
+  test('evicts normal pages when the page cap cannot be reduced by merging', async ({ browser }) => {
+    const ctx = await createTestContext(browser);
+    const errors: string[] = [];
+    const onError = (error: Error): void => { errors.push(error.message); };
+    let limits: IAtlasLimits | undefined;
+    ctx.page.on('pageerror', onError);
+    try {
+      await openTerminal(ctx, { cols: 80, rows: 24 });
+      await loadWebglStrict(ctx);
+      limits = await configureAtlasLimits(ctx);
+
+      await openTerminal(ctx, { cols: 80, rows: 24 });
+      await loadWebglStrict(ctx);
+      await createTerminalB(ctx, 80);
+      await installAtlasEventStats(ctx);
+
+      const atlasShared = await ctx.page.evaluate(() => {
+        const w = window as unknown as ITestWindow;
+        return w.term._core?._renderService?._renderer?.value?._charAtlas === w.termB?._core?._renderService?._renderer?.value?._charAtlas;
+      });
+      expect(atlasShared, 'terminals with equal configs should share one texture atlas').toBe(true);
+
+      await writeToBAndWaitForRender(ctx, `\x1b[H${NORMAL_HEADER}\x1b[2;1H${POST_EVICTION_TEXT}`);
+      const headerReference = await captureRowSignatures(ctx, TERM_B_SELECTOR, 80, 1, NORMAL_HEADER_COLS, 'atlas-overflow-header-reference');
+      const postReference = await captureRowSignatures(ctx, TERM_B_SELECTOR, 80, 2, POST_EVICTION_COLS, 'atlas-overflow-post-reference');
+      await writeToBAndWaitForRender(ctx, '\x1b[2;1H\x1b[2K');
+
+      const initialState = await getAtlasState(ctx);
+      const glyphsPerChunk = 23 * 40 - 1;
+      for (let chunk = 0; chunk < 24; chunk++) {
+        await ctx.proxy.write('\x1b[H\x1b[2J' + generateUniqueGlyphFlood(glyphsPerChunk, 80, chunk * glyphsPerChunk));
+        await ctx.page.waitForTimeout(50);
+        const state = await getAtlasState(ctx);
+        if (state.removals > 0 || state.pages > state.atlasTextures || errors.length > 0) {
+          break;
+        }
+      }
+
+      const evictionState = await getAtlasState(ctx);
+      expect(evictionState.removals, 'normal atlas pages must be evicted at the page cap').toBeGreaterThan(0);
+      expect(evictionState.pageLayoutVersion, 'eviction must invalidate renderer models').toBeGreaterThan(initialState.pageLayoutVersion);
+      expect(evictionState.maxPages, 'atlas pages must stay within renderer texture capacity').toBeLessThanOrEqual(evictionState.atlasTextures);
+      expect(errors, `renderer must not throw during atlas eviction: ${errors[0] ?? ''}`).toEqual([]);
+
+      await writeToBAndWaitForRender(ctx, `\x1b[2;1H${POST_EVICTION_TEXT}`);
+      const termBHeader = await ctx.page.evaluate(() => {
+        const w = window as unknown as ITestWindow;
+        return w.termB?.buffer.active.getLine(0)?.translateToString(true);
+      });
+      expect(termBHeader, 'terminal B buffer must still contain the header').toBe(NORMAL_HEADER);
+
+      const headerAfter = await captureRowSignatures(ctx, TERM_B_SELECTOR, 80, 1, NORMAL_HEADER_COLS, 'atlas-overflow-header-after');
+      const postAfter = await captureRowSignatures(ctx, TERM_B_SELECTOR, 80, 2, POST_EVICTION_COLS, 'atlas-overflow-post-after');
+      for (let i = 0; i < NORMAL_HEADER_COLS.length; i++) {
+        expectSignatureMatches(headerAfter[i], headerReference[i], `existing header col ${NORMAL_HEADER_COLS[i]} changed after eviction`);
+      }
+      for (let i = 0; i < POST_EVICTION_COLS.length; i++) {
+        expectSignatureMatches(postAfter[i], postReference[i], `new text col ${POST_EVICTION_COLS[i]} changed after eviction`);
+      }
+
+      const stableState = await getAtlasState(ctx);
+      await refreshAndWaitForRender(ctx, 'termB');
+      const refreshedState = await getAtlasState(ctx);
+      expect(refreshedState.pageLayoutVersion, 'an unchanged full refresh must not evict again').toBe(stableState.pageLayoutVersion);
+      expect(refreshedState.removals, 'an unchanged full refresh must not remove more pages').toBe(stableState.removals);
+    } finally {
+      ctx.page.off('pageerror', onError);
+      await restoreAtlasLimits(ctx, limits).catch(() => {});
+      await ctx.page.close();
+    }
+  });
+
+  test('evicts before adding an oversized glyph page at the page cap', async ({ browser }) => {
+    const ctx = await createTestContext(browser);
+    const errors: string[] = [];
+    const onError = (error: Error): void => { errors.push(error.message); };
+    let limits: IAtlasLimits | undefined;
+    ctx.page.on('pageerror', onError);
+    try {
+      await openTerminal(ctx, { cols: 160, rows: 24 });
+      await loadWebglStrict(ctx);
+      limits = await configureAtlasLimits(ctx);
+
+      await openTerminal(ctx, { cols: 160, rows: 24 });
+      await loadWebglStrict(ctx);
+      await installAtlasEventStats(ctx);
+
+      let state = await getAtlasState(ctx);
+      let offset = 0;
+      for (let chunk = 0; chunk < 120 && state.pages < state.atlasTextures; chunk++) {
+        const glyphCount = state.pages < state.atlasTextures - 1 ? 200 : 25;
+        await ctx.proxy.write('\x1b[H\x1b[2J' + generateUniqueGlyphFlood(glyphCount, 160, offset));
+        await ctx.page.waitForTimeout(50);
+        offset += glyphCount;
+        state = await getAtlasState(ctx);
+      }
+      expect(state.pages, 'normal atlas pages must reach the texture capacity before the oversized glyph').toBe(state.atlasTextures);
+      expect(state.overflowPageCreated, 'normal glyph filling must not create the oversized page').toBe(false);
+      expect(errors, `renderer must not fail while filling normal pages: ${errors[0] ?? ''}`).toEqual([]);
+
+      await writeAndWaitForRender(ctx, '\x1b[H\x1b[2K\x1b[24;1H');
+      const sampleCols = [1, 8, 16, 24, 32];
+      const blankSignatures = await captureRowSignatures(ctx, TERM_SELECTOR, 160, 1, sampleCols, 'atlas-overflow-wide-blank');
+      const joinedLength = await ctx.page.evaluate(() => {
+        const w = window as unknown as ITestWindow;
+        const renderer = w.term._core?._renderService?._renderer?.value;
+        const atlas = renderer?._charAtlas;
+        if (!renderer || !atlas) {
+          throw new Error('renderer and atlas must exist');
+        }
+        const cellWidth = renderer.dimensions.device.cell.width;
+        const length = Math.min(w.term.cols - 1, Math.ceil(atlas._textureSize / cellWidth) + 32);
+        if (length * cellWidth <= atlas._textureSize) {
+          throw new Error('joined glyph must be wider than a normal atlas page');
+        }
+        const marker = 'W'.repeat(length);
+        w.term.registerCharacterJoiner(text => text.startsWith(marker) ? [[0, length]] : []);
+        return length;
+      });
+
+      const beforeOversized = await getAtlasState(ctx);
+      await ctx.proxy.write(`\x1b[H${'W'.repeat(joinedLength)}`);
+      await ctx.page.waitForTimeout(50);
+      const oversizedState = await getAtlasState(ctx);
+      expect(oversizedState.overflowPageCreated, 'the joined glyph must use the oversized atlas page').toBe(true);
+      expect(oversizedState.removals, 'normal pages must be evicted before adding the oversized page').toBeGreaterThan(beforeOversized.removals);
+      expect(oversizedState.maxPages, 'oversized page creation must stay within renderer texture capacity').toBeLessThanOrEqual(oversizedState.atlasTextures);
+      expect(oversizedState.pageLayoutVersion, 'oversized eviction must invalidate renderer models').toBeGreaterThan(beforeOversized.pageLayoutVersion);
+      expect(errors, `renderer must not throw while adding the oversized page: ${errors[0] ?? ''}`).toEqual([]);
+
+      const wideSignatures = await captureRowSignatures(ctx, TERM_SELECTOR, 160, 1, sampleCols, 'atlas-overflow-wide-after');
+      for (let i = 0; i < sampleCols.length; i++) {
+        expect(signatureDiff(wideSignatures[i], blankSignatures[i]), `wide glyph col ${sampleCols[i]} must render visible pixels`).toBeGreaterThan(14);
+      }
+
+      const stableState = await getAtlasState(ctx);
+      await refreshAndWaitForRender(ctx, 'term');
+      const refreshedState = await getAtlasState(ctx);
+      expect(refreshedState.pageLayoutVersion, 'oversized glyph refresh must settle without another eviction').toBe(stableState.pageLayoutVersion);
+      expect(refreshedState.removals, 'oversized glyph refresh must not remove more pages').toBe(stableState.removals);
+      const wideAfterRefresh = await captureRowSignatures(ctx, TERM_SELECTOR, 160, 1, sampleCols, 'atlas-overflow-wide-refreshed');
+      for (let i = 0; i < sampleCols.length; i++) {
+        expectSignatureMatches(wideAfterRefresh[i], wideSignatures[i], `wide glyph col ${sampleCols[i]} changed after refresh`);
+      }
+    } finally {
+      ctx.page.off('pageerror', onError);
+      await restoreAtlasLimits(ctx, limits).catch(() => {});
+      await ctx.page.close();
+    }
+  });
+});

addons/addon-webgl/test/WebglAtlasStress.test.ts

@@ -0,0 +1,288 @@
+/**
+ * Copyright (c) 2025 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { decodePng, type IImage32 } from '@lunapaint/png-codec';
+import test, { expect } from '@playwright/test';
+import type { Terminal, ITerminalInitOnlyOptions, ITerminalOptions } from '@xterm/xterm';
+import type { IWebglAddonOptions, WebglAddon } from '@xterm/addon-webgl';
+import { ITestContext, createTestContext, openTerminal } from '../../../test/playwright/TestUtils';
+
+type CellSignature = number[];
+type TestTerminalConstructor = new (options?: ITerminalOptions & ITerminalInitOnlyOptions) => ITestTerminal;
+type TestWebglAddonConstructor = new (options?: IWebglAddonOptions) => ITestWebglAddon;
+
+interface ITestTextureAtlas {
+  readonly pages: ReadonlyArray<{ readonly canvas: HTMLCanvasElement }>;
+}
+
+interface ITestGlyphRenderer {
+  readonly _atlasTextures: ReadonlyArray<unknown>;
+}
+
+interface ITestRenderer {
+  _charAtlas?: ITestTextureAtlas;
+  _glyphRenderer?: {
+    value?: ITestGlyphRenderer;
+  };
+}
+
+interface ITestRenderService {
+  _renderer?: {
+    value?: ITestRenderer;
+  };
+}
+
+interface ITestTerminal extends Terminal {
+  _core?: {
+    _renderService?: ITestRenderService;
+  };
+}
+
+interface ITestWebglAddon extends WebglAddon {
+  _renderer?: ITestRenderer;
+}
+
+interface IAtlasEventStats {
+  additions: number;
+  maxPages: number;
+}
+
+interface ITestWindow {
+  WebglAddon: TestWebglAddonConstructor;
+  term: ITestTerminal;
+  addon?: ITestWebglAddon;
+  atlasEventStats?: IAtlasEventStats;
+}
+
+interface IAtlasState {
+  additions: number;
+  atlasTextures: number;
+  maxPages: number;
+}
+
+const REFERENCE_LINE = 'Ref0123456789ABCDEF';
+const REFERENCE_COLS = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19];
+const TERM_SELECTOR = '#terminal-container .xterm-screen';
+
+async function loadWebglStrict(ctx: ITestContext): Promise<void> {
+  await ctx.page.evaluate(() => {
+    const w = window as unknown as ITestWindow;
+    w.addon = new w.WebglAddon({ preserveDrawingBuffer: true });
+    w.term.loadAddon(w.addon);
+  });
+  const isWebglRenderer = await ctx.page.evaluate(() => {
+    const w = window as unknown as ITestWindow;
+    return !!w.addon && w.term._core?._renderService?._renderer?.value === w.addon._renderer;
+  });
+  expect(isWebglRenderer, 'WebGL renderer must be active').toBe(true);
+}
+
+async function installAtlasEventStats(ctx: ITestContext): Promise<void> {
+  const installed = await ctx.page.evaluate(() => {
+    const w = window as unknown as ITestWindow;
+    const atlas = w.term._core?._renderService?._renderer?.value?._charAtlas;
+    if (!atlas || !w.addon) {
+      return false;
+    }
+    const stats: IAtlasEventStats = {
+      additions: 0,
+      maxPages: atlas.pages.length
+    };
+    w.atlasEventStats = stats;
+    w.addon.onAddTextureAtlasCanvas(() => {
+      stats.additions++;
+      stats.maxPages = Math.max(stats.maxPages, atlas.pages.length);
+    });
+    return true;
+  });
+  expect(installed, 'atlas event tracking must be installed').toBe(true);
+}
+
+async function getAtlasState(ctx: ITestContext): Promise<IAtlasState> {
+  const state = await ctx.page.evaluate(() => {
+    const w = window as unknown as ITestWindow;
+    const renderer = w.term._core?._renderService?._renderer?.value;
+    const glyphRenderer = renderer?._glyphRenderer?.value;
+    const stats = w.atlasEventStats;
+    if (!glyphRenderer || !stats) {
+      return undefined;
+    }
+    return {
+      additions: stats.additions,
+      atlasTextures: glyphRenderer._atlasTextures.length,
+      maxPages: stats.maxPages
+    };
+  });
+  expect(state, 'atlas state must be available').toBeDefined();
+  return state!;
+}
+
+async function writeAndWaitForRender(ctx: ITestContext, data: string): Promise<void> {
+  const renderPromise = new Promise<void>(resolve => {
+    const disposable = ctx.proxy.onRender(() => {
+      disposable.dispose();
+      resolve();
+    });
+  });
+  await ctx.proxy.write(data);
+  await renderPromise;
+}
+
+async function refreshAndWaitForRender(ctx: ITestContext): Promise<void> {
+  const renderPromise = new Promise<void>(resolve => {
+    const disposable = ctx.proxy.onRender(() => {
+      disposable.dispose();
+      resolve();
+    });
+  });
+  await ctx.proxy.refresh(0, (await ctx.proxy.rows) - 1);
+  await renderPromise;
+}
+
+function generateSyntheticTuiFrames(frameCount: number, cols: number, rows: number): string[] {
+  const spinner = ['|', '/', '-', '\\'];
+  const words = ['reading', 'rendering', 'atlas', 'terminal', 'buffer', 'tokens', 'diff', 'patch'];
+  const frames: string[] = [];
+  for (let frameIndex = 0; frameIndex < frameCount; frameIndex++) {
+    const lines = [
+      `+${'-'.repeat(cols - 2)}+`,
+      `|${(` ${spinner[frameIndex % spinner.length]} Copilot is working`).padEnd(cols - 2).slice(0, cols - 2)}|`,
+      `+${'-'.repeat(cols - 2)}+`
+    ];
+    for (let row = 3; row < rows - 1; row++) {
+      const foreground = 31 + ((frameIndex + row) % 6);
+      const text = `${words[(frameIndex + row) % words.length]} ${frameIndex}:${row}`;
+      lines.push(`\x1b[${foreground}m${text}\x1b[0m`);
+    }
+    lines.push(`\x1b[2mtokens ${1000 + frameIndex * 37}\x1b[0m`);
+    frames.push(`\x1b[2J\x1b[H${lines.join('\r\n')}`);
+  }
+  return frames;
+}
+
+function generateUniqueGlyphFlood(count: number, cols: number, offset: number): string {
+  const base = 0x4E00;
+  const range = 0x9FFF - base;
+  const perRow = Math.max(1, Math.floor(cols / 2));
+  let result = '';
+  for (let i = 0; i < count; i++) {
+    result += String.fromCodePoint(base + ((offset + i) % range));
+    if ((i + 1) % perRow === 0 && i + 1 < count) {
+      result += '\r\n';
+    }
+  }
+  return result;
+}
+
+async function captureRowSignatures(ctx: ITestContext, row: number, cols: number[], debugName: string): Promise<CellSignature[]> {
+  const screenshotOptions = process.env.DEBUG ? { path: `out-esbuild-test/playwright/${debugName}.png` } : undefined;
+  const buffer = await ctx.page.locator(TERM_SELECTOR).screenshot(screenshotOptions);
+  const frame = {
+    cols: await ctx.proxy.cols,
+    rows: await ctx.proxy.rows,
+    decoded: (await decodePng(new Uint8Array(buffer), { force32: true })).image
+  };
+  return cols.map(col => cellSignature(frame, col, row));
+}
+
+function cellSignature(frame: { cols: number, rows: number, decoded: IImage32 }, col: number, row: number): CellSignature {
+  const grid = 4;
+  const data = frame.decoded.data;
+  const imageWidth = frame.decoded.width;
+  const cellWidth = frame.decoded.width / frame.cols;
+  const cellHeight = frame.decoded.height / frame.rows;
+  const x0 = (col - 1) * cellWidth;
+  const y0 = (row - 1) * cellHeight;
+  const sums = new Array<number>(grid * grid * 4).fill(0);
+  const counts = new Array<number>(grid * grid).fill(0);
+  const startX = Math.max(0, Math.floor(x0));
+  const startY = Math.max(0, Math.floor(y0));
+  const endX = Math.min(frame.decoded.width, Math.ceil(x0 + cellWidth));
+  const endY = Math.min(frame.decoded.height, Math.ceil(y0 + cellHeight));
+
+  for (let y = startY; y < endY; y++) {
+    const gy = Math.min(grid - 1, Math.max(0, Math.floor(((y - y0) / cellHeight) * grid)));
+    for (let x = startX; x < endX; x++) {
+      const gx = Math.min(grid - 1, Math.max(0, Math.floor(((x - x0) / cellWidth) * grid)));
+      const sub = gy * grid + gx;
+      const i = (y * imageWidth + x) * 4;
+      sums[sub * 4] += data[i];
+      sums[sub * 4 + 1] += data[i + 1];
+      sums[sub * 4 + 2] += data[i + 2];
+      sums[sub * 4 + 3] += data[i + 3];
+      counts[sub]++;
+    }
+  }
+
+  const signature = new Array<number>(grid * grid * 4).fill(0);
+  for (let sub = 0; sub < counts.length; sub++) {
+    if (counts[sub] > 0) {
+      signature[sub * 4] = sums[sub * 4] / counts[sub];
+      signature[sub * 4 + 1] = sums[sub * 4 + 1] / counts[sub];
+      signature[sub * 4 + 2] = sums[sub * 4 + 2] / counts[sub];
+      signature[sub * 4 + 3] = sums[sub * 4 + 3] / counts[sub];
+    }
+  }
+  return signature;
+}
+
+function expectSignatureMatches(actual: CellSignature, reference: CellSignature, message: string): void {
+  let diff = 0;
+  for (let i = 0; i < actual.length; i++) {
+    diff = Math.max(diff, Math.abs(actual[i] - reference[i]));
+  }
+  expect(diff, `${message}; max channel diff ${diff}`).toBeLessThanOrEqual(14);
+}
+
+test.describe('WebGL atlas TUI stress (#6038)', () => {
+  test.skip(({ browserName }) => browserName !== 'chromium', 'WebGL atlas tests run on Chromium/SwiftShader only');
+  test.describe.configure({ timeout: 90000 });
+
+  test('primary-buffer glyphs survive alternate-buffer redraws and atlas page churn', async ({ browser }) => {
+    const ctx = await createTestContext(browser);
+    const errors: string[] = [];
+    const onError = (error: Error): void => { errors.push(error.message); };
+    ctx.page.on('pageerror', onError);
+    try {
+      await openTerminal(ctx, { cols: 80, rows: 24, scrollback: 5000 });
+      await loadWebglStrict(ctx);
+      await installAtlasEventStats(ctx);
+
+      await writeAndWaitForRender(ctx, REFERENCE_LINE);
+      const reference = await captureRowSignatures(ctx, 1, REFERENCE_COLS, 'atlas-stress-reference');
+
+      await writeAndWaitForRender(ctx, '\x1b[?1049h');
+      for (const frame of generateSyntheticTuiFrames(30, 80, 24)) {
+        await writeAndWaitForRender(ctx, frame);
+      }
+      const glyphsPerViewport = 23 * 40 - 1;
+      for (let chunk = 0; chunk < 4; chunk++) {
+        await writeAndWaitForRender(ctx, `\x1b[2J\x1b[H${generateUniqueGlyphFlood(glyphsPerViewport, 80, chunk * glyphsPerViewport)}`);
+      }
+      await writeAndWaitForRender(ctx, '\x1b[?1049l');
+      await refreshAndWaitForRender(ctx);
+
+      const state = await getAtlasState(ctx);
+      expect(state.additions, 'stress workload must add atlas pages').toBeGreaterThan(0);
+      expect(state.maxPages, 'stress workload must exercise multiple atlas pages').toBeGreaterThan(1);
+      expect(state.maxPages, 'atlas pages must remain within renderer texture capacity').toBeLessThanOrEqual(state.atlasTextures);
+      expect(errors, `renderer must not throw during TUI stress: ${errors[0] ?? ''}`).toEqual([]);
+
+      const primaryText = await ctx.page.evaluate(() => {
+        const w = window as unknown as ITestWindow;
+        return w.term.buffer.active.getLine(0)?.translateToString(true);
+      });
+      expect(primaryText, 'primary buffer must still contain the reference line').toBe(REFERENCE_LINE);
+
+      const after = await captureRowSignatures(ctx, 1, REFERENCE_COLS, 'atlas-stress-after');
+      for (let i = 0; i < REFERENCE_COLS.length; i++) {
+        expectSignatureMatches(after[i], reference[i], `primary-buffer glyph at col ${REFERENCE_COLS[i]} changed after TUI stress`);
+      }
+    } finally {
+      ctx.page.off('pageerror', onError);
+      await ctx.page.close();
+    }
+  });
+});

addons/addon-webgl/test/WebglSharedAtlasGarble.test.ts

@@ -0,0 +1,282 @@
+/**
+ * Copyright (c) 2025 The xterm.js authors. All rights reserved.
+ * @license MIT
+ */
+
+import { IImage32, decodePng } from '@lunapaint/png-codec';
+import test, { expect } from '@playwright/test';
+import type { Terminal, ITerminalInitOnlyOptions, ITerminalOptions } from '@xterm/xterm';
+import type { IWebglAddonOptions, WebglAddon } from '@xterm/addon-webgl';
+import { ITestContext, createTestContext, openTerminal } from '../../../test/playwright/TestUtils';
+
+type CellSignature = number[];
+type TestTerminalConstructor = new (options?: ITerminalOptions & ITerminalInitOnlyOptions) => ITestTerminal;
+type TestWebglAddonConstructor = new (options?: IWebglAddonOptions) => ITestWebglAddon;
+
+interface ITestTextureAtlasConstructor {
+  maxAtlasPages: number | undefined;
+}
+
+interface ITestTextureAtlas {
+  constructor: ITestTextureAtlasConstructor;
+}
+
+interface ITestRenderer {
+  _charAtlas?: ITestTextureAtlas;
+}
+
+interface ITestRenderService {
+  _renderer?: {
+    value?: ITestRenderer;
+  };
+}
+
+interface ITestTerminal extends Terminal {
+  _core?: {
+    _renderService?: ITestRenderService;
+  };
+}
+
+interface ITestWebglAddon extends WebglAddon {
+  _renderer?: ITestRenderer;
+}
+
+declare global {
+  interface Window { // eslint-disable-line @typescript-eslint/naming-convention
+    Terminal: TestTerminalConstructor;
+    WebglAddon: TestWebglAddonConstructor;
+    term: ITestTerminal;
+    termB?: ITestTerminal;
+    addon?: ITestWebglAddon;
+    addonB?: ITestWebglAddon;
+  }
+}
+
+const HEADER = ' HEADER_REF_0123456789';
+const HEADER_COLS = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+const TERM_B_SELECTOR = '#terminal-container-b .xterm-screen';
+
+async function loadWebglStrict(ctx: ITestContext): Promise<void> {
+  await ctx.page.evaluate(() => {
+    window.addon = new window.WebglAddon({ preserveDrawingBuffer: true });
+    window.term.loadAddon(window.addon);
+  });
+  const isWebglRenderer = await ctx.page.evaluate(() => {
+    return !!window.addon && window.term?._core?._renderService?._renderer?.value === window.addon._renderer;
+  });
+  expect(isWebglRenderer, 'WebGL renderer must be active').toBe(true);
+}
+
+async function createTerminalB(ctx: ITestContext): Promise<void> {
+  await ctx.page.evaluate(() => {
+    window.termB?.dispose();
+    document.getElementById('terminal-container-b')?.remove();
+    const el = document.createElement('div');
+    el.id = 'terminal-container-b';
+    document.body.appendChild(el);
+    window.termB = new window.Terminal({ cols: 80, rows: 24, allowProposedApi: true });
+    window.termB.open(el);
+    window.addonB = new window.WebglAddon({ preserveDrawingBuffer: true });
+    window.termB.loadAddon(window.addonB);
+  });
+}
+
+async function writeToBAndWaitForRender(ctx: ITestContext, data: string): Promise<void> {
+  await ctx.page.evaluate(d => new Promise<void>(resolve => {
+    const termB = window.termB;
+    if (!termB) {
+      throw new Error('Terminal B must be created before writing to it');
+    }
+    const disposable = termB.onRender(() => {
+      disposable.dispose();
+      resolve();
+    });
+    termB.write(d);
+  }), data);
+}
+
+async function writeAndWaitForRender(ctx: ITestContext, data: string): Promise<void> {
+  const renderPromise = new Promise<void>(resolve => {
+    const disposable = ctx.proxy.onRender(() => {
+      disposable.dispose();
+      resolve();
+    });
+  });
+  await ctx.proxy.write(data);
+  await renderPromise;
+}
+
+async function setMaxAtlasPages(ctx: ITestContext, maxAtlasPages: number): Promise<void> {
+  const applied = await ctx.page.evaluate(max => {
+    const atlas = window.term?._core?._renderService?._renderer?.value?._charAtlas;
+    if (!atlas) {
+      return false;
+    }
+    atlas.constructor.maxAtlasPages = max;
+    return true;
+  }, maxAtlasPages);
+  expect(applied, 'should be able to set TextureAtlas.maxAtlasPages').toBe(true);
+}
+
+async function resetMaxAtlasPages(ctx: ITestContext): Promise<void> {
+  await ctx.page.evaluate(() => {
+    const atlas = window.term?._core?._renderService?._renderer?.value?._charAtlas;
+    if (atlas) {
+      atlas.constructor.maxAtlasPages = undefined;
+    }
+  });
+}
+
+function generateColoredAsciiFlood(cells: number, offset: number = 0): string {
+  const letters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+  let out = '';
+  for (let i = 0; i < cells; i++) {
+    const ch = letters[(offset + i) % letters.length];
+    const fg = (offset + i) % 256;
+    const bg = (offset + i * 7) % 256;
+    out += `\x1b[38;5;${fg}m\x1b[48;5;${bg}m${ch}`;
+    if ((i + 1) % 78 === 0 && i + 1 < cells) {
+      out += '\x1b[0m\r\n';
+    }
+  }
+  return out + '\x1b[0m';
+}
+
+async function captureRowSignatures(ctx: ITestContext, row: number, cols: number[]): Promise<CellSignature[]> {
+  const screenshotOptions = process.env.DEBUG ? { path: 'out-esbuild-test/playwright/shared-atlas-term-b.png' } : undefined;
+  const buffer = await ctx.page.locator(TERM_B_SELECTOR).screenshot(screenshotOptions);
+  const frame = {
+    cols: 80,
+    rows: 24,
+    decoded: (await decodePng(new Uint8Array(buffer), { force32: true })).image
+  };
+  return cols.map(col => cellSignature(frame, col, row));
+}
+
+function cellSignature(frame: { cols: number, rows: number, decoded: IImage32 }, col: number, row: number): CellSignature {
+  const grid = 4;
+  const data = frame.decoded.data;
+  const imageWidth = frame.decoded.width;
+  const cellWidth = frame.decoded.width / frame.cols;
+  const cellHeight = frame.decoded.height / frame.rows;
+  const x0 = (col - 1) * cellWidth;
+  const y0 = (row - 1) * cellHeight;
+  const sums = new Array<number>(grid * grid * 4).fill(0);
+  const counts = new Array<number>(grid * grid).fill(0);
+  const startX = Math.max(0, Math.floor(x0));
+  const startY = Math.max(0, Math.floor(y0));
+  const endX = Math.min(frame.decoded.width, Math.ceil(x0 + cellWidth));
+  const endY = Math.min(frame.decoded.height, Math.ceil(y0 + cellHeight));
+
+  for (let y = startY; y < endY; y++) {
+    const gy = Math.min(grid - 1, Math.max(0, Math.floor(((y - y0) / cellHeight) * grid)));
+    for (let x = startX; x < endX; x++) {
+      const gx = Math.min(grid - 1, Math.max(0, Math.floor(((x - x0) / cellWidth) * grid)));
+      const sub = gy * grid + gx;
+      const i = (y * imageWidth + x) * 4;
+      sums[sub * 4] += data[i];
+      sums[sub * 4 + 1] += data[i + 1];
+      sums[sub * 4 + 2] += data[i + 2];
+      sums[sub * 4 + 3] += data[i + 3];
+      counts[sub]++;
+    }
+  }
+
+  const signature = new Array<number>(grid * grid * 4).fill(0);
+  for (let sub = 0; sub < counts.length; sub++) {
+    if (counts[sub] > 0) {
+      signature[sub * 4] = sums[sub * 4] / counts[sub];
+      signature[sub * 4 + 1] = sums[sub * 4 + 1] / counts[sub];
+      signature[sub * 4 + 2] = sums[sub * 4 + 2] / counts[sub];
+      signature[sub * 4 + 3] = sums[sub * 4 + 3] / counts[sub];
+    }
+  }
+  return signature;
+}
+
+function expectSignatureMatches(actual: CellSignature, reference: CellSignature, message: string): void {
+  let diff = 0;
+  for (let i = 0; i < actual.length; i++) {
+    diff = Math.max(diff, Math.abs(actual[i] - reference[i]));
+  }
+  expect(diff, `${message}; max channel diff ${diff}`).toBeLessThanOrEqual(14);
+}
+
+test.describe('shared-atlas garble across terminals (#6038)', () => {
+  test.skip(({ browserName }) => browserName !== 'chromium');
+  test.describe.configure({ timeout: 60000 });
+
+  test('keeps a second terminal rendering correctly after shared atlas page merges', async ({ browser }) => {
+    const ctx = await createTestContext(browser);
+    try {
+      await openTerminal(ctx, { cols: 80, rows: 24 });
+      await loadWebglStrict(ctx);
+      await createTerminalB(ctx);
+
+      const atlasShared = await ctx.page.evaluate(() => {
+        return window.term._core?._renderService?._renderer?.value?._charAtlas === window.termB?._core?._renderService?._renderer?.value?._charAtlas;
+      });
+      expect(atlasShared, 'terminals with equal configs should share one texture atlas').toBe(true);
+
+      await setMaxAtlasPages(ctx, 4);
+
+      await writeToBAndWaitForRender(ctx, HEADER);
+      const reference = await captureRowSignatures(ctx, 1, HEADER_COLS);
+
+      for (let c = 0; c < 10; c++) {
+        await writeAndWaitForRender(ctx, '\x1b[2;1H' + generateColoredAsciiFlood(23 * 78, c * 23 * 78));
+      }
+
+      await writeToBAndWaitForRender(ctx, '\x1b[24;1Hx');
+      const termBHeader = await ctx.page.evaluate(() => window.termB?.buffer.active.getLine(0)?.translateToString(true));
+      expect(termBHeader, 'terminal B buffer must still contain the header').toBe(HEADER);
+
+      const after = await captureRowSignatures(ctx, 1, HEADER_COLS);
+      for (let i = 0; i < HEADER_COLS.length; i++) {
+        expectSignatureMatches(after[i], reference[i], `terminal B header col ${HEADER_COLS[i]} garbled by terminal A's atlas merges`);
+      }
+    } finally {
+      await resetMaxAtlasPages(ctx).catch(() => {});
+      await ctx.page.close();
+    }
+  });
+
+  test('keeps a second terminal rendering correctly after terminal A clears the shared atlas', async ({ browser }) => {
+    const ctx = await createTestContext(browser);
+    try {
+      await openTerminal(ctx, { cols: 80, rows: 24 });
+      await loadWebglStrict(ctx);
+      await createTerminalB(ctx);
+
+      const atlasShared = await ctx.page.evaluate(() => {
+        return window.term._core?._renderService?._renderer?.value?._charAtlas === window.termB?._core?._renderService?._renderer?.value?._charAtlas;
+      });
+      expect(atlasShared, 'terminals with equal configs should share one texture atlas').toBe(true);
+
+      await writeToBAndWaitForRender(ctx, HEADER);
+      const reference = await captureRowSignatures(ctx, 1, HEADER_COLS);
+
+      // Terminal A alone clears the shared atlas, as embedders do to force a redraw (VS Code calls
+      // this for every terminal on OS resume). This wipes the pages that terminal B's model still
+      // holds texture coords into.
+      await ctx.proxy.clearTextureAtlas();
+
+      // Terminal A repopulates the cleared pages with a different glyph set, so B's stale coords now
+      // resolve to whatever A rasterized into those slots.
+      await writeAndWaitForRender(ctx, '\x1b[2;1H' + generateColoredAsciiFlood(23 * 78));
+
+      // Nudge B into a render that does not touch row 1, mirroring a terminal that is idle but
+      // visible. Row 1 must still be drawn from a model B rebuilt against the current atlas.
+      await writeToBAndWaitForRender(ctx, '\x1b[24;1Hx');
+      const termBHeader = await ctx.page.evaluate(() => window.termB?.buffer.active.getLine(0)?.translateToString(true));
+      expect(termBHeader, 'terminal B buffer must still contain the header').toBe(HEADER);
+
+      const after = await captureRowSignatures(ctx, 1, HEADER_COLS);
+      for (let i = 0; i < HEADER_COLS.length; i++) {
+        expectSignatureMatches(after[i], reference[i], `terminal B header col ${HEADER_COLS[i]} garbled by terminal A's atlas clear`);
+      }
+    } finally {
+      await ctx.page.close();
+    }
+  });
+});