persian-data-grid 0.5.0 → 0.6.0

package/dist/GridSession-B-9lLcoB.d.cts

@@ -0,0 +1,2492 @@
+import { R as RemoteApi, A as AuditLogger, C as ConsoleAuditLogger } from './RemoteApi-CCQxiSf1.cjs';
+import * as React from 'react';
+
+/**
+ * Pure cell-range selection model (PR-104).
+ * No React/DOM — keyboard/UI wiring lands in PR-105+.
+ */
+type CellAddress = {
+    /** 0-based index in the visible/sorted row list. */
+    rowIndex: number;
+    colId: string;
+};
+/** Inclusive rectangular range in UI row/column space. */
+type CellRange = {
+    startRow: number;
+    endRow: number;
+    /** Column ids in document order (inclusive span). */
+    colIds: readonly string[];
+};
+type CellRangeSelection = {
+    ranges: readonly CellRange[];
+    anchor: CellAddress | null;
+    focus: CellAddress | null;
+};
+type CellRangeBounds = {
+    rowCount: number;
+    /** Visible/selectable columns in document order. */
+    columnOrder: readonly string[];
+};
+type ArrowDirection = 'up' | 'down' | 'left' | 'right';
+declare function createEmptyCellRangeSelection(): CellRangeSelection;
+declare function colIndex(colId: string, columnOrder: readonly string[]): number;
+declare function clampRowIndex(rowIndex: number, rowCount: number): number;
+declare function clampColIndex(colIndex: number, colCount: number): number;
+/**
+ * Clamp rows/columns to bounds and sort `colIds` by `columnOrder`.
+ */
+declare function normalizeCellRange(range: CellRange, bounds: CellRangeBounds): CellRange;
+declare function rangeFromAnchorFocus(anchor: CellAddress, focus: CellAddress, bounds: CellRangeBounds): CellRange;
+declare function isCellInRange(cell: CellAddress, range: CellRange): boolean;
+declare function rangesOverlap(a: CellRange, b: CellRange): boolean;
+/**
+ * Merge overlapping/adjacent rectangles into a minimal set.
+ */
+declare function mergeCellRanges(ranges: readonly CellRange[], columnOrder: readonly string[]): CellRange[];
+declare function moveCellAddress(cell: CellAddress, direction: ArrowDirection, bounds: CellRangeBounds): CellAddress;
+/** Plain click — single 1×1 range. */
+declare function clickCell(selection: CellRangeSelection, cell: CellAddress, bounds: CellRangeBounds): CellRangeSelection;
+/** Shift+Click — extend from anchor to clicked cell (replace primary range). */
+declare function shiftClickCell(selection: CellRangeSelection, cell: CellAddress, bounds: CellRangeBounds): CellRangeSelection;
+/** Ctrl+Click — add a new 1×1 range; anchor/focus move to the new cell. */
+declare function ctrlClickCell(selection: CellRangeSelection, cell: CellAddress, bounds: CellRangeBounds): CellRangeSelection;
+/** Shift+Arrow — extend primary range from anchor to moved focus. */
+declare function shiftArrowCell(selection: CellRangeSelection, direction: ArrowDirection, bounds: CellRangeBounds): CellRangeSelection;
+/** Ctrl+A — one range over the full grid body. */
+declare function selectAllCellRanges(bounds: CellRangeBounds): CellRangeSelection;
+
+type Actor$1 = {
+    userId: string;
+    roles: string[];
+};
+interface PermissionPolicy {
+    canChangeCell(input: {
+        actor: Actor$1;
+        rowId: number;
+        columnId: string;
+    }): boolean;
+    canEdit?: (input: {
+        actor: Actor$1;
+        rowId: number;
+        columnId: string;
+    }) => boolean;
+    canAddRow?: (input: {
+        actor: Actor$1;
+    }) => boolean;
+    canCopyRow?: (input: {
+        actor: Actor$1;
+        rowId: number;
+    }) => boolean;
+    canDeleteRow?: (input: {
+        actor: Actor$1;
+        rowId: number;
+    }) => boolean;
+    canReorderRow?: (input: {
+        actor: Actor$1;
+        rowId: number;
+    }) => boolean;
+    canReorderColumn?: (input: {
+        actor: Actor$1;
+    }) => boolean;
+}
+
+/**
+ * View-state value object for virtual scrolling.
+ * Lives in Domain types but is NOT an accounting invariant — Adapters drive it.
+ */
+declare class Viewport {
+    /** Vertical scroll offset in pixels. */
+    readonly scrollOffset: number;
+    /** Visible viewport height in pixels. */
+    readonly viewportSize: number;
+    /** Fixed row height in pixels (variable-height later). */
+    readonly rowHeight: number;
+    /** Extra rows rendered above/below the window. */
+    readonly overscan: number;
+    constructor(
+    /** Vertical scroll offset in pixels. */
+    scrollOffset: number, 
+    /** Visible viewport height in pixels. */
+    viewportSize: number, 
+    /** Fixed row height in pixels (variable-height later). */
+    rowHeight: number, 
+    /** Extra rows rendered above/below the window. */
+    overscan?: number);
+    equals(other: Viewport): boolean;
+    withScrollOffset(scrollOffset: number): Viewport;
+    withViewportSize(viewportSize: number): Viewport;
+    toJSON(): {
+        scrollOffset: number;
+        viewportSize: number;
+        rowHeight: number;
+        overscan: number;
+    };
+}
+/** Inclusive start, exclusive end — indices into the ordered row list. */
+type VisibleRange = {
+    readonly startIndex: number;
+    readonly endIndex: number;
+    readonly startOffset: number;
+    readonly endOffset: number;
+    readonly totalHeight: number;
+    readonly visibleCount: number;
+};
+
+declare class CellValue {
+    readonly value: unknown;
+    constructor(value: unknown);
+    equals(other: CellValue): boolean;
+}
+declare class CellDisplay {
+    readonly value: unknown;
+    constructor(value: unknown);
+    equals(other: CellDisplay): boolean;
+}
+declare class ColumnId {
+    readonly value: string;
+    private static readonly interned;
+    constructor(value: string);
+    /** Shared instance per field name (PR-101) — avoids 100k×cols ColumnId objects. */
+    static for(value: string): ColumnId;
+    equals(other: ColumnId): boolean;
+}
+type KeyValue = {
+    key: string;
+    value: unknown;
+    display: unknown;
+};
+type IRule = {
+    type?: string | "array" | "object" | "enum" | "date" | "number" | "integer" | "float" | "boolean" | "email" | "url" | "hex" | RegExp;
+    required?: boolean;
+    requiredIf?: () => boolean;
+    whitespace?: boolean;
+    message?: string;
+    transform?: (value: unknown) => unknown;
+    pattern?: string | RegExp;
+    min?: number;
+    max?: number;
+    len?: number;
+    enum?: unknown[];
+    validator?: (rule: IRule, value: unknown, callback: (error?: string[]) => void) => void | Promise<void>;
+    asyncValidator?: (rule: IRule, value: unknown) => Promise<void>;
+    warningOnly?: boolean;
+    validateTrigger?: string | string[];
+};
+declare class RowId {
+    value: number;
+    constructor(value: number);
+    equals(other: RowId): boolean;
+    set(id: RowId): void;
+}
+declare class RowState {
+    value: RowStateEnum;
+    constructor(value: RowStateEnum);
+    equals(other: RowStateEnum): boolean;
+    set(rowState: RowStateEnum): void;
+}
+declare enum RowStateEnum {
+    Added = "Add",
+    Modified = "Update",
+    Deleted = "Delete",
+    Unchanged = "None"
+}
+type TableActions = "copy" | "cut" | "paste" | "pasteInsert" | null;
+
+declare class Pagination {
+    readonly page: number;
+    readonly pageSize: number;
+    readonly totalRows: number;
+    readonly totalPages: number;
+    readonly canPrev: boolean;
+    readonly canNext: boolean;
+    constructor(page: number, pageSize: number, totalRows: number);
+    changePage(page: number): Pagination;
+    changePageSize(size: number): Pagination;
+    toJSON(): {
+        page: number;
+        pageSize: number;
+        totalRows: number;
+        totalPages: number;
+        canPrev: boolean;
+        canNext: boolean;
+    };
+}
+
+declare class CellChanged {
+    readonly rowId: RowId;
+    readonly columnId: ColumnId;
+    readonly newValue: unknown;
+    readonly previousValue: unknown;
+    readonly type = "CELL_CHANGED";
+    constructor(rowId: RowId, columnId: ColumnId, newValue: unknown, previousValue: unknown);
+}
+declare class DisplayChanged {
+    readonly rowId: RowId;
+    readonly columnId: ColumnId;
+    readonly newValue: unknown;
+    readonly type = "DISPLAY_CHANGED";
+    constructor(rowId: RowId, columnId: ColumnId, newValue: unknown);
+}
+declare class DescriptionSaved {
+    readonly rowId: RowId;
+    readonly flag: boolean;
+    readonly type = "DESCRIPTION_SAVED";
+    constructor(rowId: RowId, flag: boolean);
+}
+declare class ColumnReordered {
+    readonly sourceIndex: number;
+    readonly destIndex: number;
+    readonly type = "COLUMN_REORDERED";
+    constructor(sourceIndex: number, destIndex: number);
+}
+declare class RowAdded {
+    readonly rowId: RowId;
+    readonly type = "ROW_ADDED";
+    constructor(rowId: RowId);
+}
+declare class RowDeleted {
+    readonly rowId: RowId;
+    readonly type = "ROW_DELETED";
+    constructor(rowId: RowId);
+}
+declare class RowRemoved {
+    readonly rowId: RowId;
+    readonly type = "NEW_ROW_REMOVED";
+    constructor(rowId: RowId);
+}
+declare class MinimumRowConstraintViolated {
+    readonly rowId: RowId;
+    readonly type = "NEW_AND_FIRST_ROW_CAN_NOT_BE_REMOVE";
+    constructor(rowId: RowId);
+}
+declare class RowRestored {
+    readonly rowId: RowId;
+    readonly type = "ROW_RESTORED";
+    constructor(rowId: RowId);
+}
+declare class RowReordered {
+    readonly draggedRowNum: number;
+    readonly droppedRowNum: number;
+    readonly type = "ROW_REORDERED";
+    constructor(draggedRowNum: number, droppedRowNum: number);
+}
+
+/**
+ * Domain cell. Stores primitives (PR-101) — `CellValue` / `CellDisplay`
+ * wrappers are allocated only when callers ask for value objects.
+ */
+declare class Cell {
+    readonly rowId: RowId;
+    readonly columnId: ColumnId;
+    private value;
+    private originalValue;
+    private display;
+    constructor(rowId: RowId, columnId: ColumnId, value: unknown, originalValue: unknown, display: unknown);
+    changeValue(newValue: unknown): CellChanged | null;
+    changeDisplay(newValue: unknown): DisplayChanged | null;
+    changeOriginalValue(newValue: unknown): CellChanged | null;
+    getValue(): unknown;
+    getValueObject(): CellValue;
+    getDisplay(): unknown;
+    getDisplayObject(): CellDisplay;
+    getOriginalValue(): CellValue;
+    clone(): Cell;
+}
+
+declare class Row {
+    id: RowId;
+    cells: Map<string, Cell>;
+    rowState: RowState;
+    changeFields: Set<string>;
+    visibilityCondition: Record<string, boolean>;
+    collection: string;
+    isSaveDescription: boolean;
+    /**
+     * Host object for `rowData` (PR-82). Same reference — never deep-cloned —
+     * so `ColumnDef.valueGetter` can read the original `TRow`.
+     */
+    data?: unknown | undefined;
+    /** Stable host id from `getRowId` (string). */
+    sourceId?: string | undefined;
+    constructor(id: RowId, cells: Map<string, Cell>, rowState: RowState, changeFields: Set<string> | undefined, visibilityCondition: Record<string, boolean>, collection: string | undefined, isSaveDescription: boolean, 
+    /**
+     * Host object for `rowData` (PR-82). Same reference — never deep-cloned —
+     * so `ColumnDef.valueGetter` can read the original `TRow`.
+     */
+    data?: unknown | undefined, 
+    /** Stable host id from `getRowId` (string). */
+    sourceId?: string | undefined);
+    updateChangeFields(columnId: ColumnId): void;
+    getCollection(): string;
+    setCollection(collection: string): void;
+    getChangeFields(): readonly string[];
+    getSnapshotChangeFields(): readonly string[];
+    changeCell(columnId: ColumnId, value: unknown): CellChanged | null;
+    saveDescription(flag: boolean): DescriptionSaved;
+    changeDisplay(columnId: ColumnId, value: unknown): DisplayChanged | null;
+    getCells(): ReadonlyMap<string, Cell>;
+    /**
+     * Return a cell without materializing from host `data` (PR-101).
+     */
+    peekCell(columnId: string): Cell | undefined;
+    /**
+     * Lazy host cells (PR-101): when `rowData` left values on `data`, materialize
+     * a Cell on first read and cache it.
+     */
+    getCell(columnId: string): Cell | undefined;
+    /**
+     * Read a cell value without allocating a Cell when the host object still
+     * holds the canonical value (PR-101 hot path for sort/filter/quick filter).
+     */
+    readValue(columnId: string): unknown;
+    readDisplay(columnId: string): unknown;
+    ensureCell(columnId: ColumnId, defaultValue: CellValue, displayValue: CellDisplay): void;
+    setRowId(rowId: RowId): void;
+    setVisibilityCondition(Condition: Record<string, boolean>): void;
+    getVisibilityCondition(): Record<string, boolean>;
+    removeCell(columnId: ColumnId): void;
+    setData(data: unknown): void;
+    getData(): unknown;
+    clone(): Row;
+}
+
+declare class Collection {
+    name: string;
+    private rows;
+    private columns;
+    constructor(name: string | undefined, rows: Map<number, Row>, columns: Map<string, ColumnSchema>);
+    setCollectionName(name: string): void;
+    getCollectionName(): string;
+    getRows(): Map<number, Row>;
+    setRows(rows: Map<number, Row>): void;
+    getColumns(): Map<string, ColumnSchema>;
+}
+
+type CollectionScope = 'active' | 'all' | string[];
+declare class Table {
+    readonly id: string;
+    private collection;
+    private pagination;
+    private action;
+    private activeCollection;
+    constructor(id: string, collection: Map<string, Collection>, pagination: Pagination, action: TableActions, activeCollection?: string);
+    /**
+     * Page-window mode (persistence 'paged-idb'): the Collection row Maps hold
+     * ONLY the current page; Pagination.totalRows is the source of truth for
+     * totals. In the default mode the Maps hold every row and pagination slices.
+     */
+    private pageWindow;
+    isPageWindow(): boolean;
+    setPageWindow(enabled: boolean): this;
+    private getActiveCollection;
+    private getCollection;
+    /** Finds which Collection currently owns a given column id (if any). */
+    private findCollectionForColumn;
+    getCollections(): Map<string, Collection>;
+    getColumnSchema(columnId: ColumnId): ColumnSchema | undefined;
+    getActiveCollectionName(): string;
+    setActiveCollection(activeCollection: string): void;
+    getRowCollection(rowId: number): string | undefined;
+    setRowCollection(rowId: number, collection: string): void;
+    setColumnSchema(columnId: ColumnId, DetailColumnConfig: ColumnSchema): ColumnSchema | undefined;
+    getColumns(): ColumnSchema[];
+    getActiveCollectionColumns(): ColumnSchema[];
+    getColumnsForCollectionScope(collectionScope?: CollectionScope): ColumnSchema[];
+    getColumnValues(colId: string): unknown[];
+    setColumns(newColumns: ColumnSchema[]): void;
+    changeCell(rowId: RowId, columnId: ColumnId, value: unknown): CellChanged | null;
+    changeDisplay(rowId: RowId, columnId: ColumnId, value: unknown): DisplayChanged | null;
+    saveDescription(rowId: RowId, flag: boolean): DescriptionSaved | null;
+    duplicateRow(rowId: RowId): RowAdded;
+    addRow(targetRowId: number, placedRowId?: number): RowAdded;
+    addNewRow(data?: KeyValue[], nextIndex?: number): RowAdded;
+    addNewRows(cmd: {
+        rows: KeyValue[][];
+        detailFieldKey: string;
+    }): RowAdded[];
+    addColumns(newColumns: ColumnSchema[]): {
+        added: ColumnId[];
+    };
+    setColumnHidden(columnId: string, hidden: boolean): boolean;
+    /** Runtime pin on `columnDef.pinned` (PR-114). Index column is not mutable. */
+    setColumnPinned(columnId: string, pinned: 'start' | 'end' | null): boolean;
+    removeColumns(columnIds: ColumnId[]): {
+        removed: ColumnId[];
+    };
+    getRows(collectionScope?: CollectionScope): Row[];
+    getCollectionsRows(collections: string[]): Row[];
+    getRow(rowId: number): Row | undefined;
+    /** Host `rowData` sync (PR-82) — put without going through add/undo. */
+    hostPutRow(row: Row): void;
+    /** Host `rowData` sync (PR-82) — drop to match the host array. */
+    hostRemoveRow(rowId: number): void;
+    addRows(newRows: Row[]): void;
+    getPagination(): Pagination;
+    setPagination(pagination: Pagination): void;
+    changePage(page: number): void;
+    changePageSize(size: number): void;
+    /**
+     * Rows currently held in RAM for the active collection.
+     * With page-window storage the Collection Map already contains only the
+     * current page — do not slice by pagination offsets.
+     */
+    getVisibleRows(): Row[];
+    setTableAction(action: TableActions): void;
+    getTableAction(): TableActions;
+    /**
+     * Re-inserts a previously Added row after hard-remove (undo of ADD → redo).
+     * Preserves rowId and cell values; no-ops if the id already exists.
+     */
+    restoreAddedRow(params: {
+        rowId: number;
+        cells: Readonly<Record<string, {
+            readonly value: unknown;
+            readonly display?: unknown;
+            readonly originalValue?: unknown;
+        }>>;
+        collection?: string;
+        isSaveDescription?: boolean;
+    }): RowAdded;
+    /**
+     * Delete semantics:
+     * - `Added` → hard-remove from the table (physically gone).
+     * - `Deleted` → restore (قابل برگرداندن).
+     * - otherwise (`Unchanged` / `Modified`) → soft-delete (`rowState = Deleted`).
+     */
+    deleteRow(rowId: RowId): RowDeleted | RowRestored | RowRemoved | MinimumRowConstraintViolated | null;
+    reorderRows(draggedRowNum: number, droppedRowNum: number, position?: 'before' | 'after'): RowReordered;
+    reorderColumns(sourceIndex: number, destIndex: number): ColumnReordered;
+    clone(): Table;
+}
+
+/**
+ * Multi-level column group (PR-113).
+ * Nested groups are supported via `children` containing more groups.
+ */
+interface ColumnGroupDef<TRow = unknown> {
+    groupId?: string;
+    headerName: string;
+    children: readonly ColDefOrGroup<TRow>[];
+    /** When true, hiding one child hides siblings in the same group (AG Grid parity). */
+    marryChildren?: boolean;
+}
+type ColDefOrGroup<TRow = unknown> = ColumnDef<TRow> | ColumnGroupDef<TRow>;
+declare function isColumnGroupDef<TRow>(item: ColDefOrGroup<TRow>): item is ColumnGroupDef<TRow>;
+/** Persisted on leaf `ColumnSchema` for header rendering and group reorder. */
+type ColumnGroupPathEntry = {
+    groupId: string;
+    headerName: string;
+    marryChildren?: boolean;
+};
+type ColumnGroupMeta = {
+    /** Immediate parent group id. */
+    groupId: string;
+    /** Root → parent chain. */
+    path: readonly ColumnGroupPathEntry[];
+};
+
+type FieldType = 'index' | 'text' | 'textArea' | 'number' | 'price' | 'select' | 'selectOption' | 'date' | 'static' | 'description' | 'checkbox';
+type ColumnVisibilityRule = {
+    kind: 'always';
+} | {
+    kind: 'never';
+} | {
+    kind: 'showUnitLevelConditionally';
+    fieldName: string;
+} | {
+    kind: 'whenFieldTruthy';
+    fieldName: string;
+} | {
+    kind: 'whenRemoteFlag';
+    sourceFieldName: string;
+    flag: string;
+} | {
+    kind: 'whenCollection';
+    collection: string;
+} | {
+    kind: 'whenTableType';
+    tableType: string;
+};
+interface ResolveOnConfig<K = unknown, TResponse = unknown> {
+    endpoint: string;
+    fieldName: string;
+    buildParams: (row: Record<string, unknown>) => Record<string, unknown>;
+    getResponse?: (response: TResponse, row: Row) => unknown;
+    mapFlags?: (response: TResponse) => Record<string, boolean>;
+}
+type ColumnAccessControl = {
+    allowRoles?: string[];
+    denyRoles?: string[];
+    rule?: (ctx: {
+        actor: Actor$1;
+        row: Row;
+        table: Table;
+    }) => boolean;
+};
+interface IDependOn {
+    fieldName: string;
+    value: unknown;
+}
+type DefaultOptionType = {
+    value?: string | number;
+    label?: string;
+    title?: string;
+    [key: string]: unknown;
+};
+interface ColumnSchema<T = unknown, K = unknown> {
+    fieldName: string;
+    fieldCaption: string;
+    fieldType: FieldType;
+    fieldCollection?: string;
+    order?: number;
+    rules?: IRule[];
+    options?: DefaultOptionType[];
+    editable?: boolean;
+    isUnique?: boolean;
+    noCache?: boolean;
+    expandable?: boolean;
+    returnValue?: (values: T, colId: string) => unknown;
+    returnDisplayValue?: (values: T, colId: string) => unknown;
+    /**
+     * Custom cell renderer (PR-54). `CellRenderer` calls this before the FieldType
+     * switch. Not the same as `returnDisplayValue` (engine display string).
+     */
+    render?: (ctx: unknown) => unknown;
+    enableDeleteButton?: boolean;
+    enableExpandButton?: boolean;
+    enableMoveButton?: boolean;
+    enableOptionsButton?: boolean;
+    disable?: boolean;
+    colAccess?: ColumnAccessControl;
+    dynamicSource?: {
+        endpoint: string;
+        dependsOn?: string[];
+        dependOn?: IDependOn | IDependOn[];
+        params?: Record<string, string>;
+        [key: string]: unknown;
+    };
+    hidden?: boolean;
+    className?: string;
+    visibility: ColumnVisibilityRule;
+    resolveOn?: ResolveOnConfig<K>;
+    computed?: {
+        dependsOn: readonly string[];
+        compute: (row: Record<string, unknown>, remoteApi: RemoteApi) => Promise<unknown>;
+        children?: [] | undefined;
+    };
+    selectOptions?: {
+        label: string;
+        value: string | number;
+    }[];
+    indexOptions?: (...args: unknown[]) => unknown[];
+    onChange?: (...args: unknown[]) => void;
+    displayFormat?: (value: unknown) => unknown;
+    minWidth?: number;
+    style?: Record<string, string | number>;
+    popUpWidth?: number;
+    dynamicSelectFilterOption?: (inputValue: string, option: unknown) => boolean;
+    labelValue?: 'selectDisplay' | 'selectValue';
+    /**
+     * ColumnDef-only fields restored by `toColumnDef` (PR-81).
+     * ERP hosts can ignore this.
+     */
+    columnDef?: ColumnDefBridge;
+    /** Leaf column group ancestry (PR-113). */
+    columnGroup?: ColumnGroupMeta;
+}
+
+/**
+ * Filter descriptor on `ColumnDef`. Consumed in Phase 18 (PR-92+).
+ * Built-in names, a custom registry key (PR-95), or `{ type, params }`.
+ */
+type FilterDef = 'text' | 'number' | 'date' | 'set' | (string & {}) | {
+    type: string;
+    params?: Record<string, unknown>;
+};
+type ColumnPinned = 'start' | 'end' | null;
+/** Built-in footer / group aggregates (PR-118 / RFC-002). */
+type AggFuncName = 'sum' | 'avg' | 'min' | 'max' | 'count' | 'first' | 'last';
+type AggFunc<TValue = unknown> = AggFuncName | ((values: readonly TValue[]) => unknown);
+/**
+ * `field` is an unconstrained string until `TRow` is specified; then it is a key of `TRow`.
+ * `keyof unknown` is `never`, so untyped `ColumnDef[]` stays usable (PR-88).
+ */
+type ColumnField<TRow> = keyof TRow extends never ? string : Extract<keyof TRow, string>;
+/**
+ * Cell renderer slot on `ColumnDef`. Same runtime as `ColumnSchema.render`.
+ * UI `CellComponent` is the React-side shape — domain does not import React (PR-81).
+ */
+type ColumnCellRenderer = (ctx: unknown) => unknown;
+/**
+ * Public, generic column definition (PR-81 / D14).
+ * `ColumnSchema` remains the ERP host / domain persistence shape; use
+ * `toColumnSchema` / `toColumnDef` in `infrastructure/columns/` to convert.
+ */
+interface ColumnDef<TRow = unknown, TValue = unknown> {
+    colId?: string;
+    field?: ColumnField<TRow>;
+    headerName?: string;
+    type?: FieldType;
+    valueGetter?: (p: {
+        data: TRow;
+    }) => TValue;
+    valueSetter?: (p: {
+        data: TRow;
+        newValue: TValue;
+    }) => boolean;
+    valueFormatter?: (p: {
+        value: TValue;
+        data: TRow;
+    }) => string;
+    /** Consumed in Phase 18 (PR-89). */
+    comparator?: (a: TValue, b: TValue) => number;
+    editable?: boolean | ((p: {
+        data: TRow;
+    }) => boolean);
+    width?: number;
+    minWidth?: number;
+    flex?: number;
+    hide?: boolean;
+    pinned?: ColumnPinned;
+    sortable?: boolean;
+    filter?: FilterDef | false;
+    cellRenderer?: ColumnCellRenderer;
+    /**
+     * Footer / group aggregate (PR-118 / RFC-002).
+     * Built-ins are incremental; money uses integer minor units.
+     */
+    aggFunc?: AggFunc<TValue>;
+    /**
+     * Display unit for `type: 'price'` (PR-140).
+     * Stored values remain integer **rials**; `toman` only affects default formatting
+     * (÷10). Prefer `valueFormatter` / `valueGetter` for edit UX in تومان.
+     */
+    currencyUnit?: 'rial' | 'toman';
+    /**
+     * Source `ColumnSchema` when this def was produced by `toColumnDef`.
+     * `toColumnSchema` copies ERP-only fields (visibility, resolveOn, …) from it.
+     */
+    columnSchema?: ColumnSchema;
+    /** Stamped by `flattenColDefOrGroup` before `toColumnSchema` (PR-113). */
+    columnGroup?: ColumnGroupMeta;
+}
+/**
+ * ColumnDef fields that have no native `ColumnSchema` equivalent.
+ * Stashed on `ColumnSchema.columnDef` so the mapper round-trips.
+ */
+interface ColumnDefBridge {
+    field?: string;
+    colId?: string;
+    valueGetter?: (p: {
+        data: unknown;
+    }) => unknown;
+    valueSetter?: (p: {
+        data: unknown;
+        newValue: unknown;
+    }) => boolean;
+    valueFormatter?: (p: {
+        value: unknown;
+        data: unknown;
+    }) => string;
+    comparator?: (a: unknown, b: unknown) => number;
+    editableWhen?: (p: {
+        data: unknown;
+    }) => boolean;
+    width?: number;
+    flex?: number;
+    pinned?: ColumnPinned;
+    sortable?: boolean;
+    filter?: FilterDef | false;
+    aggFunc?: AggFunc;
+    currencyUnit?: 'rial' | 'toman';
+}
+
+/**
+ * Single-level row grouping (PR-120 / RFC-002). Pure — no React/DOM.
+ * Produces a flat presentation list: group nodes + leaf row ids.
+ */
+
+type FlatGroupNode = {
+    kind: 'group';
+    /** Negative sentinel id (not a domain RowId). */
+    id: number;
+    field: string;
+    key: string;
+    childRowIds: readonly number[];
+    aggregates: Record<string, unknown>;
+};
+type FlatLeafNode = {
+    kind: 'leaf';
+    id: number;
+};
+type FlatUiNode = FlatGroupNode | FlatLeafNode;
+
+/**
+ * Column filter model (PR-92). Wired to the row index in PR-94.
+ * Keys are `colId` / field names. Empty model ⇒ all rows pass.
+ */
+type FilterModel = Readonly<Record<string, ColumnFilter>>;
+type FilterJoin = 'AND' | 'OR';
+type TextFilterOp = 'contains' | 'notContains' | 'equals' | 'startsWith' | 'endsWith' | 'blank' | 'notBlank';
+/** Number ops: = ≠ < ≤ > ≥ inRange blank */
+type NumberFilterOp = 'equals' | 'notEqual' | '=' | '≠' | '!=' | 'lessThan' | '<' | 'lessThanOrEqual' | '≤' | '<=' | 'greaterThan' | '>' | 'greaterThanOrEqual' | '≥' | '>=' | 'inRange' | 'blank';
+type DateFilterOp = 'equals' | 'before' | 'after' | 'inRange' | 'blank';
+type SetFilterOp = 'in' | 'notIn';
+type BooleanFilterOp = 'true' | 'false' | 'any';
+type TextColumnFilter = {
+    filterType: 'text';
+    type: TextFilterOp;
+    filter?: string | number | null;
+};
+type NumberColumnFilter = {
+    filterType: 'number';
+    type: NumberFilterOp;
+    filter?: number | string | null;
+    filterTo?: number | string | null;
+};
+type DateColumnFilter = {
+    filterType: 'date';
+    type: DateFilterOp;
+    /** Inclusive lower / equals bound (Date, epoch ms, or date string). */
+    dateFrom?: unknown;
+    dateTo?: unknown;
+    filter?: unknown;
+    filterTo?: unknown;
+};
+type SetColumnFilter = {
+    filterType: 'set';
+    type?: SetFilterOp;
+    values: readonly unknown[];
+};
+type BooleanColumnFilter = {
+    filterType: 'boolean';
+    type: BooleanFilterOp;
+};
+/**
+ * Host / ColumnDef custom predicate. `rowId` is the engine row id;
+ * hosts that need the row object look it up themselves.
+ */
+type CustomFilterFn = (value: unknown, rowId: number) => boolean;
+type CustomColumnFilter = {
+    filterType: 'custom';
+    /** Registry key when applied from a FilterComponent (PR-95). */
+    type?: string;
+    params?: Record<string, unknown>;
+    customFilter: CustomFilterFn;
+};
+type SimpleColumnFilter = TextColumnFilter | NumberColumnFilter | DateColumnFilter | SetColumnFilter | BooleanColumnFilter | CustomColumnFilter;
+/** AND / OR of simple conditions on one column (PR-92). */
+type CombinedColumnFilter = {
+    operator: FilterJoin;
+    conditions: readonly SimpleColumnFilter[];
+};
+type ColumnFilter = SimpleColumnFilter | CombinedColumnFilter;
+type FilterAccessor = {
+    getValue: (rowId: number, colId: string) => unknown;
+    /**
+     * Optional per-column custom filter when the model uses
+     * `{ filterType: 'custom' }` without an inline `customFilter`.
+     */
+    getCustomFilter?: (colId: string) => CustomFilterFn | undefined;
+};
+/** Digits + Arabic ي/ك → Latin digits + Persian ی/ک for text compare. */
+declare function normalizeFilterText(value: string): string;
+/**
+ * Unique display values for a set-filter menu (PR-92 helper; UI in PR-94).
+ * Order is first-seen in `rowIds`.
+ */
+declare function collectUniqueFilterValues(rowIds: readonly number[], colId: string, accessor: FilterAccessor): unknown[];
+/**
+ * Pure multi-column filter (PR-92). Does not mutate `rowIds`.
+ * Columns in the model are combined with AND. Per-column conditions
+ * may use AND / OR. Empty / invalid model returns a shallow copy.
+ */
+declare function applyFilter(rowIds: readonly number[], filterModel: FilterModel | null | undefined, accessor: FilterAccessor): number[];
+/** True when the column has a non-empty filter entry (PR-94 active indicator). */
+declare function isColumnFilterActive(filterModel: FilterModel | null | undefined, colId: string): boolean;
+type BuiltinFilterKind = 'text' | 'number' | 'date' | 'set' | 'boolean';
+/**
+ * Resolve which built-in filter UI to show for a column (PR-94).
+ * Custom registry filters return `null` — use {@link resolveFilterUi}.
+ */
+declare function resolveBuiltinFilterKind(col: {
+    fieldName: string;
+    fieldType?: string;
+    columnDef?: {
+        filter?: unknown;
+    } | null;
+}): BuiltinFilterKind | null;
+
+/** Document-order column used as the final tie-breaker (PR-89). */
+declare const INDEX_COL_ID = "index";
+type SortDirection = 'asc' | 'desc';
+type SortModelItem = {
+    colId: string;
+    sort: SortDirection;
+};
+type SortModel = readonly SortModelItem[];
+type SortValueComparator = (a: unknown, b: unknown) => number;
+type SortAccessor = {
+    getValue: (rowId: number, colId: string) => unknown;
+    getFieldType?: (colId: string) => FieldType | undefined;
+    getComparator?: (colId: string) => SortValueComparator | undefined;
+};
+declare function normalizeDigits(value: string): string;
+declare function isBlankSortValue(value: unknown): boolean;
+/**
+ * Ascending compare for a FieldType. Blank handling is done by `compareSortValues`.
+ */
+declare function compareTypedValues(a: unknown, b: unknown, fieldType: FieldType | undefined): number;
+declare function compareSortValues(a: unknown, b: unknown, fieldType: FieldType | undefined, comparator: SortValueComparator | undefined): number;
+/**
+ * Pure multi-sort (PR-89). Does not mutate `rowIds`.
+ * Null/blank values sort last in both directions. `index` is the last
+ * tie-breaker so document order is preserved when sort keys match.
+ */
+declare function applySort(rowIds: readonly number[], sortModel: SortModel, accessor: SortAccessor): number[];
+/** Max pointer movement (px) that still counts as a header sort click (PR-91). */
+declare const HEADER_SORT_CLICK_MAX_MOVE_PX = 5;
+/**
+ * True when pointer travel is below the drag threshold so a header click
+ * should change sort (not a column reorder gesture).
+ */
+declare function shouldCommitHeaderSortClick(movedPx: number): boolean;
+type CycleSortModelOptions = {
+    /** Shift+Click: keep other columns; otherwise replace with this column. */
+    multi?: boolean;
+};
+/**
+ * Header click cycle (PR-91): none → asc → desc → none.
+ * Without `multi`, the model becomes a single column (or empty).
+ * With `multi`, the column is appended / toggled / removed in place.
+ */
+declare function cycleSortModel(current: SortModel, colId: string, options?: CycleSortModelOptions): SortModel;
+type AriaSortValue = 'ascending' | 'descending' | 'none';
+declare function ariaSortForColumn(sortModel: SortModel, colId: string): AriaSortValue;
+/** 1-based priority for multi-sort badge; undefined when column is unsorted. */
+declare function sortPriorityForColumn(sortModel: SortModel, colId: string): number | undefined;
+/** Index column and `sortable: false` are never header-sortable. */
+declare function isHeaderColumnSortable(col: {
+    fieldName: string;
+    fieldType?: string;
+    columnDef?: {
+        sortable?: boolean;
+    } | null;
+}): boolean;
+
+/**
+ * Row model mode (PR-96).
+ * - `clientSide` — local sort / filter / quick filter.
+ * - `infinite` / `serverSide` — models are for the host datasource; skip local apply*.
+ */
+type RowModelType = 'clientSide' | 'infinite' | 'serverSide';
+declare function isServerRowModel(rowModelType: RowModelType | undefined | null): boolean;
+/** Half-open page window `[startRow, endRow)`. */
+declare function pageWindow(page: number, pageSize: number): {
+    startRow: number;
+    endRow: number;
+};
+
+/**
+ * Session-only cell edit draft (PR-126). Not EventStore.
+ * Typing updates drafts; Commit writes; Cancel discards.
+ */
+type CellEditType = 'cell' | 'fullRow';
+type CellEditValue = {
+    value: unknown;
+    display: unknown;
+};
+type CellEditSession = {
+    rowId: number;
+    /** Focused column while editing. */
+    columnId: string;
+    editType: CellEditType;
+    /** Values at edit start — restored on cancel. */
+    baseline: Readonly<Record<string, CellEditValue>>;
+    /** Working copies. */
+    drafts: Record<string, CellEditValue>;
+};
+type CellEditOptions = {
+    /** Default true — activate cell starts edit. False ⇒ need Enter / double-click / api.startEditingCell. */
+    singleClickEdit: boolean;
+    /** Default true — leaving the grid / clearActiveCell commits the draft. */
+    stopEditingWhenCellsLoseFocus: boolean;
+    /** Default `cell`. `fullRow` edits every editable column on the row. */
+    editType: CellEditType;
+};
+
+/**
+ * Host-agnostic request config shape used by UI multi-select bindings.
+ * Host apps may narrow this to their own IRequestConfig.
+ */
+type IRequestConfig = {
+    endpoint?: string;
+    params?: Record<string, unknown>;
+    method?: 'GET' | 'POST';
+    [key: string]: unknown;
+};
+
+interface UIRow {
+    id: number;
+    cells: Record<string, TCell>;
+    rowState: RowStateEnum;
+    isExpanded: boolean;
+    changeFields: readonly string[];
+    visibilityCondition: Record<string, boolean>;
+    /** Infinite/server placeholder row (PR-103 skeleton). */
+    loading?: boolean;
+    /** Synthetic group row (PR-120). Absent / `'leaf'` = normal data row. */
+    rowKind?: 'group' | 'leaf';
+    groupField?: string;
+    groupKey?: string;
+    groupChildCount?: number;
+    groupExpanded?: boolean;
+}
+type MultiSelectDependOn = {
+    fieldName: string;
+    value: unknown;
+};
+interface IMultiSelectConfig {
+    /**
+     * Resolve `dynamicValue.dependOn` values through the host's
+     * `useDependOn` hook (e.g. header-form fields) instead of the static
+     * values carried by the items.
+     */
+    dependOnFromHost?: boolean;
+    dynamicValue: IRequestConfig & {
+        dependsOn?: string[];
+        dependOn?: MultiSelectDependOn | MultiSelectDependOn[];
+    };
+    fieldKey: string;
+    detailFieldKey: string;
+    onAdd: (rows: Record<string, unknown>[]) => void;
+    ListConfig: {
+        fieldName: string;
+        fieldCaption: string;
+        fieldType: FieldType;
+        hidden?: boolean;
+        returnValue?: (row: Record<string, unknown>, colId: string) => unknown;
+        returnDisplayValue?: (row: Record<string, unknown>, colId: string) => unknown;
+    }[];
+}
+
+type GridSearchMatch = {
+    rowId: number;
+    columnId: string;
+};
+type GridSearchState = {
+    columnId: string;
+    query: string;
+    matches: GridSearchMatch[];
+    currentIndex: number;
+} | null;
+type MobileEditorState = {
+    mode: 'add' | 'edit';
+    rowId: number;
+} | null;
+type TableViewState = {
+    activeCell: ActiveCell;
+    selectedRows: Record<number, true>;
+    rows: UIRow[];
+    deletedRows: Array<{
+        id: string;
+        cells: Record<string, unknown>;
+        isExpanded: boolean;
+    }>;
+    columns: ColumnSchema[];
+    activeCollectionColumn: ColumnSchema[];
+    pagination: {
+        page: number;
+        pageSize: number;
+        totalRows: number;
+        totalPages: number;
+        canPrev: boolean;
+        canNext: boolean;
+    };
+    action: TableActions;
+    gridSearch: GridSearchState;
+    mobileEditor: MobileEditorState;
+    /** Session-only column widths (px). Not EventStore. */
+    columnWidths: Record<string, number>;
+    /** Session-only sort (PR-90). Empty ⇒ document `index` order. Not EventStore. */
+    sortModel: SortModel;
+    /**
+     * Session-only quick filter (PR-93). Hides non-matching rows (unlike
+     * `gridSearch` find-and-navigate). Not EventStore.
+     */
+    quickFilterText: string;
+    /** Session-only column filters (PR-94). Not EventStore. */
+    filterModel: FilterModel;
+    /** Cell-range selection (PR-105). Session-only. */
+    cellRanges: readonly CellRange[];
+    /** Collapsed column group ids (PR-113). */
+    collapsedColumnGroups: Record<string, true>;
+    /** Active row-group columns (PR-120). */
+    rowGroupColumns: string[];
+    groupDefaultExpanded: boolean;
+    /** Session-only cell edit draft (PR-126). */
+    cellEdit: CellEditSession | null;
+};
+type MobileTableViewState = {
+    rows: UIRow[];
+    columns: ColumnSchema[];
+    totalRows: number;
+    visibleCount: number;
+    hasMore: boolean;
+    pageSize: number;
+    mobileEditor: MobileEditorState;
+};
+type TableSnapShot = {
+    rows: Array<{
+        id: number;
+        cells: Record<string, unknown>;
+        rowState: RowStateEnum;
+        collection: string;
+        rowType?: string;
+        changeFields: readonly string[];
+        isSaveDescription: boolean;
+    }>;
+};
+type ActiveCell = {
+    rowId: number;
+    columnId: string;
+} | null;
+type ValidCell = {
+    isValid: boolean;
+    cellError: CellError;
+};
+type TableState = {
+    table: Table;
+    expandedRows: Record<string, boolean>;
+    selectedRows: Record<number, true>;
+    activeRowId: number | undefined;
+    activeCell: ActiveCell | undefined;
+    rangeAnchorRowId: number | undefined;
+    gridSearch: GridSearchState;
+    mobileEditor: MobileEditorState;
+    columnWidths: Record<string, number>;
+    /** Session-only sort model (PR-90). Not EventStore. */
+    sortModel: SortModel;
+    /** Session-only quick filter text (PR-93). Not EventStore. */
+    quickFilterText: string;
+    /** Session-only column filter model (PR-94). Not EventStore. */
+    filterModel: FilterModel;
+    /**
+     * Row model mode (PR-96). Default `clientSide`.
+     * When `infinite` / `serverSide`, local sort/filter are skipped.
+     */
+    rowModelType: RowModelType;
+    /**
+     * Total rows from the last `GridDatasource.getRows().lastRow` (PR-96).
+     * `null` = unknown / use loaded row count.
+     */
+    serverRowCount: number | null;
+    /** Cell-range selection state (PR-105). Session-only. */
+    cellRangeSelection: CellRangeSelection;
+    /** Collapsed column group ids (PR-113). Session-only. */
+    collapsedColumnGroups: Record<string, true>;
+    /**
+     * Row group column ids (PR-120). Only the first is active in 0.12.0.
+     * Session-only — not EventStore (RFC-002).
+     */
+    rowGroupColumns: string[];
+    /** Default expand state for row groups (PR-120). */
+    groupDefaultExpanded: boolean;
+    /** Per-group expand overrides keyed by normalizeGroupKey (PR-120). */
+    rowGroupExpanded: Record<string, boolean>;
+    /** Session-only cell edit draft (PR-126). Not EventStore. */
+    cellEdit: CellEditSession | null;
+};
+type TCell = {
+    value: unknown;
+    originalValue: unknown;
+    display: unknown;
+};
+type ItemType = {
+    type?: 'submenu' | 'item' | 'group' | 'divider';
+    label?: React.ReactNode;
+    children?: ItemType[];
+    disabled?: boolean;
+    ref?: React.Ref<HTMLLIElement | null>;
+    style?: React.CSSProperties;
+    className?: string;
+    isSelected?: boolean;
+    isOpen?: boolean;
+    isSubMenu?: boolean;
+    danger?: boolean;
+    icon?: React.ReactNode;
+    title?: string;
+    key: string;
+    theme?: 'dark' | 'light';
+    dashed?: boolean;
+    rootClassName?: string;
+    itemIcon?: React.ReactNode;
+    expandIcon?: React.ReactNode;
+    popupClassName?: string;
+    popupOffset?: number[];
+    popupStyle?: React.CSSProperties;
+    onClick?: () => void;
+    extra?: React.ReactNode;
+};
+type ValidationCallback = (result: ValidationCallbackResult) => void;
+type ValidationCallbackResult = {
+    valid: boolean;
+    errors?: Map<string, CellError>;
+    data?: unknown;
+};
+interface CellError {
+    rowId: number;
+    caption: string;
+    message: string;
+}
+
+interface BaseTableCommand {
+    readonly store: string;
+    readonly tableKey: string;
+    /** When set, undoable events from separate executes merge into one undo unit. */
+    readonly correlationId?: string;
+}
+type Actor = {
+    readonly userId: string;
+    readonly roles: string[];
+};
+/**
+ * Base invariant:
+ * هر Command دقیقاً متعلق به یک Table است
+ */
+interface MoveActiveCellCommand {
+    readonly type: 'MOVE_ACTIVE_CELL';
+    readonly store: string;
+    readonly tableKey: string;
+    readonly rowId: number;
+    readonly columnId: string;
+    readonly direction: 'next' | 'prev';
+}
+interface MoveActiveCellVerticalCommand {
+    readonly type: 'MOVE_ACTIVE_CELL_VERTICAL';
+    readonly store: string;
+    readonly tableKey: string;
+    readonly rowId: number;
+    readonly columnId: string;
+    readonly direction: 'up' | 'down';
+}
+interface MoveVerticalSelectedRows {
+    readonly type: 'MOVE_VERTICAL_SELECTED_ROWS';
+    readonly tableKey: string;
+    readonly direction: 'up' | 'down';
+}
+interface MoveVerticalActiveRow {
+    readonly type: 'MOVE_VERTICAL_ACTIVE_ROW';
+    readonly tableKey: string;
+    readonly direction: 'up' | 'down';
+}
+interface ActiveCellCommand {
+    readonly type: 'ACTIVE_CELL';
+    readonly tableKey: string;
+    readonly rowId: number;
+    readonly columnId: string;
+}
+interface ActiveRowCommand extends BaseTableCommand {
+    readonly type: 'ACTIVE_ROW';
+    readonly tableKey: string;
+    readonly rowId: number;
+}
+interface ActiveFirstCellCommand {
+    readonly type: 'ACTIVATE_FIRST_CELL';
+    readonly tableKey: string;
+    readonly rowId: number;
+}
+interface ChangeCellValueCommand extends BaseTableCommand {
+    readonly type: 'CHANGE_CELL_VALUE';
+    readonly rowId: number;
+    readonly columnId: string;
+    readonly newValue: unknown;
+}
+interface SaveDescriptionCommand extends BaseTableCommand {
+    readonly type: 'SAVE_DESCRIPTION';
+    readonly rowId: number;
+    readonly flag: boolean;
+}
+interface ChangeCellDisplayValueCommand extends BaseTableCommand {
+    readonly type: 'CHANGE_CELL_DISPLAY_VALUE';
+    readonly rowId: number;
+    readonly columnId: string;
+    readonly newValue: string;
+}
+interface AddEmptyRowCommand extends BaseTableCommand {
+    readonly type: 'ADD_EMPTY_ROW';
+    readonly autoActivate: boolean;
+}
+interface AddNewRowsCommand extends BaseTableCommand {
+    readonly type: 'ADD_NEW_ROWS';
+    readonly detailFieldKey: string;
+    readonly rows: {
+        key: string;
+        value: unknown;
+        display: unknown;
+    }[][];
+    readonly autoActivate?: boolean;
+}
+interface DuplicateRowCommand extends BaseTableCommand {
+    readonly type: 'DUPLICATE_ROW';
+    readonly rowId: number;
+}
+/**
+ * Clone one source row (clipboard paste). Engine batches these with a shared
+ * correlationId so undo reverses the whole paste unit.
+ */
+interface PasteCellsCommand extends BaseTableCommand {
+    readonly type: 'PASTE_CELLS';
+    readonly updates: readonly {
+        rowId: number;
+        columnId: string;
+        rawText: string;
+    }[];
+}
+interface PasteRowCommand extends BaseTableCommand {
+    readonly type: 'PASTE_ROW';
+    readonly sourceRowId: number;
+    /** When set (pasteInsert), place the clone relative to this row. */
+    readonly placeAtRowId?: number;
+}
+interface DeleteRowCommand extends BaseTableCommand {
+    readonly type: 'ROW_DELETED';
+    readonly rowId: number;
+}
+/** Undo-stack redo: re-insert a previously added row with original identity/values. */
+interface RestoreAddedRowCommand extends BaseTableCommand {
+    readonly type: 'RESTORE_ADDED_ROW';
+    readonly rowId: number;
+    readonly cells: Readonly<Record<string, {
+        readonly value: unknown;
+        readonly display?: unknown;
+        readonly originalValue?: unknown;
+    }>>;
+    readonly collection?: string;
+    readonly isSaveDescription?: boolean;
+}
+interface DeleteRowsCommand extends BaseTableCommand {
+    readonly type: 'ROWS_DELETED';
+    /** Selected row ids (may include rows not in the RAM page window). Filled by engine if omitted. */
+    readonly rowIds?: number[];
+}
+interface ExpandRowCommand {
+    readonly type: 'ROW_EXPANDED';
+    readonly tableKey: string;
+    readonly rowId: number;
+    readonly value: boolean;
+}
+interface SelectRowCommand {
+    readonly type: 'ROW_SELECTED';
+    readonly tableKey: string;
+    readonly rowId: number;
+}
+interface ToggleRowSelectionCommand {
+    readonly type: "ROW_SELECTION_TOGGLED";
+    readonly tableKey: string;
+    readonly rowId: number;
+}
+interface ToggleRowExpandCommand {
+    readonly type: 'ROW_EXPAND_TOGGLED';
+    readonly tableKey: string;
+    readonly rowId: number;
+}
+interface SelectRangeCommand {
+    readonly type: "ROW_RANGE_SELECTED";
+    readonly tableKey: string;
+    readonly rowId: number;
+}
+interface SelectActiveRowToLastCommand {
+    readonly type: "SELECT_FROM_ACTIVE_TO_LAST";
+    readonly tableKey: string;
+    readonly anchorRowId: number;
+}
+interface RowReorderedCommand extends BaseTableCommand {
+    readonly type: 'ROW_REORDERED';
+    readonly draggedRowId: number;
+    readonly droppedRowId: number;
+    readonly position: 'before' | 'after';
+}
+interface SelectAllRowsCommand {
+    readonly type: 'TOGGLE_SELECT_ALL_ROWS';
+    readonly store: string;
+    readonly tableKey: string;
+}
+interface SelectPageRowsCommand {
+    readonly type: 'TOGGLE_SELECT_PAGE_ROWS';
+    readonly tableKey: string;
+}
+interface ClearRowSelectionCommand {
+    readonly type: 'CLEAR_ROW_SELECTION';
+    readonly tableKey: string;
+}
+interface CollapseAllRowsCommand {
+    readonly type: 'COLLAPSE_ALL_ROWS';
+    readonly tableKey: string;
+}
+interface ColumnReorderedCommand extends BaseTableCommand {
+    readonly type: 'COLUMN_REORDERED';
+    readonly sourceIndex: number;
+    readonly destIndex: number;
+}
+interface DeleteTableCommand extends BaseTableCommand {
+    readonly type: 'TABLE_DELETED';
+}
+interface SetActiveCollectionCommand extends BaseTableCommand {
+    readonly type: 'SET_ACTIVE_COLLECTION';
+    readonly activeCollection: string;
+}
+interface ResetTableCommand extends BaseTableCommand {
+    readonly type: 'TABLE_RESET';
+    readonly rowId: string;
+}
+interface RegisterTableCommand extends BaseTableCommand {
+    readonly type: 'TABLE_REGISTERED';
+    readonly store: string;
+    readonly table: Table;
+}
+interface DisposeTableCommand extends BaseTableCommand {
+    readonly type: 'TABLE_DISPOSED';
+}
+interface ChangeTableActionCommand extends BaseTableCommand {
+    readonly type: 'SET_TABLE_ACTION';
+    action: TableActions;
+}
+interface ChangePageCommand extends BaseTableCommand {
+    readonly type: 'CHANGE_PAGE';
+    readonly page: number;
+}
+interface ChangePageSizeCommand extends BaseTableCommand {
+    readonly type: 'CHANGE_PAGE_SIZE';
+    readonly pageSize: number;
+}
+interface ApplyDynamicProjectionCommand extends BaseTableCommand {
+    readonly type: 'APPLY_DYNAMIC_PROJECTION';
+    readonly tableKey: string;
+    readonly rowId: number;
+    readonly columnId: string;
+}
+/**
+ * اعمال مجدد شروط visibility ریموت برای یک سطر مشخص (مثلاً هنگام active شدن سطر
+ * در حالت ویرایش) بدون تغییر RowState یا پاک‌کردن سلول‌های وابسته.
+ */
+interface ApplyRowVisibilityCommand extends BaseTableCommand {
+    readonly type: 'APPLY_ROW_VISIBILITY';
+    readonly tableKey: string;
+    readonly rowId: number;
+}
+interface SetGridSearchCommand {
+    readonly type: 'SET_GRID_SEARCH';
+    readonly tableKey: string;
+    readonly search: GridSearchState;
+}
+interface SetMobileEditorCommand {
+    readonly type: 'SET_MOBILE_EDITOR';
+    readonly tableKey: string;
+    readonly editor: MobileEditorState;
+}
+interface ResizeColumnCommand {
+    readonly type: 'RESIZE_COLUMN';
+    readonly tableKey: string;
+    readonly columnId: string;
+    readonly width: number;
+}
+interface SetColumnVisibleCommand {
+    readonly type: 'SET_COLUMN_VISIBLE';
+    readonly tableKey: string;
+    readonly columnId: string;
+    readonly visible: boolean;
+}
+interface ToggleColumnGroupCommand {
+    readonly type: 'TOGGLE_COLUMN_GROUP';
+    readonly tableKey: string;
+    readonly groupId: string;
+}
+interface SetColumnPinnedCommand {
+    readonly type: 'SET_COLUMN_PIN';
+    readonly tableKey: string;
+    readonly columnId: string;
+    readonly pinned: 'start' | 'end' | null;
+}
+interface SetSortModelCommand {
+    readonly type: 'SET_SORT_MODEL';
+    readonly tableKey: string;
+    /** Empty / omit fields cleared by host ⇒ document `index` order. */
+    readonly sortModel: readonly {
+        readonly colId: string;
+        readonly sort: 'asc' | 'desc';
+    }[];
+}
+interface SetQuickFilterTextCommand {
+    readonly type: 'SET_QUICK_FILTER_TEXT';
+    readonly tableKey: string;
+    /** Empty string clears the filter (all rows visible). */
+    readonly quickFilterText: string;
+}
+interface SetFilterModelCommand {
+    readonly type: 'SET_FILTER_MODEL';
+    readonly tableKey: string;
+    /** Empty object clears all column filters. */
+    readonly filterModel: FilterModel;
+}
+interface SetRowGroupColumnsCommand {
+    readonly type: 'SET_ROW_GROUP_COLUMNS';
+    readonly tableKey: string;
+    /** Only the first entry is active in 0.12.0 (RFC-002). */
+    readonly columns: readonly string[];
+}
+interface SetGroupDefaultExpandedCommand {
+    readonly type: 'SET_GROUP_DEFAULT_EXPANDED';
+    readonly tableKey: string;
+    readonly expanded: boolean;
+}
+interface ToggleRowGroupCommand {
+    readonly type: 'TOGGLE_ROW_GROUP';
+    readonly tableKey: string;
+    /** `normalizeGroupKey` of the group. */
+    readonly groupKey: string;
+}
+type EngineTableCommand = SelectActiveRowToLastCommand | SelectRangeCommand | ToggleRowExpandCommand | SelectRowCommand | CollapseAllRowsCommand | RegisterTableCommand | DisposeTableCommand | DeleteRowsCommand | ToggleRowSelectionCommand | SelectAllRowsCommand | SelectPageRowsCommand | ClearRowSelectionCommand | ActiveCellCommand | ActiveRowCommand | MoveActiveCellCommand | MoveActiveCellVerticalCommand | MoveVerticalSelectedRows | MoveVerticalActiveRow | ActiveFirstCellCommand | ExpandRowCommand | ChangeTableActionCommand | SetGridSearchCommand | SetMobileEditorCommand | ResizeColumnCommand | SetColumnVisibleCommand | ToggleColumnGroupCommand | SetColumnPinnedCommand | SetSortModelCommand | SetQuickFilterTextCommand | SetFilterModelCommand | SetRowGroupColumnsCommand | SetGroupDefaultExpandedCommand | ToggleRowGroupCommand;
+type ApplicationTableCommand = ChangeCellValueCommand | SaveDescriptionCommand | ChangeCellDisplayValueCommand | AddEmptyRowCommand | AddNewRowsCommand | DuplicateRowCommand | PasteCellsCommand | PasteRowCommand | DeleteRowCommand | RestoreAddedRowCommand | DeleteTableCommand | SetActiveCollectionCommand | ResetTableCommand | RowReorderedCommand | ColumnReorderedCommand | ChangePageCommand | ChangePageSizeCommand | ApplyDynamicProjectionCommand | ApplyRowVisibilityCommand | DeleteRowsCommand;
+type TableCommand = EngineTableCommand | ApplicationTableCommand;
+
+interface TableRepository {
+    getById(store: string, tableKey: string): Promise<Table>;
+    save(store: string, table: Table): Promise<void>;
+    delete(store: string, tableKey: string): Promise<void>;
+    resetTable(store: string, tableKey: string): Promise<void>;
+    exists(store: string, tableKey: string): Promise<boolean>;
+    getFromDbById?(store: string, tableKey: string): Promise<Table>;
+}
+/** Plain serialized row as streamed from IndexedDB (no domain objects). */
+interface PersistedRowRecord {
+    rowId: number;
+    collection: string;
+    sortIndex: number;
+    rowState: string;
+    /** colId → { value, originalValue, display } — plain, no domain objects */
+    cells: Record<string, {
+        value: unknown;
+        originalValue: unknown;
+        display: unknown;
+    }>;
+}
+/**
+ * Page-window repository ("paged IndexedDB" persistence mode).
+ *
+ * IndexedDB is the single source of truth for ALL rows; RAM holds exactly one
+ * page window (Memory Iron Rule: heap is O(batch), never O(total rows)).
+ * Opt-in via `persistence: 'paged-idb'`; the default event-sourced
+ * repositories do NOT implement these methods.
+ */
+interface WindowedTableRepository extends TableRepository {
+    /**
+     * Persist metadata + upsert rows currently held in the Table (page window).
+     * Must NOT delete other pages' rows in IndexedDB.
+     */
+    save(store: string, table: Table): Promise<void>;
+    /**
+     * Replace IndexedDB source of truth with every row on `table`, then callers
+     * should `loadPage` so RAM only keeps one page.
+     */
+    replaceAll(store: string, table: Table): Promise<void>;
+    /** Flush pending IDB writes, load one page into RAM, return that window. */
+    loadPage(store: string, tableKey: string, page: number, pageSize?: number): Promise<Table | null>;
+    /**
+     * Switch the persisted active collection (page resets to 1) and return a
+     * Table whose RAM window holds page 1 of the NEW collection only.
+     * Rows of other collections must remain untouched in IndexedDB.
+     */
+    setActiveCollection(store: string, tableKey: string, collection: string): Promise<Table | null>;
+    /**
+     * @deprecated Legacy: hydrates the whole dataset. Use `iterateRowRecords`.
+     * All rows from IndexedDB (source of truth).
+     */
+    getAllRows(store: string, tableKey: string, collectionScope?: CollectionScope): Promise<Row[]>;
+    /**
+     * All row ids from IndexedDB (source of truth), without hydrating cells.
+     * Used for select-all across the full dataset (not just the RAM page window).
+     */
+    getAllRowIds(store: string, tableKey: string, collectionScope?: CollectionScope): Promise<number[]>;
+    /**
+     * Stream serialized row records from IndexedDB in bounded batches via a
+     * cursor over the byTableCollectionSort index (ordered, no full load).
+     * The heap at any moment holds one batch — never the whole dataset.
+     * Return false from onBatch to stop early.
+     */
+    iterateRowRecords(store: string, tableKey: string, collectionScope: CollectionScope, onBatch: (records: PersistedRowRecord[], 
+    /** Ordinal (0-based, collection-sorted position) of the batch's first record */
+    ordinalBase: number) => Promise<boolean | void>, batchSize?: number): Promise<void>;
+    /** Physically remove row records from IndexedDB (hard delete). */
+    removeRows(store: string, tableKey: string, rowIds: number[]): Promise<void>;
+    /**
+     * Bulk soft/hard delete applied directly to persisted row records
+     * (cursor-based — heap stays O(1)):
+     * - `Added` rows are hard-removed from the store
+     * - others get rowState = Deleted written on the record (cursor.update)
+     * - already-Deleted rows are left untouched (no restore on bulk delete)
+     */
+    softDeleteRows(store: string, tableKey: string, rowIds: number[]): Promise<{
+        softDeleted: number;
+        hardRemoved: number;
+        /** Non-deleted rows remaining in the active collection after the delete. */
+        remaining: number;
+    }>;
+    /** Drop RAM window only; IndexedDB untouched. */
+    clearLocal(store: string, tableKey: string): void;
+    /** Await queued IndexedDB writes for this table. */
+    flush(store: string, tableKey: string): Promise<void>;
+}
+/** Type guard: true only for page-window repositories (`persistence: 'paged-idb'`). */
+declare function isWindowedRepository(repo: TableRepository): repo is WindowedTableRepository;
+
+interface BaseTableEvent {
+    readonly tableId: string;
+    readonly type: string;
+}
+interface CellChangedEvent extends BaseTableEvent {
+    type: 'CELL_CHANGED';
+    rowId: number;
+    columnId: string;
+    newValue: unknown;
+    previousValue: unknown;
+}
+interface DynamicProjectionEvent extends BaseTableEvent {
+    type: 'DYNAMIC_PROJECTION_DONE';
+    rowId: number;
+    columnId: string;
+}
+interface CellDisplayChangedEvent extends BaseTableEvent {
+    type: 'CELL_DISPLAY_CHANGED';
+    rowId: number;
+    columnId: string;
+    newValue: unknown;
+}
+interface RowAddedEvent extends BaseTableEvent {
+    type: 'ROW_ADDED';
+    rowId: string;
+}
+interface NewRowAddedEvent extends BaseTableEvent {
+    type: 'NEW_ROW_ADDED';
+    rowId: string;
+}
+interface RowDeletedEvent extends BaseTableEvent {
+    type: 'ROW_DELETED';
+    rowId: string;
+}
+interface NewRowRemovedEvent extends BaseTableEvent {
+    type: 'NEW_ROW_REMOVED';
+    rowId: string;
+}
+interface RowRestoredEvent extends BaseTableEvent {
+    type: 'ROW_RESTORED';
+    rowId: string;
+}
+interface RowReorderedEvent extends BaseTableEvent {
+    type: 'ROW_REORDERED';
+    sourceIndex: number;
+    destIndex: number;
+}
+interface RowDescriptionSaved extends BaseTableEvent {
+    type: 'ROW_DESCRIPTION_SAVED';
+    rowId: number;
+    description: boolean;
+}
+interface ColumnReorderedEvent extends BaseTableEvent {
+    type: 'COLUMN_REORDERED';
+    sourceIndex: number;
+    destIndex: number;
+}
+interface UnitColumnAddedEvent extends BaseTableEvent {
+    type: 'UNIT_COLUMN_ADDED';
+    reason: string;
+    details?: unknown;
+}
+interface PageChangedEvent extends BaseTableEvent {
+    type: 'PAGE_CHANGED';
+    page: number;
+}
+interface PageSizeChangedEvent extends BaseTableEvent {
+    type: 'PAGE_SIZE_CHANGED';
+    tableId: string;
+    pageSize: number;
+}
+interface TableDeletedEvent extends BaseTableEvent {
+    type: 'TABLE_DELETED';
+    tableId: string;
+}
+interface TableResetEvent extends BaseTableEvent {
+    type: 'TABLE_RESET';
+    tableId: string;
+}
+interface ActiveCollectionChangedEvent extends BaseTableEvent {
+    type: 'ACTIVE_COLLECTION_CHANGED';
+    tableId: string;
+}
+interface RowsLoadedEvent extends BaseTableEvent {
+    type: 'ROWS_LOADED';
+    count: number;
+}
+interface DynamicDataRequestedEvent extends BaseTableEvent {
+    type: 'DYNAMIC_DATA_REQUESTED';
+    requestId: string;
+    sourceColumn: string;
+    value: unknown;
+}
+interface ValidationFailedEvent extends BaseTableEvent {
+    type: 'VALIDATION_FAILED';
+    reason: string;
+    details?: unknown;
+}
+type TableEvent = CellChangedEvent | DynamicProjectionEvent | CellDisplayChangedEvent | RowAddedEvent | NewRowAddedEvent | RowDeletedEvent | NewRowRemovedEvent | RowRestoredEvent | RowReorderedEvent | RowDescriptionSaved | ColumnReorderedEvent | UnitColumnAddedEvent | PageChangedEvent | PageSizeChangedEvent | RowsLoadedEvent | DynamicDataRequestedEvent | ValidationFailedEvent | TableDeletedEvent | ActiveCollectionChangedEvent | TableResetEvent;
+
+type DynamicConfig = {
+    columnMeta: Map<string, ColumnSchema>;
+    remoteApi: RemoteApi;
+};
+declare class ChangeCellValueHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permissionPolicy;
+    private readonly dynamic?;
+    constructor(repo: TableRepository, audit: AuditLogger, permissionPolicy: PermissionPolicy, dynamic?: DynamicConfig | undefined);
+    execute(command: ChangeCellValueCommand, actor: Actor$1): Promise<TableEvent[]>;
+    private applyRemoteVisibilityRules;
+    private applyComputedColumns;
+    private validateCellValue;
+    private applyDynamicProjection;
+}
+declare class ChangeCellDisplayValueHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permissionPolicy;
+    constructor(repo: TableRepository, audit: AuditLogger, permissionPolicy: PermissionPolicy);
+    execute(command: ChangeCellDisplayValueCommand, actor: Actor$1): Promise<TableEvent[]>;
+}
+declare class SaveDescriptionHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permissionPolicy;
+    constructor(repo: TableRepository, audit: AuditLogger, permissionPolicy: PermissionPolicy);
+    execute(command: SaveDescriptionCommand, actor: Actor$1): Promise<TableEvent[]>;
+}
+declare class ApplyDynamicProjectionHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permissionPolicy;
+    private readonly dynamic?;
+    constructor(repo: TableRepository, audit: AuditLogger, permissionPolicy: PermissionPolicy, dynamic?: DynamicConfig | undefined);
+    execute(command: ApplyDynamicProjectionCommand, actor: Actor$1): Promise<TableEvent[]>;
+    private applyRemoteVisibilityRules;
+    private applyComputedColumns;
+    private validateCellValue;
+    private applyDynamicProjection;
+}
+
+declare class DeleteRowsCommandHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permission;
+    constructor(repo: WindowedTableRepository, audit: AuditLogger, permission: PermissionPolicy);
+    /**
+     * Bulk delete — never toggles restore:
+     * - `Added` → hard-remove from IndexedDB
+     * - otherwise → `rowState = Deleted` (soft; قابل برگرداندن با حذف تکی)
+     * Already-`Deleted` rows stay deleted.
+     */
+    execute(command: DeleteRowsCommand, actor: Actor$1): Promise<{
+        removed: number;
+        softDeleted: number;
+        remaining: number;
+    } | null>;
+}
+
+/**
+ * هنگام فعال‌شدن (active) شدن یک سطر اجرا می‌شود:
+ * برای هر ستون دارای resolveOn که سلولش مقدار دارد، applyRemoteVisibilityRules
+ * را (بدون پاک‌کردن سلول‌های وابسته) صدا می‌زند تا visibilityCondition سطر فعال
+ * از سرویس ریموت به‌روز شود. مقدار RowState سطر را تغییر نمی‌دهد.
+ */
+declare class ApplyRowVisibilityHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permissionPolicy;
+    private readonly dynamic?;
+    /**
+     * Dedupe guard: آخرین امضای (row + کالکشن + مقادیر ستون‌های resolveOn) که
+     * برایش سر ریموت صدا زده شد. بدون این، دو مسیر مستقل (کلیک سطر →
+     * setActiveRow و کلیک سلول → setActiveCell) و رفرش‌های متوالی، همان API را
+     * چند بار صدا می‌زدند. وقتی مقادیر عوض شود امضای جدید است و API دوباره
+     * صدا زده می‌شود.
+     */
+    private lastSignature;
+    constructor(repo: TableRepository, audit: AuditLogger, permissionPolicy: PermissionPolicy, dynamic?: DynamicConfig | undefined);
+    execute(command: ApplyRowVisibilityCommand, actor: Actor$1): Promise<TableEvent[]>;
+    private applyRemoteVisibilityRules;
+}
+
+/**
+ * Batch clipboard paste (PR-107): one repo save, many CELL_CHANGED events.
+ */
+declare class PasteCellsCommandHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permissionPolicy;
+    constructor(repo: TableRepository, audit: AuditLogger, permissionPolicy: PermissionPolicy);
+    execute(command: PasteCellsCommand, actor: Actor$1): Promise<TableEvent[]>;
+    private validateCellValue;
+}
+
+declare class AddNewRowCommandHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permission;
+    constructor(repo: TableRepository, audit: AuditLogger, permission: PermissionPolicy);
+    execute(command: AddEmptyRowCommand, actor: Actor$1): Promise<RowAdded | null>;
+}
+declare class AddNewRowsCommandHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permission;
+    constructor(repo: TableRepository, audit: AuditLogger, permission: PermissionPolicy);
+    execute(command: AddNewRowsCommand, actor: Actor$1): Promise<RowAdded[] | null>;
+}
+declare class PasteRowCommandHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permission;
+    constructor(repo: TableRepository, audit: AuditLogger, permission: PermissionPolicy);
+    execute(command: PasteRowCommand, actor: Actor$1): Promise<RowAdded | null>;
+}
+declare class DuplicateRowCommandHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permission;
+    constructor(repo: TableRepository, audit: AuditLogger, permission: PermissionPolicy);
+    execute(command: DuplicateRowCommand, actor: Actor$1): Promise<RowAdded | null>;
+}
+declare class DeleteRowCommandHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permission;
+    constructor(repo: TableRepository, audit: AuditLogger, permission: PermissionPolicy);
+    execute(command: DeleteRowCommand, actor: Actor$1): Promise<RowDeleted | RowRemoved | MinimumRowConstraintViolated | RowRestored | null>;
+}
+declare class RestoreAddedRowCommandHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permission;
+    constructor(repo: TableRepository, audit: AuditLogger, permission: PermissionPolicy);
+    execute(command: RestoreAddedRowCommand, actor: Actor$1): Promise<RowAdded | null>;
+}
+declare class ReorderRowCommandHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permission;
+    constructor(repo: TableRepository, audit: AuditLogger, permission: PermissionPolicy);
+    execute(command: RowReorderedCommand, actor: Actor$1): Promise<RowReordered | null>;
+}
+
+declare class ChangePageCommandHandler {
+    private readonly repo;
+    private readonly audit;
+    constructor(repo: TableRepository, audit: AuditLogger);
+    execute(command: ChangePageCommand, actor: Actor$1): Promise<TableEvent[]>;
+}
+declare class ChangePageSizeCommandHandler {
+    private readonly repo;
+    private readonly audit;
+    constructor(repo: TableRepository, audit: AuditLogger);
+    execute(command: ChangePageSizeCommand, actor: Actor$1): Promise<TableEvent[]>;
+}
+declare class DeleteTableCommandHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permissionPolicy;
+    constructor(repo: TableRepository, audit: AuditLogger, permissionPolicy: PermissionPolicy);
+    execute(command: DeleteTableCommand, actor: Actor$1): Promise<TableEvent[]>;
+}
+declare class ResetTableCommandHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permissionPolicy;
+    constructor(repo: TableRepository, audit: AuditLogger, permissionPolicy: PermissionPolicy);
+    execute(command: ResetTableCommand, actor: Actor$1): Promise<TableEvent[]>;
+}
+declare class SetActiveCollectionCommandHandler {
+    private readonly repo;
+    private readonly audit;
+    constructor(repo: TableRepository, audit: AuditLogger);
+    private applyVisibility;
+    execute(command: SetActiveCollectionCommand, actor: Actor$1): Promise<TableEvent[]>;
+    private handleSetActiveError;
+}
+declare class ReorderColumnCommandHandler {
+    private readonly repo;
+    private readonly audit;
+    private readonly permission;
+    constructor(repo: TableRepository, audit: AuditLogger, permission: PermissionPolicy);
+    execute(command: ColumnReorderedCommand, actor: Actor$1): Promise<TableEvent[]>;
+}
+
+interface GridEvent<TType extends string = string, TPayload = unknown> {
+    readonly eventId: string;
+    readonly type: TType;
+    readonly tableId: string;
+    readonly streamId: string;
+    readonly version: number;
+    readonly occurredAt: number;
+    readonly actorId: string;
+    readonly payload: TPayload;
+    readonly correlationId?: string;
+    readonly causationId?: string;
+}
+interface ExportRequestedPayload {
+    readonly format: 'xlsx' | 'pdf' | 'csv';
+    readonly collectionScope: 'active' | 'all' | string[];
+    readonly fileName?: string;
+    readonly sheetName?: string;
+    readonly direction?: 'rtl' | 'ltr';
+}
+interface ImportRequestedPayload {
+    readonly format: 'xlsx';
+    readonly collectionScope: 'active' | 'all' | string[];
+    readonly sheetName?: string;
+    readonly byteLength?: number;
+}
+
+type AppendResult = {
+    ok: true;
+    version: number;
+} | {
+    ok: false;
+    conflict: {
+        expectedVersion: number;
+        actualVersion: number;
+    };
+};
+type Unsubscribe = () => void;
+interface EventStore {
+    append(streamId: string, events: GridEvent[], expectedVersion: number): Promise<AppendResult>;
+    read(streamId: string, fromVersion?: number): Promise<GridEvent[]>;
+    /** Ordered global stream for catch-up of cross-stream projections. */
+    readAll(fromPosition?: number): Promise<GridEvent[]>;
+    subscribe(streamId: string, onEvent: (event: GridEvent) => void): Unsubscribe;
+    subscribeAll(onEvent: (event: GridEvent) => void): Unsubscribe;
+}
+
+interface CellUndoEntry {
+    readonly kind: 'CELL_CHANGED';
+    readonly tableId: string;
+    readonly rowId: number;
+    readonly columnId: string;
+    readonly newValue: unknown;
+    readonly previousValue: unknown;
+}
+type RowCellSnapshot = {
+    readonly value: unknown;
+    readonly display?: unknown;
+    readonly originalValue?: unknown;
+};
+interface RowAddedUndoEntry {
+    readonly kind: 'ROW_ADDED';
+    readonly tableId: string;
+    readonly rowId: number;
+    /** Captured at record time so redo can restore identity + values. */
+    readonly cells: Readonly<Record<string, RowCellSnapshot>>;
+    readonly collection?: string;
+    readonly isSaveDescription?: boolean;
+}
+/**
+ * Compensating entry for a delete:
+ * - soft: Unchanged→Deleted (undo/redo = toggle ROW_DELETED)
+ * - hard: Added row removed from map (undo = RESTORE_ADDED_ROW)
+ */
+interface RowDeletedUndoEntry {
+    readonly kind: 'ROW_DELETED';
+    readonly tableId: string;
+    readonly rowId: number;
+    readonly mode: 'soft' | 'hard';
+    readonly cells: Readonly<Record<string, RowCellSnapshot>>;
+    readonly collection?: string;
+    readonly isSaveDescription?: boolean;
+}
+type AtomicUndoEntry = CellUndoEntry | RowAddedUndoEntry | RowDeletedUndoEntry;
+type UndoDispatchCommand = {
+    type: 'CHANGE_CELL_VALUE';
+    store: string;
+    tableKey: string;
+    rowId: number;
+    columnId: string;
+    newValue: unknown;
+} | {
+    type: 'ROW_DELETED';
+    store: string;
+    tableKey: string;
+    rowId: number;
+} | {
+    type: 'RESTORE_ADDED_ROW';
+    store: string;
+    tableKey: string;
+    rowId: number;
+    cells: Readonly<Record<string, RowCellSnapshot>>;
+    collection?: string;
+    isSaveDescription?: boolean;
+};
+type CellUndoDispatch = (command: UndoDispatchCommand) => Promise<void>;
+/**
+ * Compensating undo/redo stack for domain edits.
+ * - CELL_CHANGED: restore previousValue / re-apply newValue
+ * - ROW_ADDED: delete on undo; RESTORE_ADDED_ROW on redo
+ * - ROW_DELETED soft: toggle ROW_DELETED; hard: RESTORE_ADDED_ROW / ROW_DELETED
+ * - Same correlationId merges into one undo unit (paste / cut+paste)
+ */
+declare class CellUndoStack {
+    private undoEntries;
+    private redoEntries;
+    private applying;
+    record(event: CellChangedEvent, correlationId?: string): void;
+    recordRowAdded(event: {
+        tableId: string;
+        rowId: number;
+        cells?: Readonly<Record<string, RowCellSnapshot>>;
+        collection?: string;
+        isSaveDescription?: boolean;
+    }, correlationId?: string): void;
+    recordRowDeleted(event: {
+        tableId: string;
+        rowId: number;
+        mode: 'soft' | 'hard';
+        cells?: Readonly<Record<string, RowCellSnapshot>>;
+        collection?: string;
+        isSaveDescription?: boolean;
+    }, correlationId?: string): void;
+    recordMany(entries: AtomicUndoEntry[], correlationId?: string): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    undoDepth(): number;
+    redoDepth(): number;
+    undo(store: string, dispatch: CellUndoDispatch): Promise<boolean>;
+    redo(store: string, dispatch: CellUndoDispatch): Promise<boolean>;
+    clear(): void;
+    private pushAtomic;
+    private applyCompensating;
+    private applyForward;
+}
+
+declare class TableAppService {
+    private readonly changeCellValue;
+    private readonly changeCellDisplayValue;
+    private readonly saveDescription;
+    private readonly addEmptyRow;
+    private readonly addNewRows;
+    private readonly duplicateRow;
+    private readonly deleteRow;
+    private readonly reorderRow;
+    private readonly setPageSize;
+    private readonly setPage;
+    private readonly setActiveCollection;
+    private readonly deleteTable;
+    private readonly resetTable;
+    private readonly applyDynamicProjection;
+    private readonly pasteCells;
+    private readonly restoreAddedRow?;
+    private readonly pasteRow?;
+    private readonly reorderColumn?;
+    /** Page-window (paged-idb) mode only. */
+    /** Lazy loader (module is fetched on first row activation with `resolveOn`). */
+    private readonly applyRowVisibility?;
+    private eventStore?;
+    private undoStack?;
+    private repo?;
+    private snapshotStrategy?;
+    constructor(changeCellValue: ChangeCellValueHandler, changeCellDisplayValue: ChangeCellDisplayValueHandler, saveDescription: SaveDescriptionHandler, addEmptyRow: AddNewRowCommandHandler, addNewRows: AddNewRowsCommandHandler, duplicateRow: DuplicateRowCommandHandler, deleteRow: DeleteRowCommandHandler, reorderRow: ReorderRowCommandHandler, setPageSize: ChangePageSizeCommandHandler, setPage: ChangePageCommandHandler, setActiveCollection: SetActiveCollectionCommandHandler, deleteTable: DeleteTableCommandHandler, resetTable: ResetTableCommandHandler, applyDynamicProjection: ApplyDynamicProjectionHandler, pasteCells: PasteCellsCommandHandler, restoreAddedRow?: RestoreAddedRowCommandHandler | undefined, pasteRow?: PasteRowCommandHandler | undefined, reorderColumn?: ReorderColumnCommandHandler | undefined, 
+    /** Page-window (paged-idb) mode only. */
+    /** Lazy loader (module is fetched on first row activation with `resolveOn`). */
+    applyRowVisibility?: (() => Promise<ApplyRowVisibilityHandler>) | undefined);
+    private deleteRows?;
+    /** Page-window mode only (lazy module): bulk delete of the selected rows. */
+    setDeleteRowsHandler(handler: DeleteRowsCommandHandler): void;
+    setEventStore(eventStore: EventStore): void;
+    setSnapshotStrategy(strategy: {
+        onAppend(streamId: string, tableId: string, appendedCount: number): Promise<void>;
+    }): void;
+    setUndoStack(undoStack: CellUndoStack): void;
+    setRepository(repo: TableRepository): void;
+    execute(command: ApplicationTableCommand, actor: Actor): Promise<RowAdded | RowDeleted | RowRemoved | MinimumRowConstraintViolated | RowRestored | RowReordered | RowAdded[] | TableEvent[] | {
+        removed: number;
+        softDeleted: number;
+        remaining: number;
+    } | null>;
+    private dispatch;
+    private recordUndoableEvents;
+    private captureRowSnapshot;
+    private appendToEventStore;
+    private recordSnapshot;
+    private normalizeResult;
+    private resolveRowId;
+    private toGridPayload;
+    private createCorrelationId;
+}
+
+/**
+ * Sparse ordered index for large tables: O(1) id lookup + O(window) projection.
+ * Position map enables O(1) neighbor for keyboard nav (PR-99).
+ */
+declare class SparseRowIndex<T> {
+    private readonly byId;
+    private orderedIds;
+    /** id → position in `orderedIds` (PR-99). */
+    private readonly posById;
+    constructor(entries?: Iterable<readonly [number, T]>);
+    get size(): number;
+    getOrderedIds(): readonly number[];
+    getById(id: number): T | undefined;
+    /** O(1) position of `id`, or `-1`. */
+    indexOf(id: number): number;
+    /** O(1) neighbor id along the ordered index, or `undefined`. */
+    neighbor(id: number, delta: 1 | -1): number | undefined;
+    set(id: number, value: T): void;
+    /** Insert `id` at `pos` (0…size). Shifts later positions — O(n-pos). */
+    insertAt(pos: number, id: number, value: T): void;
+    remove(id: number): boolean;
+    /** Replace order without rebuilding payloads (e.g. after sort). */
+    setOrder(orderedIds: readonly number[]): void;
+    /** Full replace of ids + values in one pass (PR-99 rebuild). */
+    replaceAll(orderedIds: readonly number[], valueFor: (id: number) => T): void;
+    clear(): void;
+    /** Project only the visible window — O(window), not O(n). */
+    projectVisible(range: {
+        startIndex: number;
+        endIndex: number;
+    }): T[];
+}
+
+type GetRowId<TRow = unknown> = (row: TRow, index: number) => string;
+/** Default `getRowId`: array index. Hosts with a stable key should pass one. */
+declare function defaultGetRowId<TRow>(_row: TRow, index: number): string;
+/**
+ * Domain sort/pagination still keys off an `index` cell. When the host omits
+ * one, synthesize a hidden `#` column so order stays stable.
+ */
+declare function ensureIndexColumnDef<TRow>(defs: ColDefOrGroup<TRow>[]): ColDefOrGroup<TRow>[];
+type MappedRowInput = {
+    id: number;
+    values: Record<string, unknown>;
+    data: unknown;
+    sourceId: string;
+    collection: 'default';
+};
+declare function mapRowDataToRowInputs<TRow>(rowData: readonly TRow[], columnDefs: ColumnDef<TRow>[], getRowId?: GetRowId<TRow>): MappedRowInput[];
+type HostRowDataDiffResult = {
+    added: number;
+    updated: number;
+    removed: number;
+    kept: number;
+    structureChanged: boolean;
+    removedIds: number[];
+    /** Domain `Row` instances whose cells were not rewritten. */
+    unchangedRows: Row[];
+};
+/**
+ * Align table rows with a new `rowData` array without rebuilding the table.
+ * Unchanged rows keep the same `Row` instance (no deep clone of `data`).
+ */
+declare function applyHostRowDataToTable<TRow>(table: Table, rowData: readonly TRow[], columnDefs: ColumnDef<TRow>[], getRowId?: GetRowId<TRow>): HostRowDataDiffResult;
+
+declare class TableEngine {
+    private readonly app;
+    private readonly repo;
+    private readonly actor;
+    /**
+     * متای زندهٔ ستون‌ها از کانفیگ (دارای resolveOn / dynamicSource که در
+     * IndexedDB serialize نمی‌شوند). NavigationManager برای تشخیص ستون‌های
+     * شرطیِ فعال‌شدن سطر (APPLY_ROW_VISIBILITY) به آن نیاز دارد.
+     */
+    private readonly columnMeta?;
+    private tableStore?;
+    private tableKey?;
+    /** Durable command store id (for CHANGE_CELL_* on edit commit). */
+    private commandStore?;
+    private cellEditOptions;
+    readonly errors: Map<string, CellError>;
+    readonly searchResult: Map<string, CellError>;
+    private readonly asyncCellCache;
+    private readonly asyncCellSeq;
+    private readonly errHandler;
+    private readonly selection;
+    private readonly cellRange;
+    private readonly rowMgr;
+    private readonly nav;
+    private readonly viewBuilder;
+    /** Notifies host server/infinite row model after sort/filter/page (PR-96). */
+    private viewQueryListener?;
+    constructor(app: TableAppService, repo: TableRepository, actor: Actor, audit: ConsoleAuditLogger, 
+    /**
+     * متای زندهٔ ستون‌ها از کانفیگ (دارای resolveOn / dynamicSource که در
+     * IndexedDB serialize نمی‌شوند). NavigationManager برای تشخیص ستون‌های
+     * شرطیِ فعال‌شدن سطر (APPLY_ROW_VISIBILITY) به آن نیاز دارد.
+     */
+    columnMeta?: Map<string, ColumnSchema> | undefined);
+    private registerTable;
+    private deleteTable;
+    private disposeTable;
+    private resetTable;
+    private shouldInvalidateUiRowIndex;
+    private getStore;
+    /**
+     * Default case در dispatch:
+     * command را به AppService می‌دهد و سپس repo را reload می‌کند.
+     */
+    private executeAppCommand;
+    /**
+     * Paste goes through AppService (PASTE_ROW + optional ROW_DELETED for cut)
+     * with one correlationId so undo reverses the whole unit.
+     */
+    private executePasteAction;
+    dispatch(command: TableCommand): Promise<void>;
+    private setGridSearch;
+    private setMobileEditor;
+    private resizeColumn;
+    private setColumnPinned;
+    private toggleColumnGroup;
+    private setColumnVisible;
+    private setSortModel;
+    private setQuickFilterText;
+    private setFilterModel;
+    private setRowGroupColumns;
+    private setGroupDefaultExpanded;
+    private toggleRowGroup;
+    /**
+     * Server/infinite row model hooks (PR-96).
+     * Listener runs after sort / filter / page changes.
+     */
+    bindViewQueryListener(listener: (() => void) | undefined): void;
+    setRowModelType(rowModelType: RowModelType): void;
+    setServerRowCount(count: number | null): void;
+    private notifyViewQueryChanged;
+    getViewState(): TableViewState | undefined;
+    /**
+     * Diff `rowData` onto the live table without resetting it (PR-82).
+     * Unchanged domain rows keep identity so UI `React.memo` can skip them.
+     */
+    applyHostRowData<TRow>(rowData: readonly TRow[], columnDefs?: ColumnDef<TRow>[], getRowId?: GetRowId<TRow>): void;
+    getAllRows(): Row[] | null;
+    getAllUIRows(): UIRow[] | null;
+    /** Flat group/leaf nodes (PR-120). */
+    getFlatUiNodes(): readonly FlatUiNode[];
+    getGroupNode(rowId: number): FlatGroupNode | undefined;
+    /** Expand/collapse group for the active synthetic row (PR-121). */
+    toggleRowGroupById(rowId: number): boolean;
+    getUiRowIndex(): SparseRowIndex<number>;
+    /** Absolute 0-based position in the filter/sort UI order (PR-99). */
+    getUiRowAbsoluteIndex(rowId: number): number;
+    getCellRanges(): readonly CellRange[];
+    addCellRange(range: CellRange): void;
+    handleCellRangePointer(rowId: number, colId: string, modifiers: {
+        shiftKey: boolean;
+        ctrlKey: boolean;
+    }): void;
+    extendCellRangeArrow(direction: ArrowDirection): void;
+    extendCellRangeToEdge(direction: ArrowDirection): void;
+    jumpActiveCellRowEdge(edge: 'start' | 'end'): void;
+    jumpActiveCellGridCorner(corner: 'first' | 'last'): void;
+    private syncActiveCellToRangeFocus;
+    selectAllCells(): void;
+    syncCellRangeToActiveCell(): void;
+    private getCellRangeBounds;
+    findColumnSearchMatches(columnId: string, query: string): Array<{
+        rowId: number;
+        columnId: string;
+    }>;
+    getColumnTotals(): Record<string, number>;
+    getColumnAggs(): Record<string, unknown>;
+    getColumnAggValue(columnId: string, overrideAgg?: AggFunc): unknown;
+    subscribeColumnTotals(cb: (totals: Record<string, number>) => void): (() => void) | null;
+    subscribeColumnAggs(cb: (aggs: Record<string, unknown>) => void): (() => void) | null;
+    getUiRowCount(): number;
+    projectVisibleUiRows(range: {
+        startIndex: number;
+        endIndex: number;
+    }): UIRow[];
+    getMobileViewState(): MobileTableViewState | undefined;
+    getRowView(rowId: number): UIRow | null;
+    getSnapShot(collectionScope: CollectionScope): TableSnapShot | null;
+    /**
+     * Full dataset snapshot from IndexedDB (source of truth).
+     * Use for server save / export — not the RAM page window.
+     */
+    getFullSnapShot(store: string, collectionScope?: CollectionScope): Promise<TableSnapShot | null>;
+    /**
+     * Stream serialized row records from IndexedDB in bounded batches.
+     * Heap holds one batch at a time — never the whole dataset.
+     * Return false from onBatch to stop early.
+     */
+    iterateRowsFromDb(store: string, collectionScope: CollectionScope, onBatch: (records: PersistedRowRecord[], ordinalBase: number) => Promise<boolean | void>, batchSize?: number): Promise<void>;
+    /** True in persistence 'paged-idb' mode (RAM holds one page window). */
+    isPagedWindow(): boolean;
+    /** Windowed: IndexedDB (SoT). Default mode: the in-memory table. */
+    private loadAllRows;
+    getExpandedRowData(rowId: number): Record<string, unknown> | null;
+    getActiveCell(): TableState['activeCell'] | null;
+    /** Force a view-store tick so bound React rows re-read cells (PR-86). */
+    refreshView(): void;
+    setCellEditOptions(partial: Partial<CellEditOptions>): void;
+    getCellEditOptions(): CellEditOptions;
+    getCellEdit(): CellEditSession | null;
+    getEditDraft(rowId: number, columnId: string): CellEditValue | null;
+    isEditingCell(rowId: number, columnId: string): boolean;
+    /**
+     * Begin a session-only draft for the cell (or full row). Does not touch EventStore.
+     */
+    startCellEdit(rowId: number, columnId: string): void;
+    patchCellEdit(rowId: number, columnId: string, patch: Partial<CellEditValue>): void;
+    /** Discard drafts; restore UI to domain values. No EventStore write. */
+    cancelCellEdit(): void;
+    /**
+     * Write dirty drafts via CHANGE_CELL_* then clear the session.
+     * @returns number of value-change commands dispatched
+     */
+    commitCellEdit(): Promise<number>;
+    private transitionActiveCell;
+    private maybeStartEditForActiveCell;
+    /** Leave cell-edit / focus. Commits when stopEditingWhenCellsLoseFocus. */
+    clearActiveCell(options?: {
+        cancel?: boolean;
+    }): Promise<void>;
+    getActiveRow(): number | null;
+    getSelectedRows(): Record<number, boolean> | undefined;
+    getCell(rowId: number, columnId: string): Cell | undefined;
+    getMobileEditor(): TableState['mobileEditor'] | undefined;
+    isActiveCell(rowId: number, columnId: string): boolean;
+    isSelectedRow(rowId: number): boolean;
+    isCutRow(rowId: number): boolean;
+    isActiveRow(rowId: number): boolean;
+    private validateCell;
+    private schemaHasAsyncValidator;
+    private tableHasAsyncValidators;
+    private cellValueKey;
+    private errorFromAsyncFailure;
+    private applyAsyncValidators;
+    private validateCellFull;
+    private finishValidation;
+    private collectValidationJobs;
+    private applyValidationErrors;
+    private runValidationSync;
+    private runValidationAsync;
+    private scheduleAsyncCellCheck;
+    validation(cb: ValidationCallback): void;
+    isValidCell(rowId: number, caption: string): ValidCell;
+    subscribe(cb: () => void): (() => void) | null;
+    /**
+     * Selector-based subscription over engine-derived view data.
+     * `selector` closes over engine getters (snapshot, activeCell, …).
+     */
+    subscribeSelected<TSelected>(selector: () => TSelected, listener: (selected: TSelected) => void, isEqual?: (a: TSelected, b: TSelected) => boolean): (() => void) | null;
+    /**
+     * Streamed column subscription (Memory Iron Rule compliant).
+     * Consumes the dataset through `iterateRowRecords` in bounded batches and
+     * folds every non-deleted item into a small caller-owned accumulator via
+     * `reducer` — never materializes rows with getAllRows and never
+     * JSON.stringify's the whole dataset. Heap = one batch + the accumulator
+     * (O(batch) in RAM, independent of total row count).
+     * Change detection uses an incrementally-maintained double-hash signature
+     * (O(1) heap) instead of a full JSON signature.
+     * `cb` fires with the folded accumulator on the initial emit and afterwards
+     * only when the column's data actually changed. Reads are async.
+     */
+    subscribeColumn<T = unknown>(columnId: string, collections: CollectionScope, reducer: (acc: T, item: {
+        id: number;
+        rowNum: unknown;
+        value: unknown;
+    }) => T, seed: T, cb: (acc: T) => void, store?: string): (() => void) | null;
+}
+
+interface ChangelogEntry {
+    readonly eventId: string;
+    readonly type: string;
+    readonly tableId: string;
+    readonly occurredAt: number;
+    readonly actorId: string;
+    readonly payload: unknown;
+}
+interface ChangelogQuery {
+    tableId?: string;
+    rowId?: number | string;
+    columnId?: string;
+    type?: string;
+    since?: number;
+    limit?: number;
+}
+declare class ChangelogProjection {
+    private readonly eventStore;
+    private entries;
+    private unsubscribe;
+    private subscribers;
+    private seenEventIds;
+    private started;
+    constructor(eventStore: EventStore);
+    /**
+     * Catch up via readAll, then subscribe for live events.
+     * Dedupes by eventId so subscribe-before-replay races are safe.
+     */
+    start(): Promise<void>;
+    stop(): void;
+    query(filter?: ChangelogQuery): ChangelogEntry[];
+    count(filter?: ChangelogQuery): number;
+    subscribe(notify: (entries: ChangelogEntry[]) => void, filter?: ChangelogQuery): Unsubscribe;
+    clear(): void;
+    private project;
+    private notifySubscribers;
+}
+
+type HistorySeverity = 'info' | 'warning' | 'error';
+type HistoryCategory = 'data' | 'structure' | 'view' | 'system';
+interface HistoryQuery extends ChangelogQuery {
+    severity?: HistorySeverity;
+    category?: HistoryCategory;
+}
+interface HistoryItem {
+    readonly id: string;
+    readonly type: string;
+    readonly title: string;
+    readonly description: string;
+    readonly occurredAt: number;
+    readonly tableId: string;
+    readonly actorId: string;
+    readonly severity: HistorySeverity;
+    readonly category: HistoryCategory;
+    readonly raw: ChangelogEntry;
+}
+declare class HistoryPanelViewModel {
+    private readonly changelogProjection;
+    constructor(changelogProjection: ChangelogProjection);
+    query(filter?: HistoryQuery): HistoryItem[];
+    count(filter?: HistoryQuery): number;
+    subscribe(cb: (items: HistoryItem[]) => void, filter?: HistoryQuery): Unsubscribe;
+    private toHistoryItem;
+}
+
+/**
+ * Session-centric view / keyboard intents.
+ * These are not domain commands; GridSession maps them to engine dispatches.
+ */
+type ViewIntent = {
+    type: 'ADD_EMPTY_ROW';
+    autoActivate?: boolean;
+} | {
+    type: 'DUPLICATE_ROW';
+    rowId: number;
+} | {
+    type: 'DELETE_ROW';
+    rowId: number;
+} | {
+    type: 'TOGGLE_ROW_SELECTION';
+    rowId: number;
+} | {
+    type: 'SELECT_FROM_ACTIVE_TO_LAST';
+    anchorRowId: number;
+} | {
+    type: 'ACTIVATE_FIRST_CELL';
+    rowId: number;
+} | {
+    type: 'MOVE_ACTIVE_CELL';
+    rowId: number;
+    columnId: string;
+    direction: 'next' | 'prev';
+} | {
+    type: 'MOVE_ACTIVE_CELL_VERTICAL';
+    rowId: number;
+    columnId: string;
+    direction: 'up' | 'down';
+} | {
+    type: 'MOVE_VERTICAL_SELECTED_ROWS';
+    direction: 'up' | 'down';
+} | {
+    type: 'MOVE_VERTICAL_ACTIVE_ROW';
+    direction: 'up' | 'down';
+} | {
+    type: 'COLLAPSE_ALL_ROWS';
+} | {
+    type: 'CHANGE_PAGE';
+    page: number;
+} | {
+    type: 'CHANGE_PAGE_SIZE';
+    pageSize: number;
+} | {
+    type: 'SET_TABLE_ACTION';
+    action: TableActions;
+} | {
+    type: 'SET_GRID_SEARCH';
+    search: GridSearchState;
+} | {
+    type: 'SET_MOBILE_EDITOR';
+    editor: MobileEditorState;
+} | {
+    type: 'CHANGE_VIEWPORT';
+    scrollOffset: number;
+    viewportSize?: number;
+    rowHeight?: number;
+    overscan?: number;
+} | {
+    type: 'UNDO';
+} | {
+    type: 'REDO';
+} | {
+    type: 'EXTEND_CELL_RANGE';
+    direction: ArrowDirection;
+} | {
+    type: 'EXTEND_CELL_RANGE_TO_EDGE';
+    direction: ArrowDirection;
+} | {
+    type: 'JUMP_ACTIVE_CELL_ROW_EDGE';
+    edge: 'start' | 'end';
+} | {
+    type: 'JUMP_ACTIVE_CELL_GRID';
+    corner: 'first' | 'last';
+} | {
+    type: 'SELECT_ALL_CELLS';
+};
+type ViewIntentDispatcher = (intent: ViewIntent) => Promise<void>;
+
+type GridSessionSubscribeSelected = <TSelected>(selector: () => TSelected, listener: (selected: TSelected) => void, isEqual?: (a: TSelected, b: TSelected) => boolean) => () => void;
+/**
+ * Framework-agnostic session facade (target shape of useGrid / createGrid).
+ * Adapters should prefer this over raw Engine.
+ */
+interface GridSession {
+    readonly store: string;
+    readonly tableKey: string;
+    dispatchViewIntent: ViewIntentDispatcher;
+    handleKeydown(event: KeyboardEvent, ctx: {
+        activeRowId: number | null;
+        activeColumnId: string | null;
+    }): Promise<void>;
+    getSnapShot(collectionScope?: CollectionScope): TableSnapShot | null;
+    getViewState(): ReturnType<TableEngine['getViewState']>;
+    subscribe(cb: () => void): () => void;
+    subscribeSelected: GridSessionSubscribeSelected;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    undo(): Promise<boolean>;
+    redo(): Promise<boolean>;
+    getChangelog(filter?: Omit<ChangelogQuery, 'tableId'>): ChangelogEntry[];
+    getChangelogCount(filter?: Omit<ChangelogQuery, 'tableId'>): number;
+    subscribeChangelog(cb: (entries: ChangelogEntry[]) => void, filter?: Omit<ChangelogQuery, 'tableId'>): () => void;
+    getHistoryItems(filter?: Omit<HistoryQuery, 'tableId'>): HistoryItem[];
+    getHistoryItemCount(filter?: Omit<HistoryQuery, 'tableId'>): number;
+    subscribeHistoryItems(cb: (items: HistoryItem[]) => void, filter?: Omit<HistoryQuery, 'tableId'>): () => void;
+    getEngine(): TableEngine;
+    /** Current virtual-scroll viewport (view state; not domain). */
+    getViewport(): Viewport;
+    getVisibleRange(totalRows?: number): VisibleRange;
+    projectVisibleRows<T>(rows: readonly T[], totalRows?: number): T[];
+    /** Active-collection row count from the sparse UI index (order = `index` column). */
+    getUiRowCount(): number;
+    /** Visible UI rows for the current viewport — O(window), not O(n). */
+    projectVisibleUiRows(): NonNullable<ReturnType<TableEngine['getRowView']>>[];
+    /** Notify when virtual viewport scroll/size changes (PR-102 block fetch). */
+    subscribeViewport(listener: () => void): () => void;
+}
+
+export { type CycleSortModelOptions as $, type AggFunc as A, type AriaSortValue as B, type ColumnSchema as C, type DefaultOptionType as D, type EventStore as E, type FilterModel as F, type GridEvent as G, HistoryPanelViewModel as H, type ArrowDirection as I, type BooleanColumnFilter as J, type BooleanFilterOp as K, type BuiltinFilterKind as L, type MobileTableViewState as M, type CellRangeBounds as N, type CellRangeSelection as O, type ColumnDefBridge as P, type ColumnField as Q, Row as R, type ColumnFilter as S, type TableSnapShot as T, type UIRow as U, type ValidCell as V, type WindowedTableRepository as W, type ColumnPinned as X, type CombinedColumnFilter as Y, type CustomColumnFilter as Z, type CustomFilterFn as _, type Unsubscribe as a, sortPriorityForColumn as a$, type DateColumnFilter as a0, type DateFilterOp as a1, type FilterAccessor as a2, type FilterDef as a3, type FilterJoin as a4, HEADER_SORT_CLICK_MAX_MOVE_PX as a5, INDEX_COL_ID as a6, type ItemType as a7, type NumberColumnFilter as a8, type NumberFilterOp as a9, compareSortValues as aA, compareTypedValues as aB, createEmptyCellRangeSelection as aC, ctrlClickCell as aD, cycleSortModel as aE, defaultGetRowId as aF, ensureIndexColumnDef as aG, isBlankSortValue as aH, isCellInRange as aI, isColumnFilterActive as aJ, isHeaderColumnSortable as aK, isServerRowModel as aL, isWindowedRepository as aM, mapRowDataToRowInputs as aN, mergeCellRanges as aO, moveCellAddress as aP, normalizeCellRange as aQ, normalizeDigits as aR, normalizeFilterText as aS, pageWindow as aT, rangeFromAnchorFocus as aU, rangesOverlap as aV, resolveBuiltinFilterKind as aW, selectAllCellRanges as aX, shiftArrowCell as aY, shiftClickCell as aZ, shouldCommitHeaderSortClick as a_, type PersistedRowRecord as aa, type RowModelType as ab, RowStateEnum as ac, type SetColumnFilter as ad, type SetFilterOp as ae, type SimpleColumnFilter as af, type SortAccessor as ag, type SortDirection as ah, type SortModel as ai, type SortModelItem as aj, type SortValueComparator as ak, SparseRowIndex as al, type TextColumnFilter as am, type TextFilterOp as an, type ViewIntent as ao, Viewport as ap, type VisibleRange as aq, applyFilter as ar, applyHostRowDataToTable as as, applySort as at, ariaSortForColumn as au, clampColIndex as av, clampRowIndex as aw, clickCell as ax, colIndex as ay, collectUniqueFilterValues as az, type GridSession as b, type ExportRequestedPayload as b0, type ImportRequestedPayload as b1, type IRule as b2, type ColumnVisibilityRule as b3, type IDependOn as b4, type Actor$1 as b5, type ColDefOrGroup as b6, type TableRepository as b7, type PermissionPolicy as b8, type CellEditType as b9, type IMultiSelectConfig as ba, type ColumnGroupDef as bb, type ColumnGroupMeta as bc, type ColumnGroupPathEntry as bd, isColumnGroupDef as be, type CollectionScope as c, type CellRange as d, TableEngine as e, Table as f, type TableActions as g, type GridSearchState as h, ChangelogProjection as i, CellUndoStack as j, type TableViewState as k, type ColumnDef as l, type GetRowId as m, Cell as n, type ChangelogQuery as o, type ChangelogEntry as p, type HistoryQuery as q, type HistoryItem as r, type ActiveCell as s, type CellEditValue as t, type MobileEditorState as u, type ValidationCallbackResult as v, type CellAddress as w, type FieldType as x, type AggFuncName as y, type AppendResult as z };