@adia-ai/web-components 0.8.44 → 0.8.46

package/components/table/table.class.js

@@ -26,7 +26,21 @@
  * table-ui has no local `density` prop (ADR-0054) — it converges onto the
  * ambient global [density="compact"|"spacious"] attribute; --table-py/-px
  * already derive from --a-space-* steps, which --a-density scales.
- *   paginate   — rows per page (0 = no pagination)
+ *   paginate   — rows per page (0 = no pagination); purely presentational
+ *                (page-size only) when [range-total] is present — gh#1754/ADR-0082
+ *   range-total — total row count across ALL server pages (Number, reflected,
+ *                presence-gated via hasAttribute — the attribute's PRESENCE, not
+ *                its value, is the server-mode switch, gh#1754/ADR-0082). Absent
+ *                → client mode, today's behavior exactly. Present + [paginate] > 0
+ *                → server mode: no local slicing (`.data` IS the current page and
+ *                renders whole, after local search/sort/filter), page count =
+ *                max(1, ceil(range-total / paginate)), and the internal page-reset
+ *                sites (`data` set, setFilter, clearFilters) are suppressed so a
+ *                fetch write-back never fights the pager back to page 0. Explicit
+ *                range-total="0" is server-confirmed empty (pager hidden), never
+ *                conflated with absent. With [paginate] absent/0, [range-total] is
+ *                inert for this table's own rendering but stays readable by a
+ *                bound table-footer-ui for its count-only label.
  *   loading    — show loading overlay
  *   search     — global search filter string
  *
@@ -45,13 +59,43 @@
  *   .sortState  → [{key, dir}] (read-only)
  *   .exportCSV(filename?)
  *
- * Events:
+ * Events (fired):
  *   sort       — { detail: { key, dir, sortState } }
  *   select     — { detail: { selected: [...indices] } }
  *   page       — { detail: { page } }
  *   resize     — { detail: { key, width } }
  *   cell-click — { detail: { key, row, value, dataIndex } }
  *   row-click  — { detail: { row, dataIndex } }  — row-level companion to cell-click
+ *
+ * Events (listened) — gh#1764/#1780, ADR-0079. table-toolbar-ui dispatches
+ * these directly at its [for]-resolved table-ui target instead of writing
+ * a property or calling a method; any other consumer may dispatch them too:
+ *   toolbar-search       — { detail: { value } }              → this.search =
+ *   toolbar-filter-set   — { detail: { key, value, op } }     → this.setFilter(key, value, op)
+ *   toolbar-filter-clear — { detail: {} }                      → this.clearFilters()
+ *   toolbar-columns-set  — { detail: { columns } }             → this.columns =
+ *   toolbar-paginate     — { detail: { pageSize } }            → this.paginate =
+ *   footer-page          — { detail: { page } }, 1-based       → gh#1807/ADR-0080,
+ *                           refined 0.2.0/ADR-0082. Dispatched directly at this
+ *                           element (table-footer-ui, or any other consumer).
+ *                           Applies whenever [paginate] > 0 — client mode and
+ *                           table-authoritative server mode ([range-total]
+ *                           present, REQ-D-003) alike, since #pageCount already
+ *                           knows server math; clamped to [1, pageCount]; a
+ *                           non-numeric/NaN detail.page is a documented no-op.
+ *                           At [paginate="0"] the command stays a no-op in
+ *                           either mode — with no page size there is no page
+ *                           range to move within. On a valid page, applies
+ *                           exactly like an internal pager click: updates the
+ *                           page, re-renders, and fires the existing `page`
+ *                           event (the fetch trigger in server mode).
+ *
+ * [no-pager] — boolean, reflected (gh#1807/ADR-0080). Hides the internal
+ * pagination bar while [paginate] slicing, page state, the `page` event, and
+ * the `footer-page` listener all stay intact — the anti-doubled-pager
+ * mechanism for a table-footer-ui composition, client- or server-mode alike
+ * (gh#1754/ADR-0082). Explicit author intent, never an auto-suppression
+ * side-effect of binding a footer.
  */
 
 import { UIElement } from '../../core/element.js';
@@ -94,6 +138,117 @@ function csvEscape(val) {
   return str;
 }
 
+// ── SSR adopt-in-place (gh#1678) ─────────────────────────────────────────────
+
+/**
+ * Idempotent attribute set — skip the DOM write entirely when the value
+ * already matches. `setAttribute` mutates (and queues a MutationObserver
+ * record) even when the new value is byte-identical to the old one, so a
+ * host/row-level attribute this render path sets on EVERY call (`role`,
+ * `tabindex`, `data-index`, `aria-selected`) must compare-before-write to
+ * let a byte-identical SSR-rendered subtree survive upgrade with zero
+ * subtree mutations (AC-004a-equivalent probe) — bare `setAttribute` cannot
+ * give that guarantee even when the value never actually changes.
+ */
+function setAttrIfChanged(el, name, value) {
+  if (el.getAttribute(name) !== value) el.setAttribute(name, value);
+}
+
+/** Idempotent attribute removal — same rationale as setAttrIfChanged. */
+function removeAttrIfPresent(el, name) {
+  if (el.hasAttribute(name)) el.removeAttribute(name);
+}
+
+/**
+ * Marks a freshly-built candidate cell as renderer-owned — its content came
+ * from something free to attach an event listener or otherwise stash
+ * runtime state on the node it returns, where `Node.isEqualNode()` (the
+ * adopt-or-diff structural check below) has no way to see the difference
+ * (it compares tag/attributes/text/descendants only). Two, and only two,
+ * sources are marked:
+ *
+ * 1. `col.render()` — arbitrary consumer code. It can do anything to the
+ *    node it hands back, so it's always marked; there's no way to inspect
+ *    an opaque function for safety.
+ * 2. A built-in cell-type renderer (`typeDef.render`) that declares
+ *    `attachesListeners: true` (currently only `cellTypes.actions`, which
+ *    calls `addEventListener()` directly — see cell-types.js).
+ *
+ * Deliberately NOT marked: `col.format()`, the plain-text fallback, and
+ * every OTHER built-in cell-type renderer (text/number/currency/percent/
+ * date/datetime/boolean/badge/avatar/link/markdown/progress) — each of
+ * those only sets attributes on already-declarative custom elements
+ * (badge-ui, avatar-ui, check-ui, progress-ui, …) or plain nodes with no
+ * listeners; their own runtime behavior lives in their OWN
+ * `connectedCallback`, which fires independent of whether table.class.js
+ * discards or adopts the cell that contains them. Marking every
+ * `typeDef.render` cell unconditionally (an earlier draft of this fix) was
+ * tried and reverted — it broke the AC-004a zero-mutation acceptance
+ * criterion for the overwhelmingly common case (plain text/number/date
+ * cells) for no correctness benefit, since none of those renderers ever
+ * attach a listener. A cell that discards without ever being marked here
+ * (and turns out later to have needed it) is exactly the gap
+ * `guard-patterns.md` §4.1 asks a new interactive cell type to close by
+ * declaring `attachesListeners: true` on itself.
+ *
+ * A renderer-owned cell that happens to be structurally identical to the
+ * existing DOM would, without this guard, silently keep the OLD node (and
+ * its stale/missing listener) instead of the fresh one the renderer just
+ * built (gh#1678 CodeRabbit finding, table.class.js `adoptOrDiffChildren`
+ * L141-150 as originally shipped).
+ */
+const RENDERER_OWNED = new WeakSet();
+
+/**
+ * Adopt-or-diff child reconciliation — the core of table-ui's SSR
+ * adopt-in-place fix. `freshChildren` are already-built, detached candidate
+ * nodes (header cells, row cells, …) computed exactly as this file always
+ * computed them. Rather than unconditionally `replaceChild`-ing every
+ * position (the old, SSR-hostile behavior — a byte-identical server-
+ * rendered subtree got fully rebuilt at upgrade regardless), each position
+ * is compared against its EXISTING child with `Node.isEqualNode()` — a
+ * standard, structural + attribute + text deep-equality check present in
+ * every environment this framework runs under (real browsers, happy-dom,
+ * and linkedom under SSR — confirmed directly; unlike the browser-only APIs
+ * `ssr-compatibility`'s guard-patterns.md §1 guards, `isEqualNode` is core
+ * DOM and never absent). A match discards the freshly-built candidate and
+ * leaves the live DOM completely untouched — the "adopt" half. A mismatch
+ * replaces the position wholesale exactly as before — the "fall back to
+ * full rebuild" half. Never a partial/half-adopt: a position either
+ * survives byte-for-byte or gets fully rebuilt, matching the shape
+ * pagination-ui's own first-connect adoption fix (gh#1687) established for
+ * its flat, keyed item list — generalized here to an arbitrary positional
+ * child (header cells, row cells) via a value check instead of a
+ * shape/key check, since these cells have no stable identity key of their
+ * own the way a pagination item does.
+ *
+ * **Renderer-owned exception (gh#1678 CodeRabbit follow-up):** structural
+ * equality is a necessary but not sufficient adoption test — it says
+ * nothing about listeners or other runtime state a renderer attached to the
+ * node it returned. A cell in `RENDERER_OWNED` is therefore ALWAYS replaced
+ * with its fresh candidate, never adopted via the structural-equality path,
+ * even when `isEqualNode()` would have reported a match — correctness over
+ * the zero-mutation optimization for exactly the cells where structural
+ * equality can't prove the node is safe to keep. See
+ * `ssr-compatibility`'s `references/failure-shapes.md` §5.1 and
+ * `references/guard-patterns.md` §4.1 for the general shape.
+ */
+function adoptOrDiffChildren(container, freshChildren) {
+  while (container.children.length > freshChildren.length) container.lastChild.remove();
+  for (let i = 0; i < freshChildren.length; i++) {
+    const existing = container.children[i];
+    const fresh = freshChildren[i];
+    if (!existing) {
+      container.appendChild(fresh);
+    } else if (RENDERER_OWNED.has(fresh) || !existing.isEqualNode(fresh)) {
+      container.replaceChild(fresh, existing);
+    }
+    // else: existing already matches fresh byte-for-byte AND fresh carries
+    // no renderer-owned runtime state — adopt in place, discard the
+    // candidate, touch nothing.
+  }
+}
+
 // ── Component ────────────────────────────────────────────────────────────────
 
 export class UITable extends UIElement {
@@ -123,6 +278,18 @@ export class UITable extends UIElement {
     wrap:       { type: Boolean, default: false, reflect: true },
     raw:        { type: Boolean, default: false, reflect: true },
     paginate:   { type: Number,  default: 0,     reflect: true },
+    // gh#1807/ADR-0080 — opt-out for the internal pagination bar. Additive:
+    // [paginate] slicing, page state, the `page` event, and the
+    // `footer-page` listener are all unaffected; only the internally
+    // stamped [data-footer] pagination-ui is suppressed. Explicit intent,
+    // for a client-mode table-footer-ui composition to avoid a doubled
+    // pager (REQ-W-005).
+    noPager:    { type: Boolean, default: false, reflect: true, attribute: 'no-pager' },
+    // gh#1754/ADR-0082 — the server-total data contract. Presence-gated
+    // (#serverMode reads hasAttribute, never this coerced value): total row
+    // count across all server pages. See the class-header doc comment above
+    // and REQ-D-003..006 for the full server-mode contract.
+    rangeTotal: { type: Number,  default: 0,     reflect: true, attribute: 'range-total' },
     loading:    { type: Boolean, default: false, reflect: true },
     search:     { type: String,  default: '',    reflect: true },
     // adiav2 zero-overrides purge (gh#1680) deleted an app-side [data-clickable]
@@ -151,6 +318,23 @@ export class UITable extends UIElement {
   #openFilter = null;        // column key of open filter dropdown
   #filterFocusRaf = null;
 
+  // gh#1754/ADR-0082 — the mode switch is the [range-total] attribute's
+  // PRESENCE, never its coerced value (mirrors table-footer-ui's own
+  // REQ-S-001/002 hasAttribute discipline). One predicate for both the
+  // page-count/no-slice/visibility branches (step 2) and the reset-guard
+  // sites (step 3) — deliberately not narrowed by `paginate > 0` (see the
+  // reset-suppression call sites for why that widened scope is safe).
+  get #serverMode() { return this.hasAttribute('range-total'); }
+
+  // gh#1754/ADR-0082 REQ-D-003 (CodeRabbit, PR #1828) — a raw
+  // `Number(x) || 0` accepts negative and non-finite values verbatim (both
+  // are truthy), which can drive #pageCount/the footer's own range text
+  // negative or infinite. Clamps to a finite, non-negative integer.
+  #safeRangeTotal() {
+    const n = Number(this.rangeTotal);
+    return Number.isFinite(n) && n > 0 ? Math.trunc(n) : 0;
+  }
+
   // ── Public API: columns ──
 
   set columns(arr) {
@@ -165,7 +349,11 @@ export class UITable extends UIElement {
   set data(arr) {
     this.#data = Array.isArray(arr) ? arr : [];
     this.#selected.clear();
-    this.#page = 0;
+    // gh#1754/ADR-0082 REQ-D-004 — in server mode a `.data` set is the
+    // consumer's fetch write-back for the CURRENT page; resetting to page 0
+    // here would fight the pager back to the start on every fetch. Selection
+    // still clears unconditionally (rows changed under it either way).
+    if (!this.#serverMode) this.#page = 0;
     this.#requestRender();
   }
 
@@ -229,7 +417,10 @@ export class UITable extends UIElement {
     } else {
       this.#filters.set(key, { op, value });
     }
-    this.#page = 0;
+    // gh#1754/ADR-0082 REQ-D-004 — server mode: page state moves only via
+    // pager interaction, the `footer-page` command, or setState(); a filter
+    // change never resets it (the consumer's fetch loop owns page moves).
+    if (!this.#serverMode) this.#page = 0;
     this.#requestRender();
     this.dispatchEvent(new CustomEvent('filter-change', {
       detail: { filters: Object.fromEntries(this.#filters) },
@@ -240,7 +431,7 @@ export class UITable extends UIElement {
   clearFilters() {
     this.#filters.clear();
     this.#openFilter = null;
-    this.#page = 0;
+    if (!this.#serverMode) this.#page = 0; // gh#1754/ADR-0082 REQ-D-004 — same suppression as setFilter above.
     this.#requestRender();
     this.dispatchEvent(new CustomEvent('filter-change', {
       detail: { filters: {} },
@@ -250,6 +441,88 @@ export class UITable extends UIElement {
 
   get filters() { return Object.fromEntries(this.#filters); }
 
+  // ── table-toolbar-ui command-event listeners (gh#1764/#1780, ADR-0079) ──
+  // Each handler applies the exact call table-toolbar.class.js used to make
+  // directly on this element before the events-only normalization — no
+  // behavior change, only the interaction shape.
+  //
+  // `e.target !== this` guard (code-checker finding, 2026-08-20): these
+  // events are dispatched `bubbles: true` (mirroring the ratified
+  // chart-legend-ui↔chart-ui model), so one fired at an INNER table-ui
+  // (e.g. inside an expanded row — table-ui's own row-expansion API makes
+  // a nested table a real composition) would otherwise also reach and
+  // apply to every ANCESTOR table-ui's listener. The old direct-write code
+  // had no such hazard — it targeted the resolved element precisely. The
+  // ratified model guards this exact case (`chart.class.js`'s
+  // `#onLegendToggle` returns unless the bubbled event's own [for] matches
+  // `this.id`); here the equivalent guard is simpler since these events are
+  // always dispatched directly at their intended table-ui, never through a
+  // [for] filter — `e.target !== this` is the correct, minimal check.
+
+  #onToolbarSearch = (e) => {
+    if (e.target !== this) return;
+    this.search = e.detail?.value ?? '';
+  };
+
+  #onToolbarFilterSet = (e) => {
+    if (e.target !== this) return;
+    const { key, value, op } = e.detail || {};
+    if (!key) return;
+    this.setFilter(key, value, op);
+  };
+
+  #onToolbarFilterClear = (e) => {
+    if (e.target !== this) return;
+    this.clearFilters();
+  };
+
+  #onToolbarColumnsSet = (e) => {
+    if (e.target !== this) return;
+    const columns = e.detail?.columns;
+    if (Array.isArray(columns)) this.columns = columns;
+  };
+
+  #onToolbarPaginate = (e) => {
+    if (e.target !== this) return;
+    this.paginate = Number(e.detail?.pageSize) || 0;
+  };
+
+  // gh#1807/ADR-0080, refined 0.2.0/ADR-0082 — `footer-page` is the
+  // footer→table page-navigation command (REQ-W-002), sender-prefixed like
+  // the five `toolbar-*` commands above but from a second sender
+  // (table-footer-ui). Applies whenever [paginate] > 0 — client mode AND
+  // table-authoritative server mode ([range-total] present, REQ-D-003)
+  // alike, since #pageCount already knows server math (step 2 above): the
+  // clamp below reads the right ceiling in either mode with no extra
+  // branching needed here. At [paginate="0"] the command stays a documented
+  // no-op in either mode — with no page size there is no page range to move
+  // within. Clamps to the valid page range and never throws (AC-004/AC-018);
+  // a non-numeric/NaN detail.page is silently ignored (no page change, no
+  // `page` notification).
+  #onFooterPage = (e) => {
+    if (e.target !== this) return;
+    if (!(this.paginate > 0)) return; // paginate=0: documented no-op, either mode
+    const n = Number(e.detail?.page);
+    if (!Number.isFinite(n)) return;
+    const clamped = Math.max(1, Math.min(Math.trunc(n), this.#pageCount));
+    this.#page = clamped - 1; // this.#page is 0-based internally
+    this.render();
+    this.dispatchEvent(new CustomEvent('page', {
+      bubbles: true,
+      detail: { page: this.#page },
+    }));
+  };
+
+  // ── Public API: filteredCount ──
+  // gh#1807/ADR-0080, REQ-W-006 — read-only. The row count AFTER search +
+  // column filters apply but BEFORE pagination slices it — exactly the
+  // number table-footer-ui's client-mode derivation needs for its
+  // range-total (a raw `.data.length` read, the toolbar's own `count`
+  // fallback precedent, would double-count a filtered-out row). Undocumented
+  // in table.yaml by design, matching `.selected`/`.sortState`/`.filters` —
+  // a plain read-only JS getter, not a reflected attribute.
+  get filteredCount() { return this.#getProcessedIndices().length; }
+
   // ── Public API: expansion ──
 
   toggleExpand(index) {
@@ -369,8 +642,12 @@ export class UITable extends UIElement {
       } catch (_) { /* malformed JSON — leave empty, render() shows empty state */ }
     }
 
-    this.setAttribute('role', 'grid');
-    this.setAttribute('tabindex', '0');
+    // gh#1678 — idempotent: a byte-identical SSR-rendered host already
+    // carries both attributes, and an unconditional setAttribute() here
+    // would still queue a mutation record even though the value never
+    // actually changes.
+    setAttrIfChanged(this, 'role', 'grid');
+    setAttrIfChanged(this, 'tabindex', '0');
 
     // Restore persisted state
     this.#restoreState();
@@ -386,6 +663,21 @@ export class UITable extends UIElement {
       // pen automatically; Playwright's page.mouse.* synthesizes pointer
       // events (not mouse events), so a mousedown-only handler tests dead.
       this.addEventListener('pointerdown', this.#onPointerdown);
+      // gh#1764/#1780 (events-only interaction contract, ADR-0079) — the
+      // `toolbar-*` command events table-toolbar-ui dispatches AT this
+      // element in place of the direct property writes / method calls it
+      // used to make. Each handler applies the exact same public-API call
+      // the toolbar previously made directly, so observable behavior is
+      // unchanged; only the interaction shape moved to events (mirrors
+      // chart-legend-ui↔chart-ui's own bubbling-CustomEvent model).
+      this.addEventListener('toolbar-search', this.#onToolbarSearch);
+      this.addEventListener('toolbar-filter-set', this.#onToolbarFilterSet);
+      this.addEventListener('toolbar-filter-clear', this.#onToolbarFilterClear);
+      this.addEventListener('toolbar-columns-set', this.#onToolbarColumnsSet);
+      this.addEventListener('toolbar-paginate', this.#onToolbarPaginate);
+      // gh#1807/ADR-0080 — a second sender-prefixed command, alongside the
+      // five toolbar-* listeners above (same symmetric-lifecycle rule).
+      this.addEventListener('footer-page', this.#onFooterPage);
     }
   }
 
@@ -393,6 +685,12 @@ export class UITable extends UIElement {
     this.removeEventListener('click', this.#onClick);
     this.removeEventListener('keydown', this.#onKeydown);
     this.removeEventListener('pointerdown', this.#onPointerdown);
+    this.removeEventListener('toolbar-search', this.#onToolbarSearch);
+    this.removeEventListener('toolbar-filter-set', this.#onToolbarFilterSet);
+    this.removeEventListener('toolbar-filter-clear', this.#onToolbarFilterClear);
+    this.removeEventListener('toolbar-columns-set', this.#onToolbarColumnsSet);
+    this.removeEventListener('toolbar-paginate', this.#onToolbarPaginate);
+    this.removeEventListener('footer-page', this.#onFooterPage);
     this.#bound = false;
     this.#cleanupResize();
     if (this.#renderRaf) {
@@ -405,6 +703,21 @@ export class UITable extends UIElement {
     }
   }
 
+  // gh#1754/ADR-0082 — ported from table-footer.class.js's own
+  // attributeChangedCallback gotcha (its rangeTotal, same default-0 shape).
+  // [range-total]'s default is already 0 (Number), so an absent → "0"
+  // transition parses to the SAME coerced value; the base class property
+  // setter's Object.is short-circuit (element.js installProps) swallows the
+  // signal write, and the reactive render effect never re-runs on its own.
+  // This is a presence concern (#serverMode reads hasAttribute, not the
+  // coerced value), not a value one. Batched via #requestRender — never
+  // render() directly — honoring the R7 render-clock discipline (no edits to
+  // #requestRender/#renderRaf themselves).
+  attributeChangedCallback(name, oldVal, newVal) {
+    super.attributeChangedCallback(name, oldVal, newVal);
+    if (name === 'range-total') this.#requestRender();
+  }
+
   // ── <col-def> Parsing ──────────────────────────────────────────────────────
 
   #parseColDefs() {
@@ -600,9 +913,15 @@ export class UITable extends UIElement {
   }
 
   /**
-   * Paginate a set of indices.
+   * Paginate a set of indices. gh#1754/ADR-0082 REQ-D-003 — server mode:
+   * `.data` IS the current page already (the consumer sliced it server-side),
+   * so no local slicing runs; [paginate] supplies only the page-size for
+   * pager math. `indices` here has already had local search/sort/filter
+   * applied by #getProcessedIndices — server mode still renders that whole
+   * (unsliced) result.
    */
   #getPageSlice(indices) {
+    if (this.#serverMode) return indices;
     if (!this.paginate || this.paginate <= 0) return indices;
     const start = this.#page * this.paginate;
     return indices.slice(start, start + this.paginate);
@@ -610,6 +929,11 @@ export class UITable extends UIElement {
 
   get #pageCount() {
     if (!this.paginate || this.paginate <= 0) return 1;
+    // gh#1754/ADR-0082 REQ-D-003 — server mode: page count is server-total-
+    // derived, not the loaded page's own length (the exact dual-math drift
+    // gh#1754's evidence quoted — this is now the ONE calc site;
+    // #renderPagination reads this getter instead of recomputing).
+    if (this.#serverMode) return Math.max(1, Math.ceil(this.#safeRangeTotal() / this.paginate));
     // pageCount should reflect filtered data, not raw data
     const filteredCount = this.#getProcessedIndices().length;
     return Math.max(1, Math.ceil(filteredCount / this.paginate));
@@ -629,8 +953,13 @@ export class UITable extends UIElement {
 
     const visCols = this.#visibleColumns;
 
-    // Set grid template
-    this.style.gridTemplateColumns = this.#buildGridTemplate();
+    // Set grid template — gh#1678: guard the write, same rationale as the
+    // host attribute sets in connected(). Assigning the identical string
+    // again is still a real style-attribute mutation, not a no-op.
+    const gridTemplate = this.#buildGridTemplate();
+    if (this.style.gridTemplateColumns !== gridTemplate) {
+      this.style.gridTemplateColumns = gridTemplate;
+    }
 
     // ── Header row ──
 
@@ -669,13 +998,12 @@ export class UITable extends UIElement {
       const row = existing || this.#createRow(idx, visCols);
       if (existing) this.#updateRow(existing, idx, visCols);
 
-      // Expand toggle in first cell
-      if (this.#isRowExpandable(idx)) {
-        const isExpanded = this.#expanded.has(idx);
-        if (isExpanded) row.setAttribute('data-expanded', '');
-        else row.removeAttribute('data-expanded');
+      // Expand toggle in first cell — gh#1678: idempotent (see the
+      // module-level helpers' own rationale).
+      if (this.#isRowExpandable(idx) && this.#expanded.has(idx)) {
+        setAttrIfChanged(row, 'data-expanded', '');
       } else {
-        row.removeAttribute('data-expanded');
+        removeAttrIfPresent(row, 'data-expanded');
       }
 
       bodyChildren.push(row);
@@ -719,7 +1047,15 @@ export class UITable extends UIElement {
 
     // ── Pagination footer ──
 
-    const showPagination = this.paginate > 0 && this.#data.length > 0;
+    // gh#1807/ADR-0080 REQ-W-005 — [no-pager] hides only the internally
+    // stamped bar; slicing/page-state/events are untouched (they don't
+    // route through this flag at all).
+    // gh#1754/ADR-0082 REQ-D-005 — server mode drops the client-mode
+    // `data.length > 0` term: an in-flight fetch (momentarily empty `.data`)
+    // must not flicker the pager away, so visibility gates on `range-total`
+    // instead.
+    const showPagination = this.paginate > 0 && !this.noPager
+      && (this.#serverMode ? this.#safeRangeTotal() > 0 : this.#data.length > 0);
     let footer = this.querySelector(':scope > [data-footer]');
 
     if (showPagination) {
@@ -728,7 +1064,7 @@ export class UITable extends UIElement {
         footer.setAttribute('data-footer', '');
         this.appendChild(footer);
       }
-      this.#renderPagination(footer, allProcessed.length);
+      this.#renderPagination(footer);
     } else if (footer) {
       footer.remove();
     }
@@ -830,12 +1166,10 @@ export class UITable extends UIElement {
       cells.push(cell);
     }
 
-    // Reconcile header cells
-    while (header.children.length > cells.length) header.lastChild.remove();
-    for (let i = 0; i < cells.length; i++) {
-      if (header.children[i]) header.replaceChild(cells[i], header.children[i]);
-      else header.appendChild(cells[i]);
-    }
+    // Reconcile header cells — gh#1678: adopt-or-diff instead of an
+    // unconditional replaceChild per position (see the module-level
+    // adoptOrDiffChildren() doc comment for why this is safe under SSR).
+    adoptOrDiffChildren(header, cells);
   }
 
   // ── Row Builders ───────────────────────────────────────────────────────────
@@ -850,12 +1184,16 @@ export class UITable extends UIElement {
   #updateRow(row, dataIndex, visCols) {
     const data = this.#data[dataIndex];
     const isSelected = this.#selected.has(dataIndex);
-    row.dataset.index = dataIndex;
+    // gh#1678 — idempotent: `#updateRow` runs on an ADOPTED (SSR-matched)
+    // row exactly as often as on a freshly-created one, and a plain
+    // `row.dataset.index = …` / `setAttribute` always mutates regardless of
+    // whether the value already matches.
+    setAttrIfChanged(row, 'data-index', String(dataIndex));
 
     if (isSelected) {
-      row.setAttribute('aria-selected', 'true');
+      setAttrIfChanged(row, 'aria-selected', 'true');
     } else {
-      row.removeAttribute('aria-selected');
+      removeAttrIfPresent(row, 'aria-selected');
     }
 
     const cells = [];
@@ -901,6 +1239,12 @@ export class UITable extends UIElement {
       const value = getCellValue(data, col);
 
       // Render priority: column.render > column.format > cellType.render > text
+      // gh#1678 CodeRabbit follow-up: `col.render()` and a cell-type renderer
+      // are free to attach listeners / runtime state to the node they hand
+      // back — mark the cell RENDERER_OWNED so adoptOrDiffChildren() never
+      // adopts it on structural equality alone (see that function's own doc
+      // comment). `col.format()` and the plain-text fallback below build
+      // nothing but a static <span>, so they're never marked.
       if (typeof col.render === 'function') {
         const result = col.render(value, data, cell, dataIndex);
         if (isNode(result)) {
@@ -908,6 +1252,7 @@ export class UITable extends UIElement {
         } else if (typeof result === 'string') {
           cell.innerHTML = result;
         }
+        RENDERER_OWNED.add(cell);
       } else if (typeof col.format === 'function') {
         const t = col.format(value, data);
         cell.appendChild(Object.assign(document.createElement('span'), { textContent: t }));
@@ -916,6 +1261,16 @@ export class UITable extends UIElement {
         const typeDef = cellTypes[col.type || 'text'];
         if (typeDef?.render) {
           typeDef.render(value, data, cell, col.meta);
+          // Most built-in cell-type renderers only set attributes on
+          // custom elements (badge-ui, avatar-ui, check-ui, …) — safe to
+          // adopt structurally, since their own runtime behavior lives in
+          // their own connectedCallback, independent of node identity. Only
+          // a type that declares `attachesListeners` (currently: 'actions',
+          // which calls addEventListener() directly) is marked renderer-
+          // owned; marking every typeDef.render() cell would defeat the
+          // zero-mutation adoption for the overwhelming common case (plain
+          // text/number/date/badge/... cells) for no correctness benefit.
+          if (typeDef.attachesListeners) RENDERER_OWNED.add(cell);
         } else {
           const t = value != null ? String(value) : '';
           cell.appendChild(Object.assign(document.createElement('span'), { textContent: t }));
@@ -949,12 +1304,13 @@ export class UITable extends UIElement {
       cells.push(cell);
     }
 
-    // Reconcile cells in row
-    while (row.children.length > cells.length) row.lastChild.remove();
-    for (let i = 0; i < cells.length; i++) {
-      if (row.children[i]) row.replaceChild(cells[i], row.children[i]);
-      else row.appendChild(cells[i]);
-    }
+    // Reconcile cells in row — gh#1678: adopt-or-diff (see
+    // adoptOrDiffChildren()'s doc comment). This is the fix's main hot
+    // path: `#updateRow` is called on every already-adopted row found by
+    // `data-index` at connect, so this is what stops a byte-identical
+    // SSR-rendered row from having every one of its cells rebuilt at
+    // upgrade.
+    adoptOrDiffChildren(row, cells);
   }
 
   // ── Overlays ───────────────────────────────────────────────────────────────
@@ -1084,10 +1440,14 @@ export class UITable extends UIElement {
           default: result = '';
         }
 
-        // Format using cell type if available
+        // Format using cell type if available. gh#1678 CodeRabbit follow-up:
+        // same attachesListeners-only scoping as the body-row cell path
+        // above — only a cell type that declares it attaches listeners
+        // needs the always-replace guard.
         const typeDef = cellTypes[col.type || 'text'];
         if (typeof result === 'number' && typeDef?.render) {
           typeDef.render(result, {}, cell, col.meta);
+          if (typeDef.attachesListeners) RENDERER_OWNED.add(cell);
         } else {
           cell.textContent = typeof result === 'number' ? result.toLocaleString() : result;
         }
@@ -1096,17 +1456,16 @@ export class UITable extends UIElement {
       cells.push(cell);
     }
 
-    // Reconcile cells
-    while (aggRow.children.length > cells.length) aggRow.lastChild.remove();
-    for (let i = 0; i < cells.length; i++) {
-      if (aggRow.children[i]) aggRow.replaceChild(cells[i], aggRow.children[i]);
-      else aggRow.appendChild(cells[i]);
-    }
+    // Reconcile cells — gh#1678: adopt-or-diff, same helper as the header
+    // and body-row cell reconciliation above (consistency; the aggregation
+    // row is built from the exact same per-cell full-rebuild shape those
+    // had).
+    adoptOrDiffChildren(aggRow, cells);
   }
 
   // ── Pagination ─────────────────────────────────────────────────────────────
 
-  #renderPagination(footer, filteredTotal) {
+  #renderPagination(footer) {
     let pag = footer.querySelector('pagination-ui');
     if (!pag) {
       footer.innerHTML = '';
@@ -1121,10 +1480,16 @@ export class UITable extends UIElement {
       });
       footer.appendChild(pag);
     }
-    const pageCount = this.paginate > 0
-      ? Math.max(1, Math.ceil(filteredTotal / this.paginate))
-      : 1;
-    pag.setAttribute('page', String(this.#page + 1));
+    // gh#1754/ADR-0082 — #pageCount is now the single calc site (client AND
+    // server math); the duplicated `ceil(filteredTotal / paginate)` this
+    // function used to recompute is gone — that dual-math drift is exactly
+    // gh#1754's evidence. Clamp only the RENDERED page attribute (a display
+    // concern, e.g. the server total shrank below the current page) — never
+    // mutate `#page` or dispatch `page` from render (REQ-D-005: a render must
+    // never self-trigger a fetch).
+    const pageCount = this.#pageCount;
+    const p = Math.min(this.#page, pageCount - 1);
+    pag.setAttribute('page', String(p + 1));
     pag.setAttribute('total', String(pageCount));
   }