@adia-ai/web-components 0.8.44 → 0.8.46

package/components/nav/nav.yaml

@@ -38,7 +38,7 @@ props:
   heading:
     type: string
     default: ''
-    description: "Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only."
+    description: "Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only. For a VISIBLE kicker inside a primary-variant rail — or more than one kicker per <nav-ui> — hand-place <span data-nav-label> in the default slot instead; see slots below."
   multiExpand:
     type: boolean
     default: false
@@ -62,7 +62,7 @@ events:
 
 slots:
   default:
-    description: "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers."
+    description: "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers and <span data-nav-label> for hand-placed group-label kickers (titled runs of items/groups that aren't wrapped in a <nav-group-ui>). <span data-nav-label> renders with the same uppercase/tracking/muted kicker treatment as the [heading] ::before kicker, and is hidden alongside dividers whenever the primary-variant rail collapses ([collapsed] or ≤96px container width)."
 
 states:
   - name: idle
@@ -79,7 +79,18 @@ a2ui:
       wrapped in <section-ui> for app sidebars; inside an
       <aside data-subnav> with variant="section" for section / subnav
       rails; standalone on docs / auth pages. Children: <nav-group-ui>,
-      <nav-item-ui>, optional <hr data-nav-divider>.
+      <nav-item-ui>, optional <hr data-nav-divider>, optional
+      <span data-nav-label> (hand-placed titled section header).
+    - >-
+      Titled nav-item groups: hand-place <span data-nav-label>Text</span>
+      directly in the default slot, before a run of <nav-item-ui> /
+      <nav-group-ui> children, to render a section-header kicker — the
+      same uppercase/tracking/muted treatment as the [heading] ::before
+      kicker on variant="section", but usable anywhere in the child list
+      (not limited to one kicker per <nav-ui>) and always visually
+      rendered, unlike [heading] which is aria-only on variant="primary".
+      Hidden automatically whenever the primary-variant rail collapses
+      ([collapsed] or ≤96px container width), same as <hr data-nav-divider>.
     - >-
       Variants: variant="primary" (default) — app sidebar; ResizeObserver
       collapses to icon-only ≤96px; collapsible groups open as a popover

package/components/nav-group/nav-group.css

@@ -17,13 +17,31 @@
          selected — bg container · icon + text ON-SURFACE
        The selected icon no longer takes primary (supersedes gh#522's
        glyph ruling); Figma's neutral/surfaceBright was considered for the
-       selected fill and RULED OUT — container stays (gh#795's mirror). */
-    --nav-group-fg:            var(--md-sys-color-neutral-high);
+       selected fill and RULED OUT — container stays (gh#795's mirror).
+       gh#968's ladder above is about ROUTE selection (hover/selected);
+       it says nothing about the group's own open/closed disclosure state,
+       which --nav-group-fg left pinned unconditionally to one role
+       (neutral-high) regardless of [open]. gh#1740 (operator ruling,
+       2026-08-19) supersedes that unconditional pin with a second,
+       orthogonal axis — the header text and caret glyph now also shift
+       role by [open], the same way they already shift by [selected]/
+       hover; the two ladders compose (a selected-route header still wins
+       its --nav-group-fg-selected treatment regardless of open state —
+       see the :scope[open] rule below, kept lower-precedence than
+       :scope[selected] by source order). */
+    --nav-group-fg:            var(--md-sys-color-neutral);
+    --nav-group-fg-active:     var(--md-sys-color-neutral-high);
     --nav-group-fg-hover:      var(--a-fg-strong);
     --nav-group-fg-muted:      var(--a-fg-muted);
     --nav-group-fg-selected:   var(--a-fg-strong);
     --nav-group-icon-fg:       var(--md-sys-color-neutral);
     --nav-group-icon-fg-selected: var(--a-fg-strong);
+    /* Caret role ladder (gh#1740) — idle/closed: NEUTRAL-LOW (one step
+       quieter than the muted badge/kicker role); open: NEUTRAL, matching
+       the icon's own idle role so the caret doesn't outshine the icon
+       once the group is expanded. */
+    --nav-group-caret-fg:        var(--md-sys-color-neutral-low);
+    --nav-group-caret-fg-active: var(--md-sys-color-neutral);
     --nav-group-bg-hover:      var(--a-bg-muted);
     --nav-group-bg-selected:   var(--a-bg-selected); /* mirrors --nav-item-bg-selected (gh#795) */
     --nav-group-icon-size:     calc(var(--nav-group-row-height) - var(--a-space-2));
@@ -71,6 +89,20 @@
     background: var(--nav-group-indent-rail-bg, var(--md-sys-color-neutral-outline-variant));
     pointer-events: none;
   }
