handsontable 18.0.0 → 18.1.0-rc7

package/3rdparty/walkontable/src/table/domScaffold.mjs

@@ -0,0 +1,136 @@
+/**
+ * Construction-time DOM scaffolding for `Table` and every subclass.
+ *
+ * These methods build the wrapper DOM the engine renders into — the `wtSpreader` / `wtHider` /
+ * `wtHolder` wrapper chain around the `<table>`, and the `thead`/`tbody`/`colgroup` sections. They run
+ * once from the `Table` constructor. They are universal (every table type needs them), so the mixin is
+ * applied once to the base `Table` (`mixin(Table, domScaffold)` in `table.ts`) and inherited by all
+ * subclasses. The methods run on the `Table` instance (`this`), assigning its public fields
+ * (`TABLE`/`THEAD`/`TBODY`/`COLGROUP`) and reading the settings. They reach the injected deps through
+ * the read-only `this.deps` getter, since a mixin cannot see the class's `#deps` private field.
+ */ import { isHTMLElement, hasClass, setAttribute } from '../../../../helpers/dom/element.mjs';
+import { A11Y_PRESENTATION, A11Y_TABINDEX } from '../../../../helpers/a11y.mjs';
+import { defineGetter } from '../../../../helpers/object.mjs';
+const domScaffold = {
+    /**
+   * Ensures the table has `tbody`, `thead`, and `colgroup` sections, creating any that are missing.
+   *
+   * @this Table
+   */ fixTableDomTree () {
+        const rootDocument = this.deps.rootDocument;
+        this.TBODY = this.TABLE.querySelector('tbody');
+        if (!this.TBODY) {
+            this.TBODY = rootDocument.createElement('tbody');
+            this.TABLE.appendChild(this.TBODY);
+        }
+        this.THEAD = this.TABLE.querySelector('thead');
+        if (!this.THEAD) {
+            this.THEAD = rootDocument.createElement('thead');
+            this.TABLE.insertBefore(this.THEAD, this.TBODY);
+        }
+        this.COLGROUP = this.TABLE.querySelector('colgroup');
+        if (!this.COLGROUP) {
+            this.COLGROUP = rootDocument.createElement('colgroup');
+            this.TABLE.insertBefore(this.COLGROUP, this.THEAD);
+        }
+    },
+    /**
+   * @param {HTMLTableElement} table An element to process.
+   * @returns {HTMLElement}
+   * @this Table
+   */ createSpreader (table) {
+        const parent = table.parentNode;
+        let spreader;
+        if (!parent || parent.nodeType !== Node.ELEMENT_NODE || !isHTMLElement(parent) || !hasClass(parent, 'wtHolder')) {
+            spreader = this.deps.rootDocument.createElement('div');
+            spreader.className = 'wtSpreader';
+            if (parent) {
+                // if TABLE is detached (e.g. in Jasmine test), it has no parentNode so we cannot attach holder to it
+                table.before(spreader);
+            }
+            spreader.appendChild(table);
+        }
+        if (spreader) {
+            spreader.style.position = 'relative';
+            if (this.wtSettings.getSetting('ariaTags')) {
+                setAttribute(spreader, [
+                    A11Y_PRESENTATION()
+                ]);
+            }
+        }
+        return spreader;
+    },
+    /**
+   * @param {HTMLElement} spreader An element to the hider element is injected.
+   * @returns {HTMLElement}
+   * @this Table
+   */ createHider (spreader) {
+        const parent = spreader.parentNode;
+        let hider;
+        if (!parent || parent.nodeType !== Node.ELEMENT_NODE || !isHTMLElement(parent) || !hasClass(parent, 'wtHolder')) {
+            hider = this.deps.rootDocument.createElement('div');
+            hider.className = 'wtHider';
+            if (parent) {
+                // if TABLE is detached (e.g. in Jasmine test), it has no parentNode so we cannot attach holder to it
+                spreader.before(hider);
+            }
+            hider.appendChild(spreader);
+        }
+        if (hider && this.wtSettings.getSetting('ariaTags')) {
+            setAttribute(hider, [
+                A11Y_PRESENTATION()
+            ]);
+        }
+        return hider;
+    },
+    /**
+   * @param {HTMLElement} hider An element to the holder element is injected.
+   * @returns {HTMLElement}
+   * @this Table
+   */ createHolder (hider) {
+        const parent = hider.parentNode;
+        let holder;
+        if (!parent || parent.nodeType !== Node.ELEMENT_NODE || !isHTMLElement(parent) || !hasClass(parent, 'wtHolder')) {
+            holder = this.deps.rootDocument.createElement('div');
+            holder.style.position = 'relative';
+            holder.className = 'wtHolder';
+            if (this.isMaster) {
+                setAttribute(holder, [
+                    A11Y_TABINDEX(-1)
+                ]);
+            }
+            if (parent) {
+                // if TABLE is detached (e.g. in Jasmine test), it has no parentNode so we cannot attach holder to it
+                hider.before(holder);
+            }
+            if (this.isMaster) {
+                const holderParent = holder.parentNode;
+                // holderParent is null when TABLE is detached (e.g. in Jasmine tests); skip class assignment in that case.
+                // isHTMLElement() is used instead of `instanceof HTMLElement` because the latter fails in
+                // cross-frame contexts (e.g. when HoT is mounted inside an <iframe> via React portals):
+                // the iframe's HTMLElement constructor !== the parent frame's HTMLElement.
+                if (isHTMLElement(holderParent)) {
+                    holderParent.className += 'ht_master handsontable';
+                    holderParent.setAttribute('dir', this.wtSettings.getSettingPure('rtlMode') ? 'rtl' : 'ltr');
+                    if (this.wtSettings.getSetting('ariaTags')) {
+                        setAttribute(holderParent, [
+                            A11Y_PRESENTATION()
+                        ]);
+                    }
+                }
+            }
+            holder.appendChild(hider);
+        }
+        if (holder && this.wtSettings.getSetting('ariaTags')) {
+            setAttribute(holder, [
+                A11Y_PRESENTATION()
+            ]);
+        }
+        return holder;
+    }
+};
+defineGetter(domScaffold, 'MIXIN_NAME', 'domScaffold', {
+    writable: false,
+    enumerable: false
+});
+export { domScaffold };

