diff --git a/docs/superpowers/plans/2026-06-19-filter-header-menu.md b/docs/superpowers/plans/2026-06-19-filter-header-menu.md
new file mode 100644
index 00000000..31b51703
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-19-filter-header-menu.md
@@ -0,0 +1,825 @@
+# Filter Header Menu — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** A built-in per-column header filter menu in `@pretable/react` (funnel → popover with operator select + typed value control), styled in `@pretable/ui`, driving the merged engine filter API. On-by-default for `filterable` columns; live-apply; uncontrolled or controlled via `state.filters`; fires `onFiltersChange`.
+
+**Architecture:** A pure `filter-operators.ts` module (operators-per-type, value-shape, completeness gating, draft↔`ColumnFilter` conversion) underpins three React components (`FunnelButton`, `FilterMenu`, plus a `useFilterPopover` open/position hook). The surface renders one funnel **overlay** per header (absolutely-positioned sibling of the resize handle — the header is itself a `<button>`, so the funnel must NOT nest inside it) and a single `FilterMenu` dialog at the surface root (fixed-position, mirroring the reorder ghost, to escape header clipping). CSS lives in `@pretable/ui/grid.css` via `:where()` + `data-pretable-filter-*`.
+
+**Tech Stack:** React 19, TypeScript, Vitest + Testing Library, vanilla CSS (no Tailwind in packages, no runtime deps). api-extractor (required gate). Commands: `pnpm -r typecheck`/`lint`/`test`, `pnpm --filter @pretable/react test`, `pnpm format`(check)/`format:write`, `pnpm api`.
+
+**Key facts (verified against code):**
+
+- Engine API (merged #180): `grid.setColumnFilter(id, ColumnFilter | null)`, `grid.replaceFilters(Record<string,ColumnFilter>)`, `grid.distinctColumnValues(id): string[]`, `snapshot.filters: Record<string,ColumnFilter>`. Types `ColumnFilter`/`FilterOperator`/`FilterType`/`FilterOption`/`FilterValue` are exported from `@pretable/core` and re-exported from `@pretable/react` (`react/src/public_api.ts:61-64`). Columns carry `filterType`/`filterOptions`/`filterable`.
+- Header render: `pretable-surface.tsx` returns per-column an array `[<button role="columnheader" …>, resizeHandle?]` (header button ~`:1281`, resize handle ~`:1479`). `effWidth`, `plannedCol.left`, `plannedCol.pinned`, `pinnedOffset` are in scope. The resize handle is `position:absolute; top:0; height:100%; width:4; left: plannedCol.left + effWidth - 4; zIndex:4` with a `handlePinnedStyle` (sticky) for pinned columns. **Mirror this for the funnel overlay**, offset further left.
+- Props: `PretableSurfaceProps` (~`:188-287`) has `onSortChange`, `onColumnWidthsChange`, etc.; destructured ~`:428-451`. Controlled `state.filters` already applies via `usePretable` (`use-pretable.ts`, `grid.replaceFilters(state.filters)`).
+- Snapshot is available in the surface as `snapshot` (from `usePretable`), so `snapshot.filters[id]` gives a column's active filter and the funnel's active state.
+- CSS: `grid.css` uses `@layer pretable` + `:where([data-pretable-*])`; existing `[data-pretable-popover]` rule (~`:222`) uses `--pretable-bg-tooltip`/`--pretable-rule`/`--pretable-radius`. Token contract test: `packages/ui/src/__tests__/contract.test.ts` (TOKENS list, 42 tokens) — only touch if adding a token.
+- Tests: `packages/react/src/__tests__/pretable-surface.test.tsx` (sort-click test ~`:240` to mirror). RTL via `@testing-library/react`.
+
+---
+
+## File Structure
+
+New under `packages/react/src/filter-menu/`:
+
+- `filter-operators.ts` — pure helpers (no React).
+- `FunnelButton.tsx` — header funnel overlay button.
+- `useFilterPopover.ts` — open-state + fixed-position-from-rect + outside-click/Escape.
+- `FilterMenu.tsx` — the popover dialog.
+- `index.ts` — barrel for the above (internal).
+
+Modified:
+
+- `packages/react/src/pretable-surface.tsx` — funnel overlay per header, single `FilterMenu` at root, `onFiltersChange` prop.
+- `packages/ui/src/grid.css` — `data-pretable-filter-*` styling.
+- Tests: `packages/react/src/__tests__/filter-operators.test.ts`, `packages/react/src/__tests__/filter-menu.test.tsx`.
+- `packages/react/react.api.md` — regenerated.
+
+---
+
+## Task 1: `filter-operators.ts` (pure helpers, fully tested)
+
+**Files:**
+
+- Create: `packages/react/src/filter-menu/filter-operators.ts`
+- Test: `packages/react/src/__tests__/filter-operators.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+// packages/react/src/__tests__/filter-operators.test.ts
+import { describe, expect, it } from "vitest";
+import {
+  operatorsForType,
+  operatorValueShape,
+  isComplete,
+  toColumnFilter,
+  fromColumnFilter,
+  OPERATOR_LABELS,
+  type FilterDraft,
+} from "../filter-menu/filter-operators";
+
+describe("operatorsForType", () => {
+  it("lists the operators for each type incl. shared empties", () => {
+    expect(operatorsForType("text")).toEqual([
+      "contains",
+      "notContains",
+      "equals",
+      "notEquals",
+      "startsWith",
+      "endsWith",
+      "isEmpty",
+      "isNotEmpty",
+    ]);
+    expect(operatorsForType("number")).toEqual([
+      "equals",
+      "notEquals",
+      "gt",
+      "gte",
+      "lt",
+      "lte",
+      "between",
+      "isEmpty",
+      "isNotEmpty",
+    ]);
+    expect(operatorsForType("date")).toEqual([
+      "on",
+      "before",
+      "after",
+      "dateBetween",
+      "isEmpty",
+      "isNotEmpty",
+    ]);
+    expect(operatorsForType("enum")).toEqual([
+      "isAnyOf",
+      "isNoneOf",
+      "isEmpty",
+      "isNotEmpty",
+    ]);
+  });
+  it("every operator has a label", () => {
+    for (const t of ["text", "number", "date", "enum"] as const)
+      for (const op of operatorsForType(t))
+        expect(OPERATOR_LABELS[op]).toBeTruthy();
+  });
+});
+
+describe("operatorValueShape", () => {
+  it("classifies operators", () => {
+    expect(operatorValueShape("contains")).toBe("single");
+    expect(operatorValueShape("between")).toBe("range");
+    expect(operatorValueShape("dateBetween")).toBe("range");
+    expect(operatorValueShape("isAnyOf")).toBe("set");
+    expect(operatorValueShape("isEmpty")).toBe("none");
+    expect(operatorValueShape("isNotEmpty")).toBe("none");
+  });
+});
+
+describe("isComplete + toColumnFilter (gating)", () => {
+  it("text single value", () => {
+    const d: FilterDraft = { operator: "contains", text: "ab" };
+    expect(isComplete("text", d)).toBe(true);
+    expect(toColumnFilter("text", d)).toEqual({
+      operator: "contains",
+      value: "ab",
+    });
+    expect(isComplete("text", { operator: "contains", text: "" })).toBe(false);
+    expect(
+      toColumnFilter("text", { operator: "contains", text: "" }),
+    ).toBeNull();
+  });
+  it("number single + parses", () => {
+    expect(toColumnFilter("number", { operator: "gt", text: "5" })).toEqual({
+      operator: "gt",
+      value: 5,
+    });
+    expect(toColumnFilter("number", { operator: "gt", text: "x" })).toBeNull();
+  });
+  it("between needs both bounds", () => {
+    expect(
+      isComplete("number", { operator: "between", min: "1", max: "" }),
+    ).toBe(false);
+    expect(
+      toColumnFilter("number", { operator: "between", min: "1", max: "" }),
+    ).toBeNull();
+    expect(
+      toColumnFilter("number", { operator: "between", min: "1", max: "10" }),
+    ).toEqual({ operator: "between", value: [1, 10] });
+  });
+  it("dateBetween needs both ISO bounds", () => {
+    expect(
+      toColumnFilter("date", {
+        operator: "dateBetween",
+        min: "2026-01-01",
+        max: "",
+      }),
+    ).toBeNull();
+    expect(
+      toColumnFilter("date", {
+        operator: "dateBetween",
+        min: "2026-01-01",
+        max: "2026-02-01",
+      }),
+    ).toEqual({ operator: "dateBetween", value: ["2026-01-01", "2026-02-01"] });
+  });
+  it("date single", () => {
+    expect(
+      toColumnFilter("date", { operator: "before", text: "2026-06-18" }),
+    ).toEqual({ operator: "before", value: "2026-06-18" });
+  });
+  it("enum set; empty selection is incomplete", () => {
+    expect(isComplete("enum", { operator: "isAnyOf", selected: [] })).toBe(
+      false,
+    );
+    expect(
+      toColumnFilter("enum", { operator: "isAnyOf", selected: [] }),
+    ).toBeNull();
+    expect(
+      toColumnFilter("enum", { operator: "isAnyOf", selected: ["a", "b"] }),
+    ).toEqual({ operator: "isAnyOf", value: ["a", "b"] });
+  });
+  it("none-shape ops are always complete with no value", () => {
+    expect(isComplete("text", { operator: "isEmpty" })).toBe(true);
+    expect(toColumnFilter("text", { operator: "isEmpty" })).toEqual({
+      operator: "isEmpty",
+    });
+  });
+});
+
+describe("fromColumnFilter (hydrate)", () => {
+  it("round-trips each shape", () => {
+    expect(
+      fromColumnFilter("text", { operator: "contains", value: "ab" }),
+    ).toEqual({ operator: "contains", text: "ab" });
+    expect(
+      fromColumnFilter("number", { operator: "between", value: [1, 10] }),
+    ).toEqual({ operator: "between", min: "1", max: "10" });
+    expect(
+      fromColumnFilter("enum", { operator: "isAnyOf", value: ["a"] }),
+    ).toEqual({ operator: "isAnyOf", selected: ["a"] });
+    expect(fromColumnFilter("text", { operator: "isEmpty" })).toEqual({
+      operator: "isEmpty",
+    });
+  });
+  it("returns a default draft for null", () => {
+    expect(fromColumnFilter("text", null)).toEqual({
+      operator: "contains",
+      text: "",
+    });
+    expect(fromColumnFilter("enum", null)).toEqual({
+      operator: "isAnyOf",
+      selected: [],
+    });
+  });
+});
+```
+
+- [ ] **Step 2: Run the test to confirm it fails**
+
+Run: `pnpm --filter @pretable/react test -- filter-operators`
+Expected: FAIL — module not found.
+
+- [ ] **Step 3: Implement `filter-operators.ts`**
+
+```ts
+// packages/react/src/filter-menu/filter-operators.ts
+import type { ColumnFilter, FilterOperator, FilterType } from "@pretable/core";
+
+/** Local editing shape for the popover. One field set per value-shape. */
+export interface FilterDraft {
+  operator: FilterOperator;
+  text?: string; // single (text/number/date)
+  min?: string; // range lower
+  max?: string; // range upper
+  selected?: string[]; // set (enum)
+}
+
+export type ValueShape = "none" | "single" | "range" | "set";
+
+const TEXT_OPS: FilterOperator[] = [
+  "contains",
+  "notContains",
+  "equals",
+  "notEquals",
+  "startsWith",
+  "endsWith",
+];
+const NUMBER_OPS: FilterOperator[] = [
+  "equals",
+  "notEquals",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "between",
+];
+const DATE_OPS: FilterOperator[] = ["on", "before", "after", "dateBetween"];
+const ENUM_OPS: FilterOperator[] = ["isAnyOf", "isNoneOf"];
+const SHARED_OPS: FilterOperator[] = ["isEmpty", "isNotEmpty"];
+
+export function operatorsForType(type: FilterType): FilterOperator[] {
+  const base =
+    type === "number"
+      ? NUMBER_OPS
+      : type === "date"
+        ? DATE_OPS
+        : type === "enum"
+          ? ENUM_OPS
+          : TEXT_OPS;
+  return [...base, ...SHARED_OPS];
+}
+
+export const OPERATOR_LABELS: Record<FilterOperator, string> = {
+  contains: "contains",
+  notContains: "does not contain",
+  equals: "equals",
+  notEquals: "does not equal",
+  startsWith: "starts with",
+  endsWith: "ends with",
+  gt: "greater than",
+  gte: "greater than or equal",
+  lt: "less than",
+  lte: "less than or equal",
+  between: "is between",
+  isAnyOf: "is any of",
+  isNoneOf: "is none of",
+  on: "on",
+  before: "before",
+  after: "after",
+  dateBetween: "is between",
+  isEmpty: "is empty",
+  isNotEmpty: "is not empty",
+};
+
+const RANGE_OPS = new Set<FilterOperator>(["between", "dateBetween"]);
+const SET_OPS = new Set<FilterOperator>(["isAnyOf", "isNoneOf"]);
+const NONE_OPS = new Set<FilterOperator>(["isEmpty", "isNotEmpty"]);
+
+export function operatorValueShape(op: FilterOperator): ValueShape {
+  if (NONE_OPS.has(op)) return "none";
+  if (RANGE_OPS.has(op)) return "range";
+  if (SET_OPS.has(op)) return "set";
+  return "single";
+}
+
+export function defaultDraft(type: FilterType): FilterDraft {
+  const operator = operatorsForType(type)[0]!;
+  if (operatorValueShape(operator) === "set") return { operator, selected: [] };
+  if (operatorValueShape(operator) === "range")
+    return { operator, min: "", max: "" };
+  return { operator, text: "" };
+}
+
+const isNum = (s: string | undefined): s is string =>
+  s !== undefined && s.trim() !== "" && !Number.isNaN(Number(s));
+
+export function isComplete(type: FilterType, d: FilterDraft): boolean {
+  const shape = operatorValueShape(d.operator);
+  if (shape === "none") return true;
+  if (shape === "set") return (d.selected?.length ?? 0) > 0;
+  if (shape === "range") {
+    if (type === "number") return isNum(d.min) && isNum(d.max);
+    return !!d.min && !!d.max; // date ISO strings
+  }
+  // single
+  if (type === "number") return isNum(d.text);
+  return !!d.text && d.text.trim() !== "";
+}
+
+export function toColumnFilter(
+  type: FilterType,
+  d: FilterDraft,
+): ColumnFilter | null {
+  const shape = operatorValueShape(d.operator);
+  if (shape === "none") return { operator: d.operator };
+  if (!isComplete(type, d)) return null;
+  if (shape === "set") return { operator: d.operator, value: [...d.selected!] };
+  if (shape === "range") {
+    if (type === "number")
+      return { operator: d.operator, value: [Number(d.min), Number(d.max)] };
+    return { operator: d.operator, value: [d.min!, d.max!] };
+  }
+  // single
+  if (type === "number") return { operator: d.operator, value: Number(d.text) };
+  return { operator: d.operator, value: d.text! };
+}
+
+export function fromColumnFilter(
+  type: FilterType,
+  filter: ColumnFilter | null,
+): FilterDraft {
+  if (!filter) return defaultDraft(type);
+  const { operator, value } = filter;
+  const shape = operatorValueShape(operator);
+  if (shape === "none") return { operator };
+  if (shape === "set")
+    return {
+      operator,
+      selected: Array.isArray(value) ? value.map(String) : [],
+    };
+  if (shape === "range") {
+    const arr = Array.isArray(value) ? value : ["", ""];
+    return { operator, min: String(arr[0] ?? ""), max: String(arr[1] ?? "") };
+  }
+  return {
+    operator,
+    text: value === null || value === undefined ? "" : String(value),
+  };
+}
+```
+
+- [ ] **Step 4: Run the test to confirm it passes**
+
+Run: `pnpm --filter @pretable/react test -- filter-operators`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/react/src/filter-menu/filter-operators.ts packages/react/src/__tests__/filter-operators.test.ts
+git commit -m "feat(react): pure filter-operators helpers for the header menu"
+```
+
+---
+
+## Task 2: `FunnelButton`, `useFilterPopover`, `FilterMenu` components (+ direct RTL tests)
+
+**Files:**
+
+- Create: `packages/react/src/filter-menu/FunnelButton.tsx`, `useFilterPopover.ts`, `FilterMenu.tsx`, `index.ts`
+- Test: `packages/react/src/__tests__/filter-menu.test.tsx` (component-level, rendering `FilterMenu` directly)
+
+- [ ] **Step 1: Write `FunnelButton.tsx`**
+
+A presentational button (the surface positions it). Inline-SVG funnel; no icon font.
+
+```tsx
+// packages/react/src/filter-menu/FunnelButton.tsx
+import type { CSSProperties } from "react";
+
+export function FunnelButton({
+  columnId,
+  label,
+  active,
+  open,
+  style,
+  onToggle,
+}: {
+  columnId: string;
+  label: string;
+  active: boolean;
+  open: boolean;
+  style?: CSSProperties;
+  onToggle: (columnId: string) => void;
+}) {
+  return (
+    <button
+      type="button"
+      data-pretable-filter-funnel=""
+      data-pretable-column-id={columnId}
+      data-pretable-filter-active={active ? "true" : "false"}
+      aria-haspopup="dialog"
+      aria-expanded={open}
+      aria-label={`Filter ${label}`}
+      style={style}
+      onPointerDown={(e) => e.stopPropagation()}
+      onClick={(e) => {
+        e.stopPropagation();
+        onToggle(columnId);
+      }}
+    >
+      <svg
+        viewBox="0 0 16 16"
+        width="11"
+        height="11"
+        aria-hidden="true"
+        focusable="false"
+      >
+        <path d="M1.5 2.5h13l-5 6v4l-3 1.5v-5.5l-5-6z" fill="currentColor" />
+      </svg>
+    </button>
+  );
+}
+```
+
+(The `stopPropagation` on pointer-down/click is belt-and-suspenders even though the funnel is a sibling of — not a child of — the header sort button.)
+
+- [ ] **Step 2: Write `useFilterPopover.ts`** — open-state + position-from-rect + dismiss.
+
+```tsx
+// packages/react/src/filter-menu/useFilterPopover.ts
+import { useCallback, useEffect, useState } from "react";
+
+export interface PopoverState {
+  columnId: string;
+  rect: DOMRect;
+}
+
+export function useFilterPopover() {
+  const [openState, setOpenState] = useState<PopoverState | null>(null);
+
+  const toggle = useCallback(
+    (columnId: string, anchorEl: HTMLElement | null) => {
+      setOpenState((prev) => {
+        if (prev?.columnId === columnId) return null;
+        const rect = anchorEl?.getBoundingClientRect();
+        return rect ? { columnId, rect } : null;
+      });
+    },
+    [],
+  );
+
+  const close = useCallback(() => setOpenState(null), []);
+
+  useEffect(() => {
+    if (!openState) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") close();
+    };
+    // Close on scroll/resize so the popover never floats away from its anchor.
+    const onViewportChange = () => close();
+    document.addEventListener("keydown", onKey);
+    window.addEventListener("resize", onViewportChange);
+    window.addEventListener("scroll", onViewportChange, true);
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      window.removeEventListener("resize", onViewportChange);
+      window.removeEventListener("scroll", onViewportChange, true);
+    };
+  }, [openState, close]);
+
+  return { openState, toggle, close };
+}
+
+/** Fixed-position style from the anchor rect, flipped near the right/bottom edges. */
+export function popoverStyle(rect: DOMRect): React.CSSProperties {
+  const WIDTH = 240;
+  const MARGIN = 8;
+  const vw = typeof window !== "undefined" ? window.innerWidth : 1024;
+  const left = Math.min(rect.left, vw - WIDTH - MARGIN);
+  return {
+    position: "fixed",
+    top: rect.bottom + 4,
+    left: Math.max(MARGIN, left),
+    width: WIDTH,
+    zIndex: 50,
+  };
+}
+```
+
+- [ ] **Step 3: Write `FilterMenu.tsx`** — the dialog. Renders operator `<select>` + value control by shape; live-applies via the `onChange` prop (debounced for `single`/`range` text inputs); a Clear button; hydrates draft from `initialFilter`; closes on outside-click.
+
+Contract:
+
+```tsx
+export function FilterMenu({
+  columnId,
+  label,
+  filterType,
+  options,
+  initialFilter,
+  style,
+  onChange,
+  onClose,
+}: {
+  columnId: string;
+  label: string;
+  filterType: FilterType;
+  options: { value: string; label?: string }[]; // enum choices (already resolved)
+  initialFilter: ColumnFilter | null;
+  style?: React.CSSProperties;
+  onChange: (columnId: string, filter: ColumnFilter | null) => void; // null = clear
+  onClose: () => void;
+}): JSX.Element;
+```
+
+Implementation notes (write idiomatic React; the exact JSX is yours but must satisfy the tests):
+
+- `const [draft, setDraft] = useState(() => fromColumnFilter(filterType, initialFilter));`
+- On operator change: reset value fields to the new shape's empty draft (keep selection only if still a set op), then push.
+- A single `push(nextDraft)` helper computes `toColumnFilter(filterType, nextDraft)` and calls `onChange(columnId, result)` (result may be `null` → clears). For `single`/`range` **text** inputs, debounce `push` ~200ms (use a ref'd timer; flush on unmount); for `select`/`checkbox`/`date`/number-step changes call `push` immediately. (Simplest: debounce only the free-text `single` `text` input; number/date inputs can debounce too — acceptable. Keep one debounce path keyed on "is this a typed text field".)
+- Value control by `operatorValueShape(draft.operator)`:
+  - `none` → render nothing.
+  - `single` → one `<input>` (`type="date"` when `filterType==="date"`, else `type="text"`/`inputMode="numeric"` for number) bound to `draft.text`.
+  - `range` → two inputs bound to `draft.min`/`draft.max` (date or number).
+  - `set` → a checkbox list from `options`; toggling updates `draft.selected`.
+- Container: `<div role="dialog" aria-label={`Filter ${label}`} data-pretable-filter-menu="" data-pretable-popover="" style={style}>`. On mount, focus the operator `<select>`.
+- Clear button: `data-pretable-filter-clear`, calls `onChange(columnId, null)` and resets draft to `defaultDraft`.
+- Outside-click: a `useEffect` adding a `pointerdown` listener on `document`; if the target isn't inside the dialog root (ref), call `onClose()`.
+
+- [ ] **Step 4: `index.ts` barrel**
+
+```ts
+export { FunnelButton } from "./FunnelButton";
+export { FilterMenu } from "./FilterMenu";
+export { useFilterPopover, popoverStyle } from "./useFilterPopover";
+```
+
+- [ ] **Step 5: Write `filter-menu.test.tsx` (component-level)** — render `FilterMenu` directly with a spy `onChange` and fake timers. Cover:
+  - text column: default operator `contains`; type into the value input → after debounce, `onChange("c", {operator:"contains", value:"…"})`.
+  - switch operator to `isEmpty` → value input disappears; `onChange("c", {operator:"isEmpty"})` immediately.
+  - number column `between`: fill only min → `onChange` last call is `null` (cleared); fill both → `{operator:"between", value:[min,max]}`.
+  - enum column: render options as checkboxes; check two → `{operator:"isAnyOf", value:[...]}`; uncheck all → `null`.
+  - Clear button → `onChange("c", null)`.
+  - dialog has `role="dialog"` + accessible name; operator select is focused on mount.
+
+  Use `vi.useFakeTimers()` + `await vi.advanceTimersByTimeAsync(250)` around debounced assertions; wrap interactions in `act`.
+
+- [ ] **Step 6: Run tests + typecheck the package**
+
+Run: `pnpm --filter @pretable/react test -- filter-menu` and `pnpm --filter @pretable/react typecheck`.
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add packages/react/src/filter-menu packages/react/src/__tests__/filter-menu.test.tsx
+git commit -m "feat(react): FunnelButton, FilterMenu, useFilterPopover components"
+```
+
+---
+
+## Task 3: Wire into the surface + `@pretable/ui` CSS + integration test
+
+**Files:**
+
+- Modify: `packages/react/src/pretable-surface.tsx`
+- Modify: `packages/ui/src/grid.css`
+- Test: extend `packages/react/src/__tests__/filter-menu.test.tsx` with surface-integration cases (or a new `filter-menu-surface.test.tsx`).
+
+- [ ] **Step 1: Add the `onFiltersChange` prop**
+
+In `PretableSurfaceProps`, after `onTelemetryChange` (~`:235`):
+
+```ts
+  onFiltersChange?: (filters: Record<string, ColumnFilter>) => void;
+```
+
+Import `ColumnFilter` from `@pretable/core` if not already. Destructure `onFiltersChange` in the component signature (~`:428-451`).
+
+- [ ] **Step 2: Funnel overlay per header**
+
+Bring in the popover hook near the other surface hooks:
+
+```ts
+const { openState, toggle, close } = useFilterPopover();
+```
+
+In the per-column header render (the array currently `[<button>, resizeHandle]`), append a funnel overlay element when `column.filterable !== false`. Position it like the resize handle but offset left of it (so it doesn't overlap the 4px resize strip):
+
+```tsx
+column.filterable !== false ? (
+  <div
+    key={`${column.id}::filter-funnel`}
+    style={{
+      position: "absolute",
+      top: 0,
+      height: "100%",
+      display: "flex",
+      alignItems: "center",
+      left: plannedCol.left + effWidth - 22,
+      zIndex: 4,
+      ...(plannedCol.pinned === "left" && pinnedOffset !== undefined
+        ? { position: "sticky", left: pinnedOffset + effWidth - 22, zIndex: 5 }
+        : {}),
+    }}
+    data-pretable-filter-funnel-slot=""
+  >
+    <FunnelButton
+      columnId={column.id}
+      label={label}
+      active={Boolean(snapshot.filters[column.id])}
+      open={openState?.columnId === column.id}
+      onToggle={(id) => {
+        const slot = headerScrollRef.current?.querySelector(
+          `[data-pretable-filter-funnel-slot] [data-pretable-column-id="${id}"]`,
+        ) as HTMLElement | null;
+        toggle(id, slot);
+      }}
+    />
+  </div>
+) : null,
+```
+
+Notes:
+
+- `active` reads `snapshot.filters[column.id]` so the funnel stays lit while a filter is set.
+- The anchor element passed to `toggle` is the funnel button itself (look it up by the column-id within the funnel slot, or thread a ref). Simplest robust approach: have `FunnelButton`'s `onToggle` receive the event and pass `e.currentTarget` up — change the `FunnelButton` `onClick` to `onToggle(columnId, e.currentTarget)` and the prop type to `(columnId: string, anchor: HTMLElement) => void`. Update Task 2's `FunnelButton` accordingly and pass `anchor` straight to `toggle`. (Prefer this over DOM querying.)
+- Filter out the `null` entries when building the children array.
+
+- [ ] **Step 3: Render one `FilterMenu` at the surface root**
+
+Near where the reorder ghost is rendered (surface root, after the scroll container), add:
+
+```tsx
+{
+  openState
+    ? (() => {
+        const col = effectiveColumns.find((c) => c.id === openState.columnId);
+        if (!col) return null;
+        const options =
+          col.filterOptions ??
+          grid
+            .distinctColumnValues(openState.columnId)
+            .map((v) => ({ value: v }));
+        return (
+          <FilterMenu
+            columnId={openState.columnId}
+            label={col.header ?? openState.columnId}
+            filterType={col.filterType ?? "text"}
+            options={options}
+            initialFilter={snapshot.filters[openState.columnId] ?? null}
+            style={popoverStyle(openState.rect)}
+            onChange={(id, filter) => {
+              grid.setColumnFilter(id, filter);
+              onFiltersChange?.(grid.getSnapshot().filters);
+            }}
+            onClose={close}
+          />
+        );
+      })()
+    : null;
+}
+```
+
+(Confirm the in-scope names for the planned columns + grid handle — `effectiveColumns`/`grid`/`snapshot` exist in the surface; adjust to the actual identifiers.)
+
+- [ ] **Step 4: `@pretable/ui/grid.css`** — add filter styling (reuse tokens; no new tokens):
+
+```css
+:where([data-pretable-filter-funnel]) {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 18px;
+  height: 18px;
+  padding: 0;
+  border: 0;
+  border-radius: var(--pretable-radius);
+  background: transparent;
+  color: var(--pretable-text-dim);
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 0.1s ease;
+}
+:where(
+  [data-pretable-header-cell]:hover
+    ~ [data-pretable-filter-funnel-slot]
+    [data-pretable-filter-funnel]
+),
+:where([data-pretable-filter-funnel]:focus-visible),
+:where([data-pretable-filter-funnel][data-pretable-filter-active="true"]) {
+  opacity: 1;
+}
+:where([data-pretable-filter-funnel][data-pretable-filter-active="true"]) {
+  color: var(--pretable-accent);
+}
+:where([data-pretable-filter-funnel]:hover) {
+  background: var(--pretable-bg-hover);
+}
+
+:where([data-pretable-filter-menu]) {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 10px;
+  background: var(--pretable-bg-tooltip);
+  color: var(--pretable-text-cell);
+  border: 1px solid var(--pretable-rule);
+  border-radius: var(--pretable-radius);
+  box-shadow: 0 6px 24px rgba(0, 0, 0, 0.18);
+  font: inherit;
+}
+:where([data-pretable-filter-menu]) select,
+:where([data-pretable-filter-menu]) input[type="text"],
+:where([data-pretable-filter-menu]) input[type="date"],
+:where([data-pretable-filter-menu]) input:not([type]) {
+  width: 100%;
+  box-sizing: border-box;
+  padding: 5px 7px;
+  border: 1px solid var(--pretable-rule);
+  border-radius: var(--pretable-radius);
+  background: var(--pretable-bg-grid);
+  color: var(--pretable-text-cell);
+  font: inherit;
+}
+:where([data-pretable-filter-menu]) label {
+  display: flex;
+  gap: 6px;
+  align-items: center;
+}
+:where([data-pretable-filter-clear]) {
+  align-self: flex-end;
+  background: transparent;
+  border: 0;
+  color: var(--pretable-accent);
+  cursor: pointer;
+  padding: 2px 4px;
+}
+```
+
+Note: the hover selector relies on the funnel slot being a following-sibling of the header button within the header row. If the actual DOM nesting differs (e.g. funnel slot is a child of a wrapper, not a sibling of the header `<button>`), use the structurally-correct selector — the requirement is "funnel visible on header hover OR focus-within OR active". Verify against the rendered DOM and adjust the selector; do not ship a selector that doesn't actually match.
+
+- [ ] **Step 5: Integration tests** (via `PretableSurface`): mirror the sort-click test setup. Cover:
+  - A `filterable !== false` column renders a funnel (`[data-pretable-filter-funnel]`); a `filterable: false` column does not.
+  - Clicking the funnel opens the dialog (`role="dialog"`); clicking it again / pressing Escape / outside-click closes it.
+  - Clicking the funnel does NOT change sort (assert `onSortChange` not called; rows not reordered).
+  - End-to-end: open funnel on a text column, type a value → `visibleRows`/`[data-pretable-row]` count drops, `onFiltersChange` fired with the column's `ColumnFilter`.
+  - Enum column with no `filterOptions`: options come from `distinctColumnValues` (assert the checkbox labels match the column's distinct values).
+  - Controlled `state.filters`: pass a filter in, assert the funnel shows active and the dialog hydrates to that operator/value.
+
+- [ ] **Step 6: Run react tests + typecheck**
+
+Run: `pnpm --filter @pretable/react test` and `pnpm --filter @pretable/react typecheck` and `pnpm --filter @pretable/ui test` (token contract still green — no tokens added).
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add packages/react/src/pretable-surface.tsx packages/ui/src/grid.css packages/react/src/__tests__
+git commit -m "feat(react,ui): built-in header filter menu wired into the surface"
+```
+
+---
+
+## Task 4: API report + full validation
+
+**Files:** `packages/react/react.api.md` (generated); whole repo.
+
+- [ ] **Step 1: Regenerate API reports**
+
+Run: `pnpm api`. Review the diff: `react.api.md` should gain `onFiltersChange` on `PretableSurfaceProps` (and nothing else unexpected — the filter-menu internals are NOT exported from `public_api.ts`, so they must not appear; if api-extractor reports a forgotten export, that means something internal got exported — fix the export, don't add it to the public surface). Commit the updated report.
+
+- [ ] **Step 2: Full validation sweep**
+
+Run from the worktree root:
+
+```bash
+pnpm -r typecheck
+pnpm -r lint
+pnpm -r test
+pnpm format
+pnpm --filter @pretable/app-website build
+pnpm api   # second run must be a clean no-op
+```
+
+All green; second `pnpm api` reports no changes. If `pnpm format` fails, run `pnpm format:write` and re-commit. (Website still uses controlled `state.filters` on the hero — confirm it still builds; the hero does NOT adopt the menu here.)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add -A
+git commit -m "chore(api): refresh react report for onFiltersChange"
+```
+
+---
+
+## Self-Review notes (for the executor)
+
+- **Spec coverage:** pure operators module (Task 1) ✓; FunnelButton/useFilterPopover/FilterMenu (Task 2) ✓; surface wiring + on-by-default funnel + onFiltersChange + single root popover (Task 3) ✓; live-apply with `between`/`dateBetween` gating via `toColumnFilter`→`null` (Tasks 1–2) ✓; enum options from `filterOptions` or `distinctColumnValues` (Task 3) ✓; hover/focus/active visibility CSS (Task 3) ✓; a11y dialog + Escape + outside-click (Tasks 2–3) ✓; controlled `state.filters` hydrate (Tasks 2–3) ✓; api refresh (Task 4) ✓.
+- **Invalid-HTML guard:** the funnel is a sibling overlay, NOT nested in the header `<button>`. Do not nest it.
+- **No new tokens** unless unavoidable; if added, update both themes + `contract.test.ts` TOKENS (and `pnpm api` is unaffected, but the contract test must pass).
+- **Don't export filter-menu internals** from `@pretable/react`'s `public_api.ts` — only `onFiltersChange` (a prop) is new public surface. Keep the components internal.
+- **Out of scope:** hero adoption, docs page, e2e (sub-project 3).
+- **Type consistency:** `FilterDraft`, `operatorsForType`, `operatorValueShape`, `isComplete`, `toColumnFilter`, `fromColumnFilter`, `defaultDraft`, `OPERATOR_LABELS`, `FunnelButton`, `FilterMenu`, `useFilterPopover`, `popoverStyle` used identically across tasks.
diff --git a/docs/superpowers/specs/2026-06-19-filter-header-menu-design.md b/docs/superpowers/specs/2026-06-19-filter-header-menu-design.md
new file mode 100644
index 00000000..11b916b4
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-19-filter-header-menu-design.md
@@ -0,0 +1,155 @@
+# Filter header menu — design (sub-project 2 of 3)
+
+**Date:** 2026-06-19
+**Branch:** `claude/filter-ui` (off `main` after #180)
+**Status:** approved (pending written-spec review)
+
+## Context
+
+Sub-project 1 (PR #180) shipped the headless operator filter model: `setColumnFilter`,
+`distinctColumnValues`, typed `ColumnFilter`/`FilterOperator`/`FilterType`/`FilterOption`
+(exported from `@pretable/core` + `@pretable/react`), per-column `filterType`/`filterOptions`/
+`filterable`. There is **no built-in filter UI** — the surface renders no filter affordance.
+
+This is **sub-project 2 of 3**: a built-in, per-column **header filter menu** (funnel →
+popover) in `@pretable/react`, styled in `@pretable/ui`. Sub-project 3 (later) does the
+filtering docs page, hero adoption, and e2e.
+
+## Goal
+
+Give every `filterable` column a header funnel that opens a popover to edit that column's
+filter — operator dropdown + a typed value control that matches the column's `filterType`
+— applying live to the engine and firing `onFiltersChange`. Works uncontrolled (default)
+or controlled via the existing `state.filters`.
+
+## Decisions (locked in brainstorm)
+
+- **Apply timing:** live. Text inputs debounced ~200ms; dropdown/number/checkbox/date
+  apply immediately. No Apply button — a per-column **Clear** action only.
+  Multi-part operators (`between`/`dateBetween`) **gate**: apply only when both bounds are
+  valid; otherwise the column's filter is cleared (a half-range never blanks the grid).
+- **Funnel visibility:** appears on header hover/focus; **permanently shown + accented**
+  on any column with an active filter.
+- **On by default:** the funnel renders for every column with `filterable !== false`
+  (mirrors the resize/reorder precedent). Opt out per-column with `filterable: false`.
+- **Deferred to sub-project 3:** hero adoption, docs page, Playwright e2e. RTL is the
+  coverage here.
+
+## Non-goals
+
+- OR / boolean trees, a chip/filter bar, a global "clear all" toolbar (no toolbar exists).
+- `packages/*` Tailwind (vanilla CSS only). No new runtime deps (no Floating UI etc.).
+- Changes to the engine filter model (done in sub-project 1).
+- A surface-level master on/off prop (per-column `filterable` is the control).
+
+## Architecture
+
+New, all under `packages/react/src/filter-menu/`:
+
+- `filter-operators.ts` — **pure, no React.** The brains:
+  - `operatorsForType(filterType): FilterOperator[]` — which operators a column offers
+    (text/number/date/enum + shared isEmpty/isNotEmpty), in display order.
+  - `OPERATOR_LABELS: Record<FilterOperator, string>` — human labels ("contains",
+    "is between", "is any of", "is empty", …).
+  - `operatorValueShape(op): "none" | "single" | "range" | "set"` — drives which value
+    control renders.
+  - `isComplete(filterType, op, draft): boolean` — is the draft value usable (gating for
+    live-apply; e.g. `between` needs two parseable numbers).
+  - `toColumnFilter(filterType, op, draft): ColumnFilter | null` — build the engine value
+    (`null` when incomplete → clears). Parses number/date strings to the engine shape.
+  - `fromColumnFilter(filter): draft` — hydrate the popover from an existing filter
+    (controlled or re-open).
+  - Fully unit-tested in isolation.
+- `FunnelButton.tsx` — the header affordance. `<button aria-haspopup="dialog"
+aria-expanded data-pretable-filter-funnel data-pretable-filter-active={active}>` with an
+  inline-SVG funnel (no icon font). Calls back to toggle the popover for its column.
+- `useFilterPopover.ts` — open state (`openColumnId | null`), anchor rect, outside-click +
+  Escape close, and a fixed-position style computed from the funnel's
+  `getBoundingClientRect()` with viewport-edge flip (open left/up when near the edge).
+- `FilterMenu.tsx` — the popover dialog: operator `<select>` + value control by shape,
+  Clear button. Owns local draft state; pushes changes through a callback (debounced for
+  text). `role="dialog"`, labelled by the column header text.
+
+Wiring in `packages/react/src/pretable-surface.tsx`:
+
+- Render `<FunnelButton>` inside the header content (left of the resize handle). Its
+  pointer/click handlers `stopPropagation()` so sort-on-header-click and reorder-drag are
+  untouched.
+- Render **one** `<FilterMenu>` at the surface root (a fixed-position layer, mirroring the
+  reorder ghost) for the currently-open column — avoids header `overflow` clipping.
+- New prop `onFiltersChange?: (filters: Record<string, ColumnFilter>) => void`.
+
+## Data flow
+
+- **Uncontrolled (default):** the menu calls `grid.setColumnFilter(columnId, filter)` (or
+  `null` to clear), then `onFiltersChange(grid.getSnapshot().filters)`. The engine is the
+  source of truth; the funnel's active state reads from `snapshot.filters[columnId]`.
+- **Controlled:** when the consumer passes `state.filters`, that already flows through
+  `usePretable` → `grid.replaceFilters`. The menu still calls `setColumnFilter` for
+  responsiveness and fires `onFiltersChange`; the consumer updates its `state.filters` and
+  the controlled apply re-asserts (same pattern as sort/selection today). The popover
+  hydrates its draft from `snapshot.filters[columnId]` on open.
+- **Enum options:** use `column.filterOptions` if present; else
+  `grid.distinctColumnValues(columnId)` (computed when the popover opens).
+
+## Styling (`@pretable/ui`)
+
+- Vanilla CSS in `grid.css`, `:where()` + `data-pretable-filter-*` attributes (zero
+  specificity, consumer-overridable), matching existing conventions.
+- Reuse existing tokens: `--pretable-bg-tooltip` (popover bg), `--pretable-rule`,
+  `--pretable-radius`, `--pretable-text-cell`, `--pretable-bg-hover`, `--pretable-accent`
+  (active funnel + focus), `--pretable-focus-ring`. **Goal: no new tokens.** If an active-
+  funnel color genuinely needs its own token, add it to **both** themes (excel; material
+  light + dark) and the `contract.test.ts` `TOKENS` list (currently 42) — and only then.
+- Funnel is hidden by default and revealed via
+  `:where([data-pretable-header-cell]:hover [data-pretable-filter-funnel])`,
+  `:focus-within`, and always shown when `[data-pretable-filter-active="true"]`.
+- Popover reuses/extends the existing `[data-pretable-popover]` rule.
+
+## Accessibility & keyboard
+
+- Funnel: `<button>` with `aria-haspopup="dialog"`, `aria-expanded`, `aria-label`
+  (`Filter {header}`).
+- Popover: `role="dialog"`, `aria-label` referencing the column; on open, focus moves to
+  the operator select; **Escape** closes and returns focus to the funnel; outside-click
+  closes; Tab cycles native controls (select/inputs/checkboxes/Clear button).
+- Native controls throughout (`<select>`, `<input>`, `<input type="checkbox">`,
+  `<input type="date">`) for built-in keyboard support. Not a full focus trap (YAGNI);
+  Escape + return-focus + outside-click is the contract.
+
+## Testing (RTL, `packages/react/src/__tests__/`)
+
+`filter-operators.test.ts` (pure):
+
+- `operatorsForType` returns the right set per type; `operatorValueShape`/`isComplete`/
+  `toColumnFilter`/`fromColumnFilter` round-trips incl. number/date parsing and the
+  `between` gating (incomplete → `null`).
+
+`filter-menu.test.tsx` (component, via `PretableSurface`):
+
+- Funnel hidden until hover/focus; shown + `data-pretable-filter-active` when a filter
+  exists.
+- Open menu → operator select lists the type's operators; switching operator swaps the
+  value control (text input ↔ two number inputs ↔ checkbox list ↔ none for isEmpty).
+- Typing a text value (after debounce) narrows `visibleRows` and fires `onFiltersChange`
+  with `{ col: { operator, value } }`.
+- Enum checklist built from `filterOptions`; and from `distinctColumnValues` when options
+  omitted.
+- `between`: one bound → no filter applied; both bounds → applied.
+- Clear removes the column's filter (funnel returns to inactive).
+- Controlled `state.filters`: popover hydrates from it; ignoring `onFiltersChange` keeps
+  the engine pinned to the prop.
+- Funnel click does not trigger sort (stopPropagation).
+- Use fake timers for the debounce assertions.
+
+Plus `pnpm -r typecheck`/`lint`/`test`, `pnpm format`, and `pnpm api` (the new
+`onFiltersChange` prop changes `react.api.md` — refresh + commit; second run a no-op).
+
+## Risks
+
+- **Popover positioning** (fixed-position from rect, edge-flip, scroll/resize) is the
+  trickiest part and is weakly covered by jsdom. Keep the math in `useFilterPopover` small
+  and obvious; real-viewport validation comes with the e2e in sub-project 3.
+- **Default-on funnels** change every consumer's header UX. Accepted (matches
+  resize/reorder); `filterable: false` opts out.
+- **api gate**: `onFiltersChange` must land in `react.api.md` (required CI gate).
diff --git a/packages/react/react.api.md b/packages/react/react.api.md
index b301aa03..9c44af7c 100644
--- a/packages/react/react.api.md
+++ b/packages/react/react.api.md
@@ -566,6 +566,7 @@ export interface PretableSurfaceProps<TRow extends PretableRow = PretableRow> {
     // (undocumented)
     onColumnWidthsChange?: (next: Record<string, number>) => void;
     onCopy?: (args: SerializeRangesArgs<TRow>) => CopyPayload | null;
+    onFiltersChange?: (filters: Record<string, ColumnFilter>) => void;
     // (undocumented)
     onFocusChange?: (next: PretableFocusState) => void;
     // (undocumented)
@@ -721,7 +722,7 @@ export function ɵuseResolvedHeights(rowHeightProp?: number, headerHeightProp?:
 
 // Warnings were encountered during analysis:
 //
-// dist/index.d.ts:466:9 - (ae-forgotten-export) The symbol "PretableSortDirection" needs to be exported by the entry point index.d.ts
+// dist/index.d.ts:472:9 - (ae-forgotten-export) The symbol "PretableSortDirection" needs to be exported by the entry point index.d.ts
 
 // (No @packageDocumentation comment for this package)
 
diff --git a/packages/react/src/__tests__/filter-menu-surface.test.tsx b/packages/react/src/__tests__/filter-menu-surface.test.tsx
new file mode 100644
index 00000000..0680971a
--- /dev/null
+++ b/packages/react/src/__tests__/filter-menu-surface.test.tsx
@@ -0,0 +1,324 @@
+import "@testing-library/jest-dom/vitest";
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  within,
+} from "@testing-library/react";
+import * as React from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { PretableSurface } from "../pretable-surface";
+import type { ColumnFilter } from "@pretable/core";
+import type { PretableColumn } from "../types";
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+  vi.restoreAllMocks();
+});
+
+type Bug = {
+  id: string;
+  title: string;
+  severity: string;
+  count: number;
+};
+
+const columns: PretableColumn<Bug>[] = [
+  { id: "title", header: "Title", widthPx: 200, filterType: "text" },
+  {
+    id: "severity",
+    header: "Severity",
+    widthPx: 140,
+    filterType: "enum",
+  },
+  { id: "count", header: "Count", widthPx: 120, filterType: "number" },
+  // Non-filterable column: no funnel should render.
+  {
+    id: "internal",
+    header: "Internal",
+    widthPx: 120,
+    filterable: false,
+  },
+];
+
+const rows: Bug[] = [
+  { id: "b1", title: "alpha crash", severity: "high", count: 3 },
+  { id: "b2", title: "beta hang", severity: "low", count: 7 },
+  { id: "b3", title: "alpha leak", severity: "high", count: 1 },
+];
+
+const getRowId = (row: Bug) => row.id;
+
+function renderSurface(
+  extra: Partial<React.ComponentProps<typeof PretableSurface<Bug>>> = {},
+) {
+  return render(
+    <PretableSurface<Bug>
+      ariaLabel="Bug grid"
+      columns={columns}
+      getRowId={getRowId}
+      overscan={0}
+      rows={rows}
+      viewportHeight={300}
+      {...extra}
+    />,
+  );
+}
+
+describe("PretableSurface — built-in filter funnel", () => {
+  it("renders a funnel for filterable columns and omits it for filterable:false", () => {
+    const view = renderSurface();
+
+    expect(view.getByRole("button", { name: "Filter Title" })).toBeTruthy();
+    expect(view.getByRole("button", { name: "Filter Severity" })).toBeTruthy();
+    expect(view.getByRole("button", { name: "Filter Count" })).toBeTruthy();
+    expect(view.queryByRole("button", { name: "Filter Internal" })).toBeNull();
+
+    // Sanity: every funnel carries the stable hooks.
+    const funnels = view.container.querySelectorAll(
+      "[data-pretable-filter-funnel]",
+    );
+    expect(funnels.length).toBe(3);
+  });
+
+  it("re-hydrates the dialog when switching directly between two open funnels", () => {
+    // Regression: clicking a second column's funnel while one is open must
+    // remount the menu so its draft re-hydrates from the new column's filter.
+    // (The second funnel's pointerdown stops propagation, so the open menu's
+    // outside-click never fires and the FilterMenu instance would be reused
+    // unless it is keyed by columnId.)
+    const view = renderSurface({
+      state: {
+        filters: {
+          title: { operator: "endsWith", value: "crash" } as ColumnFilter,
+          count: { operator: "gt", value: 5 } as ColumnFilter,
+        },
+      },
+    });
+
+    // Open Title → operator hydrates to its filter.
+    fireEvent.click(view.getByRole("button", { name: "Filter Title" }));
+    let dialog = view.getByRole("dialog", { name: "Filter Title" });
+    expect(
+      dialog.querySelector<HTMLSelectElement>("[data-pretable-filter-operator]")
+        ?.value,
+    ).toBe("endsWith");
+
+    // Click Count's funnel WHILE Title's menu is open → switch + re-hydrate.
+    fireEvent.click(view.getByRole("button", { name: "Filter Count" }));
+    dialog = view.getByRole("dialog", { name: "Filter Count" });
+    expect(
+      dialog.querySelector<HTMLSelectElement>("[data-pretable-filter-operator]")
+        ?.value,
+    ).toBe("gt");
+    expect(
+      dialog.querySelector<HTMLInputElement>("[data-pretable-filter-value]")
+        ?.value,
+    ).toBe("5");
+  });
+
+  it("nests funnels inside the header row so the CSS hover selector matches", () => {
+    // The grid.css reveal rule is
+    //   [data-pretable-header-row]:hover [data-pretable-filter-funnel]
+    // (a DESCENDANT selector). Confirm the rendered DOM actually nests the
+    // funnel button under the header row inside a funnel slot, so the selector
+    // resolves against real markup rather than a guess.
+    const view = renderSurface();
+    const headerRow = view.container.querySelector(
+      "[data-pretable-header-row]",
+    )!;
+    expect(headerRow).toBeTruthy();
+
+    const slot = headerRow.querySelector("[data-pretable-filter-funnel-slot]")!;
+    expect(slot).toBeTruthy();
+    // Slot is a direct child of the header row (a flat sibling of the header
+    // cells / resize handles), and the funnel button lives inside the slot.
+    expect(slot.parentElement).toBe(headerRow);
+    const funnel = slot.querySelector("[data-pretable-filter-funnel]")!;
+    expect(funnel).toBeTruthy();
+    expect(headerRow.contains(funnel)).toBe(true);
+  });
+
+  it("opens the dialog on funnel click, and closes on second click / Escape / outside-click", () => {
+    const view = renderSurface();
+    const funnel = view.getByRole("button", { name: "Filter Title" });
+
+    expect(view.queryByRole("dialog")).toBeNull();
+
+    // Open.
+    fireEvent.click(funnel);
+    expect(view.getByRole("dialog", { name: "Filter Title" })).toBeTruthy();
+    expect(funnel).toHaveAttribute("aria-expanded", "true");
+
+    // Second click toggles closed.
+    fireEvent.click(funnel);
+    expect(view.queryByRole("dialog")).toBeNull();
+
+    // Reopen, then Escape closes (handled by useFilterPopover).
+    fireEvent.click(funnel);
+    expect(view.getByRole("dialog")).toBeTruthy();
+    fireEvent.keyDown(document, { key: "Escape" });
+    expect(view.queryByRole("dialog")).toBeNull();
+
+    // Reopen, then outside-click (pointerdown) closes (handled by FilterMenu).
+    fireEvent.click(funnel);
+    expect(view.getByRole("dialog")).toBeTruthy();
+    fireEvent.pointerDown(document.body);
+    expect(view.queryByRole("dialog")).toBeNull();
+  });
+
+  it("clicking the funnel does not sort the column", () => {
+    const onSortChange = vi.fn();
+    const view = renderSurface({ onSortChange });
+
+    const orderBefore = view
+      .getAllByTestId("pretable-row")
+      .map((r) => r.getAttribute("data-pretable-row-id"));
+
+    fireEvent.click(view.getByRole("button", { name: "Filter Title" }));
+
+    expect(onSortChange).not.toHaveBeenCalled();
+    const orderAfter = view
+      .getAllByTestId("pretable-row")
+      .map((r) => r.getAttribute("data-pretable-row-id"));
+    expect(orderAfter).toEqual(orderBefore);
+    // The sort header still reads "Sort" (no direction applied).
+    expect(
+      view.getByRole("columnheader", { name: "Sort Title" }),
+    ).toHaveTextContent("Sort");
+  });
+
+  it("typing into a text filter narrows the rows and fires onFiltersChange", async () => {
+    vi.useFakeTimers();
+    const onFiltersChange = vi.fn();
+    const view = renderSurface({ onFiltersChange });
+
+    expect(view.getAllByTestId("pretable-row")).toHaveLength(3);
+
+    fireEvent.click(view.getByRole("button", { name: "Filter Title" }));
+    const dialog = view.getByRole("dialog", { name: "Filter Title" });
+    const valueInput = within(dialog).getByLabelText("Filter value");
+
+    // Default text operator is "contains".
+    act(() => {
+      fireEvent.change(valueInput, { target: { value: "alpha" } });
+    });
+
+    // Text input is debounced (~200ms).
+    expect(onFiltersChange).not.toHaveBeenCalled();
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(250);
+    });
+
+    expect(onFiltersChange).toHaveBeenCalled();
+    const lastFilters = onFiltersChange.mock.lastCall?.[0] as Record<
+      string,
+      ColumnFilter
+    >;
+    expect(lastFilters.title).toEqual({ operator: "contains", value: "alpha" });
+
+    // Rows narrowed to the two "alpha" titles.
+    const ids = view
+      .getAllByTestId("pretable-row")
+      .map((r) => r.getAttribute("data-pretable-row-id"));
+    expect(ids).toEqual(["b1", "b3"]);
+  });
+
+  it("enum options come from distinctColumnValues when filterOptions is absent", () => {
+    const view = renderSurface();
+
+    fireEvent.click(view.getByRole("button", { name: "Filter Severity" }));
+    const dialog = view.getByRole("dialog", { name: "Filter Severity" });
+    const group = within(dialog).getByRole("group");
+    const labels = within(group)
+      .getAllByRole("checkbox")
+      .map((cb) => cb.closest("label")?.textContent?.trim());
+
+    // Distinct values across the rows: "high" and "low".
+    expect(new Set(labels)).toEqual(new Set(["high", "low"]));
+  });
+
+  it("checking enum values fires onFiltersChange and narrows rows", () => {
+    const onFiltersChange = vi.fn();
+    const view = renderSurface({ onFiltersChange });
+
+    fireEvent.click(view.getByRole("button", { name: "Filter Severity" }));
+    const dialog = view.getByRole("dialog", { name: "Filter Severity" });
+    const highCheckbox = within(dialog)
+      .getAllByRole("checkbox")
+      .find((cb) => cb.closest("label")?.textContent?.includes("high"))!;
+
+    fireEvent.click(highCheckbox);
+
+    const lastFilters = onFiltersChange.mock.lastCall?.[0] as Record<
+      string,
+      ColumnFilter
+    >;
+    expect(lastFilters.severity).toEqual({
+      operator: "isAnyOf",
+      value: ["high"],
+    });
+    const ids = view
+      .getAllByTestId("pretable-row")
+      .map((r) => r.getAttribute("data-pretable-row-id"));
+    expect(ids).toEqual(["b1", "b3"]);
+  });
+
+  it("controlled state.filters lights the funnel active and hydrates the dialog", () => {
+    const view = renderSurface({
+      state: {
+        filters: {
+          title: { operator: "contains", value: "beta" },
+        },
+      },
+    });
+
+    // Only the matching row survives.
+    const ids = view
+      .getAllByTestId("pretable-row")
+      .map((r) => r.getAttribute("data-pretable-row-id"));
+    expect(ids).toEqual(["b2"]);
+
+    // Funnel is marked active.
+    const funnel = view.getByRole("button", { name: "Filter Title" });
+    expect(funnel).toHaveAttribute("data-pretable-filter-active", "true");
+
+    // Opening hydrates the dialog to the active operator/value.
+    fireEvent.click(funnel);
+    const dialog = view.getByRole("dialog", { name: "Filter Title" });
+    expect(within(dialog).getByLabelText("Filter operator")).toHaveValue(
+      "contains",
+    );
+    expect(within(dialog).getByLabelText("Filter value")).toHaveValue("beta");
+  });
+
+  it("Clear resets the filter and fires onFiltersChange with the column removed", () => {
+    const onFiltersChange = vi.fn();
+    const view = renderSurface({
+      onFiltersChange,
+      state: undefined,
+    });
+
+    // Open + apply a text filter first (immediate via enum-free path uses
+    // debounce; instead clear from a hydrated controlled-less state by typing).
+    fireEvent.click(view.getByRole("button", { name: "Filter Severity" }));
+    const dialog = view.getByRole("dialog", { name: "Filter Severity" });
+    const highCheckbox = within(dialog)
+      .getAllByRole("checkbox")
+      .find((cb) => cb.closest("label")?.textContent?.includes("high"))!;
+    fireEvent.click(highCheckbox);
+    expect(view.getAllByTestId("pretable-row")).toHaveLength(2);
+
+    // Clear.
+    fireEvent.click(within(dialog).getByText("Clear"));
+    const lastFilters = onFiltersChange.mock.lastCall?.[0] as Record<
+      string,
+      ColumnFilter
+    >;
+    expect(lastFilters.severity).toBeUndefined();
+    expect(view.getAllByTestId("pretable-row")).toHaveLength(3);
+  });
+});
diff --git a/packages/react/src/__tests__/filter-menu.test.tsx b/packages/react/src/__tests__/filter-menu.test.tsx
new file mode 100644
index 00000000..8fab3c61
--- /dev/null
+++ b/packages/react/src/__tests__/filter-menu.test.tsx
@@ -0,0 +1,273 @@
+import "@testing-library/jest-dom/vitest";
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render,
+  screen,
+} from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ColumnFilter } from "@pretable/core";
+
+import { FilterMenu } from "../filter-menu";
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+type Props = Parameters<typeof FilterMenu>[0];
+
+function renderMenu(over: Partial<Props> = {}) {
+  const onChange = vi.fn<(id: string, f: ColumnFilter | null) => void>();
+  const onClose = vi.fn();
+  const props: Props = {
+    columnId: "c",
+    label: "Name",
+    filterType: "text",
+    options: [],
+    initialFilter: null,
+    onChange,
+    onClose,
+    ...over,
+  };
+  act(() => {
+    render(<FilterMenu {...props} />);
+  });
+  return { onChange, onClose };
+}
+
+const lastCall = (fn: { mock: { calls: unknown[][] } }) =>
+  fn.mock.calls[fn.mock.calls.length - 1];
+
+describe("FilterMenu — dialog basics", () => {
+  it("renders a dialog with an accessible name and focuses the operator select", () => {
+    renderMenu();
+    const dialog = screen.getByRole("dialog", { name: "Filter Name" });
+    expect(dialog).toBeInTheDocument();
+    const select = screen.getByRole("combobox", { name: "Filter operator" });
+    expect(select).toHaveFocus();
+  });
+
+  it("defaults a text column to the `contains` operator", () => {
+    renderMenu({ filterType: "text" });
+    const select = screen.getByRole("combobox", {
+      name: "Filter operator",
+    }) as HTMLSelectElement;
+    expect(select.value).toBe("contains");
+  });
+});
+
+describe("FilterMenu — text live-apply (debounced)", () => {
+  it("debounces typing then fires onChange with the contains filter", async () => {
+    const { onChange } = renderMenu({ filterType: "text" });
+    const input = screen.getByRole("textbox", { name: "Filter value" });
+
+    act(() => {
+      fireEvent.change(input, { target: { value: "ad" } });
+    });
+    // Not applied immediately.
+    expect(onChange).not.toHaveBeenCalled();
+
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(250);
+    });
+    expect(lastCall(onChange)).toEqual([
+      "c",
+      { operator: "contains", value: "ad" },
+    ]);
+  });
+});
+
+describe("FilterMenu — operator switch", () => {
+  it("switching to isEmpty hides the value input and applies immediately", () => {
+    const { onChange } = renderMenu({ filterType: "text" });
+    const select = screen.getByRole("combobox", { name: "Filter operator" });
+
+    act(() => {
+      fireEvent.change(select, { target: { value: "isEmpty" } });
+    });
+
+    expect(screen.queryByRole("textbox", { name: "Filter value" })).toBeNull();
+    expect(lastCall(onChange)).toEqual(["c", { operator: "isEmpty" }]);
+  });
+});
+
+describe("FilterMenu — number between gating", () => {
+  it("clears when only min is set, applies when both bounds present", async () => {
+    const { onChange } = renderMenu({ filterType: "number" });
+    const select = screen.getByRole("combobox", { name: "Filter operator" });
+
+    act(() => {
+      fireEvent.change(select, { target: { value: "between" } });
+    });
+    // operator change with empty range → null
+    expect(lastCall(onChange)).toEqual(["c", null]);
+
+    const min = screen.getByRole("textbox", { name: "Filter minimum" });
+    act(() => {
+      fireEvent.change(min, { target: { value: "1" } });
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(250);
+    });
+    // only min → still null
+    expect(lastCall(onChange)).toEqual(["c", null]);
+
+    const max = screen.getByRole("textbox", { name: "Filter maximum" });
+    act(() => {
+      fireEvent.change(max, { target: { value: "10" } });
+    });
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(250);
+    });
+    expect(lastCall(onChange)).toEqual([
+      "c",
+      { operator: "between", value: [1, 10] },
+    ]);
+  });
+});
+
+describe("FilterMenu — enum set", () => {
+  it("renders options as checkboxes; checking applies, unchecking all clears", () => {
+    const { onChange } = renderMenu({
+      filterType: "enum",
+      options: [
+        { value: "a", label: "Alpha" },
+        { value: "b", label: "Beta" },
+      ],
+    });
+
+    const alpha = screen.getByRole("checkbox", { name: "Alpha" });
+    const beta = screen.getByRole("checkbox", { name: "Beta" });
+
+    act(() => {
+      fireEvent.click(alpha);
+    });
+    expect(lastCall(onChange)).toEqual([
+      "c",
+      { operator: "isAnyOf", value: ["a"] },
+    ]);
+
+    act(() => {
+      fireEvent.click(beta);
+    });
+    expect(lastCall(onChange)).toEqual([
+      "c",
+      { operator: "isAnyOf", value: ["a", "b"] },
+    ]);
+
+    act(() => {
+      fireEvent.click(alpha);
+    });
+    act(() => {
+      fireEvent.click(beta);
+    });
+    // all unchecked → null
+    expect(lastCall(onChange)).toEqual(["c", null]);
+  });
+});
+
+describe("FilterMenu — clear", () => {
+  it("Clear button fires onChange(id, null)", () => {
+    const { onChange } = renderMenu({
+      filterType: "text",
+      initialFilter: { operator: "contains", value: "ada" },
+    });
+    const clear = screen.getByRole("button", { name: "Clear" });
+    act(() => {
+      fireEvent.click(clear);
+    });
+    expect(lastCall(onChange)).toEqual(["c", null]);
+  });
+});
+
+describe("FilterMenu — hydrate from initialFilter", () => {
+  it("seeds the operator and value from an existing filter", () => {
+    renderMenu({
+      filterType: "text",
+      initialFilter: { operator: "startsWith", value: "Ad" },
+    });
+    const select = screen.getByRole("combobox", {
+      name: "Filter operator",
+    }) as HTMLSelectElement;
+    expect(select.value).toBe("startsWith");
+    expect(screen.getByRole("textbox", { name: "Filter value" })).toHaveValue(
+      "Ad",
+    );
+  });
+});
+
+describe("FilterMenu — date single applies immediately", () => {
+  it("date input applies without waiting for the debounce", () => {
+    const { onChange } = renderMenu({ filterType: "date" });
+    const select = screen.getByRole("combobox", { name: "Filter operator" });
+    act(() => {
+      fireEvent.change(select, { target: { value: "before" } });
+    });
+    const input = screen.getByLabelText("Filter value");
+    act(() => {
+      fireEvent.change(input, { target: { value: "2026-06-18" } });
+    });
+    expect(lastCall(onChange)).toEqual([
+      "c",
+      { operator: "before", value: "2026-06-18" },
+    ]);
+  });
+});
+
+describe("FilterMenu — outside click", () => {
+  it("calls onClose when a pointerdown lands outside the dialog", () => {
+    const { onClose } = renderMenu();
+    act(() => {
+      fireEvent.pointerDown(document.body);
+    });
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it("does not close on a pointerdown inside the dialog", () => {
+    const { onClose } = renderMenu();
+    const dialog = screen.getByRole("dialog");
+    act(() => {
+      fireEvent.pointerDown(dialog);
+    });
+    expect(onClose).not.toHaveBeenCalled();
+  });
+});
+
+describe("FilterMenu — flush on unmount", () => {
+  it("applies a pending debounced edit when unmounted before the timer fires", () => {
+    const onChange = vi.fn<(id: string, f: ColumnFilter | null) => void>();
+    let unmount: () => void;
+    act(() => {
+      const r = render(
+        <FilterMenu
+          columnId="c"
+          label="Name"
+          filterType="text"
+          options={[]}
+          initialFilter={null}
+          onChange={onChange}
+          onClose={vi.fn()}
+        />,
+      );
+      unmount = r.unmount;
+    });
+    const input = screen.getByRole("textbox", { name: "Filter value" });
+    act(() => {
+      fireEvent.change(input, { target: { value: "x" } });
+    });
+    expect(onChange).not.toHaveBeenCalled();
+    act(() => {
+      unmount();
+    });
+    expect(lastCall(onChange)).toEqual([
+      "c",
+      { operator: "contains", value: "x" },
+    ]);
+  });
+});
diff --git a/packages/react/src/__tests__/filter-operators.test.ts b/packages/react/src/__tests__/filter-operators.test.ts
new file mode 100644
index 00000000..49e3fd3e
--- /dev/null
+++ b/packages/react/src/__tests__/filter-operators.test.ts
@@ -0,0 +1,165 @@
+// packages/react/src/__tests__/filter-operators.test.ts
+import { describe, expect, it } from "vitest";
+import {
+  operatorsForType,
+  operatorValueShape,
+  isComplete,
+  toColumnFilter,
+  fromColumnFilter,
+  OPERATOR_LABELS,
+  type FilterDraft,
+} from "../filter-menu/filter-operators";
+
+describe("operatorsForType", () => {
+  it("lists the operators for each type incl. shared empties", () => {
+    expect(operatorsForType("text")).toEqual([
+      "contains",
+      "notContains",
+      "equals",
+      "notEquals",
+      "startsWith",
+      "endsWith",
+      "isEmpty",
+      "isNotEmpty",
+    ]);
+    expect(operatorsForType("number")).toEqual([
+      "equals",
+      "notEquals",
+      "gt",
+      "gte",
+      "lt",
+      "lte",
+      "between",
+      "isEmpty",
+      "isNotEmpty",
+    ]);
+    expect(operatorsForType("date")).toEqual([
+      "on",
+      "before",
+      "after",
+      "dateBetween",
+      "isEmpty",
+      "isNotEmpty",
+    ]);
+    expect(operatorsForType("enum")).toEqual([
+      "isAnyOf",
+      "isNoneOf",
+      "isEmpty",
+      "isNotEmpty",
+    ]);
+  });
+  it("every operator has a label", () => {
+    for (const t of ["text", "number", "date", "enum"] as const)
+      for (const op of operatorsForType(t))
+        expect(OPERATOR_LABELS[op]).toBeTruthy();
+  });
+});
+
+describe("operatorValueShape", () => {
+  it("classifies operators", () => {
+    expect(operatorValueShape("contains")).toBe("single");
+    expect(operatorValueShape("between")).toBe("range");
+    expect(operatorValueShape("dateBetween")).toBe("range");
+    expect(operatorValueShape("isAnyOf")).toBe("set");
+    expect(operatorValueShape("isEmpty")).toBe("none");
+    expect(operatorValueShape("isNotEmpty")).toBe("none");
+  });
+});
+
+describe("isComplete + toColumnFilter (gating)", () => {
+  it("text single value", () => {
+    const d: FilterDraft = { operator: "contains", text: "ab" };
+    expect(isComplete("text", d)).toBe(true);
+    expect(toColumnFilter("text", d)).toEqual({
+      operator: "contains",
+      value: "ab",
+    });
+    expect(isComplete("text", { operator: "contains", text: "" })).toBe(false);
+    expect(
+      toColumnFilter("text", { operator: "contains", text: "" }),
+    ).toBeNull();
+  });
+  it("number single + parses", () => {
+    expect(toColumnFilter("number", { operator: "gt", text: "5" })).toEqual({
+      operator: "gt",
+      value: 5,
+    });
+    expect(toColumnFilter("number", { operator: "gt", text: "x" })).toBeNull();
+  });
+  it("between needs both bounds", () => {
+    expect(
+      isComplete("number", { operator: "between", min: "1", max: "" }),
+    ).toBe(false);
+    expect(
+      toColumnFilter("number", { operator: "between", min: "1", max: "" }),
+    ).toBeNull();
+    expect(
+      toColumnFilter("number", { operator: "between", min: "1", max: "10" }),
+    ).toEqual({ operator: "between", value: [1, 10] });
+  });
+  it("dateBetween needs both ISO bounds", () => {
+    expect(
+      toColumnFilter("date", {
+        operator: "dateBetween",
+        min: "2026-01-01",
+        max: "",
+      }),
+    ).toBeNull();
+    expect(
+      toColumnFilter("date", {
+        operator: "dateBetween",
+        min: "2026-01-01",
+        max: "2026-02-01",
+      }),
+    ).toEqual({ operator: "dateBetween", value: ["2026-01-01", "2026-02-01"] });
+  });
+  it("date single", () => {
+    expect(
+      toColumnFilter("date", { operator: "before", text: "2026-06-18" }),
+    ).toEqual({ operator: "before", value: "2026-06-18" });
+  });
+  it("enum set; empty selection is incomplete", () => {
+    expect(isComplete("enum", { operator: "isAnyOf", selected: [] })).toBe(
+      false,
+    );
+    expect(
+      toColumnFilter("enum", { operator: "isAnyOf", selected: [] }),
+    ).toBeNull();
+    expect(
+      toColumnFilter("enum", { operator: "isAnyOf", selected: ["a", "b"] }),
+    ).toEqual({ operator: "isAnyOf", value: ["a", "b"] });
+  });
+  it("none-shape ops are always complete with no value", () => {
+    expect(isComplete("text", { operator: "isEmpty" })).toBe(true);
+    expect(toColumnFilter("text", { operator: "isEmpty" })).toEqual({
+      operator: "isEmpty",
+    });
+  });
+});
+
+describe("fromColumnFilter (hydrate)", () => {
+  it("round-trips each shape", () => {
+    expect(
+      fromColumnFilter("text", { operator: "contains", value: "ab" }),
+    ).toEqual({ operator: "contains", text: "ab" });
+    expect(
+      fromColumnFilter("number", { operator: "between", value: [1, 10] }),
+    ).toEqual({ operator: "between", min: "1", max: "10" });
+    expect(
+      fromColumnFilter("enum", { operator: "isAnyOf", value: ["a"] }),
+    ).toEqual({ operator: "isAnyOf", selected: ["a"] });
+    expect(fromColumnFilter("text", { operator: "isEmpty" })).toEqual({
+      operator: "isEmpty",
+    });
+  });
+  it("returns a default draft for null", () => {
+    expect(fromColumnFilter("text", null)).toEqual({
+      operator: "contains",
+      text: "",
+    });
+    expect(fromColumnFilter("enum", null)).toEqual({
+      operator: "isAnyOf",
+      selected: [],
+    });
+  });
+});
diff --git a/packages/react/src/filter-menu/FilterMenu.tsx b/packages/react/src/filter-menu/FilterMenu.tsx
new file mode 100644
index 00000000..4bced596
--- /dev/null
+++ b/packages/react/src/filter-menu/FilterMenu.tsx
@@ -0,0 +1,261 @@
+// packages/react/src/filter-menu/FilterMenu.tsx
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type JSX,
+} from "react";
+import type { ColumnFilter, FilterOperator, FilterType } from "@pretable/core";
+import {
+  OPERATOR_LABELS,
+  defaultDraft,
+  fromColumnFilter,
+  operatorValueShape,
+  operatorsForType,
+  toColumnFilter,
+  type FilterDraft,
+} from "./filter-operators";
+
+const DEBOUNCE_MS = 200;
+
+export function FilterMenu({
+  columnId,
+  label,
+  filterType,
+  options,
+  initialFilter,
+  style,
+  onChange,
+  onClose,
+}: {
+  columnId: string;
+  label: string;
+  filterType: FilterType;
+  options: { value: string; label?: string }[];
+  initialFilter: ColumnFilter | null;
+  style?: CSSProperties;
+  onChange: (columnId: string, filter: ColumnFilter | null) => void;
+  onClose: () => void;
+}): JSX.Element {
+  const [draft, setDraft] = useState<FilterDraft>(() =>
+    fromColumnFilter(filterType, initialFilter),
+  );
+
+  const rootRef = useRef<HTMLDivElement>(null);
+  const selectRef = useRef<HTMLSelectElement>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Keep the latest draft in a ref so the unmount flush sees current state.
+  // Synced in an effect (not during render) so the ref write is not a render
+  // side effect; the flush only fires on unmount, after this has run.
+  const latestDraftRef = useRef(draft);
+  useEffect(() => {
+    latestDraftRef.current = draft;
+  }, [draft]);
+
+  const apply = useCallback(
+    (next: FilterDraft) => {
+      onChange(columnId, toColumnFilter(filterType, next));
+    },
+    [columnId, filterType, onChange],
+  );
+
+  const clearTimer = useCallback(() => {
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+  }, []);
+
+  // Immediate apply (operator/checkbox/date changes).
+  const pushNow = useCallback(
+    (next: FilterDraft) => {
+      clearTimer();
+      setDraft(next);
+      apply(next);
+    },
+    [apply, clearTimer],
+  );
+
+  // Debounced apply (free-text/number typing).
+  const pushDebounced = useCallback(
+    (next: FilterDraft) => {
+      setDraft(next);
+      clearTimer();
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        apply(next);
+      }, DEBOUNCE_MS);
+    },
+    [apply, clearTimer],
+  );
+
+  // Flush any pending debounced apply on unmount.
+  useEffect(() => {
+    return () => {
+      if (timerRef.current !== null) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+        apply(latestDraftRef.current);
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // Focus the operator select on mount.
+  useEffect(() => {
+    selectRef.current?.focus();
+  }, []);
+
+  // Outside-click → close.
+  useEffect(() => {
+    const onPointerDown = (e: PointerEvent) => {
+      const root = rootRef.current;
+      if (root && e.target instanceof Node && !root.contains(e.target)) {
+        onClose();
+      }
+    };
+    document.addEventListener("pointerdown", onPointerDown);
+    return () => document.removeEventListener("pointerdown", onPointerDown);
+  }, [onClose]);
+
+  const onOperatorChange = useCallback(
+    (operator: FilterOperator) => {
+      const shape = operatorValueShape(operator);
+      let next: FilterDraft;
+      if (shape === "none") next = { operator };
+      else if (shape === "set")
+        // Keep prior selection only when staying within a set shape.
+        next = {
+          operator,
+          selected:
+            operatorValueShape(draft.operator) === "set"
+              ? (draft.selected ?? [])
+              : [],
+        };
+      else if (shape === "range") next = { operator, min: "", max: "" };
+      else next = { operator, text: "" };
+      pushNow(next);
+    },
+    [draft, pushNow],
+  );
+
+  const shape = operatorValueShape(draft.operator);
+  const operators = operatorsForType(filterType);
+  const inputType = filterType === "date" ? "date" : "text";
+  const numericProps =
+    filterType === "number" ? { inputMode: "numeric" as const } : {};
+
+  const onClear = useCallback(() => {
+    clearTimer();
+    setDraft(defaultDraft(filterType));
+    onChange(columnId, null);
+  }, [clearTimer, columnId, filterType, onChange]);
+
+  const toggleSelected = useCallback(
+    (value: string, checked: boolean) => {
+      const current = new Set(draft.selected ?? []);
+      if (checked) current.add(value);
+      else current.delete(value);
+      pushNow({ ...draft, selected: [...current] });
+    },
+    [draft, pushNow],
+  );
+
+  return (
+    <div
+      ref={rootRef}
+      role="dialog"
+      aria-label={`Filter ${label}`}
+      data-pretable-filter-menu=""
+      data-pretable-popover=""
+      style={style}
+    >
+      <select
+        ref={selectRef}
+        data-pretable-filter-operator=""
+        aria-label="Filter operator"
+        value={draft.operator}
+        onChange={(e) => onOperatorChange(e.target.value as FilterOperator)}
+      >
+        {operators.map((op) => (
+          <option key={op} value={op}>
+            {OPERATOR_LABELS[op]}
+          </option>
+        ))}
+      </select>
+
+      {shape === "single" ? (
+        <input
+          type={inputType}
+          {...numericProps}
+          data-pretable-filter-value=""
+          aria-label={`Filter value`}
+          value={draft.text ?? ""}
+          onChange={(e) =>
+            inputType === "date"
+              ? pushNow({ ...draft, text: e.target.value })
+              : pushDebounced({ ...draft, text: e.target.value })
+          }
+        />
+      ) : null}
+
+      {shape === "range" ? (
+        <>
+          <input
+            type={inputType}
+            {...numericProps}
+            data-pretable-filter-min=""
+            aria-label="Filter minimum"
+            value={draft.min ?? ""}
+            onChange={(e) =>
+              inputType === "date"
+                ? pushNow({ ...draft, min: e.target.value })
+                : pushDebounced({ ...draft, min: e.target.value })
+            }
+          />
+          <input
+            type={inputType}
+            {...numericProps}
+            data-pretable-filter-max=""
+            aria-label="Filter maximum"
+            value={draft.max ?? ""}
+            onChange={(e) =>
+              inputType === "date"
+                ? pushNow({ ...draft, max: e.target.value })
+                : pushDebounced({ ...draft, max: e.target.value })
+            }
+          />
+        </>
+      ) : null}
+
+      {shape === "set" ? (
+        <div
+          data-pretable-filter-set=""
+          role="group"
+          aria-label="Filter values"
+        >
+          {options.map((opt) => {
+            const checked = (draft.selected ?? []).includes(opt.value);
+            return (
+              <label key={opt.value}>
+                <input
+                  type="checkbox"
+                  checked={checked}
+                  onChange={(e) => toggleSelected(opt.value, e.target.checked)}
+                />
+                {opt.label ?? opt.value}
+              </label>
+            );
+          })}
+        </div>
+      ) : null}
+
+      <button type="button" data-pretable-filter-clear="" onClick={onClear}>
+        Clear
+      </button>
+    </div>
+  );
+}
diff --git a/packages/react/src/filter-menu/FunnelButton.tsx b/packages/react/src/filter-menu/FunnelButton.tsx
new file mode 100644
index 00000000..68cbbecd
--- /dev/null
+++ b/packages/react/src/filter-menu/FunnelButton.tsx
@@ -0,0 +1,46 @@
+// packages/react/src/filter-menu/FunnelButton.tsx
+import type { CSSProperties } from "react";
+
+export function FunnelButton({
+  columnId,
+  label,
+  active,
+  open,
+  style,
+  onToggle,
+}: {
+  columnId: string;
+  label: string;
+  active: boolean;
+  open: boolean;
+  style?: CSSProperties;
+  onToggle: (columnId: string, anchor: HTMLElement) => void;
+}) {
+  return (
+    <button
+      type="button"
+      data-pretable-filter-funnel=""
+      data-pretable-column-id={columnId}
+      data-pretable-filter-active={active ? "true" : "false"}
+      aria-haspopup="dialog"
+      aria-expanded={open}
+      aria-label={`Filter ${label}`}
+      style={style}
+      onPointerDown={(e) => e.stopPropagation()}
+      onClick={(e) => {
+        e.stopPropagation();
+        onToggle(columnId, e.currentTarget);
+      }}
+    >
+      <svg
+        viewBox="0 0 16 16"
+        width="11"
+        height="11"
+        aria-hidden="true"
+        focusable="false"
+      >
+        <path d="M1.5 2.5h13l-5 6v4l-3 1.5v-5.5l-5-6z" fill="currentColor" />
+      </svg>
+    </button>
+  );
+}
diff --git a/packages/react/src/filter-menu/filter-operators.ts b/packages/react/src/filter-menu/filter-operators.ts
new file mode 100644
index 00000000..7b906aed
--- /dev/null
+++ b/packages/react/src/filter-menu/filter-operators.ts
@@ -0,0 +1,144 @@
+// packages/react/src/filter-menu/filter-operators.ts
+import type { ColumnFilter, FilterOperator, FilterType } from "@pretable/core";
+
+/** Local editing shape for the popover. One field set per value-shape. */
+export interface FilterDraft {
+  operator: FilterOperator;
+  text?: string; // single (text/number/date)
+  min?: string; // range lower
+  max?: string; // range upper
+  selected?: string[]; // set (enum)
+}
+
+export type ValueShape = "none" | "single" | "range" | "set";
+
+const TEXT_OPS: FilterOperator[] = [
+  "contains",
+  "notContains",
+  "equals",
+  "notEquals",
+  "startsWith",
+  "endsWith",
+];
+const NUMBER_OPS: FilterOperator[] = [
+  "equals",
+  "notEquals",
+  "gt",
+  "gte",
+  "lt",
+  "lte",
+  "between",
+];
+const DATE_OPS: FilterOperator[] = ["on", "before", "after", "dateBetween"];
+const ENUM_OPS: FilterOperator[] = ["isAnyOf", "isNoneOf"];
+const SHARED_OPS: FilterOperator[] = ["isEmpty", "isNotEmpty"];
+
+export function operatorsForType(type: FilterType): FilterOperator[] {
+  const base =
+    type === "number"
+      ? NUMBER_OPS
+      : type === "date"
+        ? DATE_OPS
+        : type === "enum"
+          ? ENUM_OPS
+          : TEXT_OPS;
+  return [...base, ...SHARED_OPS];
+}
+
+export const OPERATOR_LABELS: Record<FilterOperator, string> = {
+  contains: "contains",
+  notContains: "does not contain",
+  equals: "equals",
+  notEquals: "does not equal",
+  startsWith: "starts with",
+  endsWith: "ends with",
+  gt: "greater than",
+  gte: "greater than or equal",
+  lt: "less than",
+  lte: "less than or equal",
+  between: "is between",
+  isAnyOf: "is any of",
+  isNoneOf: "is none of",
+  on: "on",
+  before: "before",
+  after: "after",
+  dateBetween: "is between",
+  isEmpty: "is empty",
+  isNotEmpty: "is not empty",
+};
+
+const RANGE_OPS = new Set<FilterOperator>(["between", "dateBetween"]);
+const SET_OPS = new Set<FilterOperator>(["isAnyOf", "isNoneOf"]);
+const NONE_OPS = new Set<FilterOperator>(["isEmpty", "isNotEmpty"]);
+
+export function operatorValueShape(op: FilterOperator): ValueShape {
+  if (NONE_OPS.has(op)) return "none";
+  if (RANGE_OPS.has(op)) return "range";
+  if (SET_OPS.has(op)) return "set";
+  return "single";
+}
+
+export function defaultDraft(type: FilterType): FilterDraft {
+  const operator = operatorsForType(type)[0]!;
+  if (operatorValueShape(operator) === "set") return { operator, selected: [] };
+  if (operatorValueShape(operator) === "range")
+    return { operator, min: "", max: "" };
+  return { operator, text: "" };
+}
+
+const isNum = (s: string | undefined): s is string =>
+  s !== undefined && s.trim() !== "" && !Number.isNaN(Number(s));
+
+export function isComplete(type: FilterType, d: FilterDraft): boolean {
+  const shape = operatorValueShape(d.operator);
+  if (shape === "none") return true;
+  if (shape === "set") return (d.selected?.length ?? 0) > 0;
+  if (shape === "range") {
+    if (type === "number") return isNum(d.min) && isNum(d.max);
+    return !!d.min && !!d.max; // date ISO strings
+  }
+  // single
+  if (type === "number") return isNum(d.text);
+  return !!d.text && d.text.trim() !== "";
+}
+
+export function toColumnFilter(
+  type: FilterType,
+  d: FilterDraft,
+): ColumnFilter | null {
+  const shape = operatorValueShape(d.operator);
+  if (shape === "none") return { operator: d.operator };
+  if (!isComplete(type, d)) return null;
+  if (shape === "set") return { operator: d.operator, value: [...d.selected!] };
+  if (shape === "range") {
+    if (type === "number")
+      return { operator: d.operator, value: [Number(d.min), Number(d.max)] };
+    return { operator: d.operator, value: [d.min!, d.max!] };
+  }
+  // single
+  if (type === "number") return { operator: d.operator, value: Number(d.text) };
+  return { operator: d.operator, value: d.text! };
+}
+
+export function fromColumnFilter(
+  type: FilterType,
+  filter: ColumnFilter | null,
+): FilterDraft {
+  if (!filter) return defaultDraft(type);
+  const { operator, value } = filter;
+  const shape = operatorValueShape(operator);
+  if (shape === "none") return { operator };
+  if (shape === "set")
+    return {
+      operator,
+      selected: Array.isArray(value) ? value.map(String) : [],
+    };
+  if (shape === "range") {
+    const arr = Array.isArray(value) ? value : ["", ""];
+    return { operator, min: String(arr[0] ?? ""), max: String(arr[1] ?? "") };
+  }
+  return {
+    operator,
+    text: value === null || value === undefined ? "" : String(value),
+  };
+}
diff --git a/packages/react/src/filter-menu/index.ts b/packages/react/src/filter-menu/index.ts
new file mode 100644
index 00000000..09214950
--- /dev/null
+++ b/packages/react/src/filter-menu/index.ts
@@ -0,0 +1,3 @@
+export { FunnelButton } from "./FunnelButton";
+export { FilterMenu } from "./FilterMenu";
+export { useFilterPopover, popoverStyle } from "./useFilterPopover";
diff --git a/packages/react/src/filter-menu/useFilterPopover.ts b/packages/react/src/filter-menu/useFilterPopover.ts
new file mode 100644
index 00000000..07e837da
--- /dev/null
+++ b/packages/react/src/filter-menu/useFilterPopover.ts
@@ -0,0 +1,58 @@
+// packages/react/src/filter-menu/useFilterPopover.ts
+import { useCallback, useEffect, useState, type CSSProperties } from "react";
+
+export interface PopoverState {
+  columnId: string;
+  rect: DOMRect;
+}
+
+export function useFilterPopover() {
+  const [openState, setOpenState] = useState<PopoverState | null>(null);
+
+  const toggle = useCallback(
+    (columnId: string, anchorEl: HTMLElement | null) => {
+      setOpenState((prev) => {
+        if (prev?.columnId === columnId) return null;
+        const rect = anchorEl?.getBoundingClientRect();
+        return rect ? { columnId, rect } : null;
+      });
+    },
+    [],
+  );
+
+  const close = useCallback(() => setOpenState(null), []);
+
+  useEffect(() => {
+    if (!openState) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") close();
+    };
+    // Close on scroll/resize so the popover never floats away from its anchor.
+    const onViewportChange = () => close();
+    document.addEventListener("keydown", onKey);
+    window.addEventListener("resize", onViewportChange);
+    window.addEventListener("scroll", onViewportChange, true);
+    return () => {
+      document.removeEventListener("keydown", onKey);
+      window.removeEventListener("resize", onViewportChange);
+      window.removeEventListener("scroll", onViewportChange, true);
+    };
+  }, [openState, close]);
+
+  return { openState, toggle, close };
+}
+
+/** Fixed-position style from the anchor rect, flipped near the right/bottom edges. */
+export function popoverStyle(rect: DOMRect): CSSProperties {
+  const WIDTH = 240;
+  const MARGIN = 8;
+  const vw = typeof window !== "undefined" ? window.innerWidth : 1024;
+  const left = Math.min(rect.left, vw - WIDTH - MARGIN);
+  return {
+    position: "fixed",
+    top: rect.bottom + 4,
+    left: Math.max(MARGIN, left),
+    width: WIDTH,
+    zIndex: 50,
+  };
+}
diff --git a/packages/react/src/pretable-surface.tsx b/packages/react/src/pretable-surface.tsx
index 29a80c53..e8bad546 100644
--- a/packages/react/src/pretable-surface.tsx
+++ b/packages/react/src/pretable-surface.tsx
@@ -14,6 +14,7 @@ import {
 } from "react";
 import type {
   AutosizeOptions,
+  ColumnFilter,
   PretableCellAddress,
   PretableCellRange,
   PretableFocusState,
@@ -60,6 +61,12 @@ export { ROW_SELECT_COLUMN_ID } from "./constants";
 import { ROW_SELECT_COLUMN_ID } from "./constants";
 import { useCellEditController } from "./use-cell-edit-controller";
 import { CellEditor } from "./cell-editor";
+import {
+  FilterMenu,
+  FunnelButton,
+  popoverStyle,
+  useFilterPopover,
+} from "./filter-menu";
 import {
   type CopyPayload,
   type SerializeRangesArgs,
@@ -233,6 +240,12 @@ export interface PretableSurfaceProps<TRow extends PretableRow = PretableRow> {
   onColumnOrderChange?: (next: readonly string[]) => void;
   onColumnPinnedChange?: (next: Record<string, "left" | null>) => void;
   onTelemetryChange?: (telemetry: PretableTelemetry) => void;
+  /**
+   * Called when the built-in column filter menu mutates the active filter set.
+   * Receives the engine's full `filters` map after the change. Use to mirror
+   * filter state externally (e.g. controlled `state.filters`).
+   */
+  onFiltersChange?: (filters: Record<string, ColumnFilter>) => void;
   onGridReady?: (grid: PretableGrid<TRow>) => void;
   renderBodyCell?: (
     input: PretableSurfaceBodyCellRenderInput<TRow>,
@@ -435,6 +448,7 @@ export function PretableSurface<TRow extends PretableRow = PretableRow>({
   onColumnOrderChange,
   onColumnPinnedChange,
   onTelemetryChange,
+  onFiltersChange,
   renderBodyCell,
   renderHeaderCell,
   rows,
@@ -598,6 +612,13 @@ export function PretableSurface<TRow extends PretableRow = PretableRow>({
     ),
   });
 
+  // Built-in column filter menu: one open-state for the whole surface.
+  const {
+    openState: filterOpenState,
+    toggle: toggleFilter,
+    close: closeFilter,
+  } = useFilterPopover();
+
   const pinnedOffsets = useMemo(
     () => getPinnedLeftOffsets(effectiveColumns),
     [effectiveColumns],
@@ -1561,6 +1582,39 @@ export function PretableSurface<TRow extends PretableRow = PretableRow>({
                 }}
               />
             ) : null,
+            // Built-in filter funnel overlay — an absolutely-positioned sibling
+            // of the resize handle (NOT nested in the header <button>, which
+            // would be invalid HTML). Offset left of the 4px resize strip.
+            column.filterable !== false ? (
+              <div
+                key={`${column.id}::filter-funnel`}
+                data-pretable-filter-funnel-slot=""
+                style={{
+                  position: "absolute",
+                  top: 0,
+                  height: "100%",
+                  display: "flex",
+                  alignItems: "center",
+                  left: plannedCol.left + effWidth - 22,
+                  zIndex: 4,
+                  ...(plannedCol.pinned === "left" && pinnedOffset !== undefined
+                    ? {
+                        position: "sticky" as const,
+                        zIndex: 5,
+                        left: pinnedOffset + effWidth - 22,
+                      }
+                    : {}),
+                }}
+              >
+                <FunnelButton
+                  columnId={column.id}
+                  label={label}
+                  active={Boolean(snapshot.filters[column.id])}
+                  open={filterOpenState?.columnId === column.id}
+                  onToggle={(id, anchor) => toggleFilter(id, anchor)}
+                />
+              </div>
+            ) : null,
           ];
         })}
       </div>
@@ -1938,6 +1992,37 @@ export function PretableSurface<TRow extends PretableRow = PretableRow>({
           />
         </>
       ) : null}
+      {filterOpenState
+        ? (() => {
+            const col = effectiveColumns.find(
+              (c) => c.id === filterOpenState.columnId,
+            );
+            if (!col) return null;
+            const options =
+              col.filterOptions ??
+              grid
+                .distinctColumnValues(filterOpenState.columnId)
+                .map((v) => ({ value: v }));
+            return (
+              <FilterMenu
+                key={filterOpenState.columnId}
+                columnId={filterOpenState.columnId}
+                label={col.header ?? filterOpenState.columnId}
+                filterType={col.filterType ?? "text"}
+                options={options}
+                initialFilter={
+                  snapshot.filters[filterOpenState.columnId] ?? null
+                }
+                style={popoverStyle(filterOpenState.rect)}
+                onChange={(id, filter) => {
+                  grid.setColumnFilter(id, filter);
+                  onFiltersChange?.(grid.getSnapshot().filters);
+                }}
+                onClose={closeFilter}
+              />
+            );
+          })()
+        : null}
     </div>
   );
 }
