@tanstack/table-core 9.0.0-beta.31 → 9.0.0-beta.33

package/dist/worker/tableWorkerProtocol.cjs

@@ -0,0 +1,29 @@
+
+//#region src/worker/tableWorkerProtocol.ts
+/**
+* Row model stages that can be offloaded to the worker, in pipeline order.
+* Everything else in this module is derived from this list; adding a stage
+* means adding an entry here and to `tableWorkerStageStateDeps`.
+*/
+const tableWorkerPipeline = [
+	"filtered",
+	"grouped",
+	"sorted",
+	"expanded"
+];
+/**
+* The state slices each stage's computation depends on. The main thread sends
+* the union of deps for its registered stages; a change to any of them
+* triggers one worker round trip.
+*/
+const tableWorkerStageStateDeps = {
+	filtered: ["columnFilters", "globalFilter"],
+	grouped: ["grouping"],
+	sorted: ["sorting"],
+	expanded: ["expanded"]
+};
+
+//#endregion
+exports.tableWorkerPipeline = tableWorkerPipeline;
+exports.tableWorkerStageStateDeps = tableWorkerStageStateDeps;
+//# sourceMappingURL=tableWorkerProtocol.cjs.map

package/dist/worker/tableWorkerProtocol.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tableWorkerProtocol.cjs","names":[],"sources":["../../src/worker/tableWorkerProtocol.ts"],"sourcesContent":["import type { RowData } from '../types/type-utils'\n\n/**\n * Row model stages that can be offloaded to the worker, in pipeline order.\n * Everything else in this module is derived from this list; adding a stage\n * means adding an entry here and to `tableWorkerStageStateDeps`.\n */\nexport const tableWorkerPipeline = [\n  'filtered',\n  'grouped',\n  'sorted',\n  'expanded',\n] as const\n\nexport type TableWorkerStage = (typeof tableWorkerPipeline)[number]\n\n/**\n * The state slices each stage's computation depends on. The main thread sends\n * the union of deps for its registered stages; a change to any of them\n * triggers one worker round trip.\n */\nexport const tableWorkerStageStateDeps: Record<\n  TableWorkerStage,\n  Array<string>\n> = {\n  filtered: ['columnFilters', 'globalFilter'],\n  grouped: ['grouping'],\n  sorted: ['sorting'],\n  expanded: ['expanded'],\n}\n\n/**\n * A serialized synthetic (group) row. Leaf rows serialize as their position in\n * `options.data`; group rows carry what `constructRow` + the grouped row model\n * need to rebuild them, plus eagerly computed aggregate values so no\n * aggregation runs on the main thread.\n */\nexport interface TableWorkerGroupNode {\n  id: string\n  groupingColumnId: string\n  groupingValue: unknown\n  index: number\n  aggregates: Record<string, unknown>\n  children: Array<TableWorkerRowNode>\n}\n\nexport type TableWorkerRowNode = number | TableWorkerGroupNode\n\n/**\n * A stage result. Flat models (every row is a data row) travel as a\n * transferable index permutation; models containing synthetic rows (grouping)\n * travel as a tree. The kind is chosen from the model's actual shape at\n * runtime, not from the stage name: a sorted model is flat without grouping\n * and a tree with it.\n *\n * `unchanged` means the stage's model is identical to the last one sent for\n * this dataset (its memoized inputs did not change); the main thread keeps\n * its previous result and skips the rebuild entirely.\n */\nexport type TableWorkerStagePayload =\n  | { kind: 'flat'; indices: Uint32Array }\n  | { kind: 'tree'; children: Array<TableWorkerRowNode> }\n  | { kind: 'unchanged' }\n\nexport type TableWorkerRequest<TData extends RowData = any> =\n  | {\n      type: 'data'\n      dataVersion: number\n      data: Array<TData>\n    }\n  | {\n      type: 'process'\n      requestId: number\n      dataVersion: number\n      /** The stages the main thread has worker-backed row models for. */\n      stages: Array<TableWorkerStage>\n      /** Serializable state slices (union of the stages' deps). */\n      state: Record<string, unknown>\n    }\n\nexport interface TableWorkerResult {\n  type: 'result'\n  requestId: number\n  dataVersion: number\n  stages: { [K in TableWorkerStage]?: TableWorkerStagePayload }\n  computeMs: number\n}\n\nexport type TableWorkerResponse = TableWorkerResult\n\n/**\n * The state slice added by `workerRowModelsFeature`. `version` bumps when a\n * worker result lands (driving re-renders through the normal state path);\n * `isPending` is true while a request is in flight. The timing fields expose\n * the last result's worker compute time and full round trip for devtools and\n * debugging.\n */\nexport interface TableState_WorkerRowModels {\n  workerRowModels: {\n    version: number\n    isPending: boolean\n    lastComputeMs?: number\n    lastRoundTripMs?: number\n  }\n}\n"],"mappings":";;;;;;;AAOA,MAAa,sBAAsB;CACjC;CACA;CACA;CACA;AACF;;;;;;AASA,MAAa,4BAGT;CACF,UAAU,CAAC,iBAAiB,cAAc;CAC1C,SAAS,CAAC,UAAU;CACpB,QAAQ,CAAC,SAAS;CAClB,UAAU,CAAC,UAAU;AACvB"}