package/3rdparty/walkontable/src/table/drawCycle.d.mts

@@ -0,0 +1 @@
+export * from './drawCycle.js';

package/3rdparty/walkontable/src/table/drawCycle.d.ts

@@ -0,0 +1,16 @@
+import type Table from './baseTable';
+/**
+ * Runs one draw of a Walkontable table. Dispatches to the master or the overlay-clone cycle by
+ * instance role. Both cycles are free functions over the table's public surface + `get deps()`
+ * (never `#deps`), exactly like the `cellAccess`/`domScaffold` mixins — so the draw orchestration
+ * lives outside the `Table` class while the measurement/query methods it calls stay on it.
+ *
+ * Behavior is byte-identical to the previous single `Table.draw()`: the master cycle keeps every
+ * step in its original order, and the clone cycle is the strict subset a clone executed (a clone
+ * never has a begin-layout phase, never fires the view hooks, and never runs the fixed-position
+ * pass, so `positionChanged` stays `false` and it always renders selections through the else-path).
+ *
+ * @param {Table} table The table instance (master or an overlay clone).
+ * @param {boolean} fastDraw If `true`, try to only reposition rather than re-render cells.
+ */
+export declare function runDrawCycle(table: Table, fastDraw: boolean): void;

package/3rdparty/walkontable/src/table/drawCycle.js