diff --git a/packages/ui/src/grid.css b/packages/ui/src/grid.css
index ca00ef15..550c0fd5 100644
--- a/packages/ui/src/grid.css
+++ b/packages/ui/src/grid.css
@@ -218,6 +218,75 @@
     pointer-events: none;
   }
 
+  /* Built-in column filter menu (sub-project 2/3) */
+  :where([data-pretable-filter-funnel]) {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 18px;
+    height: 18px;
+    padding: 0;
+    border: 0;
+    border-radius: var(--pretable-radius);
+    background: transparent;
+    color: var(--pretable-text-dim);
+    cursor: pointer;
+    opacity: 0;
+    transition: opacity 0.1s ease;
+  }
+  /* Reveal funnels on header-row hover, on funnel keyboard focus, or when a
+     filter is active. The header row is a flat list of sibling header cells,
+     resize handles, and funnel slots (see pretable-surface.tsx), so a
+     per-column `~` hover selector would over-match every column to the right
+     of the hovered one; hovering the whole header row is the structurally
+     correct trigger. Active/focus-visible funnels stay lit regardless. */
+  :where([data-pretable-header-row]:hover [data-pretable-filter-funnel]),
+  :where([data-pretable-filter-funnel]:focus-visible),
+  :where([data-pretable-filter-funnel][data-pretable-filter-active="true"]) {
+    opacity: 1;
+  }
+  :where([data-pretable-filter-funnel][data-pretable-filter-active="true"]) {
+    color: var(--pretable-accent);
+  }
+  :where([data-pretable-filter-funnel]:hover) {
+    background: var(--pretable-bg-hover);
+  }
+
+  :where([data-pretable-filter-menu]) {
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    padding: 10px;
+    box-shadow: var(--pretable-reorder-ghost-shadow);
+    font: inherit;
+  }
+  :where([data-pretable-filter-menu]) select,
+  :where([data-pretable-filter-menu]) input[type="text"],
+  :where([data-pretable-filter-menu]) input[type="date"],
+  :where([data-pretable-filter-menu]) input:not([type]) {
+    width: 100%;
+    box-sizing: border-box;
+    padding: 5px 7px;
+    border: 1px solid var(--pretable-rule);
+    border-radius: var(--pretable-radius);
+    background: var(--pretable-bg-grid);
+    color: var(--pretable-text-cell);
+    font: inherit;
+  }
+  :where([data-pretable-filter-set]) label {
+    display: flex;
+    gap: 6px;
+    align-items: center;
+  }
+  :where([data-pretable-filter-clear]) {
+    align-self: flex-end;
+    background: transparent;
+    border: 0;
+    color: var(--pretable-accent);
+    cursor: pointer;
+    padding: 2px 4px;
+  }
+
   /* Tooltip / popover */
   :where([data-pretable-popover]) {
     background: var(--pretable-bg-tooltip);