feat: 3x3 frozen band model - right-frozen columns + simultaneous top/bottom frozen rows (ViewportMgr Phase 4)

cypress/cypress.config.ts

@@ -7,6 +7,10 @@ export default defineConfig({
   video: false,
   viewportWidth: 1200,
   viewportHeight: 900,
+  // retry once in headless runs only: absorbs machine-load flakes in timing-sensitive
+  // tests (native clipboard paste, render waits) while Cypress still reports retried
+  // tests as flaky, so real intermittent bugs stay visible
+  retries: { runMode: 1, openMode: 0 },
   e2e: {
     experimentalRunAllSpecs: true,
     testIsolation: false,

cypress/e2e/dom-shape-characterization.cy.ts

@@ -107,6 +107,20 @@ describe('DOM shape characterization - non-frozen grid (example1-simple)', () =>
   it('should render all rows into the top-left canvas only', () => {
     assertRowRouting({ topL: true, topR: false, bottomL: false, bottomR: false });
   });
+
+  it('should stamp band-truth markers: left elements are the live main/body band, right panes unmarked (M18a)', () => {
+    cy.get('#myGrid .slick-pane-top.slick-pane-left')
+      .should('have.attr', 'data-colband', 'main')
+      .and('have.attr', 'data-rowband', 'body');
+    cy.get('#myGrid .grid-canvas-top.grid-canvas-left')
+      .should('have.attr', 'data-colband', 'main')
+      .and('have.attr', 'data-rowband', 'body');
+    cy.get('#myGrid .slick-pane-header.slick-pane-left').should('have.attr', 'data-rowband', 'header');
+    cy.get('#myGrid .slick-pane-header.slick-pane-right').should('not.have.attr', 'data-colband');
+    cy.get('#myGrid .slick-pane-bottom.slick-pane-left').should('not.have.attr', 'data-rowband');
+    // the live body canvas is uniquely selectable without mode logic
+    cy.get('#myGrid .grid-canvas[data-colband="main"][data-rowband="body"]').should('have.length', 1);
+  });
 });
 
 describe('DOM shape characterization - frozen columns only (example-frozen-columns)', () => {
@@ -161,4 +175,18 @@ describe('DOM shape characterization - frozen columns and rows (example-frozen-c
   it('should render rows into all four canvases', () => {
     assertRowRouting({ topL: true, topR: true, bottomL: true, bottomR: true });
   });
+
+  it('should stamp band-truth markers per role in the frozen-both configuration (M18a)', () => {
+    cy.get('#myGrid .slick-pane-top.slick-pane-left')
+      .should('have.attr', 'data-colband', 'left')
+      .and('have.attr', 'data-rowband', 'top-frozen');
+    cy.get('#myGrid .slick-pane-top.slick-pane-right')
+      .should('have.attr', 'data-colband', 'main')
+      .and('have.attr', 'data-rowband', 'top-frozen');
+    cy.get('#myGrid .slick-pane-bottom.slick-pane-right')
+      .should('have.attr', 'data-colband', 'main')
+      .and('have.attr', 'data-rowband', 'body');
+    // exactly one live main/body canvas, mode-independently
+    cy.get('#myGrid .grid-canvas[data-colband="main"][data-rowband="body"]').should('have.length', 1);
+  });
 });

cypress/e2e/dom-shape-lazy-panes.cy.ts

@@ -0,0 +1,57 @@
+/**
+ * DOM-shape characterization for the lazyPanes opt-in (Phase 3 of the ViewportMgr
+ * refactor). A grid built with `lazyPanes: true` and no frozen rows/columns must
+ * create ONLY the top-left pane set — 2 panes (header-left, top-left), 1 viewport,
+ * 1 canvas — instead of the historical 6/4/4 structure, while remaining fully
+ * functional. Companion to dom-shape-characterization.cy.ts (the default mode).
+ */
+
+describe('DOM shape - lazyPanes single-pane build (example-lazy-panes)', () => {
+  it('should load the example', () => {
+    cy.visit(`${Cypress.config('baseUrl')}/examples/example-lazy-panes.html`);
+  });
+
+  it('should build only the header-left and top-left panes, in order', () => {
+    cy.get('#myGrid > .slick-pane')
+      .should('have.length', 2)
+      .then(($panes) => {
+        expect($panes.eq(0)).to.have.class('slick-pane-header');
+        expect($panes.eq(0)).to.have.class('slick-pane-left');
+        expect($panes.eq(1)).to.have.class('slick-pane-top');
+        expect($panes.eq(1)).to.have.class('slick-pane-left');
+      });
+    cy.get('#myGrid .slick-pane-right').should('have.length', 0);
+    cy.get('#myGrid .slick-pane-bottom').should('have.length', 0);
+  });
+
+  it('should build exactly one viewport and one canvas, correctly nested', () => {
+    cy.get('#myGrid .slick-viewport').should('have.length', 1);
+    cy.get('#myGrid .grid-canvas').should('have.length', 1);
+    cy.get('#myGrid .slick-pane-top.slick-pane-left > .slick-viewport.slick-viewport-top.slick-viewport-left').should('have.length', 1);
+    cy.get('#myGrid .slick-viewport-top.slick-viewport-left > .grid-canvas.grid-canvas-top.grid-canvas-left').should('have.length', 1);
+  });
+
+  it('should build only left-side header chrome', () => {
+    cy.get('#myGrid .slick-header').should('have.length', 1);
+    cy.get('#myGrid .slick-header-columns').should('have.length', 1);
+    cy.get('#myGrid .slick-headerrow').should('have.length', 1);
+    cy.get('#myGrid .slick-top-panel-scroller').should('have.length', 1);
+  });
+
+  it('should render header columns and rows normally', () => {
+    cy.get('#myGrid .slick-header-columns .slick-header-column').should('have.length', 6);
+    cy.get('#myGrid .grid-canvas-top.grid-canvas-left .slick-row').should('have.length.greaterThan', 0);
+    cy.get('#myGrid .grid-canvas .slick-row .slick-cell').first().should('contain', 'Task 0');
+  });
+
+  it('should support basic navigation (click makes a cell active)', () => {
+    cy.get('#myGrid .slick-row .slick-cell').first().click();
+    cy.get('#myGrid .slick-cell.active').should('have.length', 1);
+  });
+
+  it('should scroll vertically and keep rendering rows', () => {
+    cy.get('#myGrid .slick-viewport').scrollTo(0, 2000);
+    cy.get('#myGrid .grid-canvas .slick-row').should('have.length.greaterThan', 0);
+    cy.get('#myGrid .slick-viewport').scrollTo(0, 0);
+  });
+});

cypress/e2e/viewportmgr-band-routing.cy.ts

@@ -0,0 +1,131 @@
+/**
+ * Characterization of the band ROUTING and PREDICATE semantics ahead of M19b
+ * (facade column/row routing — FACADE-FEASIBILITY.md). These tests pin the
+ * boundary-value behavior the 'one predicate per historical semantic' rule
+ * protects: the inclusive `<= frozenColumn` / `<= frozenRow` comparisons, the
+ * header-cells-take-'frozen'-left-band-only vs data-cells-left-OR-right split,
+ * and cross-band element routing at the exact boundary indices.
+ *
+ * Named to sort after the example-* specs (shared browser session; see
+ * viewportmgr-lazy-materialization.cy.ts).
+ */
+
+describe('band routing - left freeze + frozen rows (example-frozen-columns-and-rows: frozenColumn 2, frozenRow 5)', () => {
+  it('should load the example', () => {
+    cy.visit(`${Cypress.config('baseUrl')}/examples/example-frozen-columns-and-rows.html`);
+  });
+
+  it('should route getHeaderColumn across the freeze boundary: idx 2 -> left container, idx 3 -> right container', () => {
+    cy.window().then((win: any) => {
+      const left = win.grid.getHeaderColumn(2) as HTMLElement;
+      const right = win.grid.getHeaderColumn(3) as HTMLElement;
+      expect(left.parentElement!.classList.contains('slick-header-columns-left'), 'idx 2 in left band').to.be.true;
+      expect(right.parentElement!.classList.contains('slick-header-columns-right'), 'idx 3 in main band').to.be.true;
+    });
+  });
+
+  it('should route getHeaderRowColumn across the same boundary', () => {
+    cy.window().then((win: any) => {
+      const left = win.grid.getHeaderRowColumn(2) as HTMLElement;
+      const right = win.grid.getHeaderRowColumn(3) as HTMLElement;
+      expect(left.parentElement!.classList.contains('slick-headerrow-columns-left'), 'idx 2 in left band').to.be.true;
+      expect(right.parentElement!.classList.contains('slick-headerrow-columns-right'), 'idx 3 in main band').to.be.true;
+    });
+  });
+
+  it('should give header CELLS the frozen class only in the left band, inclusive of the boundary column', () => {
+    cy.window().then((win: any) => {
+      [0, 1, 2].forEach((i) => {
+        expect((win.grid.getHeaderColumn(i) as HTMLElement).classList.contains('frozen'), `header ${i} frozen`).to.be.true;
+      });
+      expect((win.grid.getHeaderColumn(3) as HTMLElement).classList.contains('frozen'), 'header 3 not frozen').to.be.false;
+    });
+  });
+
+  it('should mark every top-band row frozen AND exactly one bottom-canvas row (the row == frozenRow inclusive quirk)', () => {
+    cy.get('#myGrid .grid-canvas-top.grid-canvas-left .slick-row').then(($rows) => {
+      expect($rows.length, '5 frozen-band rows rendered').to.eq(5);
+      $rows.each((_, row) => expect(row.classList.contains('frozen'), 'top row frozen').to.be.true);
+    });
+    // row index 5 satisfies `row <= frozenRow` (inclusive) but renders in the
+    // scrollable bottom canvas — the historical off-by-one, pinned deliberately
+    cy.get('#myGrid .grid-canvas-bottom.grid-canvas-left .slick-row.frozen').should('have.length', 1);
+  });
+
+  it('should give data CELLS the frozen class in the left band only', () => {
+    cy.get('#myGrid .grid-canvas-top.grid-canvas-left .slick-row').first().find('.slick-cell.frozen').should('have.length', 3);
+    cy.get('#myGrid .grid-canvas-top.grid-canvas-right .slick-row').first().find('.slick-cell.frozen').should('have.length', 0);
+  });
+
+  it('should span bands in getColumnByIndex and getHeaderChildren', () => {
+    cy.window().then((win: any) => {
+      const visibleCount = win.grid.getColumns().filter((c: any) => !c.hidden).length;
+      expect(win.grid.getHeaderChildren().length, 'header children across all bands').to.eq(visibleCount);
+      expect(win.grid.getColumnByIndex(2), 'idx 2 same element via both walks').to.eq(win.grid.getHeaderColumn(2));
+      expect(win.grid.getColumnByIndex(3), 'idx 3 same element via both walks').to.eq(win.grid.getHeaderColumn(3));
+    });
+  });
+
+  it('should never horizontally scroll for a left-frozen cell, inclusive of the boundary column', () => {
+    cy.window().then((win: any) => {
+      const scroller = win.document.querySelector('#myGrid .slick-pane-top.slick-pane-right .slick-viewport') as HTMLElement;
+      expect(scroller.scrollLeft, 'starts unscrolled').to.eq(0);
+      win.grid.scrollCellIntoView(8, 2); // boundary column: cell <= frozenColumn early-out
+      expect(scroller.scrollLeft, 'boundary frozen cell does not scroll').to.eq(0);
+    });
+  });
+});
+
+describe('band routing - right-frozen band (example-frozen-right-columns: frozenRightColumn 2, no left freeze)', () => {
+  it('should load the example', () => {
+    cy.visit(`${Cypress.config('baseUrl')}/examples/example-frozen-right-columns.html`);
+  });
+
+  it('should route getHeaderColumn across the RF boundary: main stays in the left container, RF in the right-frozen container', () => {
+    cy.window().then((win: any) => {
+      const rfStart = win.grid.getFrozenRightStartIndex();
+      const main = win.grid.getHeaderColumn(rfStart - 1) as HTMLElement;
+      const rf = win.grid.getHeaderColumn(rfStart) as HTMLElement;
+      expect(main.parentElement!.classList.contains('slick-header-columns-left'), 'main band hosts pre-boundary column').to.be.true;
+      expect(rf.parentElement!.classList.contains('slick-header-columns-right-frozen'), 'RF band hosts boundary column').to.be.true;
+    });
+  });
+
+  it('should NOT give RF header cells the frozen class (left-band-only semantic) while RF data cells DO get it', () => {
+    cy.window().then((win: any) => {
+      const rfStart = win.grid.getFrozenRightStartIndex();
+      expect((win.grid.getHeaderColumn(rfStart) as HTMLElement).classList.contains('frozen'), 'RF header cell not frozen-classed').to.be.false;
+    });
+    cy.get('#myGrid .grid-canvas-right-frozen .slick-row').first().find('.slick-cell.frozen').should('have.length', 2);
+    cy.get('#myGrid .grid-canvas-left .slick-row').first().find('.slick-cell.frozen').should('have.length', 0);
+  });
+
+  it('should never horizontally scroll for a right-frozen cell', () => {
+    cy.window().then((win: any) => {
+      const rfStart = win.grid.getFrozenRightStartIndex();
+      const scroller = win.document.querySelector('#myGrid .slick-pane-top.slick-pane-left .slick-viewport') as HTMLElement;
+      expect(scroller.scrollLeft, 'starts unscrolled').to.eq(0);
+      win.grid.scrollCellIntoView(5, rfStart);
+      expect(scroller.scrollLeft, 'RF cell does not scroll').to.eq(0);
+    });
+  });
+});
+
+describe('band routing - simultaneous top+bottom frozen rows (example-frozen-top-bottom-rows: frozenRow 3, frozenBottomRow 2)', () => {
+  it('should load the example', () => {
+    cy.visit(`${Cypress.config('baseUrl')}/examples/example-frozen-top-bottom-rows.html`);
+  });
+
+  it('should mark all top-band rows and all bottom-frozen-band rows frozen, plus exactly one body row (inclusive quirk)', () => {
+    cy.get('#myGrid .grid-canvas-top.grid-canvas-left .slick-row').then(($rows) => {
+      expect($rows.length, '3 top-frozen rows').to.eq(3);
+      $rows.each((_, row) => expect(row.classList.contains('frozen'), 'top row frozen').to.be.true);
+    });
+    cy.get('#myGrid .grid-canvas-bottom-frozen .slick-row').then(($rows) => {
+      expect($rows.length, '2 bottom-frozen rows').to.eq(2);
+      $rows.each((_, row) => expect(row.classList.contains('frozen'), 'bf row frozen').to.be.true);
+    });
+    // row index 3 passes `row <= frozenRow` (inclusive) but lives in the body canvas
+    cy.get('#myGrid .grid-canvas-bottom.grid-canvas-left:not(.grid-canvas-bottom-frozen) .slick-row.frozen').should('have.length', 1);
+  });
+});

cypress/e2e/viewportmgr-bottom-frozen-band.cy.ts

@@ -0,0 +1,120 @@
+/**
+ * DOM-shape characterization for the bottom-frozen row band (Phase 4, M14b of the
+ * ViewportMgr refactor). With frozenRow AND frozenBottomRow both set, a third row of
+ * panes materializes with `*-bottom-frozen` css classes — one per active column band.
+ * At this stage only the DOM exists: geometry (M14c) and routing (M14d) have not
+ * landed, so the classic top-frozen layout still renders all rows and these tests pin
+ * exactly that staged state.
+ *
+ * Named to sort after the example-* specs (shared browser session).
+ */
+
+describe('bottom-frozen band DOM - frozenRow + frozenBottomRow at init (example-frozen-top-bottom-rows)', () => {
+  it('should load the example', () => {
+    cy.visit(`${Cypress.config('baseUrl')}/examples/example-frozen-top-bottom-rows.html`);
+  });
+
+  it('should build 8 panes: the classic six plus two bottom-frozen panes after them', () => {
+    cy.get('#myGrid > .slick-pane').should('have.length', 8).then(($panes) => {
+      expect($panes.eq(6)).to.have.class('slick-pane-bottom-frozen');
+      expect($panes.eq(6)).to.have.class('slick-pane-left');
+      expect($panes.eq(7)).to.have.class('slick-pane-bottom-frozen');
+      expect($panes.eq(7)).to.have.class('slick-pane-right');
+    });
+    cy.get('#myGrid .slick-pane-right-frozen').should('have.length', 0);
+  });
+
+  it('should build the bottom-frozen viewports and canvases, correctly nested', () => {
+    cy.get('#myGrid .slick-viewport').should('have.length', 6);
+    cy.get('#myGrid .grid-canvas').should('have.length', 6);
+    cy.get('#myGrid .slick-pane-bottom-frozen.slick-pane-left > .slick-viewport.slick-viewport-bottom-frozen.slick-viewport-left').should('have.length', 1);
+    cy.get('#myGrid .slick-viewport-bottom-frozen.slick-viewport-left > .grid-canvas.grid-canvas-bottom-frozen.grid-canvas-left').should('have.length', 1);
+  });
+
+  it('should size and pin the band below the shrunk body pane (M14c geometry)', () => {
+    // example options: frozenRow: 3, frozenBottomRow: 2, default rowHeight 25
+    cy.get('#myGrid .slick-pane-bottom-frozen.slick-pane-left').then(($bf) => {
+      const bf = $bf[0] as HTMLElement;
+      expect(bf.offsetHeight, 'band height = frozenBottomRow * rowHeight').to.equal(2 * 25);
+
+      cy.get('#myGrid .slick-pane-bottom.slick-pane-left').then(($body) => {
+        const body = $body[0] as HTMLElement;
+        expect(bf.offsetTop, 'band sits directly below the body pane')
+          .to.be.closeTo(body.offsetTop + body.offsetHeight, 2);
+      });
+    });
+
+    cy.get('#myGrid .slick-viewport-bottom-frozen.slick-viewport-left').then(($vp) => {
+      expect(($vp[0] as HTMLElement).offsetHeight).to.equal(2 * 25);
+    });
+  });
+
+  it('should stamp three-row-band markers in simultaneous mode (M18a)', () => {
+    cy.get('#myGrid .slick-pane-top.slick-pane-left').should('have.attr', 'data-rowband', 'top-frozen');
+    cy.get('#myGrid .slick-pane-bottom.slick-pane-left').should('have.attr', 'data-rowband', 'body');
+    cy.get('#myGrid .slick-pane-bottom-frozen.slick-pane-left')
+      .should('have.attr', 'data-rowband', 'bottom-frozen')
+      .and('have.attr', 'data-colband', 'main');
+    cy.get('#myGrid .grid-canvas[data-rowband="bottom-frozen"]').should('have.length', 1);
+  });
+
+  it('should route rows into all three row bands (M14d routing)', () => {
+    // top band: 3 frozen rows; body: scrollable middle; bottom band: last 2 rows
+    cy.get('#myGrid .grid-canvas-top.grid-canvas-left .slick-row').should('have.length', 3);
+    cy.get('#myGrid .grid-canvas-top.grid-canvas-left .slick-cell').first().should('contain', 'Task 0');
+    cy.get('#myGrid .grid-canvas-bottom.grid-canvas-left .slick-row').should('have.length.greaterThan', 0);
+
+    cy.get('#myGrid .grid-canvas-bottom-frozen.grid-canvas-left .slick-row').should('have.length', 2);
+    cy.get('#myGrid .grid-canvas-bottom-frozen.grid-canvas-left .slick-row').first()
+      .should('have.class', 'frozen')
+      .find('.slick-cell').first().should('contain', 'Task 498');
+    cy.get('#myGrid .grid-canvas-bottom-frozen.grid-canvas-left .slick-row').last()
+      .find('.slick-cell').first().should('contain', 'Task 499');
+
+    // band-local coordinates: the first bottom-frozen row sits at the band origin
+    cy.get('#myGrid .grid-canvas-bottom-frozen.grid-canvas-left .slick-row').first().then(($row) => {
+      expect(($row[0] as HTMLElement).offsetTop, 'first band row rebased to y=0').to.equal(0);
+    });
+  });
+
+  it('should activate a bottom-frozen cell on click without scrolling the body', () => {
+    cy.get('#myGrid .slick-viewport-bottom.slick-viewport-left').then(($vp) => {
+      const before = ($vp[0] as HTMLElement).scrollTop;
+      cy.get('#myGrid .grid-canvas-bottom-frozen.grid-canvas-left .slick-cell').first().click();
+      cy.get('#myGrid .grid-canvas-bottom-frozen.grid-canvas-left .slick-cell.active').should('have.length', 1);
+      cy.get('#myGrid .slick-viewport-bottom.slick-viewport-left').then(($vp2) => {
+        expect(($vp2[0] as HTMLElement).scrollTop, 'body did not scroll').to.equal(before);
+      });
+    });
+  });
+});
+
+describe('bottom-frozen band DOM - runtime materialization on a classic grid', () => {
+  it('should materialize the band when both freeze options are set at runtime', () => {
+    cy.visit(`${Cypress.config('baseUrl')}/examples/example1-simple.html`);
+    cy.get('#myGrid > .slick-pane').should('have.length', 6);
+
+    cy.window().then((win: any) => {
+      win.grid.setOptions({ frozenRow: 2, frozenBottomRow: 2 });
+    });
+
+    cy.get('#myGrid > .slick-pane').should('have.length', 8);
+    cy.get('#myGrid .slick-viewport').should('have.length', 6);
+    cy.get('#myGrid .grid-canvas').should('have.length', 6);
+
+    // routing follows the runtime toggle
+    cy.get('#myGrid .grid-canvas-bottom-frozen.grid-canvas-left .slick-row').should('have.length', 2);
+    cy.get('#myGrid .grid-canvas-bottom-frozen.grid-canvas-left .slick-cell').first().should('contain', 'Task 498');
+  });
+
+  it('should keep the band in the DOM but hidden when simultaneous mode is turned off, restoring classic routing', () => {
+    cy.window().then((win: any) => {
+      win.grid.setOptions({ frozenBottomRow: 0 });
+    });
+
+    cy.get('#myGrid > .slick-pane').should('have.length', 8);
+    cy.get('#myGrid .slick-pane-bottom-frozen.slick-pane-left').should('not.be.visible');
+    cy.get('#myGrid .grid-canvas-bottom-frozen.grid-canvas-left .slick-row').should('have.length', 0);
+    cy.get('#myGrid .grid-canvas-top.grid-canvas-left .slick-row').should('have.length.greaterThan', 0);
+  });
+});