package/dist/worker/tableWorkerProtocol.d.cts

@@ -0,0 +1,88 @@
+import { RowData } from "../types/type-utils.cjs";
+
+//#region src/worker/tableWorkerProtocol.d.ts
+/**
+ * Row model stages that can be offloaded to the worker, in pipeline order.
+ * Everything else in this module is derived from this list; adding a stage
+ * means adding an entry here and to `tableWorkerStageStateDeps`.
+ */
+declare const tableWorkerPipeline: readonly ["filtered", "grouped", "sorted", "expanded"];
+type TableWorkerStage = (typeof tableWorkerPipeline)[number];
+/**
+ * The state slices each stage's computation depends on. The main thread sends
+ * the union of deps for its registered stages; a change to any of them
+ * triggers one worker round trip.
+ */
+declare const tableWorkerStageStateDeps: Record<TableWorkerStage, Array<string>>;
+/**
+ * A serialized synthetic (group) row. Leaf rows serialize as their position in
+ * `options.data`; group rows carry what `constructRow` + the grouped row model
+ * need to rebuild them, plus eagerly computed aggregate values so no
+ * aggregation runs on the main thread.
+ */
+interface TableWorkerGroupNode {
+  id: string;
+  groupingColumnId: string;
+  groupingValue: unknown;
+  index: number;
+  aggregates: Record<string, unknown>;
+  children: Array<TableWorkerRowNode>;
+}
+type TableWorkerRowNode = number | TableWorkerGroupNode;
+/**
+ * A stage result. Flat models (every row is a data row) travel as a
+ * transferable index permutation; models containing synthetic rows (grouping)
+ * travel as a tree. The kind is chosen from the model's actual shape at
+ * runtime, not from the stage name: a sorted model is flat without grouping
+ * and a tree with it.
+ *
+ * `unchanged` means the stage's model is identical to the last one sent for
+ * this dataset (its memoized inputs did not change); the main thread keeps
+ * its previous result and skips the rebuild entirely.
+ */
+type TableWorkerStagePayload = {
+  kind: 'flat';
+  indices: Uint32Array;
+} | {
+  kind: 'tree';
+  children: Array<TableWorkerRowNode>;
+} | {
+  kind: 'unchanged';
+};
+type TableWorkerRequest<TData extends RowData = any> = {
+  type: 'data';
+  dataVersion: number;
+  data: Array<TData>;
+} | {
+  type: 'process';
+  requestId: number;
+  dataVersion: number; /** The stages the main thread has worker-backed row models for. */
+  stages: Array<TableWorkerStage>; /** Serializable state slices (union of the stages' deps). */
+  state: Record<string, unknown>;
+};
+interface TableWorkerResult {
+  type: 'result';
+  requestId: number;
+  dataVersion: number;
+  stages: { [K in TableWorkerStage]?: TableWorkerStagePayload };
+  computeMs: number;
+}
+type TableWorkerResponse = TableWorkerResult;
+/**
+ * The state slice added by `workerRowModelsFeature`. `version` bumps when a
+ * worker result lands (driving re-renders through the normal state path);
+ * `isPending` is true while a request is in flight. The timing fields expose
+ * the last result's worker compute time and full round trip for devtools and
+ * debugging.
+ */
+interface TableState_WorkerRowModels {
+  workerRowModels: {
+    version: number;
+    isPending: boolean;
+    lastComputeMs?: number;
+    lastRoundTripMs?: number;
+  };
+}
+//#endregion
+export { TableState_WorkerRowModels, TableWorkerGroupNode, TableWorkerRequest, TableWorkerResponse, TableWorkerResult, TableWorkerRowNode, TableWorkerStage, TableWorkerStagePayload, tableWorkerPipeline, tableWorkerStageStateDeps };
+//# sourceMappingURL=tableWorkerProtocol.d.cts.map