+  /* Disclosure-state ladder (gh#1740, operator ruling 2026-08-19): the
+     header text and caret glyph step UP a role when the group is open —
+     idle/closed reads NEUTRAL, expanded reads NEUTRAL-HIGH. Placed BEFORE
+     the [selected]/[data-selected-within] block below so an equal-
+     specificity (0,3,0) tie always resolves to the route-selection color:
+     a selected-route group keeps its existing --nav-group-fg-selected
+     treatment regardless of its own open/closed state — this rule only
+     ever wins when the group is open AND not selected. */
+  :scope[open] > [slot="header"] {
+    color: var(--nav-group-fg-active);
+  }
+  :scope[open] > [slot="header"] [slot="caret"] {
+    color: var(--nav-group-caret-fg-active);
+  }
   /* Selected-look header treatment keys on [selected] — the CSS half of
      gh issue 459 (PR 460 corrected the icon weight): the group CONTAINING
      the selected route reads strong; a merely-expanded group does not.
@@ -174,7 +206,9 @@
 
   [slot="header"] [slot="caret"] {
     /*--a-icon-size: 0.5rem;*/
-    color: var(--nav-group-fg-muted);
+    /* idle/closed caret = NEUTRAL-LOW (gh#1740 role ladder); steps up to
+       --nav-group-caret-fg-active via the :scope[open] rule above. */
+    color: var(--nav-group-caret-fg);
     transition:
       transform var(--nav-duration-fast) var(--nav-easing),
       color var(--nav-duration-fast) var(--nav-easing);

package/components/pagination/pagination.class.js

@@ -24,6 +24,32 @@
 import { UIElement } from '../../core/element.js';
 import { KEY_MAP } from '../../core/template.js';
 