@@ -0,0 +1,405 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "runDrawCycle", {
+    enumerable: true,
+    get: function() {
+        return runDrawCycle;
+    }
+});
+const _column = /*#__PURE__*/ _interop_require_default(require("../filter/column"));
+const _row = /*#__PURE__*/ _interop_require_default(require("../filter/row"));
+const _overlay = require("../overlay");
+const _oversizedRows = require("../axisSizing/oversizedRows");
+function _interop_require_default(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+function runDrawCycle(table, fastDraw) {
+    const { wtSettings } = table;
+    const rowHeaders = wtSettings.getSetting('rowHeaders');
+    const columnHeaders = wtSettings.getSetting('columnHeaders');
+    const ctx = {
+        runFastDraw: fastDraw,
+        performRedraw: true,
+        positionChanged: false,
+        syncFrozenRows: false,
+        rowHeaders,
+        columnHeaders,
+        rowHeadersCount: rowHeaders.length,
+        columnHeadersCount: columnHeaders.length
+    };
+    if (table.isMaster) {
+        runMasterDrawCycle(table, ctx);
+    } else {
+        runCloneDrawCycle(table, ctx);
+    }
+}
+/**
+ * The master table's draw cycle: resolve the layout, decide fast vs full, (optionally) render the
+ * cells, place the overlays, then reconcile a 1px border shift or render the active selections.
+ *
+ * @param {Table} table The master table.
+ * @param {DrawContext} ctx The per-draw scratch.
+ */ function runMasterDrawCycle(table, ctx) {
+    const { wtSettings } = table;
+    const wtOverlays = table.deps.getWtOverlays();
+    const wtViewport = table.deps.getWtViewport();
+    // What is on the screen before this draw touches anything. Restored (when safe — see
+    // `restoreRenderedStateIfSafe`) if the `beforeDraw` hook cancels the cell render below.
+    const renderedStateBeforeDraw = captureRenderedState(table, wtViewport);
+    // Record whether this master draw was entered as a fast/scroll draw, BEFORE `createCalculators`
+    // below can downgrade `ctx.runFastDraw`. A `forceFullRender` (`hot.render()`) enters as `draw(false)`,
+    // so this is `false` for it even if the scroll-direction flags are still set (an `afterScroll` hook
+    // can trigger a render while they are). The clones read this off the master through their clone
+    // source, so the header-render skip decision stays consistent across the master and its overlays.
+    wtOverlays.isScrollDrivenDraw = ctx.runFastDraw;
+    wtOverlays.beforeDraw();
+    table.holderOffset = table.deps.geometryReader.offset(table.holder);
+    wtViewport.rowHeightCache.ensureBuilt();
+    wtViewport.columnWidthCache.ensureBuilt();
+    // On the single-pass gated path, decide and apply the header-border classes
+    // (`innerBorderTop` / `innerBorderInlineStart`) BEFORE resolving the snapshot and rendering the
+    // cells, from the pre-render scroll position + settings. Cells then render in their final
+    // position, so the post-render `resetFixedPosition` toggle is a no-op (`positionChanged` stays
+    // `false`) and the nested `wot.draw(true)` re-render never fires. Element mode only (guaranteed
+    // by the gate); the border box is thus present when `beginDrawLayout` measures the workspace,
+    // matching a steady-state scrolled draw.
+    if (wtViewport.usesLayoutSnapshotForCalculators()) {
+        wtOverlays.prepareHeaderBorders();
+    }
+    // Resolve the single-pass layout snapshot for this draw (scrollbar prediction from numbers).
+    // Not yet the source of truth for the calculators below — see Viewport#beginDrawLayout.
+    wtViewport.beginDrawLayout();
+    // On a scroll-driven draw both rendered bands (rows AND columns) keep their previous size
+    // (extending the new band past the viewport edge when the natural count is smaller). Stable band
+    // sizes mean the `OrderView`s never add or remove TR/TD/TH/COL nodes while scrolling — a
+    // structural DOM mutation would trigger the host page's `:has()` style invalidation, whose cost
+    // scales with the whole host document. Both axes stabilize on ANY scroll-driven draw: a draw for
+    // one axis recomputes the other axis' band too, so per-axis gating would let each axis shrink the
+    // other's band back and re-oscillate it. On top of that, both bands gain directional overscan
+    // (`applyRenderedColumnsBandOverscan` / `applyRenderedRowsBandOverscan`) so consecutive scroll
+    // steps land inside the rendered band and resolve as fast draws.
+    ctx.runFastDraw = wtViewport.createCalculators(ctx.runFastDraw, {
+        stationaryBands: wtOverlays.isScrollDrivenDraw && wtViewport.allowsStationaryBands()
+    });
+    if (ctx.rowHeadersCount && !wtSettings.getSetting('fixedColumnsStart')) {
+        const leftScrollPos = wtOverlays.inlineStartOverlay.getScrollPosition();
+        const previousState = table.correctHeaderWidth;
+        table.correctHeaderWidth = leftScrollPos !== 0;
+        if (previousState !== table.correctHeaderWidth) {
+            ctx.runFastDraw = false;
+        }
+    }
+    if (ctx.runFastDraw) {
+        wtOverlays.refresh(true);
+        // Fast (scroll) draws skip the full-render header-height pass below, so the master/top
+        // header heights can drift against the frozen overlays during scrolling (a tall wrapped
+        // frozen header that the master never renders). Re-sync here. The method is a cheap no-op
+        // unless the grid has frozen columns with column headers, so non-frozen grids are unaffected.
+        // No row-height twin of the call above is needed here: a fast draw re-renders neither the master
+        // nor the clones, so no cell content — and therefore no row height — can have changed.
+        (0, _oversizedRows.syncOversizedColumnHeadersWithFrozenOverlays)(table);
+    } else {
+        table.tableOffset = table.deps.geometryReader.offset(table.TABLE);
+        const filters = buildRenderFilters(table, ctx);
+        // Decided before the master renders, because `resetOversizedRows` (inside `renderCellBand`) has
+        // to know whether the frozen-derived records are still being maintained. When they are not — the
+        // master's band starts at column 0, so it renders every frozen column itself — they go back to
+        // the ordinary machinery, which wipes and re-measures them like any other oversized row.
+        ctx.syncFrozenRows = (0, _oversizedRows.shouldSyncOversizedRowsWithFrozenOverlays)(table);
+        if (!ctx.syncFrozenRows) {
+            wtViewport.releaseFrozenOversizedRows();
+        }
+        table.alignOverlaysWithTrimmingContainer(); // todo It calls method from child class (MasterTable).
+        const skipRender = {};
+        // Read the counter as late as possible — right before the hook fires — so the guard in
+        // `restoreRenderedStateIfSafe` asks exactly "did the HOOK render?", and a hypothetical engine-
+        // internal render earlier in this draw cannot silently disable a rollback that is still safe.
+        const renderCycleSeqBeforeHook = wtViewport.renderCycleSeq;
+        wtSettings.getSetting('beforeDraw', true, skipRender);
+        ctx.performRedraw = skipRender.skipRender !== true;
+        if (!ctx.performRedraw) {
+            // The cells are not rendered on this draw, so the rendered bands and the filters resolved above
+            // describe a band that never reached the DOM. Everything that resolves an element from a source
+            // index (`Table#getCell` and, through it, the selection render below) gates on the bands but
+            // reads the element through the filters and the TBODY, so leaving them advanced makes those two
+            // disagree: `getCell` then throws "TR was expected to be rendered but is not" for every row past
+            // the end of the stale DOM. Put the pre-draw state back when doing so is provably safe — the
+            // guard conditions and the deliberate fallbacks are documented on the helper.
+            restoreRenderedStateIfSafe(table, wtViewport, renderedStateBeforeDraw, renderCycleSeqBeforeHook);
+        } else {
+            renderCellBand(table, ctx, filters, isPureVerticalScrollDraw(wtOverlays));
+            if (!wtSettings.getSetting('externalRowCalculator')) {
+                // Single-pass: the fully/partially-visible calculators were already computed in pass 1
+                // (`createCalculators`) from the layout snapshot. On the snapshot path, the only thing that
+                // can change them post-render is `markOversizedRows` invalidating the row-height cache when
+                // rendered content is genuinely taller than its configured size. If both size caches are
+                // still current, the post-render values are identical, so this second pass is a redundant
+                // recompute — skip it. (Read `isCurrent()` before `ensureBuilt()` rebuilds an invalidated
+                // cache. Validated non-destructively across the full e2e: this predicate would skip 595
+                // draws with byte-identical ranges and 0 divergences.) The legacy measured path, and any
+                // draw with an oversized row, still recompute here.
+                const skipSecondPass = wtViewport.usesLayoutSnapshotForCalculators() && wtViewport.rowHeightCache.isCurrent() && wtViewport.columnWidthCache.isCurrent();
+                wtViewport.rowHeightCache.ensureBuilt();
+                wtViewport.columnWidthCache.ensureBuilt();
+                if (!skipSecondPass) {
+                    wtViewport.createVisibleCalculators();
+                }
+            }
+            // The seam: the master has rendered and both size caches and the viewport calculators were
+            // built from the frozen-derived heights, so clearing them now costs nothing — and it makes the
+            // frozen overlays below render at their natural content height, which is what keeps them
+            // re-measurable instead of ratcheting on their own cached value.
+            const wipedFrozenRows = ctx.syncFrozenRows ? (0, _oversizedRows.resetFrozenOversizedRows)(table) : undefined;
+            wtOverlays.refresh(false);
+            (0, _oversizedRows.syncOversizedColumnHeadersWithFrozenOverlays)(table);
+            // The frozen overlays have now rendered, so a row whose tallest cell lives in a frozen column
+            // (which the master's rendered band skips) can finally be measured. Runs after the header sync
+            // so a taller frozen header is already reflected in the THEAD when the body rows are re-sized.
+            const frozenRowHeightsChanged = (0, _oversizedRows.syncOversizedRowsWithFrozenOverlays)(table, wipedFrozenRows);
+            if (frozenRowHeightsChanged && !wtSettings.getSetting('externalRowCalculator')) {
+                // The calculators above were built from row heights this sync has since changed, and a
+                // frozen-derived height cannot be known any earlier — the frozen overlays had not rendered.
+                // An ordinary oversized row never reaches here: the master invalidates inside
+                // `renderCellBand`, before the calculators are computed. Left alone, the frame reports a
+                // visible row range measured against the old heights, which self-corrects on the next draw
+                // and so reads as an intermittent off-by-a-row to anything asking during this one.
+                // Both caches, as at the sibling call above: `createVisibleCalculators` builds the COLUMN
+                // visible calculators too, and an unbuilt strategy answers every offset with 0.
+                wtViewport.rowHeightCache.ensureBuilt();
+                wtViewport.columnWidthCache.ensureBuilt();
+                wtViewport.createVisibleCalculators();
+            }
+            wtOverlays.applyToDOM();
+            wtSettings.getSetting('onDraw', true);
+        }
+    }
+    placeFixedOverlays(table, ctx);
+    if (ctx.positionChanged) {
+        if (ctx.performRedraw) {
+            // It refreshes the cells borders caused by a 1px shift (introduced by overlays which add or
+            // remove `innerBorderTop` and `innerBorderInlineStart` CSS classes to the DOM element. This happens
+            // when there is a switch between rendering from 0 to N rows/columns and vice versa).
+            wtOverlays.refreshAll(); // `refreshAll()` internally already calls `refreshSelections()` method
+        } else {
+            // A skipped render must not run the nested reconciliation draw above (`refreshAll` is
+            // `wot.draw(true)`): the rolled-back band would fail its fast-draw check and escalate it to a
+            // full render that fires `beforeDraw` a second time and renders the cells the hook just
+            // cancelled. But the `innerBorder*` toggle has already shifted the layout by 1px AFTER the
+            // overlay positions were computed, so rerun the fixed-position pass against the post-toggle
+            // layout — it converges, because the second border-state check finds the class already in
+            // place — and render the selections that `refreshAll` would have refreshed.
+            placeFixedOverlays(table, ctx);
+            renderActiveSelections(table, ctx.runFastDraw);
+        }
+        // Outside the render gate on purpose: the master hider/spreader size is written ONLY here on the
+        // 1px-shift path (the per-overlay `adjustElementsSize()` calls inside `placeFixedOverlays` size
+        // the clone roots, not the master hider), and the bands it reads are current whether or not the
+        // cell render ran — a skipped draw would otherwise keep a stale scrollbar until an unrelated
+        // full draw.
+        wtOverlays.adjustElementsSize();
+    } else {
+        renderActiveSelections(table, ctx.runFastDraw);
+    }
+    wtOverlays.afterDraw(!ctx.runFastDraw && ctx.performRedraw);
+    table.deps.setDrawn(true);
+}
+/**
+ * The overlay-clone draw cycle. A clone is a separate Walkontable instance whose `draw()` is driven
+ * from the master's `wtOverlays.refresh(fastDraw)`. It has no begin-layout phase (so it cannot
+ * downgrade `runFastDraw` — it takes the master-resolved value), fires no view hooks, and runs no
+ * fixed-position pass, so it always renders selections through the normal path.
+ *
+ * @param {Table} table The overlay-clone table.
+ * @param {DrawContext} ctx The per-draw scratch.
+ */ function runCloneDrawCycle(table, ctx) {
+    if (!ctx.runFastDraw) {
+        table.tableOffset = table.deps.getParentTableOffset();
+        const filters = buildRenderFilters(table, ctx);
+        // A clone's render is never gated by `skipRender` (that gate is master-only), so it always runs.
+        // The scroll-direction flags live on the master's overlays, reached via the clone source.
+        const cloneSourceOverlays = table.deps.getCloneSource().wtOverlays;
+        renderCellBand(table, ctx, filters, isPureVerticalScrollDraw(cloneSourceOverlays));
+        if (table.is(_overlay.CLONE_BOTTOM)) {
+            table.deps.getCloneSource().wtOverlays.adjustElementsSize();
+        }
+    }
+    renderActiveSelections(table, ctx.runFastDraw);
+    table.deps.setDrawn(true);
+}
+/**
+ * Rebuilds the row/column render filters from the current first-rendered row/column. Shared by both
+ * cycles and called BEFORE the master `beforeDraw` gate, because the hook (and
+ * `alignOverlaysWithTrimmingContainer` before it) may read the filters for the band about to render.
+ * The filters and the rendered bands are the pair that `Table#getCell` resolves an element with, so
+ * when that gate cancels the render the master puts BOTH back to their pre-draw values — see
+ * {@link restoreRenderedStateIfSafe}.
+ *
+ * @param {Table} table The table (master or clone).
+ * @param {DrawContext} ctx The per-draw scratch (supplies the pre-hook header counts).
+ */ function buildRenderFilters(table, ctx) {
+    const startRow = Math.max(table.getFirstRenderedRow(), 0);
+    const startColumn = Math.max(table.getFirstRenderedColumn(), 0);
+    const rowFilter = new _row.default(startRow, table.wtSettings.getSetting('totalRows'), ctx.columnHeadersCount);
+    const columnFilter = new _column.default(startColumn, table.wtSettings.getSetting('totalColumns'), ctx.rowHeadersCount);
+    table.rowFilter = rowFilter;
+    table.columnFilter = columnFilter;
+    return {
+        rowFilter,
+        columnFilter
+    };
+}
+/**
+ * Captures the rendered row/column bands, the render filters, and the `correctHeaderWidth` flag,
+ * i.e. everything that describes which source rows and columns the current DOM holds and how it was
+ * rendered. Master-only: the `skipRender` gate it serves is master-only.
+ *
+ * @param {Table} table The master table.
+ * @param {Viewport} wtViewport The viewport that owns the rendered bands.
+ * @returns {RenderedState}
+ */ function captureRenderedState(table, wtViewport) {
+    return {
+        rowsRenderCalculator: wtViewport.rowsRenderCalculator,
+        columnsRenderCalculator: wtViewport.columnsRenderCalculator,
+        rowFilter: table.rowFilter,
+        columnFilter: table.columnFilter,
+        correctHeaderWidth: table.correctHeaderWidth
+    };
+}
+/**
+ * Puts the pre-draw rendered state back, undoing the band and filter advance of a draw whose render
+ * the `beforeDraw` hook cancelled — but only when the rollback is provably safe. When any guard
+ * fails, the this-draw state is kept, which is exactly the pre-rollback behavior of the engine, so
+ * a blocked rollback is never worse than what shipped before the rollback existed.
+ *
+ * The guards:
+ * - The viewport's render-cycle counter must not have moved since it was read right before the
+ *   `beforeDraw` hook fired. A hook that renders (a nested master `draw()`, or a draw of any overlay
+ *   clone — the clones share this viewport) has put a NEWER band into the DOM; rolling the shared
+ *   band back under it would create the very band/DOM divergence this rollback exists to prevent.
+ * - Per axis, the captured filter's build-time total must still match the current
+ *   `totalRows`/`totalColumns`. When the dataset shrank before the skipped draw (NestedRows cancels
+ *   the render right after its row removal), the captured band names rows that no longer exist — the
+ *   this-draw band, capped at the new totals, is the correct description. Each axis decides
+ *   independently, so a column-count change never blocks the row rollback (and vice versa); the
+ *   axes never disagree inside `getCell`, which gates and resolves each axis on its own pair.
+ *   (A dataset that GREW before a skipped draw keeps the this-draw band too; that band can then
+ *   overhang the stale DOM — a pre-existing edge of the skip contract, unchanged here.)
+ *
+ * The restore itself is asymmetric by design:
+ * - The render calculators are restored — `null` on a skipped first draw correctly reports
+ *   "nothing rendered", so `Table#getCell` answers with its out-of-viewport exit codes (and the
+ *   overlays' `applyToDOM` treats a `null` calculator as the nothing-rendered spreader offset).
+ * - The filters are restored only when the captured ones are non-null; on a skipped first draw the
+ *   just-built filters are kept instead, because filter consumers (`getRowHeader`, `getTrForRow`,
+ *   the selection scanner's header loop) read `rowFilter!` unguarded and must never see `null`
+ *   after a completed draw.
+ * - `correctHeaderWidth` is restored whenever no render happened, regardless of the totals gates:
+ *   the flag describes the row-header width the DOM was rendered with, and that DOM did not change.
+ *   Leaving it advanced would make the next draw see "no change" and never re-render the corrected
+ *   header width.
+ * - The visible-row/column calculators are deliberately NOT restored: they describe what the user
+ *   can see (scroll position), not what the DOM holds. After a skipped draw the visible band may
+ *   therefore extend past the rendered band — unlike a fast draw, which guarantees the visible band
+ *   sits inside the rendered one — and `getCell` answers those rows with exit codes.
+ *
+ * @param {Table} table The master table.
+ * @param {Viewport} wtViewport The viewport that owns the rendered bands.
+ * @param {RenderedState} state The state captured before the draw.
+ * @param {number} renderCycleSeqBeforeHook The render-cycle counter read right before the
+ *   `beforeDraw` hook fired.
+ */ function restoreRenderedStateIfSafe(table, wtViewport, state, renderCycleSeqBeforeHook) {
+    const { wtSettings } = table;
+    if (wtViewport.renderCycleSeq !== renderCycleSeqBeforeHook) {
+        return;
+    }
+    table.correctHeaderWidth = state.correctHeaderWidth;
+    if (state.rowFilter === null || state.rowFilter.total === wtSettings.getSetting('totalRows')) {
+        wtViewport.rowsRenderCalculator = state.rowsRenderCalculator;
+        if (state.rowFilter !== null) {
+            table.rowFilter = state.rowFilter;
+        }
+    }
+    if (state.columnFilter === null || state.columnFilter.total === wtSettings.getSetting('totalColumns')) {
+        wtViewport.columnsRenderCalculator = state.columnsRenderCalculator;
+        if (state.columnFilter !== null) {
+            table.columnFilter = state.columnFilter;
+        }
+    }
+}
+/**
+ * Returns `true` when this draw is a pure vertical scroll (only the vertical scroll position moved),
+ * so the column window (and thus the THEAD) is unchanged. The scroll-direction flags live on the
+ * master's overlays, so the master passes its own overlays and a clone passes its clone source's —
+ * each cycle already knows its role, so the resolution stays at the call site rather than re-branching
+ * here. `isScrollDrivenDraw` guards against a `forceFullRender` that runs while the scroll-direction
+ * flags are still set (an `afterScroll` hook can trigger one): a full render enters as `draw(false)`,
+ * so it is excluded here and always rebuilds the headers.
+ *
+ * @param {Overlays} wtOverlays The master's overlays object (the owner of the scroll-direction flags).
+ * @returns {boolean}
+ */ function isPureVerticalScrollDraw(wtOverlays) {
+    return !!wtOverlays && wtOverlays.isScrollDrivenDraw && wtOverlays.verticalScrolling && !wtOverlays.horizontalScrolling;
+}
+/**
+ * Renders the header + cell band and measures the rendered rows. Shared by both cycles. The
+ * role-specific branches stay inline and verbatim: bottom / bottom-left-corner overlays suppress
+ * column headers, and only the master or the bottom clone marks oversized rows.
+ *
+ * @param {Table} table The table (master or clone).
+ * @param {DrawContext} ctx The per-draw scratch (supplies the pre-hook header renderers).
+ * @param {{ rowFilter: RowFilter, columnFilter: ColumnFilter }} filters The filters just built by
+ *   `buildRenderFilters` (passed non-null rather than re-read off the nullable `table.*Filter`).
+ * @param {boolean} columnHeadersRenderSkippable Whether the column-header (THEAD) pass may be skipped
+ *   for this draw (a pure vertical scroll); resolved per role by the caller.
+ */ function renderCellBand(table, ctx, filters, columnHeadersRenderSkippable) {
+    table.tableRenderer.setHeaderContentRenderers(ctx.rowHeaders, ctx.columnHeaders);
+    if (table.is(_overlay.CLONE_BOTTOM) || table.is(_overlay.CLONE_BOTTOM_INLINE_START_CORNER)) {
+        // do NOT render headers on the bottom or bottom-left corner overlay
+        table.tableRenderer.setHeaderContentRenderers(ctx.rowHeaders, []);
+    }
+    table.tableRenderer.setColumnHeadersRenderSkippable(columnHeadersRenderSkippable);
+    const wipedOversizedRows = (0, _oversizedRows.resetOversizedRows)(table);
+    table.tableRenderer.setActiveOverlayName(table.name).setViewportSize(table.getRenderedRowsCount(), table.getRenderedColumnsCount()).setFilters(filters.rowFilter, filters.columnFilter).render();
+    // Mark that a cell band reached the DOM. The viewport is shared by the master and all overlay
+    // clones, so this advances one counter no matter which table rendered — the signal the master's
+    // `skipRender` rollback guards on (see `restoreRenderedStateIfSafe`).
+    table.deps.getWtViewport().renderCycleSeq += 1;
+    (0, _oversizedRows.adjustColumnHeaderHeights)(table);
+    if (table.isMaster || table.is(_overlay.CLONE_BOTTOM)) {
+        (0, _oversizedRows.markOversizedRows)(table, wipedOversizedRows);
+    }
+}
+/**
+ * Renders the active selections for this table's overlay. Shared by both cycles (the clone always
+ * reaches here; the master reaches here only when the fixed-position pass reported no 1px shift).
+ *
+ * @param {Table} table The table (master or clone).
+ * @param {boolean} runFastDraw Whether this draw is a fast (reposition-only) draw.
+ */ function renderActiveSelections(table, runFastDraw) {
+    table.deps.getSelectionManager().setActiveOverlay(table.facadeGetter()).render(runFastDraw);
+}
+/**
+ * Master-only fixed-position pass: repositions the top / bottom / inline-start / corner overlays and
+ * records in `ctx.positionChanged` whether an `innerBorder*` toggle shifted the layout by 1px (the
+ * corners do not contribute to the flag, matching the original).
+ *
+ * @param {Table} table The master table.
+ * @param {DrawContext} ctx The per-draw scratch (receives `positionChanged`).
+ */ function placeFixedOverlays(table, ctx) {
+    const wtOverlays = table.deps.getWtOverlays();
+    ctx.positionChanged = wtOverlays.topOverlay.resetFixedPosition();
+    if (wtOverlays.bottomOverlay.clone) {
+        ctx.positionChanged = wtOverlays.bottomOverlay.resetFixedPosition() || ctx.positionChanged;
+    }
+    ctx.positionChanged = wtOverlays.inlineStartOverlay.resetFixedPosition() || ctx.positionChanged;
+    if (wtOverlays.topInlineStartCornerOverlay) {
+        wtOverlays.topInlineStartCornerOverlay.resetFixedPosition();
+    }
+    if (wtOverlays.bottomInlineStartCornerOverlay && wtOverlays.bottomInlineStartCornerOverlay.clone) {
+        wtOverlays.bottomInlineStartCornerOverlay.resetFixedPosition();
+    }
+}