package/dist/worker/tableWorkerProtocol.d.ts

@@ -0,0 +1,88 @@
+import { RowData } from "../types/type-utils.js";
+
+//#region src/worker/tableWorkerProtocol.d.ts
+/**
+ * Row model stages that can be offloaded to the worker, in pipeline order.
+ * Everything else in this module is derived from this list; adding a stage
+ * means adding an entry here and to `tableWorkerStageStateDeps`.
+ */
+declare const tableWorkerPipeline: readonly ["filtered", "grouped", "sorted", "expanded"];
+type TableWorkerStage = (typeof tableWorkerPipeline)[number];
+/**
+ * The state slices each stage's computation depends on. The main thread sends
+ * the union of deps for its registered stages; a change to any of them
+ * triggers one worker round trip.
+ */
+declare const tableWorkerStageStateDeps: Record<TableWorkerStage, Array<string>>;
+/**
+ * A serialized synthetic (group) row. Leaf rows serialize as their position in
+ * `options.data`; group rows carry what `constructRow` + the grouped row model
+ * need to rebuild them, plus eagerly computed aggregate values so no
+ * aggregation runs on the main thread.
+ */
+interface TableWorkerGroupNode {
+  id: string;
+  groupingColumnId: string;
+  groupingValue: unknown;
+  index: number;
+  aggregates: Record<string, unknown>;
+  children: Array<TableWorkerRowNode>;
+}
+type TableWorkerRowNode = number | TableWorkerGroupNode;
+/**
+ * A stage result. Flat models (every row is a data row) travel as a
+ * transferable index permutation; models containing synthetic rows (grouping)
+ * travel as a tree. The kind is chosen from the model's actual shape at
+ * runtime, not from the stage name: a sorted model is flat without grouping
+ * and a tree with it.
+ *
+ * `unchanged` means the stage's model is identical to the last one sent for
+ * this dataset (its memoized inputs did not change); the main thread keeps
+ * its previous result and skips the rebuild entirely.
+ */
+type TableWorkerStagePayload = {
+  kind: 'flat';
+  indices: Uint32Array;
+} | {
+  kind: 'tree';
+  children: Array<TableWorkerRowNode>;
+} | {
+  kind: 'unchanged';
+};
+type TableWorkerRequest<TData extends RowData = any> = {
+  type: 'data';
+  dataVersion: number;
+  data: Array<TData>;
+} | {
+  type: 'process';
+  requestId: number;
+  dataVersion: number; /** The stages the main thread has worker-backed row models for. */
+  stages: Array<TableWorkerStage>; /** Serializable state slices (union of the stages' deps). */
+  state: Record<string, unknown>;
+};
+interface TableWorkerResult {
+  type: 'result';
+  requestId: number;
+  dataVersion: number;
+  stages: { [K in TableWorkerStage]?: TableWorkerStagePayload };
+  computeMs: number;
+}
+type TableWorkerResponse = TableWorkerResult;
+/**
+ * The state slice added by `workerRowModelsFeature`. `version` bumps when a
+ * worker result lands (driving re-renders through the normal state path);
+ * `isPending` is true while a request is in flight. The timing fields expose
+ * the last result's worker compute time and full round trip for devtools and
+ * debugging.
+ */
+interface TableState_WorkerRowModels {
+  workerRowModels: {
+    version: number;
+    isPending: boolean;
+    lastComputeMs?: number;
+    lastRoundTripMs?: number;
+  };
+}
+//#endregion
+export { TableState_WorkerRowModels, TableWorkerGroupNode, TableWorkerRequest, TableWorkerResponse, TableWorkerResult, TableWorkerRowNode, TableWorkerStage, TableWorkerStagePayload, tableWorkerPipeline, tableWorkerStageStateDeps };
+//# sourceMappingURL=tableWorkerProtocol.d.ts.map