+// ── SSR idempotent-write guard (gh#1755, follow-up to table-ui's gh#1678) ──
+//
+// Local copies of table.class.js's own setAttrIfChanged()/removeAttrIfPresent()
+// — module-local there too (not exported), so a shared-utility extraction for
+// two call sites would be a premature abstraction; these mirror that shape.
+//
+/**
+ * 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
+ * per-item attribute this render path sets on EVERY call (`aria-current`,
+ * `variant`, `disabled`, `tabindex`, `text`, `aria-label`, `data-value`,
+ * `size`) must compare-before-write to let a byte-identical adopted SSR
+ * `<nav>` (gh#1687) survive re-render with zero mutations — 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);
+}
+
 export class UIPagination extends UIElement {
   static properties = {
     page:     { type: Number, default: 1, reflect: true },
@@ -251,21 +277,21 @@ export class UIPagination extends UIElement {
     }
 
     const btn = document.createElement('button-ui');
-    btn.setAttribute('size', this.size);
+    setAttrIfChanged(btn, 'size', this.size);
 
     if (item.type === 'prev') {
       btn.setAttribute('data-prev', '');
-      btn.setAttribute('icon', 'caret-left');
-      btn.setAttribute('aria-label', 'Previous page');
+      setAttrIfChanged(btn, 'icon', 'caret-left');
+      setAttrIfChanged(btn, 'aria-label', 'Previous page');
     } else if (item.type === 'next') {
       btn.setAttribute('data-next', '');
-      btn.setAttribute('icon', 'caret-right');
-      btn.setAttribute('aria-label', 'Next page');
+      setAttrIfChanged(btn, 'icon', 'caret-right');
+      setAttrIfChanged(btn, 'aria-label', 'Next page');
     } else {
       btn.setAttribute('data-page', '');
-      btn.dataset.value = String(item.value);
-      btn.setAttribute('text', String(item.value));
-      btn.setAttribute('aria-label', `Page ${item.value}`);
+      setAttrIfChanged(btn, 'data-value', String(item.value));
+      setAttrIfChanged(btn, 'text', String(item.value));
+      setAttrIfChanged(btn, 'aria-label', `Page ${item.value}`);
     }
 
     this.#updateItem(btn, item, page);
@@ -276,32 +302,36 @@ export class UIPagination extends UIElement {
     if (item.type === 'ellipsis') return;
 
     // Keep size in sync \u2014 the host's [size] may change between renders.
-    el.setAttribute('size', this.size);
+    // gh#1755 \u2014 compare-before-write: this runs on EVERY render pass
+    // (including one triggered by an unrelated reactive dependency), so a
+    // bare setAttribute() would re-mutate an already-correct adopted
+    // gh#1687 SSR `<nav>` child even when nothing here actually changed.
+    setAttrIfChanged(el, 'size', this.size);
 
     if (item.type === 'prev') {
-      el.setAttribute('variant', this.#restVariant());
-      if (page <= 1) { el.setAttribute('disabled', ''); el.setAttribute('tabindex', '-1'); }
-      else { el.removeAttribute('disabled'); el.setAttribute('tabindex', '0'); }
+      setAttrIfChanged(el, 'variant', this.#restVariant());
+      if (page <= 1) { setAttrIfChanged(el, 'disabled', ''); setAttrIfChanged(el, 'tabindex', '-1'); }
+      else { removeAttrIfPresent(el, 'disabled'); setAttrIfChanged(el, 'tabindex', '0'); }
     } else if (item.type === 'next') {
-      el.setAttribute('variant', this.#restVariant());
-      if (page >= this.total) { el.setAttribute('disabled', ''); el.setAttribute('tabindex', '-1'); }
-      else { el.removeAttribute('disabled'); el.setAttribute('tabindex', '0'); }
+      setAttrIfChanged(el, 'variant', this.#restVariant());
+      if (page >= this.total) { setAttrIfChanged(el, 'disabled', ''); setAttrIfChanged(el, 'tabindex', '-1'); }
+      else { removeAttrIfPresent(el, 'disabled'); setAttrIfChanged(el, 'tabindex', '0'); }
     } else {
-      el.dataset.value = String(item.value);
-      el.setAttribute('text', String(item.value));
-      el.setAttribute('aria-label', `Page ${item.value}`);
+      setAttrIfChanged(el, 'data-value', String(item.value));
+      setAttrIfChanged(el, 'text', String(item.value));
+      setAttrIfChanged(el, 'aria-label', `Page ${item.value}`);
       if (item.value === page) {
         // Active page reads as `variant="primary"` so the filled-accent
         // state comes from button-ui's primary surface matrix (the
         // canonical token chain) \u2014 not a pagination-tier re-impl.
-        el.setAttribute('variant', 'primary');
+        setAttrIfChanged(el, 'variant', 'primary');
         // aria-current="page" alone carries the active-page state — no
         // private data-active mirror (gh#1332 Category A; admin-roster's
         // aria-checked precedent from PR #1438).
-        el.setAttribute('aria-current', 'page');
+        setAttrIfChanged(el, 'aria-current', 'page');
       } else {
-        el.setAttribute('variant', this.#restVariant());
-        el.removeAttribute('aria-current');
+        setAttrIfChanged(el, 'variant', this.#restVariant());
+        removeAttrIfPresent(el, 'aria-current');
       }
     }
   }

package/components/search/search.class.js

@@ -22,6 +22,30 @@
 
 import { UIFormElement } from '../../core/form.js';
 
+// ── SSR idempotent-write guard (gh#1755, follow-up to table-ui's gh#1678) ──
+//
+// Local copies of table.class.js's own setAttrIfChanged()/removeAttrIfPresent()
+// — module-local there too (not exported), so a shared-utility extraction for
+// two call sites would be a premature abstraction; these mirror that shape.
+//
+/**
+ * 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/child attribute this render path sets on EVERY call (`placeholder`,
+ * `value`) must compare-before-write to let a byte-identical SSR-rendered
+ * `<input-ui>` survive upgrade with zero mutations — 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);
+}
+
 export class UISearch extends UIFormElement {
   static properties = {
     ...UIFormElement.properties,
@@ -37,7 +61,10 @@ export class UISearch extends UIFormElement {
 
   connected() {
     super.connected();
-    this.setAttribute('role', 'search');
+    // gh#1755 — a byte-identical SSR-rendered host already carries this
+    // attribute; an unconditional setAttribute() here would still queue a
+    // mutation record even though the value never actually changes.
+    setAttrIfChanged(this, 'role', 'search');
 
     if (!this.querySelector('input-ui')) {
       const size = this.getAttribute('size');
@@ -69,12 +96,19 @@ export class UISearch extends UIFormElement {
   render() {
     if (!this.#inputEl) return;
 
-    this.#inputEl.setAttribute('placeholder', this.placeholder);
-    if (this.disabled) this.#inputEl.setAttribute('disabled', '');
-    else this.#inputEl.removeAttribute('disabled');
+    // gh#1755 — this render effect re-runs on ANY of this element's
+    // reactive properties changing (element.js's connectedCallback effect
+    // reads every signal unconditionally), not only placeholder/disabled/
+    // value themselves — so a bare setAttribute() here would re-mutate an
+    // already-correct adopted `<input-ui>` (or this host's own `value`
+    // attribute) on every unrelated re-render, defeating SSR zero-mutation
+    // upgrade even when nothing this pass actually cares about changed.
+    setAttrIfChanged(this.#inputEl, 'placeholder', this.placeholder);
+    if (this.disabled) setAttrIfChanged(this.#inputEl, 'disabled', '');
+    else removeAttrIfPresent(this.#inputEl, 'disabled');
 
     // Reflect value for CSS (clear button visibility)
-    this.setAttribute('value', this.value || '');
+    setAttrIfChanged(this, 'value', this.value || '');
   }
 
   #onInput = () => {

package/components/select/select.a2ui.json

@@ -66,6 +66,11 @@
       "type": "string",
       "default": ""
     },
+    "label-hidden": {
+      "description": "When true, [label] still sets the accessible name (aria-label) but the visible `::before` text is suppressed via the canonical sr-only technique (gh#1748, mirrors check-ui's [label-hidden], gh#1010). Use when a sibling/ancestor composition already conveys the same name visually (e.g. a scope/view-switcher select in a table-toolbar-ui [slot=\"scope\"], where the toolbar's own title already names the view) and a second visible \"Scope\"-style label would paint it twice.",
+      "type": "boolean",
+      "default": false
+    },
     "mark": {
       "description": "Renders the Adia brand mark (`<adia-mark-ui>`) as the leading visual — takes precedence over avatar and icon. Token-driven (light/dark handled internally), so it fits a scheme-switching workspace/app switcher where a static logo URL can't invert. Per-option `mark` on an `<option>`/options-array entry works the same way, scoped to that row.",
       "type": "boolean",

package/components/select/select.class.js

@@ -47,6 +47,11 @@ export class UISelect extends UIFormElement {
     size:        { type: String,  default: 'md', reflect: true },
     open:        { type: Boolean, default: false, reflect: true },
     label:       { type: String,  default: '', reflect: true },
+    // gh#1748: keeps [label] as the accessible name (bridged to an explicit
+    // aria-label in #syncAccessibleName below) while suppressing the VISIBLE
+    // `::before` text (select.css) — for compositions that already show the
+    // name elsewhere. Mirrors check-ui's [label-hidden] (gh#1010).
+    labelHidden: { type: Boolean, default: false, reflect: true, attribute: 'label-hidden' },
     icon:        { type: String,  default: '', reflect: true },
     avatar:      { type: String,  default: '', reflect: true },
     mark:        { type: Boolean, default: false, reflect: true },
@@ -361,6 +366,21 @@ export class UISelect extends UIFormElement {
    */
   #syncAccessibleName() {
     const DEFAULT_PLACEHOLDER = 'Select...'; // matches static properties.placeholder.default
