@rozie-ui/data-table-lit 0.7.1 → 0.7.3

package/src/DataTable.ts

@@ -46,63 +46,167 @@ import { columnSpecsEquivalent } from './helpers/columnDefUtils';
 
 // The registry API handed to <Column> children (whole-object-replace — T-48-PP guard).
 
+import type { Column as TableColumn, ColumnDef, ColumnFiltersState, ColumnOrderState, ColumnPinningState, ColumnSizingState, ExpandedState, GroupingState, PaginationState, RowSelectionState, SortingState, VisibilityState } from '@tanstack/table-core';
+
+/** A cell position as integers over the visible (display-order) model. */
+export interface DataTableCellPosition {
+  rowIndex: number;
+  colIndex: number;
+}
+/** The active (roving-focus) cell. A header cell reports `rowIndex: null` and `isHeader: true`. */
+export interface DataTableActiveCell {
+  rowIndex: number | null;
+  colIndex: number;
+  isHeader: boolean;
+}
+/** The rectangular cell-range selection. Both corners are `null` when there is no range. */
+export interface DataTableRange {
+  anchor: DataTableCellPosition | null;
+  focus: DataTableCellPosition | null;
+}
+/** One data column offered to the `#groupBar` slot. */
+export interface DataTableGroupableColumn {
+  id: string;
+  label: string;
+}
+/** One changed cell inside a row edit commit. */
+export interface DataTableCellChange {
+  columnId: string;
+  oldValue: any;
+  newValue: any;
+}
+
+/** The `activecell-change` payload. `isHeader` is set when the move landed on or left a header cell. */
+export interface DataTableActiveCellChangePayload {
+  rowIndex: number | null;
+  colIndex: number;
+  isHeader?: boolean;
+}
+/** The `cell-edit-commit` payload: one committed cell. */
+export interface DataTableCellEditCommitPayload {
+  rowId: string;
+  columnId: string;
+  oldValue: any;
+  newValue: any;
+}
+/** The `row-edit-commit` payload: the row and every cell the save changed. */
+export interface DataTableRowEditCommitPayload {
+  rowId: string;
+  changes: DataTableCellChange[];
+}
+/** The `filter-change` payload: `globalFilter` for the search box, `columnFilters` for a per-column filter. Exactly one key is set. */
+export interface DataTableFilterChangePayload {
+  globalFilter?: string;
+  columnFilters?: ColumnFiltersState;
+}
+/** The `history-change` payload: undo/redo availability. */
+export interface DataTableHistoryChangePayload {
+  canUndo: boolean;
+  canRedo: boolean;
+}
+/** The `range-change` payload: the new range corners (both `null` when the range cleared). */
+export type DataTableRangeChangePayload = DataTableRange;
+/** The `row-activate` payload. `row` is the original data object and `index` its position in the rendered model. */
+export interface DataTableRowActivatePayload {
+  row: any;
+  index: number;
+  trigger: 'keyboard' | 'click';
+}
+/** The `visible-range-change` payload: the rendered row window, `end` exclusive. */
+export interface DataTableVisibleRangeChangePayload {
+  start: number;
+  end: number;
+}
+
+export interface RozieDataTableEventMap extends Omit<HTMLElementEventMap, 'activecell-change' | 'cell-edit-commit' | 'expand-change' | 'filter-change' | 'group-change' | 'history-change' | 'page-change' | 'pin-change' | 'range-change' | 'reorder-change' | 'resize-change' | 'row-activate' | 'row-edit-commit' | 'selection-change' | 'sort-change' | 'visibility-change' | 'visible-range-change' | 'data-change' | 'sorting-change' | 'global-filter-change' | 'column-filters-change' | 'pagination-change' | 'expanded-change' | 'grouping-change' | 'row-selection-change' | 'column-visibility-change' | 'column-sizing-change' | 'column-order-change' | 'column-pinning-change'> {
+  'activecell-change': CustomEvent<DataTableActiveCellChangePayload>;
+  'cell-edit-commit': CustomEvent<DataTableCellEditCommitPayload>;
+  'expand-change': CustomEvent<ExpandedState>;
+  'filter-change': CustomEvent<DataTableFilterChangePayload>;
+  'group-change': CustomEvent<GroupingState>;
+  'history-change': CustomEvent<DataTableHistoryChangePayload>;
+  'page-change': CustomEvent<PaginationState>;
+  'pin-change': CustomEvent<ColumnPinningState>;
+  'range-change': CustomEvent<DataTableRangeChangePayload>;
+  'reorder-change': CustomEvent<ColumnOrderState>;
+  'resize-change': CustomEvent<ColumnSizingState>;
+  'row-activate': CustomEvent<DataTableRowActivatePayload>;
+  'row-edit-commit': CustomEvent<DataTableRowEditCommitPayload>;
+  'selection-change': CustomEvent<RowSelectionState>;
+  'sort-change': CustomEvent<SortingState>;
+  'visibility-change': CustomEvent<VisibilityState>;
+  'visible-range-change': CustomEvent<DataTableVisibleRangeChangePayload>;
+  'data-change': CustomEvent<any[]>;
+  'sorting-change': CustomEvent<any[]>;
+  'global-filter-change': CustomEvent<string>;
+  'column-filters-change': CustomEvent<any[]>;
+  'pagination-change': CustomEvent<any>;
+  'expanded-change': CustomEvent<any | boolean>;
+  'grouping-change': CustomEvent<any[]>;
+  'row-selection-change': CustomEvent<any>;
+  'column-visibility-change': CustomEvent<any>;
+  'column-sizing-change': CustomEvent<any>;
+  'column-order-change': CustomEvent<any[]>;
+  'column-pinning-change': CustomEvent<any>;
+}
+
 const __rozieCtx_data_table_columns = createContext(Symbol.for("rozie:data-table:columns"));
 
 interface RozieGroupBarSlotCtx {
-  grouping: any;
-  groupableColumns: any;
-  applyGrouping: any;
-  clearGrouping: any;
+  grouping: string[];
+  groupableColumns: DataTableGroupableColumn[];
+  applyGrouping: (cols: string[]) => void;
+  clearGrouping: () => void;
 }
 
 interface RozieSelectAllSlotCtx {
-  checked: any;
-  indeterminate: any;
-  toggle: any;
+  checked: boolean;
+  indeterminate: boolean;
+  toggle: (event: any) => void;
 }
 
 interface RozieDynamicColHeaderSlotCtx {
-  columnId: any;
-  column: any;
-  label: any;
+  columnId: string;
+  column: TableColumn<any, unknown>;
+  label: string;
 }
 
 interface RozieDynamicFilterSlotCtx {
-  columnId: any;
+  columnId: string;
   value: any;
-  uniqueValues: any;
-  minMax: any;
-  columnLabel: any;
-  setFilter: any;
+  uniqueValues: any[];
+  minMax: [number, number] | null;
+  columnLabel: string;
+  setFilter: (columnId: string, value: any) => void;
 }
 
 interface RoziePlaceholderSlotCtx {
-  index: any;
-  columnId: any;
+  index: number;
+  columnId: string;
 }
 
 interface RozieSelectCellSlotCtx {
   row: any;
-  checked: any;
-  toggle: any;
+  checked: boolean;
+  toggle: (event: any) => void;
 }
 
 interface RozieDynamicCellSlotCtx {
-  columnId: any;
-  column: any;
+  columnId: string;
+  column: TableColumn<any, unknown>;
   row: any;
   value: any;
 }
 
 interface RozieDynamicEditorSlotCtx {
-  columnId: any;
-  column: any;
+  columnId: string;
+  column: TableColumn<any, unknown>;
   row: any;
   value: any;
-  commit: any;
-  cancel: any;
-  columnLabel: any;
-  autofocus: any;
+  commit: (value: any) => void;
+  cancel: () => void;
+  columnLabel: string;
+  autofocus: boolean;
 }
 
 interface RozieDetailSlotCtx {
@@ -110,36 +214,36 @@ interface RozieDetailSlotCtx {
 }
 
 interface RozieColHeaderSlotCtx {
-  columnId: any;
-  column: any;
-  label: any;
+  columnId: string;
+  column: TableColumn<any, unknown>;
+  label: string;
 }
 
 interface RozieFilterSlotCtx {
-  columnId: any;
+  columnId: string;
   value: any;
-  uniqueValues: any;
-  minMax: any;
-  columnLabel: any;
-  setFilter: any;
+  uniqueValues: any[];
+  minMax: [number, number] | null;
+  columnLabel: string;
+  setFilter: (columnId: string, value: any) => void;
 }
 
 interface RozieCellSlotCtx {
-  columnId: any;
-  column: any;
+  columnId: string;
+  column: TableColumn<any, unknown>;
   row: any;
   value: any;
 }
 
 interface RozieEditorSlotCtx {
-  columnId: any;
-  column: any;
+  columnId: string;
+  column: TableColumn<any, unknown>;
   row: any;
   value: any;
-  commit: any;
-  cancel: any;
-  columnLabel: any;
-  autofocus: any;
+  commit: (value: any) => void;
+  cancel: () => void;
+  columnLabel: string;
+  autofocus: boolean;
 }
 
 @customElement('rozie-data-table')
@@ -768,8 +872,10 @@ export default class DataTable extends SignalWatcher(LitElement) {
   private _liveAnnounce = signal('');
   @query('[data-rozie-ref="__rozieRoot"]') private _ref__rozieRoot!: HTMLElement;
 private __rozieWatchInitial_0 = true;
+private __rozieWatchPrev_1: unknown;
 private __rozieWatchInitial_1 = true;
 private __rozieWatchInitial_2 = true;
+private __rozieFirstUpdateDone = false;
 private __rozieCtxProvider_data_table_columns = new ContextProvider(this, { context: __rozieCtx_data_table_columns, initialValue: ((__rozieCtxHost) => ({
   registerColumn: (id: any, spec: any) => {
     if (id == null) return;
@@ -806,20 +912,20 @@ private __rozieCtxProvider_data_table_columns = new ContextProvider(this, { cont
   @queryAssignedElements({ flatten: true }) private _slotDefaultElements!: Element[];
   @state() private _hasSlotGroupBar = false;
   @queryAssignedElements({ slot: 'groupBar', flatten: true }) private _slotGroupBarElements!: Element[];
-  @property({ attribute: false }) groupBar?: (scope: { grouping: any; groupableColumns: any; applyGrouping: any; clearGrouping: any }) => unknown;
+  @property({ attribute: false }) groupBar?: (scope: { grouping: string[]; groupableColumns: DataTableGroupableColumn[]; applyGrouping: (cols: string[]) => void; clearGrouping: () => void }) => unknown;
   @state() private _hasSlotSelectAll = false;
   @queryAssignedElements({ slot: 'selectAll', flatten: true }) private _slotSelectAllElements!: Element[];
-  @property({ attribute: false }) selectAll?: (scope: { checked: any; indeterminate: any; toggle: any }) => unknown;
+  @property({ attribute: false }) selectAll?: (scope: { checked: boolean; indeterminate: boolean; toggle: (event: any) => void }) => unknown;
   @state() private _hasSlotDynamicColHeader = false;
   @queryAssignedElements({ flatten: true }) private _slotDynamicColHeaderElements!: Element[];
   @state() private _hasSlotDynamicFilter = false;
   @queryAssignedElements({ flatten: true }) private _slotDynamicFilterElements!: Element[];
   @state() private _hasSlotPlaceholder = false;
   @queryAssignedElements({ slot: 'placeholder', flatten: true }) private _slotPlaceholderElements!: Element[];
-  @property({ attribute: false }) placeholder?: (scope: { index: any; columnId: any }) => unknown;
+  @property({ attribute: false }) placeholder?: (scope: { index: number; columnId: string }) => unknown;
   @state() private _hasSlotSelectCell = false;
   @queryAssignedElements({ slot: 'selectCell', flatten: true }) private _slotSelectCellElements!: Element[];
-  @property({ attribute: false }) selectCell?: (scope: { row: any; checked: any; toggle: any }) => unknown;
+  @property({ attribute: false }) selectCell?: (scope: { row: any; checked: boolean; toggle: (event: any) => void }) => unknown;
   @state() private _hasSlotDynamicCell = false;
   @queryAssignedElements({ flatten: true }) private _slotDynamicCellElements!: Element[];
   @state() private _hasSlotDynamicEditor = false;
@@ -829,16 +935,16 @@ private __rozieCtxProvider_data_table_columns = new ContextProvider(this, { cont
   @property({ attribute: false }) detail?: (scope: { row: any }) => unknown;
   @state() private _hasSlotColHeader = false;
   @queryAssignedElements({ slot: 'colHeader', flatten: true }) private _slotColHeaderElements!: Element[];
-  @property({ attribute: false }) colHeader?: (scope: { columnId: any; column: any; label: any }) => unknown;
+  @property({ attribute: false }) colHeader?: (scope: { columnId: string; column: TableColumn<any, unknown>; label: string }) => unknown;
   @state() private _hasSlotFilter = false;
   @queryAssignedElements({ slot: 'filter', flatten: true }) private _slotFilterElements!: Element[];
-  @property({ attribute: false }) filter?: (scope: { columnId: any; value: any; uniqueValues: any; minMax: any; columnLabel: any; setFilter: any }) => unknown;
+  @property({ attribute: false }) filter?: (scope: { columnId: string; value: any; uniqueValues: any[]; minMax: [number, number] | null; columnLabel: string; setFilter: (columnId: string, value: any) => void }) => unknown;
   @state() private _hasSlotCell = false;
   @queryAssignedElements({ slot: 'cell', flatten: true }) private _slotCellElements!: Element[];
-  @property({ attribute: false }) cell?: (scope: { columnId: any; column: any; row: any; value: any }) => unknown;
+  @property({ attribute: false }) cell?: (scope: { columnId: string; column: TableColumn<any, unknown>; row: any; value: any }) => unknown;
   @state() private _hasSlotEditor = false;
   @queryAssignedElements({ slot: 'editor', flatten: true }) private _slotEditorElements!: Element[];
-  @property({ attribute: false }) editor?: (scope: { columnId: any; column: any; row: any; value: any; commit: any; cancel: any; columnLabel: any; autofocus: any }) => unknown;
+  @property({ attribute: false }) editor?: (scope: { columnId: string; column: TableColumn<any, unknown>; row: any; value: any; commit: (value: any) => void; cancel: () => void; columnLabel: string; autofocus: boolean }) => unknown;
   // Phase 79 Plan 08 (R4) contract for 79-09: the record intake for
   // record-routed slot fills. 79-09's consumer-side emitSlotFiller
   // accumulates an object literal onto the SAME `.rozieSlots=${{ ... }}`
@@ -848,7 +954,7 @@ private __rozieCtxProvider_data_table_columns = new ContextProvider(this, { cont
   // named function-prop / <slot> fallback (AC-9). Attribute
   // deserialization is disabled — this is a function-valued record,
   // never reflected to/from an HTML attribute.
-  @property({ attribute: false }) rozieSlots?: { [key: `colHeader-${string}`]: (scope: { columnId: any; column: any; label: any }) => unknown; [key: `filter-${string}`]: (scope: { columnId: any; value: any; uniqueValues: any; minMax: any; columnLabel: any; setFilter: any }) => unknown; [key: `cell-${string}`]: (scope: { columnId: any; column: any; row: any; value: any }) => unknown; [key: `editor-${string}`]: (scope: { columnId: any; column: any; row: any; value: any; commit: any; cancel: any; columnLabel: any; autofocus: any }) => unknown; } & Record<string, (scope: any) => unknown>;
+  @property({ attribute: false }) rozieSlots?: { [key: `colHeader-${string}`]: (scope: { columnId: string; column: TableColumn<any, unknown>; label: string }) => unknown; [key: `filter-${string}`]: (scope: { columnId: string; value: any; uniqueValues: any[]; minMax: [number, number] | null; columnLabel: string; setFilter: (columnId: string, value: any) => void }) => unknown; [key: `cell-${string}`]: (scope: { columnId: string; column: TableColumn<any, unknown>; row: any; value: any }) => unknown; [key: `editor-${string}`]: (scope: { columnId: string; column: TableColumn<any, unknown>; row: any; value: any; commit: (value: any) => void; cancel: () => void; columnLabel: string; autofocus: boolean }) => unknown; } & Record<string, (scope: any) => unknown>;
 
   private _disconnectCleanups: Array<() => void> = [];
   // Re-parenting guard: set true once the deferred teardown has actually
@@ -1048,7 +1154,7 @@ private __rozieCtxProvider_data_table_columns = new ContextProvider(this, { cont
     // columnDefs()/tableColumns() build the UNION of both, and reFeed re-passes columns.
     // (Consumers memoize the array as with $props.data/$props.sorting; the uncontrolled
     // <Column>-children path leaves $props.columns undefined — a stable no-op getter.)
-    this.columns, this._colReg.value])(); untracked(() => { if (this.__rozieWatchInitial_1) { this.__rozieWatchInitial_1 = false; return; } (() => {
+    this.columns, this._colReg.value])(); untracked(() => { this.__rozieWatchPrev_1 = __watchVal; if (this.__rozieWatchInitial_1) { this.__rozieWatchInitial_1 = false; return; } (() => {
       // Seed BEFORE the re-feed so the pinning this call may write is part of the state object
       // table-core receives on this same tick (rather than landing a frame late and re-ordering
       // getVisibleCells() a render after the columns appear). One-shot and self-latching — see
@@ -1104,15 +1210,8 @@ private __rozieCtxProvider_data_table_columns = new ContextProvider(this, { cont
     // re-ordering a render later. Covers the `:columns` config-array form, which is available
     // now; `<Column>` children register during mount and are covered by the re-feed watch's own
     // call. One-shot and self-latching — see seedColumnPinning() in stateAssembly.rzts.
-    // Apply any per-column `pinned` declaration as the INITIAL pinning state BEFORE createTable
-    // reads currentState() below, so the first row model table-core builds is already correctly
-    // ordered (getVisibleCells() returns [left-pinned, center, right-pinned]) rather than
-    // re-ordering a render later. Covers the `:columns` config-array form, which is available
-    // now; `<Column>` children register during mount and are covered by the re-feed watch's own
-    // call. One-shot and self-latching — see seedColumnPinning() in stateAssembly.rzts.
     this.seedColumnPinning();
     // Build the table instance HERE so the closures below capture the live `table`.
-    // Build the table instance HERE so the closures below capture the live `table`.
     this.table = createTable({
       // Plain value (NOT a `get data()` getter): an object-literal getter rebinds
       // `this` to the options object, and the Angular/Lit emitters resolve $props via
@@ -1295,14 +1394,9 @@ private __rozieCtxProvider_data_table_columns = new ContextProvider(this, { cont
       if (typeof queueMicrotask !== 'undefined') queueMicrotask(this.syncIndeterminate);else Promise.resolve().then(this.syncIndeterminate);
     };
 
-    // initial pull
     // initial pull
     this.refreshRowModel();
 
-    // ── Grid mode: capture the table root ──────────────────────────────────────────────
-    // $el is the component root; the <table class="rozie-data-table"> is the grid root the
-    // cell selectors hang off (the exact idiom proven ×6 by plan 01's probe). Captured here
-    // (post-mount) so it is non-null and ROZ123-clean.
     // ── Grid mode: capture the table root ──────────────────────────────────────────────
     // $el is the component root; the <table class="rozie-data-table"> is the grid root the
     // cell selectors hang off (the exact idiom proven ×6 by plan 01's probe). Captured here
@@ -1311,9 +1405,6 @@ private __rozieCtxProvider_data_table_columns = new ContextProvider(this, { cont
     // B-02: the click-away detector. `composedPath()` rather than `ev.target` because on Lit the
     // grid lives in a shadow root and a document-level listener sees the retargeted HOST element,
     // which is never `gridRoot.contains(...)` — every in-grid click would read as "outside".
-    // B-02: the click-away detector. `composedPath()` rather than `ev.target` because on Lit the
-    // grid lives in a shadow root and a document-level listener sees the retargeted HOST element,
-    // which is never `gridRoot.contains(...)` — every in-grid click would read as "outside".
     if (typeof document !== 'undefined') {
       this.docPointerDown = (ev: any) => {
         if (!this.gridRoot) {
@@ -1332,20 +1423,6 @@ private __rozieCtxProvider_data_table_columns = new ContextProvider(this, { cont
     // cell IS the first Tab-in target (matching the Wave-0 probe's "no auto-focus on
     // mount"); the consumer drives focus by Tabbing/clicking in, never the component.
 
-    // ── Windowing: capture the scroll element + construct the row virtualizer (req-1/2 — the
-    // row virtual-core instance ONLY when rows are windowed; the scroll-element capture whenever
-    // EITHER axis is windowed, since both axes observe the SAME .rdt-scroll element — D-03). Built
-    // HERE (post-mount) so getScrollElement resolves the rendered .rdt-scroll div and
-    // getPrePaginationRowModel reads the live table. ENTIRELY inside the isWindowed()/rowsWindowed()
-    // guards: when both axes are off, NO virtual-core runtime code executes (byte-identical-off).
-    // _didMount() registers the scroll-element ResizeObserver and returns the teardown stored for
-    // $onUnmount.
-    // WR-04: NO on-mount auto-focus of the entry cell. Auto-focusing here stole focus on
-    // page load AND was non-deterministic on React/Solid (the entry cell may not be
-    // committed to the DOM yet at the $onMount microtask). The roving tabindex="0" entry
-    // cell IS the first Tab-in target (matching the Wave-0 probe's "no auto-focus on
-    // mount"); the consumer drives focus by Tabbing/clicking in, never the component.
-
     // ── Windowing: capture the scroll element + construct the row virtualizer (req-1/2 — the
     // row virtual-core instance ONLY when rows are windowed; the scroll-element capture whenever
     // EITHER axis is windowed, since both axes observe the SAME .rdt-scroll element — D-03). Built
@@ -1364,9 +1441,6 @@ private __rozieCtxProvider_data_table_columns = new ContextProvider(this, { cont
     // Phase 87 87-04: construct the SECOND, horizontal Virtualizer instance when the COLUMN
     // axis is windowed — entirely inside its own colsWindowed() guard, byte-identical-off for
     // 'rows'/true/false.
-    // Phase 87 87-04: construct the SECOND, horizontal Virtualizer instance when the COLUMN
-    // axis is windowed — entirely inside its own colsWindowed() guard, byte-identical-off for
-    // 'rows'/true/false.
     if (this.colsWindowed()) {
       this.colVirtualizer = new Virtualizer(this.columnVirtualizerOptions());
       this.colVirtualizerCleanup = this.colVirtualizer._didMount();
@@ -1389,24 +1463,6 @@ private __rozieCtxProvider_data_table_columns = new ContextProvider(this, { cont
     // idiom lowers to a functional React setState update and is safe regardless of ordering, the
     // same reasoning virtualizerOptions()'s onChange documents), but collapsing to one bump avoids
     // manufacturing the false-positive warning at all rather than accepting it.
-    // FINE-GRAINED FIRST-WINDOW KICK (Solid/Svelte), either axis: the windowed <For>/{#each}
-    // accessor was first evaluated at initial render — while `virtualizer`/`colVirtualizer` were
-    // still null — and (because windowedRows()/windowedColIndices() read $data.windowVer up top)
-    // subscribed to windowVer then returned []/the full set. Both `let`s are non-reactive, so
-    // their assignment above does NOT notify the accessor; we must bump the SIGNAL it subscribed
-    // to. _didMount() computes the first window synchronously but its onChange only fires on
-    // SUBSEQUENT scroll/resize, so without this explicit bump the first window would never paint
-    // on the fine-grained targets. Idempotent + harmless on the coarse targets (they re-render
-    // wholesale anyway). ONE bump here (not one per axis, Rule 1 — see the ROZ138 note below)
-    // covers both: windowedRows()/windowedColIndices() each simply re-derive against their own
-    // now-non-null virtualizer instance off the SAME counter (87-02 checkpoint decision (b): no
-    // separate $data.colWindowVer). Gated on isWindowed() (either axis) rather than two separate
-    // per-axis bumps: a second `$data.windowVer = $data.windowVer + 1` write later in this SAME
-    // $onMount body would dominate-flag ROZ138 (React stale-read) on its own right-hand-side read
-    // of the counter it had just written a few lines above — a false positive (this increment
-    // idiom lowers to a functional React setState update and is safe regardless of ordering, the
-    // same reasoning virtualizerOptions()'s onChange documents), but collapsing to one bump avoids
-    // manufacturing the false-positive warning at all rather than accepting it.
     if (this.isWindowed()) {
       this._windowVer.value = this._windowVer.value + 1;
     }
@@ -1416,12 +1472,6 @@ private __rozieCtxProvider_data_table_columns = new ContextProvider(this, { cont
     // row-specific measurement + warns stay further guarded by rowsWindowed() (byte-identical to
     // before this restructure); the column-axis warn (Phase 87 D-07(a)) is guarded by
     // colsWindowed() so it can fire ONLY on the 'columns'/'both' path, never on 'rows'/true/false.
-    // After the first window commits (next frame), refine heights + fire the dev-mode warns ONCE.
-    // Entirely inside the isWindowed() guard so the off (neither axis windowed) emitted path adds
-    // NO code and these warns can never fire there (req-1 byte-identical-off preserved). The
-    // row-specific measurement + warns stay further guarded by rowsWindowed() (byte-identical to
-    // before this restructure); the column-axis warn (Phase 87 D-07(a)) is guarded by
-    // colsWindowed() so it can fire ONLY on the 'columns'/'both' path, never on 'rows'/true/false.
     if (this.isWindowed()) {
       const afterFirstFrame = () => {
         if (this.rowsWindowed()) {
@@ -1488,9 +1538,6 @@ private __rozieCtxProvider_data_table_columns = new ContextProvider(this, { cont
       if (typeof requestAnimationFrame === 'function') requestAnimationFrame(() => requestAnimationFrame(afterFirstFrame));else setTimeout(afterFirstFrame, 0);
     }
 
-    // #14: seed the sort/filter announce baseline from the initial (post-mount) state so the LAZY
-    // watch's first fire — a real user sort/filter — compares against the true starting values and
-    // is classified correctly (a null sentinel would misread the first filter change as a sort change).
     // #14: seed the sort/filter announce baseline from the initial (post-mount) state so the LAZY
     // watch's first fire — a real user sort/filter — compares against the true starting values and
     // is classified correctly (a null sentinel would misread the first filter change as a sort change).
@@ -1500,41 +1547,55 @@ private __rozieCtxProvider_data_table_columns = new ContextProvider(this, { cont
   }
 
   updated(changedProperties: Map<string, unknown>): void {
-    this.maybeClearHistoryOnExternalSwap();
-    // visible-range-change backstop (quick 260925-dtl part 2): a re-render from new data can move
-    // the rendered window WITHOUT a window-version bump (measured on React: filling placeholders
-    // shifted the window by two rows and nothing was reported). Deduped, so a render that leaves
-    // the window where it was emits nothing.
-    // visible-range-change backstop (quick 260925-dtl part 2): a re-render from new data can move
-    // the rendered window WITHOUT a window-version bump (measured on React: filling placeholders
-    // shifted the window by two rows and nothing was reported). Deduped, so a render that leaves
-    // the window where it was emits nothing.
-    this.emitVisibleRangeIfChanged();
-    // A-02: the post-render hook is the one place that observes EVERY column-width change on all
-    // six targets — an interactive resize writes `columnSizing` through table-core under
-    // `columnResizeMode: 'onChange'` and never reaches the coarse re-feed watch (which keys on
-    // `$props.columnSizing`, undefined on the uncontrolled path). Self-guarded on the width
-    // signature, so a tick that changed no width costs one loop over the leaf columns.
-    // A-02: the post-render hook is the one place that observes EVERY column-width change on all
-    // six targets — an interactive resize writes `columnSizing` through table-core under
-    // `columnResizeMode: 'onChange'` and never reaches the coarse re-feed watch (which keys on
-    // `$props.columnSizing`, undefined on the uncontrolled path). Self-guarded on the width
-    // signature, so a tick that changed no width costs one loop over the leaf columns.
-    this.remeasureColumnSizes();
-    if (!this.table) return;
-    // Phase 51 req-4: track currentData() (the bound prop OR the uncontrolled
-    // $data.dataDefault) so a committed edit re-feeds on Lit whether or not the two-way
-    // `data` model is bound. Compare by reference AND length so a same-length single-cell edit (fresh array,
-    // identical length) still re-feeds.
-    // Phase 51 req-4: track currentData() (the bound prop OR the uncontrolled
-    // $data.dataDefault) so a committed edit re-feeds on Lit whether or not the two-way
-    // `data` model is bound. Compare by reference AND length so a same-length single-cell edit (fresh array,
-    // identical length) still re-feeds.
-    const d = this.currentData() || [];
-    if (d === this.lastData && d.length === this.lastDataLen) return;
-    this.lastData = d;
-    this.lastDataLen = d.length;
-    this.reFeed();
+    if (this.__rozieFirstUpdateDone && (changedProperties.has('rowCount') || changedProperties.has('pageCount') || changedProperties.has('expandable') || changedProperties.has('groupable') || changedProperties.has('selectionMode') || changedProperties.has('columns'))) { const __watchVal = untracked(() => [this.sorting, this.globalFilter, this.columnFilters, this.pagination, // Server-side page-count sources (#2): re-feed when the consumer's rowCount/pageCount
+    // changes at runtime (e.g. a server response updates the total) so getPageCount() and the
+    // Next button availability track the new total.
+    this.rowCount, this.pageCount, this.rowSelection, this.expanded, this.expandable, this.grouping, this.groupable, this.columnVisibility, this.columnSizing, this.columnOrder, this.columnPinning, this.selectionMode, (this.data || []).length, // Phase 51 req-4: key on the data REFERENCE (both sinks) so a committed edit re-feeds
+    // even when the fresh array is the SAME length (a single-cell edit replaces one row
+    // object → new array ref, identical length → the .length key alone would miss it). The
+    // controlled path observes $props.data; the uncontrolled path observes $data.dataDefault.
+    // writeData is echo-guarded (programmatic) and reFeed writes neither sink, so no loop.
+    this.data, this._dataDefault.value, // Column CONFIG prop (the `:columns` array form) — the sibling column source to
+    // $data.colReg (the `<Column>` children). Watch it so a runtime `:columns` swap re-feeds:
+    // columnDefs()/tableColumns() build the UNION of both, and reFeed re-passes columns.
+    // (Consumers memoize the array as with $props.data/$props.sorting; the uncontrolled
+    // <Column>-children path leaves $props.columns undefined — a stable no-op getter.)
+    this.columns, this._colReg.value]); if (!Object.is(__watchVal, this.__rozieWatchPrev_1)) { this.__rozieWatchPrev_1 = __watchVal; untracked(() => (() => {
+      // Seed BEFORE the re-feed so the pinning this call may write is part of the state object
+      // table-core receives on this same tick (rather than landing a frame late and re-ordering
+      // getVisibleCells() a render after the columns appear). One-shot and self-latching — see
+      // seedColumnPinning() in stateAssembly.rzts. This is the `<Column>`-children entry point:
+      // those register during mount, so the $onMount call below can find zero columns.
+      this.seedColumnPinning();
+      this.reFeed();
+      this.maybeClearHistoryOnExternalSwap();
+    })()); } }
+    this.__rozieFirstUpdateDone = true;
+
+    (() => {
+      this.maybeClearHistoryOnExternalSwap();
+      // visible-range-change backstop (quick 260925-dtl part 2): a re-render from new data can move
+      // the rendered window WITHOUT a window-version bump (measured on React: filling placeholders
+      // shifted the window by two rows and nothing was reported). Deduped, so a render that leaves
+      // the window where it was emits nothing.
+      this.emitVisibleRangeIfChanged();
+      // A-02: the post-render hook is the one place that observes EVERY column-width change on all
+      // six targets — an interactive resize writes `columnSizing` through table-core under
+      // `columnResizeMode: 'onChange'` and never reaches the coarse re-feed watch (which keys on
+      // `$props.columnSizing`, undefined on the uncontrolled path). Self-guarded on the width
+      // signature, so a tick that changed no width costs one loop over the leaf columns.
+      this.remeasureColumnSizes();
+      if (!this.table) return;
+      // Phase 51 req-4: track currentData() (the bound prop OR the uncontrolled
+      // $data.dataDefault) so a committed edit re-feeds on Lit whether or not the two-way
+      // `data` model is bound. Compare by reference AND length so a same-length single-cell edit (fresh array,
+      // identical length) still re-feeds.
+      const d = this.currentData() || [];
+      if (d === this.lastData && d.length === this.lastDataLen) return;
+      this.lastData = d;
+      this.lastDataLen = d.length;
+      this.reFeed();
+    })();
   }
 
   disconnectedCallback(): void {
@@ -2458,7 +2519,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   this.programmatic++;
   this._sortingDefault.value = next; // fresh array only (never in-place)
   this._sortingControllable.write(next); // two-way emit if bound (no-op-diff if not)
-  this.dispatchEvent(new CustomEvent("sort-change", {
+  this.dispatchEvent(new CustomEvent<SortingState>("sort-change", {
     detail: next,
     bubbles: true,
     composed: true
@@ -2488,7 +2549,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // → duplicate-identifier TS2300 (the model-prop==emit-name collision class). Every
   // sibling slice avoids this by stemming the event off a DISTINCT name (sorting→
   // sort-change, rowSelection→selection-change); `expanded`→`expand-change` follows suit.
-  this.dispatchEvent(new CustomEvent("expand-change", {
+  this.dispatchEvent(new CustomEvent<ExpandedState>("expand-change", {
     detail: next,
     bubbles: true,
     composed: true
@@ -2512,7 +2573,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   this.programmatic++;
   this._groupingDefault.value = next; // fresh ordered array only (never in-place push)
   this._groupingControllable.write(next); // two-way emit if bound (no-op-diff if not)
-  this.dispatchEvent(new CustomEvent("group-change", {
+  this.dispatchEvent(new CustomEvent<GroupingState>("group-change", {
     detail: next,
     bubbles: true,
     composed: true
@@ -2528,7 +2589,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   this.programmatic++;
   this._globalFilterDefault.value = next;
   this._globalFilterControllable.write(next);
-  this.dispatchEvent(new CustomEvent("filter-change", {
+  this.dispatchEvent(new CustomEvent<DataTableFilterChangePayload>("filter-change", {
     detail: {
       globalFilter: next
     },
@@ -2547,7 +2608,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   this.programmatic++;
   this._columnFiltersDefault.value = next;
   this._columnFiltersControllable.write(next);
-  this.dispatchEvent(new CustomEvent("filter-change", {
+  this.dispatchEvent(new CustomEvent<DataTableFilterChangePayload>("filter-change", {
     detail: {
       columnFilters: next
     },
@@ -2564,7 +2625,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   this.programmatic++;
   this._paginationDefault.value = next;
   this._paginationControllable.write(next);
-  this.dispatchEvent(new CustomEvent("page-change", {
+  this.dispatchEvent(new CustomEvent<PaginationState>("page-change", {
     detail: next,
     bubbles: true,
     composed: true
@@ -2580,7 +2641,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   this.programmatic++;
   this._rowSelectionDefault.value = next;
   this._rowSelectionControllable.write(next);
-  this.dispatchEvent(new CustomEvent("selection-change", {
+  this.dispatchEvent(new CustomEvent<RowSelectionState>("selection-change", {
     detail: next,
     bubbles: true,
     composed: true
@@ -2596,7 +2657,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   this.programmatic++;
   this._columnVisibilityDefault.value = next;
   this._columnVisibilityControllable.write(next);
-  this.dispatchEvent(new CustomEvent("visibility-change", {
+  this.dispatchEvent(new CustomEvent<VisibilityState>("visibility-change", {
     detail: next,
     bubbles: true,
     composed: true
@@ -2612,7 +2673,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   this.programmatic++;
   this._columnSizingDefault.value = next;
   this._columnSizingControllable.write(next);
-  this.dispatchEvent(new CustomEvent("resize-change", {
+  this.dispatchEvent(new CustomEvent<ColumnSizingState>("resize-change", {
     detail: next,
     bubbles: true,
     composed: true
@@ -2628,7 +2689,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   this.programmatic++;
   this._columnOrderDefault.value = next;
   this._columnOrderControllable.write(next);
-  this.dispatchEvent(new CustomEvent("reorder-change", {
+  this.dispatchEvent(new CustomEvent<ColumnOrderState>("reorder-change", {
     detail: next,
     bubbles: true,
     composed: true
@@ -2655,7 +2716,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   this.programmatic++;
   this._columnPinningDefault.value = clean;
   this._columnPinningControllable.write(clean);
-  this.dispatchEvent(new CustomEvent("pin-change", {
+  this.dispatchEvent(new CustomEvent<ColumnPinningState>("pin-change", {
     detail: clean,
     bubbles: true,
     composed: true
@@ -2767,13 +2828,13 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   this.redoStack = [];
 };
 
-  canUndo = () => this.undoStack.length > 0;
+  canUndo: () => boolean = () => this.undoStack.length > 0;
 
-  canRedo = () => this.redoStack.length > 0;
+  canRedo: () => boolean = () => this.redoStack.length > 0;
 
   // Both stacks empty — the external-swap latch (DataTable.rozie reFeed) and the
   // clearHistory() $expose verb share this single implementation.
-  clearHistory = () => {
+  clearHistory: () => void = () => {
   this.undoStack = [];
   this.redoStack = [];
 };
@@ -2783,7 +2844,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // per call per the design — NOT edge-gated there; only the writeData-triggered recording path
   // below is edge-gated, since a routine sequence of edits would otherwise spam the event).
   emitHistoryChange = () => {
-  this.dispatchEvent(new CustomEvent("history-change", {
+  this.dispatchEvent(new CustomEvent<DataTableHistoryChangePayload>("history-change", {
     detail: {
       canUndo: this.canUndo(),
       canRedo: this.canRedo()
@@ -2809,7 +2870,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // re-capture this replay (which would corrupt the stack). Replaying through writeData
   // (rather than writing $data/$model directly) is deliberate: the two-way $model.data
   // writeback, the re-feed $watch, and the echo guard all keep working with zero new code.
-  undo = () => {
+  undo: () => void = () => {
   if (!this.canUndo()) return;
   const prev = this.undoStack.pop();
   this.redoStack.push(this.currentData());
@@ -2821,7 +2882,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
 
   // redo(): symmetric — pop the redo stack, push the CURRENT data back onto the undo stack,
   // replay through the same guarded writeData seam.
-  redo = () => {
+  redo: () => void = () => {
   if (!this.canRedo()) return;
   const next = this.redoStack.pop();
   this.undoStack.push(this.currentData());
@@ -3410,7 +3471,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   if (start === this.lastRangeStart && end === this.lastRangeEnd) return;
   this.lastRangeStart = start;
   this.lastRangeEnd = end;
-  this.dispatchEvent(new CustomEvent("visible-range-change", {
+  this.dispatchEvent(new CustomEvent<DataTableVisibleRangeChangePayload>("visible-range-change", {
     detail: {
       start,
       end
@@ -3447,7 +3508,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // into the internal `.rdt-scroll` class selector. Returns null when nothing is windowed:
   // gridScrollEl is only ever assigned inside the isWindowed() guard, so no extra gate is
   // needed here beyond that natural null.
-  getScrollElement = (): any => this.gridScrollEl;
+  getScrollElement: () => HTMLElement | null = (): any => this.gridScrollEl;
 
   // ══ Generic vertical windowing math (Phase 64, D-04) — the target-agnostic virtual-core bridge ══
   // Lifted verbatim from the DataTable virtualization.rzts (the Phase 53/63 B13 baseline). This partial
@@ -5024,39 +5085,39 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // is dropped on ALL SIX targets, only the by-reference key survives → a
   // runtime ReferenceError at `defineExpose`/`useImperativeHandle`). Sorting verbs +
   // a fresh column-def readout, selection, pagination, and column-management verbs.
-  sortColumn = (colId: any, desc: any) => {
+  sortColumn: (colId: string, desc?: boolean) => void = (colId: any, desc: any) => {
   if (this.table) this.table.getColumn(colId) && this.table.getColumn(colId).toggleSorting(desc, false);
 };
 
-  clearSorting = () => {
+  clearSorting: () => void = () => {
   if (this.table) this.table.resetSorting(true);
 };
 
-  getColumnDefs = () => this.columnDefs();
+  getColumnDefs: () => ColumnDef<any, any>[] = () => this.columnDefs();
 
   // selection verbs (req-7) — drive table-core so the onRowSelectionChange funnel
   // emits the fresh state + selection-change.
-  toggleAllRows = (value: any) => {
+  toggleAllRows: (value?: boolean) => void = (value: any) => {
   if (this.table) this.table.toggleAllRowsSelected(value);
 };
 
-  clearSelection = () => {
+  clearSelection: () => void = () => {
   if (this.table) this.table.resetRowSelection(true);
 };
 
-  getSelectedRows = () => this.table ? this.table.getSelectedRowModel().rows.map((r: any) => r.original) : [];
+  getSelectedRows: () => any[] = () => this.table ? this.table.getSelectedRowModel().rows.map((r: any) => r.original) : [];
 
   // pagination verbs.
-  setPage = (idx: any) => {
+  setPage: (idx: number) => void = (idx: any) => {
   if (this.table) this.table.setPageIndex(idx);
 };
 
-  setRowsPerPage = (size: any) => {
+  setRowsPerPage: (size: number) => void = (size: any) => {
   if (this.table) this.table.setPageSize(size);
 };
 
   // column-management verbs (req-8/9/10/11) — drive table-core so the funnels fire.
-  toggleColumnVisibility = (colId: any) => {
+  toggleColumnVisibility: (colId: string) => void = (colId: any) => {
   if (this.table) {
     const c = this.table.getColumn(colId);
     if (c && c.toggleVisibility) c.toggleVisibility();
@@ -5070,17 +5131,17 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // off-limits). So the public verb is `applyColumnOrder` (semantically: apply a
   // new column order). The other set* verbs (setPage/setRowsPerPage) do NOT match
   // any model prop's setter, so they are collision-free.
-  applyColumnOrder = (order: any) => {
+  applyColumnOrder: (order: string[]) => void = (order: any) => {
   if (this.table) this.table.setColumnOrder(order);
 };
 
-  resetColumnSizing = () => {
+  resetColumnSizing: () => void = () => {
   if (this.table) this.table.resetColumnSizing(true);
 };
 
   // pinColumn: the verb that drives column.pin; distinct from the template handler
   // onPinColumn (no shadow — the deferred-items finding #4 collision check).
-  pinColumn = (colId: any, side: any) => {
+  pinColumn: (colId: string, side: 'left' | 'right' | false) => void = (colId: any, side: any) => {
   if (this.table) {
     const c = this.table.getColumn(colId);
     if (c && c.pin) c.pin(side);
@@ -5094,7 +5155,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // there is no page (windowing replaces pagination) → the windowed model IS the full model, so it
   // returns the absolute index unchanged. Collision-safe: no *-change event, prop, React auto-setter,
   // or inherited Lit DOM method named getRowIndexRelativeToPage (ROZ121/124/137 clear).
-  getRowIndexRelativeToPage = (absRow: any) => {
+  getRowIndexRelativeToPage: (absRow?: number) => number = (absRow: any) => {
   const abs = absRow == null ? this.toAbsRow(this._activeRow.value) : Math.trunc(Number(absRow)) || 0;
   if (this.rowsWindowed()) return abs;
   return abs - this.pageRowOffset();
@@ -5106,7 +5167,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // active cell, so it cuts the current selection even when the call arrives off a control that
   // moved DOM focus off the grid. Collision-safe: no `cut` event / model prop / React auto-setter /
   // inherited Lit DOM method named `cut` (ROZ121/124/137 clear) — `cut` is not on HTMLElement.
-  cut = () => this.cutRange();
+  cut: () => void = () => this.cutRange();
 
   // 260709-8ct (grid-wide undo/redo): NO pass-through wrapper lands here for
   // undo/redo/canUndo/canRedo/clearHistory. Unlike `cut` above (which delegates to a
@@ -5174,9 +5235,6 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // page-relative active row → absolute (display-order) index.
   toAbsRow = (localRow: any) => localRow + this.pageRowOffset();
 
-  // A body row's ABSOLUTE display-order index = its page-relative index + the page offset. Drives
-  // aria-rowindex on the non-virtual paginated body (B27); the virtual path uses wr.vi.index
-  // directly (already absolute). Reactive via rowIndexOf's tick().
   // Total filtered+sorted PRE-pagination row count — the clamp bound for an absolute focusCell.
   // In virtual mode $data.rows IS the full pre-pagination model (bodyRowCount suffices); in the
   // non-virtual paginated body $data.rows is only the page slice, so read the live model.
@@ -6117,7 +6175,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
     // SAME language): a header cell has no body-row index, so emit rowIndex:null + isHeader:true
     // rather than a bogus toAbsRow(nextRow) — which would compute a real body-row absolute index
     // for a HEADER move, misleading a consumer into thinking that body row is the active cell.
-    this.dispatchEvent(new CustomEvent("activecell-change", {
+    this.dispatchEvent(new CustomEvent<DataTableActiveCellChangePayload>("activecell-change", {
       detail: nextIsHeader ? {
         rowIndex: null,
         colIndex: nextCol,
@@ -6327,7 +6385,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   activateRowAt = (index: any, trigger: any) => {
   const row = (this._rows.value || [])[index];
   if (!row || this.rowIsGrouped(row) || this.rowIsLazyPlaceholder(row)) return;
-  this.dispatchEvent(new CustomEvent("row-activate", {
+  this.dispatchEvent(new CustomEvent<DataTableRowActivatePayload>("row-activate", {
     detail: {
       row: row.original,
       index,
@@ -6734,7 +6792,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // { rowIndex, colIndex } pair (or null when no range). T-49-02: positions only, no row
   // data, no DOM node. Used by the getSelectedRange $expose verb AND every range-change emit
   // (the single payload source) AND copyRange/fillRange (the rectangle they operate over).
-  getSelectedRange = () => {
+  getSelectedRange: () => DataTableRange = () => {
   // B8: clamp the corners to the CURRENT bounds ON READ so the verb (and the range-change emit
   // payload) never reports a corner past a shrunken model — React-stale-safe (the eager
   // refreshRowModel clamp is async-defeated on React; this read-time clamp is the guarantee).
@@ -6799,7 +6857,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
 
   emitRangeChange = (anchor: any, focus: any) => {
   this._rangeAnnounce.value = this.rangeSummary(anchor, focus);
-  this.dispatchEvent(new CustomEvent("range-change", {
+  this.dispatchEvent(new CustomEvent<DataTableRangeChangePayload>("range-change", {
     detail: {
       anchor,
       focus
@@ -7242,7 +7300,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
     // is the first-party code that actually escapes.
     for (let i = 0; i < committed.length; i++) {
       try {
-        this.dispatchEvent(new CustomEvent("cell-edit-commit", {
+        this.dispatchEvent(new CustomEvent<DataTableCellEditCommitPayload>("cell-edit-commit", {
           detail: committed[i],
           bubbles: true,
           composed: true
@@ -8241,7 +8299,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
     const next = replaceRowValue(this.currentData(), srcIndex, field, newValue);
     this.writeData(next);
     // Exactly one emit per commit, from this single call site (writeData does NOT emit).
-    this.dispatchEvent(new CustomEvent("cell-edit-commit", {
+    this.dispatchEvent(new CustomEvent<DataTableCellEditCommitPayload>("cell-edit-commit", {
       detail: {
         rowId,
         columnId: colId,
@@ -8326,7 +8384,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   this.writeData(replaceRowValue(this.currentData(), srcIndex, field, newValue));
   // Exactly one emit per toggle, from this single call site (writeData does NOT emit) —
   // mirrors commitEdit's D-07 single-emit discipline.
-  this.dispatchEvent(new CustomEvent("cell-edit-commit", {
+  this.dispatchEvent(new CustomEvent<DataTableCellEditCommitPayload>("cell-edit-commit", {
     detail: {
       rowId,
       columnId: colId,
@@ -8562,7 +8620,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
     const next = replaceRowValues(this.currentData(), srcIndex, fieldValues);
     this.writeData(next);
     // EXACTLY ONE emit per row commit, from THIS single call site (React multi-emit dedup, D-07).
-    this.dispatchEvent(new CustomEvent("row-edit-commit", {
+    this.dispatchEvent(new CustomEvent<DataTableRowEditCommitPayload>("row-edit-commit", {
       detail: {
         rowId,
         changes
@@ -9107,7 +9165,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // editCell(rowIndex, colIndex) — programmatic edit-entry ($expose, req-3). Coerces +
   // clamps indices, moves the active cell, and opens the editor (no-op on a non-editable
   // cell). Collision-clean (RESEARCH name-check): not a verb/event/prop/ROZ137 member.
-  editCell = (rowIndex: any, colIndex: any) => {
+  editCell: (rowIndex: number, colIndex: number) => void = (rowIndex: any, colIndex: any) => {
   const lastRow = this.bodyRowCount() - 1;
   const maxRow = lastRow < 0 ? 0 : lastRow;
   const maxCol = this.visibleColCount() - 1;
@@ -9126,7 +9184,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // edit (editRow()/Shift+F2) drives editingRowIndex and leaves editingRow at -1, so the
   // single-cell commitEdit guard (editingRow >= 0) is false during a row edit — route to
   // commitRow() first so a programmatic commit of a row editor is not a silent no-op.
-  commitEditing = () => {
+  commitEditing: () => void = () => {
   if (this.inRowEdit()) {
     this.commitRow();
     return;
@@ -9140,7 +9198,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // name-check): `editRow` is not in the 15 existing verbs, not a prop, not a *-change/commit
   // event, not a Lit ROZ137-reserved host member. Moves the active cell to the row first so the
   // commit/cancel focus-return lands in the right row.
-  editRow = (rowIndex: any) => {
+  editRow: (rowIndex: number) => void = (rowIndex: any) => {
   const lastRow = this.bodyRowCount() - 1;
   const maxRow = lastRow < 0 ? 0 : lastRow;
   const r = clamp(Math.trunc(Number(rowIndex)) || 0, 0, maxRow);
@@ -9203,7 +9261,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // data-* selector is built (T-49-01/T-63-06-01: never interpolate a raw consumer string; clamp
   // the abs index into getPrePaginationRowModel bounds). The activecell-change payload + getActiveCell
   // speak the SAME absolute language (toAbsRow).
-  focusCell = (rowIndex: any, colIndex: any) => {
+  focusCell: (rowIndex: number, colIndex: number) => void = (rowIndex: any, colIndex: any) => {
   // B16: isGrid()-gate the verb. In 'table' mode there is no roving active cell, so focusCell
   // is a NO-OP (never an activecell-change emit) — the keyboard path (onGridKeyDown) is already
   // isGrid-gated; the exposed verb must mirror that so a consumer's focusCell on a table-mode
@@ -9267,7 +9325,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
     }
   }
   if (absRow !== prevAbs || c !== prevCol || prevIsHeader) {
-    this.dispatchEvent(new CustomEvent("activecell-change", {
+    this.dispatchEvent(new CustomEvent<DataTableActiveCellChangePayload>("activecell-change", {
       detail: {
         rowIndex: absRow,
         colIndex: c
@@ -9287,7 +9345,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // is unchanged for the body case).
   // C1: a body cell returns the ABSOLUTE display-order rowIndex (toAbsRow) — matching focusCell's
   // addressing + the activecell-change payload — in BOTH paginated and virtual modes.
-  getActiveCell = () => this._activeIsHeader.value ? {
+  getActiveCell: () => DataTableActiveCell = () => this._activeIsHeader.value ? {
   rowIndex: null,
   colIndex: this._activeColIndex.value,
   isHeader: true
@@ -9301,7 +9359,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // exit interaction mode; the next Tab-in re-enters at the entry cell (D-01). Does NOT emit
   // (no move to a new addressable cell — a reset, not a navigation). B16: isGrid()-gated — a
   // table-mode instance has no roving active cell, so the verb is a no-op there.
-  clearActiveCell = () => {
+  clearActiveCell: () => void = () => {
   if (!this.isGrid()) return;
   this._activeIsHeader.value = false;
   this._activeInControl.value = false;
@@ -9318,7 +9376,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // toggleRowExpanded(rowId) — toggle ONE row's expanded state, addressed by the consumer's
   // row id (the data `id` field) OR the table-core row id. Scans the core flat-row set (all
   // rows regardless of current expansion) so a collapsed parent is still resolvable.
-  toggleRowExpanded = (rowId: any) => {
+  toggleRowExpanded: (rowId: string | number) => void = (rowId: any) => {
   if (!this.table) return;
   const target = String(rowId);
   const flat = this.table.getCoreRowModel().flatRows;
@@ -9332,14 +9390,14 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
 
   // expandAll() — open every expandable row (table-core sets ExpandedState to the `true`
   // literal under the hood → Pitfall 2: writeExpanded passes it through verbatim).
-  expandAll = () => {
+  expandAll: () => void = () => {
   if (!this.table) return;
   this.table.toggleAllRowsExpanded(true);
 };
 
   // collapseAll() — reset to a blank expanded state ({}). resetExpanded(true) forces the
   // blank reset (NOT the initialState) and fires onExpandedChange → one expanded-change.
-  collapseAll = () => {
+  collapseAll: () => void = () => {
   if (!this.table) return;
   this.table.resetExpanded(true);
 };
@@ -9347,7 +9405,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // getExpandedRows() — return the original row data for every currently-expanded row
   // (read-verb twin of expanded-change). Integers/data only — scans the core flat rows and
   // filters by getIsExpanded(). Empty when nothing is expanded.
-  getExpandedRows = () => {
+  getExpandedRows: () => any[] = () => {
   if (!this.table) return [];
   const out = [];
   const flat = this.table.getCoreRowModel().flatRows;
@@ -9362,11 +9420,11 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // setColumnOrder→applyColumnOrder) + clearGrouping. Both drive @tanstack/table-core's
   // table.setGrouping so the onGroupingChange → writeGrouping funnel fires one group-change with
   // the fresh ordered key list. Also handed to the headless #groupBar slot as apply/clear helpers.
-  applyGrouping = (cols: any) => {
+  applyGrouping: (cols: string[]) => void = (cols: any) => {
   if (this.table) this.table.setGrouping(cols);
 };
 
-  clearGrouping = () => {
+  clearGrouping: () => void = () => {
   if (this.table) this.table.setGrouping([]);
 };
 
@@ -9384,7 +9442,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   // column/table. NAMED to match the $expose verb exactly (the ExposedMethod.name shorthand
   // contract: an exposed verb lowers to `{ getFacetedUniqueValues }`, which must resolve to THIS
   // helper — the table-core factory was aliased to makeFacetedUniqueValues to free this name).
-  getFacetedUniqueValues = (colId: any) => {
+  getFacetedUniqueValues: (colId: string) => any[] = (colId: any) => {
   if (this.tick() < 0 || !this.table) return [];
   const col = this.table.getColumn(colId);
   if (!col || !col.getFacetedUniqueValues) return [];
@@ -9394,7 +9452,7 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
 
   // getFacetedMinMaxValues: the column's [min, max] numeric range, or null when unavailable.
   // Named to match the $expose verb (same shorthand contract as getFacetedUniqueValues above).
-  getFacetedMinMaxValues = (colId: any) => {
+  getFacetedMinMaxValues: (colId: string) => [number, number] | null = (colId: any) => {
   if (this.tick() < 0 || !this.table) return null;
   const col = this.table.getColumn(colId);
   if (!col || !col.getFacetedMinMaxValues) return null;
@@ -9425,4 +9483,15 @@ ${this.groupable ? html`<div class="rdt-group-bar-host" data-rozie-s-d5dcab4c>
   set columnOrder(v: any[]) { this._columnOrderControllable.notifyPropertyWrite(v); }
   get columnPinning(): any { return this._columnPinningControllable.read(); }
   set columnPinning(v: any) { this._columnPinningControllable.notifyPropertyWrite(v); }
+
+  addEventListener<K extends keyof RozieDataTableEventMap>(type: K, listener: (this: DataTable, ev: RozieDataTableEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void {
+    super.addEventListener(type, listener, options);
+  }
+  removeEventListener<K extends keyof RozieDataTableEventMap>(type: K, listener: (this: DataTable, ev: RozieDataTableEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+  removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+  removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void {
+    super.removeEventListener(type, listener, options);
+  }
 }