package/dist/worker/tableWorkerProtocol.js

@@ -0,0 +1,27 @@
+//#region src/worker/tableWorkerProtocol.ts
+/**
+* Row model stages that can be offloaded to the worker, in pipeline order.
+* Everything else in this module is derived from this list; adding a stage
+* means adding an entry here and to `tableWorkerStageStateDeps`.
+*/
+const tableWorkerPipeline = [
+	"filtered",
+	"grouped",
+	"sorted",
+	"expanded"
+];
+/**
+* The state slices each stage's computation depends on. The main thread sends
+* the union of deps for its registered stages; a change to any of them
+* triggers one worker round trip.
+*/
+const tableWorkerStageStateDeps = {
+	filtered: ["columnFilters", "globalFilter"],
+	grouped: ["grouping"],
+	sorted: ["sorting"],
+	expanded: ["expanded"]
+};
+
+//#endregion
+export { tableWorkerPipeline, tableWorkerStageStateDeps };
+//# sourceMappingURL=tableWorkerProtocol.js.map

package/dist/worker/tableWorkerProtocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tableWorkerProtocol.js","names":[],"sources":["../../src/worker/tableWorkerProtocol.ts"],"sourcesContent":["import type { RowData } from '../types/type-utils'\n\n/**\n * Row model stages that can be offloaded to the worker, in pipeline order.\n * Everything else in this module is derived from this list; adding a stage\n * means adding an entry here and to `tableWorkerStageStateDeps`.\n */\nexport const tableWorkerPipeline = [\n  'filtered',\n  'grouped',\n  'sorted',\n  'expanded',\n] as const\n\nexport type TableWorkerStage = (typeof tableWorkerPipeline)[number]\n\n/**\n * The state slices each stage's computation depends on. The main thread sends\n * the union of deps for its registered stages; a change to any of them\n * triggers one worker round trip.\n */\nexport const tableWorkerStageStateDeps: Record<\n  TableWorkerStage,\n  Array<string>\n> = {\n  filtered: ['columnFilters', 'globalFilter'],\n  grouped: ['grouping'],\n  sorted: ['sorting'],\n  expanded: ['expanded'],\n}\n\n/**\n * A serialized synthetic (group) row. Leaf rows serialize as their position in\n * `options.data`; group rows carry what `constructRow` + the grouped row model\n * need to rebuild them, plus eagerly computed aggregate values so no\n * aggregation runs on the main thread.\n */\nexport interface TableWorkerGroupNode {\n  id: string\n  groupingColumnId: string\n  groupingValue: unknown\n  index: number\n  aggregates: Record<string, unknown>\n  children: Array<TableWorkerRowNode>\n}\n\nexport type TableWorkerRowNode = number | TableWorkerGroupNode\n\n/**\n * A stage result. Flat models (every row is a data row) travel as a\n * transferable index permutation; models containing synthetic rows (grouping)\n * travel as a tree. The kind is chosen from the model's actual shape at\n * runtime, not from the stage name: a sorted model is flat without grouping\n * and a tree with it.\n *\n * `unchanged` means the stage's model is identical to the last one sent for\n * this dataset (its memoized inputs did not change); the main thread keeps\n * its previous result and skips the rebuild entirely.\n */\nexport type TableWorkerStagePayload =\n  | { kind: 'flat'; indices: Uint32Array }\n  | { kind: 'tree'; children: Array<TableWorkerRowNode> }\n  | { kind: 'unchanged' }\n\nexport type TableWorkerRequest<TData extends RowData = any> =\n  | {\n      type: 'data'\n      dataVersion: number\n      data: Array<TData>\n    }\n  | {\n      type: 'process'\n      requestId: number\n      dataVersion: number\n      /** The stages the main thread has worker-backed row models for. */\n      stages: Array<TableWorkerStage>\n      /** Serializable state slices (union of the stages' deps). */\n      state: Record<string, unknown>\n    }\n\nexport interface TableWorkerResult {\n  type: 'result'\n  requestId: number\n  dataVersion: number\n  stages: { [K in TableWorkerStage]?: TableWorkerStagePayload }\n  computeMs: number\n}\n\nexport type TableWorkerResponse = TableWorkerResult\n\n/**\n * The state slice added by `workerRowModelsFeature`. `version` bumps when a\n * worker result lands (driving re-renders through the normal state path);\n * `isPending` is true while a request is in flight. The timing fields expose\n * the last result's worker compute time and full round trip for devtools and\n * debugging.\n */\nexport interface TableState_WorkerRowModels {\n  workerRowModels: {\n    version: number\n    isPending: boolean\n    lastComputeMs?: number\n    lastRoundTripMs?: number\n  }\n}\n"],"mappings":";;;;;;AAOA,MAAa,sBAAsB;CACjC;CACA;CACA;CACA;AACF;;;;;;AASA,MAAa,4BAGT;CACF,UAAU,CAAC,iBAAiB,cAAc;CAC1C,SAAS,CAAC,UAAU;CACpB,QAAQ,CAAC,SAAS;CAClB,UAAU,CAAC,UAAU;AACvB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/table-core",
-  "version": "9.0.0-beta.31",
+  "version": "9.0.0-beta.33",
   "description": "Headless UI for building powerful tables & datagrids for TS/JS.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -35,6 +35,10 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./experimental-worker-plugin": {
+      "import": "./dist/experimental-worker-plugin.js",
+      "require": "./dist/experimental-worker-plugin.cjs"
+    },
     "./flex-render": {
       "import": "./dist/flex-render.js",
       "require": "./dist/flex-render.cjs"
@@ -55,7 +59,7 @@
   },
   "sideEffects": false,
   "engines": {
-    "node": ">=16"
+    "node": ">=20"
   },
   "files": [
     "dist/",

package/src/experimental-worker-plugin.ts

@@ -0,0 +1,22 @@
+/**
+ * Web Worker row models sub-entry (experimental POC).
+ *
+ * Offloads row model stages to a dedicated worker running a headless "shadow
+ * table" built with the same table-core row model pipeline. The main thread
+ * receives transferable index permutations and rebuilds its row models from
+ * them, stale-while-revalidate style.
+ *
+ * Main thread:
+ * - `createTableWorker` — one shared handle per table worker
+ * - `createWorkerRowModel` — turns any flat row model stage into a
+ *   worker-backed factory for the matching `features` slot
+ * - `workerRowModelsFeature` — registers the `workerRowModels` state slice
+ *
+ * Worker entry (user-authored file):
+ * - `initTableWorker` — runs the shadow table; computes only the stages whose
+ *   row model factories are registered in its config
+ */
+export * from './worker/tableWorkerProtocol'
+export * from './worker/initTableWorker'
+export * from './worker/createTableWorker'
+export * from './worker/createWorkerRowModel'

package/src/worker/createTableWorker.ts

@@ -0,0 +1,357 @@
+import { table_autoResetPageIndex } from '../features/row-pagination/rowPaginationFeature.utils'
+import { table_autoResetExpanded } from '../features/row-expanding/rowExpandingFeature.utils'
+import {
+  tableWorkerPipeline,
+  tableWorkerStageStateDeps,
+} from './tableWorkerProtocol'
+import type { Table_Internal } from '../types/Table'
+import type { TableFeature } from '../types/TableFeatures'
+import type { TableWorkerDataPayload } from './rebuildRowModel'
+import type {
+  TableState_WorkerRowModels,
+  TableWorkerResponse,
+  TableWorkerStage,
+  TableWorkerStagePayload,
+} from './tableWorkerProtocol'
+
+// Importing anything from this module (e.g. `workerRowModelsFeature`)
+// registers the plugin key and its state slice with the core type maps, so
+// userland needs no `declare module` of its own. Apps that never use worker
+// row models never load this module and never see the types.
+declare module '../types/TableFeatures' {
+  interface Plugins {
+    workerRowModelsFeature: TableFeature
+  }
+}
+declare module '../types/TableState' {
+  interface TableState_FeatureMap {
+    workerRowModelsFeature: TableState_WorkerRowModels
+  }
+}
+
+export interface TableWorkerOptions {
+  /**
+   * Creates the dedicated worker that runs the shadow table. The worker entry
+   * must call `initTableWorker` with the same columns and processing config.
+   *
+   * The `new Worker(new URL(...))` expression must live in your code (not the
+   * library) so your bundler can statically discover and bundle the worker
+   * entry file.
+   *
+   * @example
+   * ```ts
+   * createWorker: () =>
+   *   new Worker(new URL('./table.worker.ts', import.meta.url), {
+   *     type: 'module',
+   *   })
+   * ```
+   */
+  createWorker: () => Worker
+}
+
+export interface TableWorkerBridge {
+  worker: Worker | null
+  /** The worker errored (load failure or uncaught throw); stop posting. */
+  failed: boolean
+  lastData: unknown
+  dataVersion: number
+  requestId: number
+  resultRequestId: number
+  /** A process request has been posted and its result has not arrived yet. */
+  inFlight: boolean
+  /** State changed since the last posted request; post when possible. */
+  needsProcess: boolean
+  sentAt: number
+  /** The stages registered on this table (grows as factories initialize). */
+  stages: Set<TableWorkerStage>
+  /** Snapshot of state refs + stage count captured at the last post. */
+  sentState: Record<string, unknown> | null
+  sentStageCount: number
+  /** Latest observed state refs, posted on the trailing edge if in flight. */
+  lastState: Record<string, unknown>
+  results: { [K in TableWorkerStage]?: TableWorkerDataPayload }
+  /** Bumped per stage only when that stage's payload actually changed. */
+  stageVersions: { [K in TableWorkerStage]?: number }
+}
+
+type AnyTable = Table_Internal<any, any>
+
+/**
+ * A handle shared by every worker-backed row model on a table. It owns the
+ * worker instance and the per-table request/result bookkeeping, so registering
+ * one stage or four costs exactly one worker and one round trip per change.
+ */
+export interface TableWorker {
+  _options: TableWorkerOptions
+  _bridges: WeakMap<object, TableWorkerBridge>
+  _liveBridges: Set<TableWorkerBridge>
+  /**
+   * Terminates every worker created through this handle and resets the
+   * bookkeeping. Safe to call at any time: the next row model read lazily
+   * recreates the worker and re-sends the data (self-healing). Note that
+   * nothing calls this automatically yet; React StrictMode double-mounts and
+   * HMR updates still leak a worker in development until the reactivity
+   * bindings grow a real `unmount` hook.
+   */
+  terminate: () => void
+}
+
+/**
+ * Registers the `workerRowModels` state slice
+ * (`{ version, isPending, lastComputeMs, lastRoundTripMs }`). Worker results
+ * land by bumping `version`, so re-renders flow through the exact same state
+ * mechanism as every other table state change.
+ */
+export const workerRowModelsFeature: TableFeature = {
+  getInitialState: (initialState: any) => ({
+    workerRowModels: { version: 0, isPending: false },
+    ...initialState,
+  }),
+}
+
+/**
+ * Creates the shared worker handle for a table's worker-backed row models.
+ * Pass it to `createWorkerRowModel()` once per stage you want offloaded.
+ */
+export function createTableWorker(options: TableWorkerOptions): TableWorker {
+  const liveBridges = new Set<TableWorkerBridge>()
+  return {
+    _options: options,
+    _bridges: new WeakMap(),
+    _liveBridges: liveBridges,
+    terminate: () => {
+      for (const bridge of liveBridges) {
+        bridge.worker?.terminate()
+        bridge.worker = null
+        bridge.failed = false
+        bridge.lastData = undefined
+        bridge.inFlight = false
+        bridge.needsProcess = true
+        bridge.sentState = null
+        bridge.sentStageCount = 0
+      }
+      liveBridges.clear()
+    },
+  }
+}
+
+export function getTableWorkerBridge(
+  tableWorker: TableWorker,
+  table: AnyTable,
+): TableWorkerBridge {
+  let bridge = tableWorker._bridges.get(table)
+  if (!bridge) {
+    bridge = {
+      worker: null,
+      failed: false,
+      lastData: undefined,
+      dataVersion: 0,
+      requestId: 0,
+      resultRequestId: 0,
+      inFlight: false,
+      needsProcess: true,
+      sentAt: 0,
+      stages: new Set(),
+      sentState: null,
+      sentStageCount: 0,
+      lastState: {},
+      results: {},
+      stageVersions: {},
+    }
+    tableWorker._bridges.set(table, bridge)
+  }
+  return bridge
+}
+
+/** Shallow reference comparison; atoms return stable refs when unchanged. */
+function statesEqual(
+  a: Record<string, unknown> | null,
+  b: Record<string, unknown>,
+): boolean {
+  if (a === null) return false
+  const aKeys = Object.keys(a)
+  const bKeys = Object.keys(b)
+  if (aKeys.length !== bKeys.length) return false
+  for (const key of bKeys) {
+    if (a[key] !== b[key]) return false
+  }
+  return true
+}
+
+function setWorkerRowModelsState(
+  table: AnyTable,
+  update: (prev: any) => Record<string, unknown>,
+) {
+  const stateAtom = (table.baseAtoms as Record<string, any>).workerRowModels
+  stateAtom?.set((prev: any) => update(prev ?? { version: 0 }))
+}
+
+function postProcess(table: AnyTable, bridge: TableWorkerBridge): void {
+  const stages = tableWorkerPipeline.filter((stage) => bridge.stages.has(stage))
+  bridge.needsProcess = false
+  bridge.sentState = bridge.lastState
+  bridge.sentStageCount = bridge.stages.size
+  bridge.inFlight = true
+  bridge.sentAt = performance.now()
+  const requestId = ++bridge.requestId
+  bridge.worker!.postMessage({
+    type: 'process',
+    requestId,
+    dataVersion: bridge.dataVersion,
+    stages,
+    state: bridge.lastState,
+  })
+  // postProcess can run during render (via sync); defer the pending write.
+  table._reactivity.schedule(() => {
+    if (bridge.requestId === requestId && bridge.resultRequestId < requestId) {
+      setWorkerRowModelsState(table, (prev) => ({ ...prev, isPending: true }))
+    }
+  })
+}
+
+function handleResult(
+  table: AnyTable,
+  bridge: TableWorkerBridge,
+  message: TableWorkerResponse,
+) {
+  if (message.requestId !== bridge.requestId) return
+  bridge.inFlight = false
+  bridge.resultRequestId = message.requestId
+
+  // A data change raced this request: the result is for the old dataset.
+  // Drop it and immediately re-process against the new data.
+  if (message.dataVersion !== bridge.dataVersion) {
+    postProcess(table, bridge)
+    return
+  }
+
+  // Merge stage payloads: `unchanged` keeps the previous result (and its
+  // rebuilt model, via the per-stage version), changed payloads replace it.
+  let anyChanged = false
+  let groupedChanged = false
+  for (const [stage, payload] of Object.entries(message.stages) as Array<
+    [TableWorkerStage, TableWorkerStagePayload]
+  >) {
+    if (payload.kind === 'unchanged') continue
+    bridge.results[stage] = payload
+    bridge.stageVersions[stage] = (bridge.stageVersions[stage] ?? 0) + 1
+    anyChanged = true
+    if (stage === 'grouped') groupedChanged = true
+  }
+
+  const roundTripMs = performance.now() - bridge.sentAt
+  setWorkerRowModelsState(table, (prev) => ({
+    version: (prev.version ?? 0) + 1,
+    isPending: false,
+    lastComputeMs: message.computeMs,
+    lastRoundTripMs: roundTripMs,
+  }))
+
+  // The async equivalent of the sync models' `onAfterUpdate` hooks. The
+  // worker's unchanged-detection is its memo identity, so `groupedChanged`
+  // mirrors exactly when the sync grouped model would have recomputed (and
+  // reset expansion).
+  if (anyChanged) {
+    table._reactivity.schedule(() =>
+      table._reactivity.untrack(() => {
+        if (groupedChanged) {
+          table_autoResetExpanded(table)
+        }
+        table_autoResetPageIndex(table)
+      }),
+    )
+  }
+
+  // Trailing edge: state changed while this request was in flight.
+  if (bridge.needsProcess) {
+    postProcess(table, bridge)
+  }
+}
+
+function handleError(
+  table: AnyTable,
+  bridge: TableWorkerBridge,
+  event: unknown,
+) {
+  if (bridge.failed) return
+  bridge.failed = true
+  bridge.inFlight = false
+  console.error(
+    '[table-worker] The table worker failed; worker row models will keep ' +
+      'their last results and stop updating. Check that the worker entry ' +
+      'loads and that its initTableWorker() config is thread-portable.',
+    event,
+  )
+  bridge.worker?.terminate()
+  bridge.worker = null
+  setWorkerRowModelsState(table, (prev) => ({ ...prev, isPending: false }))
+}
+
+function ensureWorker(
+  tableWorker: TableWorker,
+  table: AnyTable,
+  bridge: TableWorkerBridge,
+) {
+  if (bridge.worker) return
+  bridge.worker = tableWorker._options.createWorker()
+  tableWorker._liveBridges.add(bridge)
+  bridge.worker.onmessage = (event: MessageEvent<TableWorkerResponse>) => {
+    handleResult(table, bridge, event.data)
+  }
+  bridge.worker.onerror = (event) => handleError(table, bridge, event)
+  bridge.worker.onmessageerror = (event) => handleError(table, bridge, event)
+}
+
+/**
+ * Pull-based sync, called at the top of every worker-backed row model read
+ * (i.e. every render). Posts data on identity change and a single-flight
+ * process request on state change; both are cheap no-ops otherwise, and
+ * multiple stages sharing the handle dedupe onto one request.
+ */
+export function syncTableWorker(tableWorker: TableWorker, table: AnyTable) {
+  // SSR: no Worker global. Getters fall back to pre-stage models, so the
+  // server renders unprocessed rows and the client takes over after hydration.
+  if (typeof Worker === 'undefined') return
+
+  const bridge = getTableWorkerBridge(tableWorker, table)
+  if (bridge.failed) return
+  ensureWorker(tableWorker, table, bridge)
+
+  const data = table.options.data
+  if (data !== bridge.lastData) {
+    bridge.lastData = data
+    bridge.dataVersion++
+    bridge.worker!.postMessage({
+      type: 'data',
+      dataVersion: bridge.dataVersion,
+      data,
+    })
+    bridge.needsProcess = true
+  }
+
+  // Union of the registered stages' state deps, compared by reference (atoms
+  // return stable refs when a slice did not change).
+  const atoms = table.atoms as Record<string, any>
+  const state: Record<string, unknown> = {}
+  for (const stage of bridge.stages) {
+    for (const key of tableWorkerStageStateDeps[stage]) {
+      state[key] = atoms[key]?.get()
+    }
+  }
+  bridge.lastState = state
+
+  if (
+    !bridge.needsProcess &&
+    (!statesEqual(bridge.sentState, state) ||
+      bridge.stages.size !== bridge.sentStageCount)
+  ) {
+    bridge.needsProcess = true
+  }
+
+  // Single-flight: at most one request in the worker at a time. If one is in
+  // flight, the latest state is posted from the result handler (trailing
+  // edge), so rapid input coalesces instead of queueing doomed computes.
+  if (bridge.needsProcess && !bridge.inFlight) {
+    postProcess(table, bridge)
+  }
+}