+    // gh#1748: [label-hidden] suppresses the visible `::before` text
+    // (select.css's `attr(label)` content) but [label] must still name the
+    // control — bridge it through the SAME tracked-ownership pipeline used
+    // below for the placeholder-only case, so a consumer's own directly-set
+    // aria-label is never clobbered (gh#1646 guarantee extends for free) and
+    // toggling [label-hidden] back off cleanly releases the bridged value
+    // (falls through to the visible-label path, which sets no aria-label —
+    // the generated `::before` content supplies the name instead, unchanged
+    // from today). Mirrors check-ui's [label-hidden] (gh#1010), which
+    // instead sets aria-label unconditionally since check-ui never relies
+    // on generated-content naming.
+    if (this.labelHidden && this.label) {
+      this.#lastAutoAriaLabel = syncAutoAriaLabel(this, this.#lastAutoAriaLabel, this.label);
+      return;
+    }
     const labeledElsewhere = !!this.label || this.hasAttribute('aria-labelledby');
     const namable = !labeledElsewhere
       && this.placeholder && this.placeholder !== DEFAULT_PLACEHOLDER;

package/components/select/select.css

@@ -98,6 +98,31 @@
   :scope:not([label])::before,
   :scope[label=""]::before { display: none; }
 
+  /* Visually-hidden label (gh#1748) — [label-hidden] keeps the a11y name
+     (aria-label, bridged from [label] in select.class.js's
+     #syncAccessibleName()) but drops the visible text, for compositions
+     that already show the name elsewhere (e.g. a table-toolbar-ui
+     [slot="scope"] select whose scope/view name is redundant chrome next
+     to the toolbar's own title). Same canonical sr-only recipe as
+     <visually-hidden-ui> (visually-hidden.css) and check-ui's own
+     [label-hidden] (gh#1010) — clip-path does the real hiding, the rest is
+     belt-and-suspenders for cross-UA. More specific than the bare
+     `::before` rule above, so it wins whenever both [label] and
+     [label-hidden] are set. */
+  :scope[label][label-hidden]::before {
+    content: attr(label);
+    position: absolute !important;
+    width: 1px !important;
+    height: 1px !important;
+    padding: 0 !important;
+    margin: -1px !important;
+    overflow: hidden !important;
+    clip: rect(0, 0, 0, 0) !important;
+    clip-path: inset(100%) !important;
+    white-space: nowrap !important;
+    border: 0 !important;
+  }
+
   /* Trigger */
   [slot="trigger"] {
     display: flex;

package/components/select/select.d.ts

@@ -45,6 +45,8 @@ export class UISelect extends UIFormElement {
   /** Open/closed reflected attribute — toggled by trigger click / keyboard. */
   open: boolean;
   label: string;
+  /** When true, [label] still sets the accessible name but the visible text is sr-only hidden (gh#1748, mirrors check-ui's [label-hidden], gh#1010). */
+  labelHidden: boolean;
   /** Leading icon name (Phosphor registry). */
   icon: string;
   /** Leading avatar URL or name. */

package/components/select/select.yaml

@@ -104,6 +104,18 @@ props:
     description: Label text above the trigger
     type: string
     default: ""
+  label-hidden:
+    description: >-
+      When true, [label] still sets the accessible name (aria-label) but the
+      visible `::before` text is suppressed via the canonical sr-only
+      technique (gh#1748, mirrors check-ui's [label-hidden], gh#1010). Use
+      when a sibling/ancestor composition already conveys the same name
+      visually (e.g. a scope/view-switcher select in a table-toolbar-ui
+      [slot="scope"], where the toolbar's own title already names the
+      view) and a second visible "Scope"-style label would paint it twice.
+    type: boolean
+    default: false
+    reflect: true
   hint:
     description: |-
       §184 (v0.5.5, FEEDBACK-08 §7): small caption rendered beneath the select. Sets `aria-describedby` on the host so screen readers announce it as a description (distinct from `aria-label`, which comes from `label`). Does not conflict with the in-component `label`.

package/components/table/cell-types.js

@@ -312,6 +312,15 @@ registerCellType('progress', {
 
 // 13. actions
 registerCellType('actions', {
+  // gh#1678 CodeRabbit follow-up: this render() calls addEventListener()
+  // directly on a plain node it creates — unlike every other cell type
+  // above (which only set attributes on custom elements, safe to adopt
+  // structurally), a discarded 'actions' cell loses a real listener with
+  // no way for isEqualNode() to see the loss. `attachesListeners: true`
+  // tells table.class.js's adoptOrDiffChildren() (via RENDERER_OWNED) to
+  // always replace this cell rather than ever adopt it on structural
+  // equality alone. See ssr-compatibility's references/guard-patterns.md §4.1.
+  attachesListeners: true,
   render(value, row, cell, meta) {
     const actions = meta?.actions || [];
     let wrapper = cell.querySelector('row-ui');

package/components/table/table.a2ui.json

@@ -34,6 +34,11 @@
       "type": "boolean",
       "default": false
     },
+    "filteredCount": {
+      "description": "Read-only. The row count AFTER search + column filters apply but BEFORE pagination slices it (gh#1807, ADR-0080, REQ-W-006) — a plain JS getter, no setter, never a reflected attribute. table-footer-ui's client-mode range-total derivation reads this directly; a raw `.data.length` read (the toolbar's own `count` fallback precedent) would double-count a filtered-out row. In server mode ([range-total] set, gh#1754, ADR-0082), filteredCount stays page-scoped — the loaded page's rows after local filters, NOT the server total across all pages; [range-total] is the server total, filteredCount never is (REQ-D-006).",
+      "type": "number",
+      "readOnly": true
+    },
     "frameless": {
       "description": "Drop the table's outer 1px perimeter and nothing else (gh#511) — row dividers are untouched (the perimeter is split onto its own --table-perimeter token, defaulting to --table-border). For card-composed tables: the card owns the frame, so the table's square perimeter otherwise renders a doubled edge (flush bleed) or a stray inner box (with content above). Standalone tables keep their chrome by default. Theming path without the attribute: set --table-perimeter to transparent per instance. Note: `<card-ui><section bleed>` already drops a direct-child table-ui's chrome automatically (card.css, gh#796) — `frameless`/`raw` on the instance still applies and is honored, but is no longer required just to avoid the doubled-edge look in that composition.",
       "type": "boolean",
@@ -44,8 +49,18 @@
       "type": "boolean",
       "default": false
     },
+    "no-pager": {
+      "description": "Hide the internal pagination bar while leaving [paginate] slicing, page state, the `page` event, and the `footer-page` command listener all intact (gh#1807, ADR-0080). The anti-doubled-pager mechanism for a table-footer-ui composition, client- or server-mode alike (gh#1754, ADR-0082): without it, a bound footer's own composed pager and the table's own internal one would both render for any non-empty paginated table. Explicit author intent — never suppressed automatically just because a footer happens to be bound.",
+      "type": "boolean",
+      "default": false
+    },
     "paginate": {
-      "description": "Rows per page. 0 = show all rows without pagination. When > 0, renders a pagination bar below the table.",
+      "description": "Rows per page. 0 = show all rows without pagination. When > 0, renders the internal pagination bar below the table — UNLESS [no-pager] is also set (gh#1807, ADR-0080), which keeps [paginate]'s slicing/page-state/`page`-event/`footer-page`-listener behavior but suppresses only the bar itself (the anti-doubled-pager path for a table-footer-ui composition). When [range-total] is also set (gh#1754, ADR-0082), [paginate] becomes purely presentational — it supplies only the page-size for pager math; no local slicing runs.",
+      "type": "number",
+      "default": 0
+    },
+    "range-total": {
+      "description": "Total row count across ALL server pages (gh#1754, ADR-0082) — the table-authoritative server-mode data contract. Presence-gated: the attribute's PRESENCE, not its value, is the mode switch (checked via hasAttribute, never the coerced value alone — the same discipline table-footer-ui's own [range-total] ships). Absent (the default) means client mode: today's behavior exactly, [paginate] slices `.data` as always. Present with [paginate] > 0 means server mode: no local slicing (`.data` IS the current page and renders whole, after local search/sort/filter), the internal pager's page count becomes `max(1, ceil(range-total / paginate))` (one calc site, consolidated), 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 — page state then moves only via pager interaction, the `footer-page` command, or `setState()`. The existing `page` event (0-based, unchanged) becomes the fetch trigger: the consumer listens for it, fetches that server page, and writes `.data` back. 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 (REQ-W-006 branch 2) for its count-only label — see the footer-authoritative shape below, which remains lawful and is unaffected by this attribute. Named identically to table-toolbar-ui's and table-footer-ui's own [range-total] (rows, never `pagination-ui[total]`'s pages — the ADR-0063 B5 collision rule); a third instance of one name for one concept.",
       "type": "number",
       "default": 0
     },
@@ -55,7 +70,7 @@
       "default": false
     },
     "search": {
-      "description": "Global search/filter string. Filters visible rows across all columns using case-insensitive substring matching. Resets to page 1 on change.",
+      "description": "Global search/filter string. Filters visible rows across all columns using case-insensitive substring matching. Does NOT reset the current page (verified against source at the gh#1754/ADR-0082 build — unlike setFilter()/clearFilters(), no internal page reset ever ran for a search change; this description previously claimed \"resets to page 1 on change,\" which the source never did). Aligning the doc to observed behavior here, not a behavior change — a page reset on search, if wanted, is a separate client-mode ticket.",
       "type": "string",
       "default": ""
     },
@@ -141,10 +156,10 @@
         }
       },
       "page": {
-        "description": "Fired when the user navigates to a different page.",
+        "description": "Fired when the table's own internal page state changes — an internal pager click, or a `footer-page` command applied (REQ-W-002). This is a RESYNC notification a bound `<table-footer-ui>` listens to for its own `page` attribute (REQ-W-004) — it is NOT the public server-mode fetch trigger a consumer should listen to; use `<table-footer-ui>`'s own `page-change` event for that (1-based, gh#1754/ADR-0082 REQ-W-003). Listening to both risks a duplicate fetch or an index-base mismatch.",
         "detail": {
           "page": {
-            "description": "New active page index (1-based).",
+            "description": "New active page index (0-based — gh#1808; the `footer-page` command and the `page` attribute on <table-footer-ui> are 1-based, this event's own detail is not).",
             "type": "number"
           }
         }