@vmscloud/moz-ui-grid-vue 0.1.41

package/docs/manual/reference.md

@@ -0,0 +1,4695 @@
+# moz-ui-grid-core 레퍼런스 (Config · 타입 · API · 이벤트)
+
+> 패키지: `@vmscloud/moz-ui-grid-core` (export 클래스명은 호환을 위해 `PureSheet` 유지)
+> 버전: 0.1.41
+> 마지막 업데이트: 2026-09-02
+
+> 📋 **사용 예제 코드는 별도 파일**: [examples.md](examples.md) — Sub-API별 사용, Reactive React 통합, 이벤트, 선택 모드, Excel I/O 등 약 30개 시나리오
+
+## 목차
+
+- [개요](#개요)
+- [비동기 API 규칙](#비동기-api-규칙)
+- [Config (설정)](#config-설정)
+  - [PureSheetConfig](#puresheetconfig)
+  - [FlatModeConfig](#flatmodeconfig)
+  - [PivotModeConfig](#pivotmodeconfig)
+- [FieldDef (필드 정의)](#fielddef-필드-정의)
+- [PureSheet 최상위 API](#puresheet-최상위-api)
+- [Sub-API](#sub-api)
+  - [grid.rows — 행 API](#gridrows--행-api)
+  - [grid.columns — 컬럼 API](#gridcolumns--컬럼-api)
+  - [grid.changes — 변경 추적 API](#gridchanges--변경-추적-api)
+  - [grid.undoManager — Undo/Redo API](#gridundomanager--undoredo-api)
+  - [grid.rowGroup — 그룹화 API](#gridrowgroup--그룹화-api)
+  - [grid.tree — 트리 API](#gridtree--트리-api)
+  - [grid.pivot — 피벗 API](#gridpivot--피벗-api)
+  - [grid.masterDetail — 마스터-디테일 API](#gridmasterdetail--마스터-디테일-api)
+  - [grid.validation — 검증 API](#gridvalidation--검증-api)
+  - [grid.clipboard — 클립보드 API](#gridclipboard--클립보드-api)
+  - [grid.headers — 컬럼 그룹 API](#gridheaders--컬럼-그룹-api)
+  - [grid.io — Excel Import/Export API](#gridio--excel-importexport-api)
+  - [grid.dragDrop — 드래그앤드롭 API](#griddragdrop--드래그앤드롭-api)
+- [Reactive API (반응형 구독)](#reactive-api-반응형-구독)
+  - [grid.select()](#gridselect)
+  - [GridState 필드](#gridstate-필드)
+  - [grid.rows.observeById()](#gridrowsobservebyid)
+  - [ReactiveRow](#reactiverow)
+  - [ReactiveCell](#reactivecell)
+- [이벤트](#이벤트)
+- [타입 정의](#타입-정의)
+  - [ColumnGroupDef](#columngroupdef)
+  - [TreeConfig](#treeconfig)
+  - [MasterDetailConfig](#masterdetailconfig)
+  - [GroupConfig](#groupconfig)
+  - [GroupingConfig](#groupingconfig)
+  - [EditorConfig](#editorconfig)
+  - [MaskConfig](#maskconfig)
+  - [피벗 필드 타입](#피벗-필드-타입)
+  - [열거형/유니온 타입](#열거형유니온-타입)
+- [공용/내부 타입 레퍼런스](#공용내부-타입-레퍼런스)
+  - [데이터 기본 타입 (CellValue / Row / ColumnDef / ColumnState / ColumnInfo / SortState / FilterState 등)](#데이터-기본-타입)
+  - [데이터 로더 — LoaderConfig](#데이터-로더--loaderconfig)
+  - [Drag-Drop — DragDropConfig](#drag-drop--dragdropconfig-adr-110)
+  - [셀 병합 — MergeConfig](#셀-병합--mergeconfig)
+  - [스트리밍 — StreamingOptions](#스트리밍--streamingoptions)
+  - [트랜잭션 — RowTransaction / TransactionOptions / TransactionResult](#트랜잭션--rowtransaction--transactionoptions--transactionresult)
+  - [Multi-Row 레이아웃 — RowTemplate](#multi-row-레이아웃--rowtemplate)
+  - [구조적 행 — RowConfig / AggregateConfig](#구조적-행--rowconfig)
+  - [검증 — ValidationRule / ValidationError](#검증--validationrule--validationerror)
+  - [셀 에디터 — EditorOption / CustomEditorParams](#셀-에디터--editoroption--customeditorparams)
+  - [셀 렌더러 (Lifecycle 포함)](#셀-렌더러-lifecycle-포함)
+  - [설정 스냅샷 — GridConfigExport / GridConfigSnapshot](#설정-스냅샷--gridconfigexport--gridconfigsnapshot)
+  - [저장 스키마 버전 — GridConfigMigrator](#저장-스키마-버전--gridconfigmigrator)
+  - [컬럼 식별자 유틸 — columnKeys](#컬럼-식별자-유틸--columnkeys)
+  - [수식 엔진 — FormulaEngine](#수식-엔진--formulaengine)
+  - [값 목록 위젯 — ValueCheckList](#값-목록-위젯--valuechecklist)
+  - [formatRow 컨텍스트 — FormatRowInfo](#formatrow-컨텍스트--formatrowinfo)
+  - [formatHeader 컨텍스트 — FormatHeaderContext](#formatheader-컨텍스트--formatheadercontext)
+  - [RowHeaderConfig](#rowheaderconfig)
+  - [셀 속성 — CellAttributes / CellAttributesFn](#셀-속성--cellattributes--cellattributesfn)
+  - [DataLoader 클래스](#dataloader-클래스--워커-기반-커스텀-데이터-로딩)
+  - [UndoStack 클래스](#undostack-클래스--공유-undoredo)
+  - [Row 클래스 정적 팩토리](#row-클래스-정적-팩토리)
+  - [에러 코드 전체 레퍼런스](#에러-코드-전체-레퍼런스)
+  - [기타 export 항목](#기타-export-항목)
+- [API 네이밍 규칙](#api-네이밍-규칙)
+- [사용 예제](#사용-예제) — 상세 코드는 [examples.md](examples.md)
+
+---
+
+## 개요
+
+moz-ui-grid-core는 고성능 데이터 그리드 라이브러리로, 대용량 데이터 처리, 피벗, 그룹화, CRUD 등을 지원합니다.
+패키지명은 `@vmscloud/moz-ui-grid-core`이며, 메인 클래스는 호환성 유지를 위해 `PureSheet`라는 이름을 그대로 사용합니다.
+
+### 주요 특징
+
+- **고성능**: Web Worker 기반 대용량 데이터 처리 (500만 건+)
+- **피벗/그룹화**: 강력한 데이터 집계 및 분석
+- **CRUD**: Dirty State 및 Undo/Redo 지원
+- **트리**: 계층형 데이터, lazy loading 지원
+- **마스터-디테일**: 행 확장 패널
+- **커스터마이징**: formatRow, cellRenderer, cellAttributes, 마스킹 등
+- **반응형**: Reactive API (React useSyncExternalStore 호환)
+- **타입 안전**: TypeScript strict 모드 완벽 지원
+
+### 기본 사용법
+
+```typescript
+import { PureSheet } from '@vmscloud/moz-ui-grid-core';
+// 코어 패키지(@vmscloud/moz-ui-grid-core)는 CSS를 동봉하지 않습니다 — 그리드 스타일은 wrapper 패키지가 제공합니다.
+import '@vmscloud/moz-ui-grid-wrapper/style.css';
+
+const grid = new PureSheet(container, {
+  mode: 'flat',
+  fields: [
+    { id: 'name', header: '이름', dataType: 'string', width: 200 },
+    { id: 'age', header: '나이', dataType: 'number', width: 100 },
+  ],
+  data: [
+    { id: 1, name: '홍길동', age: 30 },
+    { id: 2, name: '김철수', age: 25 },
+  ],
+});
+```
+
+---
+
+## 비동기 API 규칙
+
+moz-ui-grid-core API는 **상태 변경 = async**, **순수 조회 = sync** 원칙을 따릅니다.
+
+### 기준
+
+| 분류 | 반환 타입 | 설명 |
+|------|-----------|------|
+| 상태 변경 | `Promise<void>` | 데이터 로드, 정렬, 필터, 그룹 접기/펼치기, 디테일 토글 등 |
+| 순수 조회 | 즉시 반환 | `getConfig()`, `isCollapsed()`, `getMode()` 등 |
+
+### 사용 패턴
+
+```typescript
+// ✅ 올바른 사용: await로 완료 대기
+await grid.rowGroup.collapseAll();
+await grid.tree.expandToLevel(2);
+await grid.masterDetail.expandAll();
+
+// ✅ 순수 조회는 await 불필요
+const config = grid.rowGroup.getConfig();
+const collapsed = grid.tree.isCollapsed('node-1');
+
+// ⚠️ fire-and-forget (완료를 기다릴 필요 없는 경우)
+// 이벤트 핸들러 내에서는 await 없이 호출 가능하나,
+// 후속 작업이 결과에 의존하면 반드시 await 사용
+grid.on('row:click', ({ rowIndex }) => {
+  grid.masterDetail.toggle(rowIndex); // fire-and-forget OK
+});
+```
+
+### Sub-API별 비동기 현황
+
+| Sub-API | 상태 변경 | 순수 조회 |
+|---------|-----------|-----------|
+| `grid.rows` | `deleteSelectedRows()`, `updateSelectedRows()`, `discardSelectedRows()` 등 async | `getById()`, `all()`, `getSelectedRowIds()` 등 sync |
+| `grid.columns` | 전체 sync (DOM 즉시 반영) | 전체 sync |
+| `grid.changes` | 전체 async (`addRow`, `updateCellById`, `commit`, `deleteSelectedRows` 등) | `hasChanges`, `getAll()`, `getRowStateById()` sync |
+| `grid.rowGroup` | `setConfig`, `toggle`, `expand`, `collapse` 등 async | `getConfig()`, `isCollapsed()` sync |
+| `grid.tree` | `setConfig`, `toggle`, `expand`, `collapse` 등 async | `getConfig()`, `isCollapsed()` sync |
+| `grid.pivot` | 대부분 async (프로세서 호출) | `getMode()`, `getConfig()`, `getResult()`, `getState()`, `isRowCollapsed()`, `isColumnCollapsed()`, `getCollapsedRowNodes()`, `getCollapsedColumnNodes()`, `getPivotMeta()` sync. `getFieldValues()` / `getDataMatrix()` / `getSeriesData()` / `getAllRows()`는 async |
+| `grid.masterDetail` | `setConfig`, `toggle`, `expand`, `collapse` 등 async | `getConfig()`, `isExpanded()` sync |
+| `grid.headers` | 전체 sync (DOM 즉시 반영) | 전체 sync |
+| `grid.validation` | `clear()` async | `validateAll()`, `hasErrors()`, `getCellErrors()`, `setCellErrors()`, `nextInvalid()`, `prevInvalid()` 등 sync |
+| `grid.clipboard` | 전체 async | — |
+| `grid.io` | 전체 async (`toExcel`, `saveExcelToFile`, `fromExcel`, `previewExcel`, `getSheetInfo`) | — |
+| `grid.dragDrop` | `setConfig()` async | `getConfig()`, `isActive()` sync |
+
+---
+
+## Config (설정)
+
+`PureSheetConfig = FlatModeConfig | PivotModeConfig`
+
+### PureSheetConfig
+
+#### 공통 속성 (PureSheetConfigBase)
+
+| 속성 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `data` | `Row[]` | — | 데이터 배열 |
+| `loader` | `LoaderConfig` | — | Worker 기반 데이터 로더 설정 |
+| `fields` | `FieldDef[]` | 필수 | 필드(컬럼) 정의 |
+| `keyFields` | `string[]` | `['id']` | 행 고유 ID 식별 필드 목록. 복합 키도 가능(예: `['exchange', 'symbol']`) |
+| `enableReferCache` | `boolean` | `false` | 행 객체 참조 캐시 활성화 — 행 객체 기반 API(`updateCell(row, ...)`, `deleteRow(row)` 등) 사용 시 필수 |
+| **엔진** | | | |
+| `engine` | `'native'` | `'native'` | 데이터 처리 엔진. **`'aq'`(Arquero)는 제거됨** — 단일 엔진(native)만 남았습니다(ITSM-2026-002190) |
+| `useWorker` | `boolean` | `false` | Web Worker 사용 여부 |
+| **저장본 호환** | | | |
+| `migrateConfig` | `GridConfigMigrator` | — | `applyConfig()` 가 옛 버전 저장본을 받았을 때 호출할 변환기. core 는 **호출 시점·순서만** 책임지고 변환 내용은 소비처(wrapper)가 소유 (→ [저장 스키마 버전](#저장-스키마-버전--gridconfigmigrator)) |
+| **UI** | | | |
+| `theme` | `'light' \| 'dark' \| 'auto' \| 'excel' \| 'sheets' \| 'material' \| (string & {})` | `'light'` | 테마. 빌트인 프리셋 외 임의 문자열도 허용(사용자가 `.ps-theme-{name}` 클래스 정의 시 자동 적용) |
+| `rowHeight` | `number` | — | 행 높이 (px) |
+| `dynamicRowHeights` | `boolean` | `false` | 동적 행 높이 활성화 |
+| `rowHeightChangeThreshold` | `number` | `2` | 높이 변경 감지 임계값 (px) |
+| `headerHeight` | `number` | — | 헤더 높이 (px) |
+| `showHeader` | `boolean` | `true` | 헤더 표시 여부 |
+| `rowHeader` | `boolean \| RowHeaderConfig` | `false` | 좌측 행 헤더 컬럼(`_rowHeader`) 표시. `true`면 빈 셀(너비 40, 체크박스 트리거 시 체크박스), 객체면 `width`/`cellRenderer`/`headerRenderer`로 커스터마이즈 (→ [RowHeaderConfig](#rowheaderconfig)). `rowSelection.trigger`가 `'rowHeader'`/`'checkbox'`면 미지정이어도 자동 ON. (구 `showRowHeader` — deprecated alias 유지) |
+| `showStatusBar` | `boolean` | `true` | 상태 바 표시 |
+| `alternatingRows` | `boolean` | `false` | 줄무늬 행 스타일 |
+| `rowStyle` | `string` | — | 행 CSS 스타일 |
+| `headerStyle` | `string` | — | 헤더 CSS 스타일 |
+| **컬럼 동작** | | | |
+| `resizableColumns` | `boolean` | `true` | 컬럼 리사이즈 허용 |
+| `reorderableColumns` | `boolean` | `true` | 컬럼 재정렬 허용 |
+| `autoFitColumns` | `boolean` | `false` | 로드 시 전체 컬럼 자동 맞춤 |
+| **선택** | | | |
+| `rowSelection` | `RowSelectionConfig` | — | 행 선택 설정 (identity 추종, rowId 기반). 서브필드: `mode`, `trigger`, `includeInSelectAll`. 자세한 내용은 "선택 모드 사용 예제" 참조 |
+| `cellSelection` | `CellSelectionConfig` | — | 셀 선택 설정 (자리 추종, viewIndex 기반). 서브필드: `mode`. 둘 다 미지정 시 기본 `{mode:'range'}` (셀 전용 Excel 스타일) |
+| `cellSelectionImpliesRows` | `boolean` | `false` | 셀만 선택된 상태에서 행 액션(Ctrl+H 등) 작동 여부 — Policy B fallback. Ctrl+A 동작은 `rowSelection.includeInSelectAll`이 별도 제어 |
+| **서버/수동 row-model** | | | |
+| `rowModel` | `'client' \| 'server'` | `'client'` | `'server'`이면 `sort()`/`filter()`는 정렬·필터 상태와 이벤트만 갱신하고 supplied row order/membership을 로컬에서 변경하지 않습니다. 데이터 재조회/append는 호출자가 서버 정본으로 수행합니다. |
+| `endReachedThresholdRows` | `number` | `0` | `scroll:endReached` 선발화 행 임계값. 현재 가시 범위 끝에서 남은 행 수가 이 값 이하이면 끝 도달로 간주합니다. |
+| **편집** | | | |
+| `editable` | `boolean` | `false` | 전역 편집 가능 여부 |
+| `preventKeyEdit` | `boolean` | `true` | 키 컬럼 편집 방지 — `keyFields` 컬럼은 신규 행(added)에서만 편집 가능, 기존 행(pristine/modified)에서는 자동 readonly |
+| **드래그앤드롭** | | | |
+| `dragDropConfig` | `DragDropConfig` | — | 행 드래그앤드롭 설정 (같은 그리드 reorder, 크로스-그리드 드롭, `rowOrderField`, `mutateOnDirty` 등). 런타임 변경은 `grid.dragDrop.setConfig()` |
+| **툴팁** | | | |
+| `tooltipMode` | `'none' \| 'overflow' \| 'always'` | `'none'` | 툴팁 표시 모드 |
+| **Undo** | | | |
+| `undoStack` | `UndoStack` | — | 외부 UndoStack 주입 |
+| **국제화** | | | |
+| `locale` | `string` | 자동 감지 | 로케일 (예: `'ko-KR'`) |
+| `translations` | `PartialTranslationMap` | — | 번역 오버라이드 |
+| **포맷팅** | | | |
+| `formatRow` | `FormatRowCallback` | — | 행 포맷팅 콜백 (config에서 설정 시 `_config` 키로 자동 등록) |
+| `formatHeader` | `FormatHeaderCallback` | — | 헤더 행 포맷팅 콜백 (config에서 설정 시 `_config` 키로 자동 등록). 헤더 (재)렌더 시 발화. 스크롤로는 발화 X |
+| **이벤트 핸들러** | | | |
+| ~~`onRowClick`~~ | — | — | **제거됨.** `grid.on('row:click', ...)` 이벤트 구독으로 대체 (→ [이벤트](#이벤트)) |
+| ~~`onCellClick`~~ | — | — | **제거됨.** `grid.on('cell:click', ...)` 이벤트 구독으로 대체 (→ [이벤트](#이벤트)) |
+| ~~`onGroupToggle`~~ | — | — | **제거됨.** 로우 그룹 토글은 이벤트로 노출됩니다 — `rowGroup:toggle`(단일), `rowGroup:batchToggle`(일괄: `scope`로 `level`/`toLevel`/`all` 구분). `grid.on('rowGroup:toggle', ...)` 등으로 구독 (→ [이벤트](#이벤트)) |
+
+### FlatModeConfig
+
+`PureSheetConfigBase`에 추가:
+
+| 속성 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `mode` | `'flat'` | `'flat'` | 그리드 모드 |
+| `rowGroup` | `GroupConfig` | — | 초기 그룹화 설정 (`{ columns, subtotals }`). 런타임에는 `grid.rowGroup.setConfig(GroupingConfig)`로 변경하며 시그니처가 다름 (→ [GroupConfig](#groupconfig) vs [GroupingConfig](#groupingconfig)) |
+| `group` | `GroupConfig` | — | **deprecated 하위호환 별칭** — `rowGroup`과 동일. 둘 다 주면 `rowGroup`이 우선. 신규 코드는 `rowGroup` 사용 |
+| `rowTemplate` | `RowTemplate` | — | Multi-Row 레이아웃 템플릿 |
+| `columnGroups` | `ColumnGroupDef[]` | — | 컬럼 그룹(다단계 컬럼 헤더) 정의 (→ [ColumnGroupDef](#columngroupdef)). (구 `headerGroups`) |
+| ~~`onColumnGroupToggle`~~ | — | — | **제거됨.** 컬럼 그룹 토글은 `columnGroup:toggle` 이벤트로 노출됩니다. `grid.on('columnGroup:toggle', ...)`로 구독 (→ [이벤트](#이벤트)) |
+| `treeConfig` | `TreeConfig` | — | 트리 모드 초기 설정 — `parentField`/`pathField`로 flat 데이터를 트리로 표시. 런타임 변경은 `grid.tree.setConfig()` (→ [TreeConfig](#treeconfig)) |
+| `masterDetailConfig` | `MasterDetailConfig` | — | 마스터-디테일 초기 설정 — 데이터 행을 확장하면 아래에 디테일 패널 표시. 런타임 변경은 `grid.masterDetail.setConfig()` (→ [MasterDetailConfig](#masterdetailconfig)) |
+
+### PivotModeConfig
+
+`PureSheetConfigBase`에서 `fields` 대신 피벗 필드 사용:
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `mode` | `'pivot'` | 피벗 모드 (필수) |
+| `rowFields` | `PivotRowField[]` | 행 축 필드 |
+| `columnFields` | `PivotColumnField[]` | 열 축 필드 (피벗) |
+| `valueFields` | `PivotValueField[]` | 값 필드 (집계) |
+
+---
+
+## FieldDef (필드 정의)
+
+각 컬럼의 동작, 외형, 편집 설정을 정의합니다.
+
+### 기본 속성
+
+| 속성 | 타입 | 필수 | 설명 |
+|------|------|------|------|
+| `id` | `string` | O | 컬럼 **식별자** — 이 컬럼을 *가리킬* 때 쓴다. 정렬/필터 상태(`SortState.id`/`FilterState.id`), 컬럼 폭 상태, DOM dataset, 저장 레이아웃이 전부 이 값을 참조 |
+| `field` | `string` | — | 원본 데이터 객체의 **키** — 값을 *읽을* 때만 쓴다(`row[field]`). 생략 시 `id` 와 같은 값으로 정규화 |
+| `header` | `string` | O | 헤더 표시명 |
+| `dataType` | `DataType` | O | 데이터 타입 (`'string' \| 'number' \| 'boolean' \| 'date' \| 'array'`) |
+
+> **`id` ≠ `field` — 이중 역할 해소 (ITSM-2026-002188)**
+> 예전에는 `id` 하나가 "식별자"와 "데이터 키"를 겸했습니다("필드 ID = 데이터 객체의 키"). 이제 두 축이 분리되어 **가리킬 때는 `id`, 읽을 때는 `field`** 입니다.
+>
+> `field` 를 생략하면 경계에서 1회 `field = id` 로 정규화되므로 **기존 소비처는 아무것도 바꾸지 않아도 동작이 동일**합니다.
+>
+> ```typescript
+> // 같은 원본 컬럼을 두 번 배치 — id 로 구분
+> { id: 'dept_raw',   field: 'dept', header: '부서(원본)', dataType: 'string' }
+> { id: 'dept_short', field: 'dept', header: '부서(약칭)', dataType: 'string' }
+> ```
+>
+> ⚠️ 계산 필드(`formula`)는 원본 데이터에 존재하지 않으므로 `field` 가 의미 없습니다 — `id` 만 지정하고 값 조회는 `FormulaEngine` 이 담당합니다.
+>
+> 정규화 헬퍼는 core 가 export 합니다: `normalizeColumnKeys` / `getColumnId` / `getColumnField` / `resolveFieldKey` (→ [컬럼 식별자 유틸](#컬럼-식별자-유틸--columnkeys)).
+
+### 너비/크기
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `width` | `number` | 너비 (px) |
+| `minWidth` | `number` | 최소 너비 (px) |
+| `maxWidth` | `number` | 최대 너비 (px) |
+| `flex` | `number` | Flex 비율 (남은 공간 배분) |
+| `autoFit` | `boolean` | 콘텐츠에 맞게 자동 너비 조절 |
+| `style` | `string` | CSS 스타일 문자열 |
+
+### 정렬/표시
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `align` | `'left' \| 'center' \| 'right'` | 셀 정렬 (dataType에서 자동 추론) |
+| `hidden` | `boolean` | 숨김 필드 |
+| `lockVisible` | `boolean` | 가시성 잠금 (기본 `false`). 아래 참조 |
+| `pinned` | `'left' \| 'right'` | 컬럼 고정 위치 |
+
+> **`lockVisible` — 가시성 하드 잠금**
+> `true` 면 **현재 가시성 상태가 고정**되어 표시/숨김을 바꿀 수 없습니다. 컬럼 옵션 패널의 체크박스가 비활성화되고(체크 상태는 실제 가시성 그대로), 전체표시 토글의 대상에서도 제외됩니다. UI 뿐 아니라 **프로그램적 API**(`columns.hide` / `show` / `setHidden` / `toggle` / `update({ hidden })`)도 거부하고 `console.warn` 을 남깁니다.
+>
+> 초기 상태는 `hidden` 과 조합해 정합니다 — `hidden:false`+잠금 = **항상 표시**, `hidden:true`+잠금 = **항상 숨김**.
+>
+> 요청값이 현재값과 같으면 조용한 no-op 이므로 `reset()` / `resetAll()` / `load()` / `updateFields()` 의 상태 복원 경로는 영향받지 않습니다. 저장된 레이아웃(`load`)이나 새 `fields`(`updateFields`)가 잠긴 컬럼을 반대 상태로 담고 있어도 선언된 고정 가시성으로 되돌립니다.
+>
+> 잠기는 것은 **가시성뿐**입니다 — 순서·너비·고정·서식은 그대로 변경 가능합니다.
+>
+> (AG Grid 의 동명 옵션 `lockVisible` 은 UI 만 막고 API 는 통과시키지만, moz-ui-grid 에서는 소비처가 기대하는 불변식이 "그 컬럼은 반드시 보인다/숨는다" 이므로 **하드 불변식**으로 정의했습니다.)
+
+### 정렬/필터
+
+| 속성 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `sortable` | `boolean` | `true` | 정렬 허용. `PureSheet.toggleSort` 에 게이트가 있어 실제로 동작 |
+| `showFilterIcon` | `boolean` | `true` | 헤더에 **필터 아이콘을 표시할지** (ITSM-2026-002194) |
+| `filterable` | `boolean` | `true` | 필터 허용 — ⚠️ **현재 동작에 반영되지 않음**(아래 참조) |
+
+> **`showFilterIcon` — 표시 축 (ITSM-2026-002194)**
+> `false` 면 core 가 아이콘 span **자체를 만들지 않습니다**. CSS 로 숨기는 것과 달리 클릭 대상이 존재하지 않으므로 `header:filterClick` 도 발생하지 않습니다(소비 지점마다 걸러야 하는 무증상 실패를 만들지 않기 위한 선택 — `resizable` 이 리사이즈 핸들 DOM 생성을 가르는 것과 같은 층위).
+>
+> ⚠️ 이것은 **표시 축**이며 필터 **능력**을 막지 않습니다. 툴바 필터 창·수식 등 다른 경로로는 여전히 조건을 걸고 **해제**할 수 있습니다 — 능력까지 막으면 이미 걸어 둔 조건을 되돌릴 수 없습니다. (AG Grid 도 `suppressHeaderFilterButton`(표시)과 `filter: false`(능력)를 분리합니다.)
+>
+> 정렬 쪽에는 대응 옵션이 **없습니다.** 정렬 진입점은 아이콘과 **헤더 셀 클릭** 둘이라 아이콘만 숨기면 "정렬은 되는데 상태 표시가 없는" 상태가 됩니다. 정렬을 막으려면 `sortable` 을 쓰세요.
+
+> **⚠️ `filterable` 은 현재 미동작입니다 (ITSM-2026-002167, 실측)**
+> 값은 `configAdapter` 를 거쳐 `ColumnDef.filterable` 로 전달되지만 **이를 읽어 분기하는 코드가 없습니다** — 툴바 필터 창·컨텍스트 메뉴의 컬럼 후보에서 제외되지 않습니다. (`sortable` 은 게이트가 있어 동작하는데 그 짝이 없는 상태입니다.)
+>
+> 헤더 필터 아이콘만 감추려면 **`showFilterIcon: false`** 를 쓰세요. `filterable` 은 "필터 능력" 축을 위해 예약돼 있으며, 실제 게이트가 생기기 전까지 표시 축과 혼동하지 마세요.
+
+### 편집
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `editable` | `boolean` | 편집 가능 여부 |
+| `readonly` | `boolean` | 읽기 전용 (전역 editable 오버라이드) |
+| `editor` | `EditorConfig` | 에디터 설정 |
+| `editableWhen` | `(params) => boolean` | 동적 편집 가능 조건 |
+| `editorResolver` | `(params) => EditorConfig \| null` | 동적 에디터 결정 |
+| `validation` | `ValidationRule[]` | 검증 규칙 |
+
+### 포맷팅
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `mask` | `MaskConfig` | 마스킹 설정 |
+| `aggregate` | `AggregateFunc` | 그룹/피벗 집계 함수 |
+
+### 그룹 행
+
+| 속성 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `unmergeOnGroupRow` | `boolean` | `false` | 그룹 행의 배너 머지에서 이 컬럼을 제외하고 **자기 셀을 유지**해 집계값(`aggregate`)을 그룹 행에 표시한다. 그룹 행의 center 영역은 라벨/집계를 보여주는 하나의 긴 배너(머지 셀)인데, 이 옵션이 켜진 컬럼은 배너에 흡수되지 않는다 |
+
+> **`unmergeOnGroupRow` 활성 조건** — 배너 머지는 **연속된 범위**여야 하므로 이 옵션은 필드가 center 영역의 연속된 **맨 왼쪽(prefix)** 또는 **맨 오른쪽(suffix)** 에 위치할 때만 활성화됩니다(중간에 위치하면 무시되고 배너에 흡수). 강제 컬럼 이동은 하지 않으므로 헤더·데이터·그룹 행 셀이 자동 정렬됩니다. `pinned` 컬럼은 이미 자기 고정 셀에 집계를 표시하므로 이 옵션과 무관합니다. 그룹 행에서 합계 등 집계값을 컬럼별로 보이게 하려는 용도입니다.
+
+### 계산 필드
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `formula` | `string \| ((row) => unknown)` | 다른 컬럼 기반의 계산 필드. 문자열은 단순 표현식, 함수는 임의 계산. 결과는 표시·정렬·필터·집계에 사용됨 |
+
+```typescript
+{
+  id: 'total',
+  header: '합계',
+  dataType: 'number',
+  // 함수 수식
+  formula: (row) => (row.price as number) * (row.quantity as number),
+}
+```
+
+### 렌더링
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `cellRenderer` | `CellRenderer` (Simple \| Lifecycle) | 커스텀 셀 렌더러 — `(params) => HTMLElement\|string`(Simple, arity 1) 또는 `(container, params) => CellRendererInstance`(Lifecycle, arity 2). 상세는 [CellRendererParams / CellRenderer](#) 타입 정의 참조 |
+| `cellAttributes` | `CellAttributes \| CellAttributesFn` | 셀 HTML 속성 (정적/동적) |
+| `headerRenderer` | `(params) => HTMLElement \| string` | 커스텀 헤더 렌더러 |
+| `headerAttributes` | `CellAttributes` | 헤더 셀 HTML 속성 |
+| `headerTooltip` | `string` | 헤더 커스텀 툴팁 문구(고정). 설정 시 헤더 hover 툴팁이 라벨 대신 이 문구 표시(overflow 무관 항상). `tooltipMode !== 'none'` 필요 |
+| `cellTooltip` | `(params: { value, row, columnId }) => string` | 셀 커스텀 툴팁 문구(행별 동적). **hover 시점에만** 호출(렌더/스크롤 시 전 셀 호출 아님 → 성능 부담 없음). 반환값을 라벨 대신 표시(overflow 무관 항상). `tooltipMode !== 'none'` 필요 |
+
+### cellRenderer 예시
+
+```typescript
+{
+  id: 'status',
+  header: '상태',
+  dataType: 'string',
+  cellRenderer: ({ value, rowData }) => {
+    const span = document.createElement('span');
+    span.className = `badge badge-${value}`;
+    span.textContent = String(value);
+    return span;
+  },
+}
+```
+
+### cellAttributes 예시
+
+```typescript
+{
+  id: 'amount',
+  header: '금액',
+  dataType: 'number',
+  cellAttributes: ({ value }) => ({
+    style: Number(value) < 0 ? 'color: red' : 'color: blue',
+    class: 'amount-cell',
+  }),
+}
+```
+
+---
+
+## PureSheet 최상위 API
+
+PureSheet 인스턴스에서 직접 호출하는 메서드들입니다. Sub-API 네임스페이스(`grid.rows`, `grid.columns` 등)는 별도 섹션에서 설명합니다.
+
+### 라이프사이클
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `waitForReady()` | `Promise<void>` | 초기 렌더링 완료까지 대기 |
+| `refresh()` | `Promise<void>` | 데이터 재처리 + 렌더링 갱신 |
+| `notifyResize()` | `void` | 컨테이너 가시성/크기 변경을 호스트가 명시적으로 알리는 훅. viewport 재측정 + 스크롤 재동기화 + 가상 가시범위 재계산 → 재렌더. 데이터/컬럼 변경 없이 레이아웃만 다시 맞추므로 `refresh()`보다 가벼움 (ResizeObserver로 감지 못 한 컨테이너 표시/크기 변경 시나리오용) |
+| `destroy()` | `void` | 리소스 해제, DOM 정리 |
+
+### 데이터
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `loadData(data)` | `Promise<void>` | 데이터 로드 (기존 데이터 교체) |
+| `getAllData()` | `Promise<RowData[]>` | 전체 데이터 조회 |
+| `getVisibleData()` | `Promise<RowData[]>` | 필터/정렬 적용된 processor 데이터 조회. 하위 호환 API라 rowGroup/tree collapse로 renderer에서 숨긴 자식 행은 제외하지 않음 |
+| `getDisplayedData()` | `Promise<RowData[]>` | 현재 renderer view-index 순서의 순수 도메인 데이터 행. rowGroup/tree collapse 반영(접힌 자식 제외), group header/subtotal/grand-total/master-detail 구조 행 제외, DOM/viewport 가상화와 무관 |
+| `getDisplayedRowIds()` | `Promise<RowId[]>` | `getDisplayedData()`와 같은 순서의 도메인 rowId 목록 |
+| `rows.displayedCount()` | `number` | displayed 좌표계 총 행 수(그룹/트리 collapse 반영). traversal 경계 계산용 |
+| `rows.getByDisplayedIndex(i)` | `Promise<DisplayedRowInfo \\| null>` | displayed 좌표 i의 단일 행 정보(O(1)~O(log g), 배열 materialize 없음). 다음/이전 이동 등 traversal용. 범위 밖 `null` |
+| `rows.getDisplayedIndexById(id)` | `Promise<number>` | rowId → displayed 인덱스. 접힘/필터로 숨겨졌으면 `-1`. rowId만으로 호출 시 idMap O(N) 유발 가능하므로 대용량 traversal은 index 보관 권장 |
+| `getRowById(rowId)` | `Promise<RowData \| undefined>` | ID로 단일 행 조회 |
+| `getRowIndexById(rowId)` | `Promise<number>` | ID → 데이터 인덱스 |
+| `getRowVirtualIndexById(rowId)` | `Promise<number>` | ID → 가상 인덱스 (그룹 행 포함) |
+
+> sourceIndex 기반 단일 행 조회는 `grid.rows.getByIndex(idx).data` 또는 `grid.changes.getRowStateByIndex(idx)` 경로를 사용하세요. 최상위 `getRowByIndex` 메서드는 더 이상 존재하지 않습니다.
+
+### CRUD
+
+최상위에는 별도의 CRUD 메서드가 없습니다. 모든 추가/수정/삭제는 `grid.changes` 네임스페이스로 통합되어 있습니다. 자세한 내용은 [grid.changes — 변경 추적 API](#gridchanges--변경-추적-api) 참조.
+
+```typescript
+// ✅ 행 추가/수정/삭제는 grid.changes로
+await grid.changes.addRow({ name: '신규' });
+await grid.changes.updateCellById('row-1', 'name', '수정됨');
+await grid.changes.deleteRowById('row-1');
+await grid.changes.commit();
+```
+
+### 정렬 / 필터
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `sort(sorts)` | `Promise<void>` | 정렬 적용 |
+| `filter(filters)` | `Promise<void>` | 필터 적용. `FilterState[]`(평면, 하위 호환) 또는 **`FilterGroupMap`**(소스별 그룹) 둘 다 받음 |
+| `setFilterGroup(key, group)` | `Promise<void>` | 그룹 하나만 교체/삭제(`null`=삭제). 다른 그룹은 건드리지 않음 |
+| `getFilterGroup(key)` | `FilterGroup \| undefined` | 그룹 하나 조회 (sync) |
+| `getFilterGroups()` | `FilterGroupMap` | 전체 그룹 맵 조회 (sync) |
+| `getViewState()` | `{ sorts, filters, filterGroups }` | 현재 뷰 상태 조회 (sync). `filters` 는 그룹을 평탄화한 **파생값** |
+| `setViewState(state)` | `Promise<void>` | 정렬+필터 일괄 적용 |
+| `toggleSort(columnId, opts?)` | `void` | 헤더 클릭형 정렬 토글. 대상 컬럼을 none → asc → desc → none 사이클로 토글하고 `sort()`를 적용. `opts.additive: true`면 기존 정렬을 유지하며 해당 컬럼만 토글/추가(다중 정렬, shift+클릭 용도), `false`(기본)면 단일 컬럼 정렬. `sortable: false` 컬럼은 무시 |
+
+> **헤더 클릭 = 정렬 정책은 소비처 소유.** core는 헤더 클릭 시 자동으로 정렬하지 **않고** `header:click` 이벤트만 발행합니다(아래 [이벤트 목록](#이벤트-목록) 참조). "헤더 클릭 = 정렬"을 원하면 소비처가 `header:click`을 구독해 `grid.toggleSort(columnId, { additive: event.shiftKey })`를 직접 호출하세요. 정책을 비활성화하려면 구독하지 않으면 됩니다.
+
+#### 값 목록 필터 (엑셀식 체크박스)
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `getFilterValues(columnId, options?)` | `Promise<ColumnValuesResult>` | 값 목록 후보 수집. `options`: `{ keyword?, limit?, onProgress? }`. **자기 컬럼의 값 목록 조건(`in`/`notIn`)만 제외**한 나머지 필터를 적용해 수집 |
+| `getUniqueValues(columnId)` | `Promise<CellValue[]>` | 고유값 배열 (하위 호환·단순 조회용) |
+| `formatColumnValue(columnId, raw)` | `string` | 원본값 → 그 컬럼의 화면 표시 문구(mask 적용). 소비처가 mask 규칙을 재구현하면 어긋나므로 core 가 소유 |
+
+> **왜 "컬럼"이 아니라 "값 목록 조건"만 제외하나 (ITSM-2026-000531)**
+> 한 컬럼에 값 목록 조건과 **조건식**(`neq`, `contains`, 수식 …)이 **함께** 걸릴 수 있습니다. 컬럼 id 만 보고 제외하면 조건식까지 빠져, 조건식으로 숨긴 값이 목록에 되살아납니다(실측: 이름 컬럼에 "김철수 제외" 조건식을 걸어도 목록에 김철수가 남음). 되돌릴 수 있어야 하는 것은 **이 패널이 만든 체크 상태**뿐입니다.
+>
+> **표시값(mask) 기준 dedupe** — 컬럼에 mask 가 있으면(명시 `mask` 또는 number 컬럼의 천단위 구분자) 표시값 기준으로 dedupe 합니다. 검색·필터가 이미 표시값 기준이라 목록만 원본값을 쓰면 "보이는 값으로 골랐는데 안 걸리는" 불일치가 납니다. 다만 **필터에 실을 값은 `rawValues`(원본)** 입니다 — 표시값 비교는 5M 행에서 30.6배 느리고 함수형 mask 는 Worker 복제가 안 됩니다.
+>
+> **상한** — 기본 `DEFAULT_VALUE_LIST_LIMIT = 10,000`(Excel AutoFilter 와 동일). 도달하면 스캔을 조기 종료하고 `truncated: true` 로 알립니다. 소비처는 이때 "검색으로 좁혀 주세요"를 안내합니다.
+
+```typescript
+const res = await grid.getFilterValues('dept', { keyword: '영업', limit: 5000 });
+res.values;     // 표시 라벨 (mask 적용)
+res.rawValues;  // 필터에 실을 원본값 — values[i] 와 1:1
+res.truncated;  // true 면 상한 도달 (검색 유도)
+
+await grid.filter([{ id: 'dept', operator: 'in', filterValue: res.rawValues, sequence: 0 }]);
+```
+
+### 셀 병합
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `setMergeConfig(config)` | `Promise<void>` | 셀 병합 설정 (`null`로 해제) |
+
+### 트랜잭션
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `applyTransaction(tx, options?)` | `Promise<TransactionResult>` | 동기 트랜잭션 (add/update/remove 일괄) |
+| `applyTransactionAsync(tx, callback?)` | `void` | 비동기 트랜잭션 큐잉 |
+| `flushAsyncTransactions()` | `Promise<TransactionResult[]>` | 대기 중인 비동기 트랜잭션 일괄 실행 |
+
+### 데이터 로더
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `updateLoaderParams(params)` | `Promise<void>` | 로더 파라미터 변경 + 재조회 |
+| `refreshLoaderData()` | `Promise<void>` | 로더 데이터 재조회 |
+
+### 스크롤 / 내비게이션
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `scrollToRow(rowIndex)` | `void` | 특정 행으로 스크롤 |
+| `ensureCellVisible(dataIndex, columnId)` | `void` | 특정 셀이 보이도록 스크롤 |
+
+### 검색
+
+전체 데이터(가상 스크롤 영역 포함, 피벗 모드에서는 `cachedPivotData`)를 대상으로 청크 분할 검색을 수행합니다. 진행률은 `cell:tooltip`이 아닌 `search:highlighted` 이벤트로 전달됩니다. 검색 활동 중에는 `GridState.activity === 'search'`와 `GridState.isSearching === true`가 true입니다.
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `search(keyword, options?)` | `Promise<{ matches: CellPosition[]; total: number; currentIndex: number }>` | 키워드 검색. `options`: `{ caseSensitive?, useRegex? }`. 빈 문자열이면 `clearSearch()`와 동일 |
+| `findNext()` | `CellPosition \| null` | 다음 매칭으로 이동(순환). 매칭 없으면 `null` |
+| `findPrev()` | `CellPosition \| null` | 이전 매칭으로 이동(순환). 매칭 없으면 `null` |
+| `findAt(index)` | `CellPosition \| null` | 지정 인덱스의 검색 매칭으로 이동(스크롤+하이라이트). `index`는 0-based(`getSearchState().currentIndex`와 동일 규약). 범위 밖이거나 매칭 없으면 `null` |
+| `clearSearch()` | `void` | 검색 결과 초기화 + 하이라이트 해제 |
+| `getSearchState()` | `SearchHighlightState & { matches, total, currentIndex }` | 현재 키워드/매칭 좌표/커서 인덱스 등 검색 상태 스냅샷 |
+
+```typescript
+const result = await grid.search('홍길동');
+console.log(result.total);             // 매칭 셀 수
+console.log(result.currentIndex);      // 0이면 첫 매칭 셀이 선택됨
+
+grid.findNext();                       // 다음 매칭으로 스크롤
+grid.findPrev();                       // 이전 매칭
+
+const state = grid.getSearchState();
+state.matches.forEach(({ rowIndex, columnId }) => { /* ... */ });
+
+grid.clearSearch();                    // 종료
+```
+
+### 레이아웃 / UI
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `setDynamicRowHeights(enabled)` | `void` | 동적 행 높이 켜기/끄기 |
+| `isDynamicRowHeightsEnabled()` | `boolean` | 동적 행 높이 상태 조회 |
+| `setHeaderVisible(visible)` | `void` | 헤더 표시/숨김 |
+| `isHeaderVisible()` | `boolean` | 헤더 표시 상태 조회 |
+| `setStatusBarVisible(visible)` | `void` | 상태 바 표시/숨김 |
+| `formatRow.addHandler(id, cb, opts?)` | `void` | 행 포맷 핸들러 등록 (네임드 키 + priority) |
+| `formatRow.removeHandler(id)` | `void` | 행 포맷 핸들러 해제 |
+| `formatRow.has(id)` | `boolean` | 핸들러 등록 여부 확인 |
+| `formatRow.size` | `number` | 등록된 핸들러 수 |
+| `formatRow.clear()` | `void` | 모든 핸들러 제거 |
+| `formatHeader.addHandler(id, cb, opts?)` | `void` | **헤더 행** 포맷 핸들러 등록 (네임드 키 + priority). 헤더 (재)렌더 시 발화 — formatRow 의 헤더 카운터파트 |
+| `formatHeader.removeHandler(id)` | `void` | 헤더 핸들러 해제 |
+| `formatHeader.has(id)` | `boolean` | 등록 여부 |
+| `formatHeader.size` | `number` | 등록된 핸들러 수 |
+| `formatHeader.clear()` | `void` | 모든 헤더 핸들러 제거 |
+
+### 스트리밍
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `setStreamingOptions(options)` | `void` | 스트리밍 옵션 설정 |
+| `flushRowBatch()` | `void` | 배치된 행 즉시 렌더링 |
+
+### 선택
+
+선택 동작은 생성자의 `rowSelection` / `cellSelection` 옵션으로만 설정. 런타임 모드 변경은
+재생성으로 처리(소수 사용처). 선택 결과 조회는 `grid.rows.getSelectedRowIds()` / `grid.rows.getSelectedRowsAccessor()`
+또는 SelectionManager 직접 접근(`getSelectedRows`, `getSelectedCells` 등).
+
+> **그룹 행과 선택** — 그룹 행(그룹 배너)은 데이터 없는 구조적 행이라 선택 대상이 아닙니다.
+> 드래그 range는 그룹 경계에서 **분리(split)** 되고, `selectAll()`은 그룹 행을 제외한 **모든
+> 데이터 행**을 덮습니다(중간에 그룹 행이 끼어 있어도 하단까지 포함). 자세한 동작은 예제 문서의
+> 「그룹 행과 선택」 참조.
+
+### 이벤트
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `on(event, handler)` | `Unsubscribe` | 이벤트 구독 (해제 함수 반환) |
+| `off(event, handler)` | `void` | 이벤트 구독 해제 |
+
+### 카운트
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `getTotalRowCount()` | `number` | 전체 행 수 (필터 전) |
+| `getVisibleRowCount()` | `number` | 가시 행 수 (필터 후) |
+
+### 내보내기
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `getExportData(options?)` | `Promise<{ headers, rows }>` | 데이터 내보내기 (scope: `'all'` \| `'visible'` \| `'selected'`) |
+
+### 필드 / 로케일
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `getFields()` | `FieldDef[] \| null` | 필드 정의 조회 (flat 모드 전용, 피벗에서 null) |
+| `updateFields(fields)` | `Promise<void>` | 필드 정의 교체 (flat 모드 전용). 기존 컬럼의 레이아웃 상태(너비, 순서, 가시성, 고정)를 보존하면서 필드를 교체. 새 필드는 추가, 삭제된 필드는 제거. **`getFields()` 가 반환하는 원본 필드 목록도 함께 갱신됩니다**(ITSM-2026-002177) — 이전에는 갱신되지 않아 화면에는 있는데 필드 목록에 없는 동적 컬럼이 생겼고, `getFields().find(id)` 로 필드를 찾는 소비처(필터 팝오버·툴바 필터 창·정렬 패널)가 **에러 없이 조용히 무시**했습니다(실측: 동적 컬럼의 필터 아이콘 무반응). 합성 컬럼(`_rowHeader`/`__drag_handle__`)은 core 주입분이라 원본 필드 목록에 포함되지 않습니다 |
+| `getPivotFields()` | `{ rowFields, columnFields, valueFields, filterFields } \| null` | 피벗 필드 조회 (각 카테고리별 FieldDef[], flat에서 null) |
+| `setLocale(locale)` | `void` | 로케일 변경 |
+| `getLocale()` | `string` | 현재 로케일 조회 |
+
+### 설정 저장/복원 (Config Snapshot)
+
+그리드의 **레이아웃/뷰 상태**(컬럼 너비·순서·숨김·고정, 정렬/필터, 피벗·트리·디테일 설정, UI 옵션 등)와 **reset baseline** 을 직렬화 가능한 bundle 로 추출하고 다시 적용합니다. 사용자별 레이아웃 저장, 프리셋 전환, 백엔드 동기화에 활용합니다.
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `getConfig()` | `GridConfigExport` | 현재 그리드 상태 + reset baseline 을 `{ current, snapshot }` bundle 로 반환 |
+| `applyConfig(cfg, options?)` | `Promise<void>` | Export bundle 을 현재 그리드에 적용. `cfg.snapshot` 이 있고 `options.applySnapshot !== false` 면 baseline 도 함께 복원 |
+
+**`GridConfigExport` bundle 구조**
+
+```ts
+interface GridConfigExport {
+  /** 현재 그리드 상태 (런타임 — 컬럼 width/visible/pinned/order, sort/filter/group/pivot 등 모두 반영) */
+  current: GridConfigSnapshot;
+  /**
+   * Reset 의 복귀 기준 baseline. 현재는 컬럼 정적 정의(`fields`) 만 반영됨.
+   * 없으면 `applyConfig` 가 기존 baseline 유지.
+   */
+  snapshot?: GridConfigSnapshot;
+}
+```
+
+- **`current`** — `columns.update` / `setWidth` / `pinLeft` / sort / filter / pivot 변경 등 **현재 그리드 상태**
+- **`snapshot`** — `columns.reset / resetAll` 호출 시 복귀할 **baseline**. 코어 내부의 `initialSnapshot` (construction-time 또는 `captureSnapshot` 으로 박힌 시점) 의 직렬화
+
+`applyConfig` 의 `options.applySnapshot` (default `true`):
+- `true` (default) — `cfg.snapshot` 이 있으면 baseline 도 복원. 라운드트립 보장
+- `false` — `cfg.snapshot` 이 있어도 무시. `current` 만 임시 layout 으로 적용 (기존 baseline 유지)
+
+**`current` / `snapshot` 에 포함되는 항목 — `GridConfigSnapshot` 형식**
+
+| 카테고리 | 내용 |
+|---|---|
+| **모드** | `mode` (`'flat'` / `'pivot'`) |
+| **컬럼(flat)** | `fields[]` — 각 필드의 `id`, `width`, `hidden`, `pinned`, 사용자 정의 순서 |
+| **컬럼 그룹(flat)** | `columnGroups` |
+| **행 템플릿(flat)** | `rowTemplate` (Multi-Row 레이아웃) |
+| **그룹핑(flat)** | `group` |
+| **피벗** | `rowFields`, `columnFields`, `valueFields`, 모든 subtotal/grandTotal 옵션, `rowDisplayMode`, `outlineColumnWidth`, `outlineIndentSize`, `showZeros`, `trackSourceRows`, `rowCollapsible`, `columnCollapsible` 등 |
+| **뷰 상태** | `sorts`, `filters` |
+| **서버/수동 row-model** | `rowModel`, `endReachedThresholdRows` |
+| **트리/디테일** | `treeConfig`, `masterDetailConfig` |
+| **UI 옵션** | `theme`, `rowHeight`, `headerHeight`, `rowSelection`, `cellSelection`, `cellSelectionImpliesRows`, `editable`, `tooltipMode`, `alternatingRows`, `showHeader`, `resizableColumns`, `reorderableColumns`, `rowHeader`, `reorderableRows`, `showDragHandleColumn`, `autoFitColumns`, `showStatusBar`, `locale`, `translations`, `keyFields` 등 |
+
+**제외되는 항목**
+
+| 항목 | 이유 |
+|---|---|
+| **data** | 원본 데이터는 스냅샷에 포함되지 않음. `loadData`로 별도 복원 |
+| **함수 (cellRenderer, formatRow, validator 등)** | 직렬화 불가. 사용자 코드에서 다시 등록 |
+| **DOM/객체 참조 (undoStack, loader, dragDropConfig 등)** | 직렬화 불가 |
+| **dirty 상태** | ChangeTracker는 스냅샷에 포함되지 않음. 필요하면 `grid.changes.getAll()`로 별도 저장 |
+
+**특징**
+
+- **라운드트립 보장** — `applyConfig(getConfig())` 가 항상 동일한 상태로 복원 (baseline 포함)
+- **`current.fields` 등 부분 적용** — `current` 안의 키들은 `Partial` 형태로 처리 — 누락된 키는 그리드 기존 값 유지
+- **모드 전환 자동 처리** — `current.mode` 가 현재와 다르면 `pivot.setMode()` 자동 호출
+- **순서 복원** — flat 모드의 `current.fields` 배열 순서 그대로 컬럼이 재정렬됨
+- **getConfig 는 sync, applyConfig 는 async** — 복원 중 엔진 재계산(정렬/필터/피벗)이 포함되기 때문
+- **`snapshot` 구조** — 현재는 `fields` 만 채워서 반환 (`columns.initialSnapshot` 의 정적 정의 직렬화). 나머지 키는 향후 확장 여지
+
+**사용 예제**
+
+```typescript
+// 1) localStorage 에 사용자 레이아웃 저장 (baseline 포함)
+function saveLayout() {
+  const cfg = grid.getConfig();
+  localStorage.setItem('gridLayout', JSON.stringify(cfg));
+}
+
+// 2) 복원 — baseline 까지 함께 복원 (라운드트립)
+async function loadLayout() {
+  const raw = localStorage.getItem('gridLayout');
+  if (!raw) return;
+  const cfg = JSON.parse(raw);
+  await grid.applyConfig(cfg);
+}
+
+// 3) bundle 의 current 만 적용, baseline 손대지 않음 — 임시 layout 미리보기
+await grid.applyConfig(savedCfg, { applySnapshot: false });
+grid.columns.resetAll();  // → 원래 baseline 으로 복귀
+
+// 4) 정렬/필터만 적용 (snapshot 키 생략 → baseline 유지)
+await grid.applyConfig({
+  current: {
+    mode: 'flat',
+    sorts: [{ id: 'price', direction: 'desc', sequence: 1 }],
+    filters: [{ columnId: 'brand', operator: 'equals', value: 'Apple' }],
+  },
+});
+
+// 5) 피벗 상태 전환
+await grid.applyConfig({
+  current: {
+    mode: 'pivot',
+    rowFields: [{ field: 'region' }, { field: 'category' }],
+    valueFields: [{ field: 'amount', aggregate: 'sum' }],
+  },
+});
+
+// 6) 현재 상태를 새 baseline 으로 승격
+const cfg = grid.getConfig();
+await grid.applyConfig({ current: cfg.current, snapshot: cfg.current });
+// 이후 columns.reset 호출 시 이 시점의 layout 으로 복귀
+
+// 7) 백엔드에 사용자별 프리셋 저장
+async function syncToServer(userId: string) {
+  const cfg = grid.getConfig();
+  await fetch(`/api/users/${userId}/grid-preset`, {
+    method: 'PUT',
+    body: JSON.stringify(cfg),
+  });
+}
+```
+
+**주의사항**
+
+- `applyConfig` 호출 전후로 `data`는 유지됩니다. 데이터 자체는 `grid.loadData()`로 별도 관리.
+- `current.fields` 배열의 `id` 가 현재 컬럼과 매칭되지 않으면 해당 항목은 조용히 무시됩니다. 완전히 다른 스키마로 전환하려면 새 `PureSheet` 인스턴스를 만드세요.
+- 복원 직후 DOM이 즉시 갱신되지만, scroll 위치는 복원하지 않습니다. 필요하면 별도로 저장/복원하세요 (`grid.select('scroll')` 관찰 등).
+
+### 성능 측정
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `addTiming(name, duration)` | `void` | 타이밍 기록 추가 |
+| `clearTimings()` | `void` | 타이밍 기록 초기화 |
+| `setTimings(timings)` | `void` | 타이밍 기록 일괄 설정 |
+| `getTimings()` | `PerformanceTiming[]` | 타이밍 기록 조회 |
+
+### 피벗 mask 캐시 진단 (ADR-112)
+
+피벗 컬럼 mask 캐시의 hit-rate와 signature 비용을 측정합니다. 벤치마크/회귀 진단용. 운영 동작에는 영향 없으며 정수 카운터 + 누적 시간만 기록.
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `getPivotMaskCacheStats()` | `{ hits, misses, hitRate, signatureTimeMs, avgSignatureUs }` | 누적 진단 통계 조회 |
+| `resetPivotMaskCacheStats()` | `void` | 카운터 리셋 |
+
+```typescript
+grid.resetPivotMaskCacheStats();
+await runWorkload();
+console.log(grid.getPivotMaskCacheStats());
+// → { hits: 10000, misses: 5, hitRate: 0.9995, signatureTimeMs: 12.4, avgSignatureUs: 1.24 }
+
+// 추가로, 캐시 검증 모드 (테스트/디버깅 전용):
+PureSheet.debugPivotMaskCache = true;
+// 캐시 hit마다 fresh 빌드와 동등성 검증 — signature 누락 입력 탐지.
+// production에서는 절대 활성화하지 말 것 (Fast-Path 무효화).
+```
+
+### 반응형 구독
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `select(selector)` | `Subscribable<T>` | GridState 파생 상태 구독 ([상세](#gridselect)) |
+
+### Sub-API 접근
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `rows` | `IRowsAPI` | 행 API |
+| `columns` | `IColumnsAPI` | 컬럼 API |
+| `changes` | `IChangesAPI` | 변경 추적 API |
+| `undoManager` | `IUndoManagerAPI` | Undo/Redo API |
+| `group` | `IGroupAPI` | 그룹화 API |
+| `tree` | `ITreeAPI` | 트리 API |
+| `pivot` | `IPivotAPI` | 피벗 API |
+| `masterDetail` | `IMasterDetailAPI` | 마스터-디테일 API |
+| `validation` | `IValidationAPI` | 검증 API |
+| `clipboard` | `IClipboardAPI` | 클립보드 API |
+| `headers` | `IHeadersAPI` | 컬럼 그룹(다단계 컬럼 헤더) API |
+| `io` | `IIOApi` | Excel Import/Export API |
+| `dragDrop` | `IDragDropAPI` | 행 드래그앤드롭 / 크로스-그리드 드롭 설정 API |
+
+---
+
+## Sub-API
+
+PureSheet 인스턴스는 기능별 Sub-API 네임스페이스를 제공합니다.
+
+### grid.rows — 행 API
+
+#### 행 조회
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `get(row)` | `SingleRowAccessor` | 행 객체로 단일 행 접근자 (`enableReferCache` 필요) |
+| `getById(id)` | `SingleRowAccessor` | ID로 단일 행 접근자 |
+| `getByIndex(sourceIndex)` | `SingleRowAccessor` | sourceIndex로 단일 행 접근 O(1) |
+| `getByIds(ids)` | `MultiRowAccessor` | ID 목록으로 행 접근 |
+| `getByIndices(indices)` | `MultiRowAccessor` | sourceIndex 목록으로 행 접근 |
+| `all()` | `MultiRowAccessor` | 전체 행 접근자 |
+| `where(predicate)` | `MultiRowAccessor` | 조건부 행 접근자. `predicate: (data, state) => boolean` (state는 `'pristine'\|'added'\|'modified'\|'deleted'`) |
+
+#### 반응형
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `observe(row)` | `ReactiveRow` | 행 객체로 반응형 구독 (`enableReferCache` 필요) |
+| `observeById(id)` | `ReactiveRow` | ID로 행 반응형 구독 ([상세](#gridrowsobservebyid)) |
+| `observeByIndex(sourceIndex)` | `ReactiveRow` | sourceIndex로 행 반응형 구독 |
+
+#### 선택 (행 — 쓰기)
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `selectRowsByIds(ids)` | `void` | rowId 배열로 행 선택 (enableReferCache 필요) |
+| `selectRowsByViewIndices(viewIndices)` | `void` | viewIndex(화면 물리 순서) 배열로 행 선택. 정렬/필터 후에도 "화면상 그 위치"를 선택(sourceIndex 아님), data 행만 |
+| `selectRowRangeByViewIndex(startViewIndex, endViewIndex)` | `void` | viewIndex 범위로 행 선택. "화면상 N~M번째" 범위, 구조행 자동 제외 |
+| `selectRowRangeByIds(startRowId, endRowId)` | `void` | rowId 범위로 행 선택(정렬/필터 안정). 한쪽이라도 숨김이면 no-op |
+| `selectAll()` | `void` | 전체 행 선택 |
+| `clearSelection()` | `void` | 행 선택 해제 |
+
+#### 선택 조회 (행 — grid.rows)
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `selected()` | `MultiRowAccessor` | 선택된 행 접근자 |
+| `getSelectedRowIds()` | `(string \| number)[]` | 선택된 행 rowId |
+| `getSelectedRowIndices()` | `Promise<number[]>` | 선택된 행 sourceIndex |
+| `getSelectedRowViewIndices()` | `Promise<number[]>` | 선택된 행 viewIndex(화면 물리 순서) |
+| `getSelectedRowDisplayedIndices()` | `Promise<number[]>` | 선택된 행 displayedIndex(화면 표시 순서, 접힘/필터 반영). 숨김 행 제외 |
+| `selectionAggregates()` | `SelectionAggregateResult \| null` | 선택 범위 집계 (컬럼별 + 총 집계) |
+
+> **displayed 좌표계 조회**(`displayedCount`/`getByDisplayedIndex`/`getDisplayedIndexById`)는 위 [행 조회](#grid.rows) 표 참조 — 다음/이전(traversal) 이동에 사용.
+
+### grid.cells — 셀 선택 API
+
+셀 = 행(rowId/viewIndex) + 열(columnId)의 교차점. 쓰기(select)와 조회(selected)를 제공한다.
+
+#### 선택 (셀 — 쓰기)
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `selectCellsByIds(cells)` | `void` | `{rowId, columnId}` 배열로 셀 선택. 숨김 행은 건너뜀 |
+| `selectCellsByViewIndices(cells)` | `void` | `{viewIndex, columnId}` 배열로 셀 선택 |
+| `selectCellRangeByViewIndex(start, end)` | `void` | `{viewIndex, columnId}` 두 점으로 사각형 범위 선택 |
+| `selectCellRangeByIds(start, end)` | `void` | `{rowId, columnId}` 두 점으로 사각형 범위 선택(정렬/필터 안정) |
+| `clearCellSelection()` | `void` | 셀 선택만 해제 (행 선택 유지) |
+
+#### 선택 조회 (셀 — grid.cells)
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `selected()` | `{rowId, columnId}[]` | 선택된 셀 목록 |
+| `getSelectedCellRowIds()` | `string[]` | 선택된 셀이 걸친 행 rowId 목록(중복 제거) |
+| `getSelectedCellColumnIds()` | `string[]` | 선택된 셀이 걸친 컬럼 columnId 목록(중복 제거) |
+| `getSelectedCellIndices()` | `number[]` | 선택된 셀이 걸친 행 sourceIndex 목록(중복 제거) |
+| `getSelectedCellViewIndices()` | `number[]` | 선택된 셀이 걸친 행 viewIndex 목록(중복 제거) |
+| `getSelectedCellDisplayedIndices()` | `Promise<number[]>` | 선택된 셀이 걸친 행 displayedIndex 목록(중복 제거, async) |
+
+### grid.selection — 선택 상태 조회 (RowHandle 기반, 행/셀 공통)
+
+rowSelection(선택된 행들)·cellSelection(선택된 셀 range)은 서로 다를 수 있으며(행은 3,5인데 셀 range는 7~9행 등), 각각 **RowHandle**(viewIndex/sourceIndex 좌표 채워진 가상 행 — data·조작 접근 가능) 기반으로 조회한다. 앵커(anchorCell)는 행/셀 어느 쪽이든 "마지막 상호작용"이 덮어쓰는 단일 고정점으로 traversal 시작점이다.
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `selection.getSelectedRows()` | `RowHandle[]` | 현재 선택된 행들(viewIndex/sourceIndex 채워짐) |
+| `selection.getActiveRow()` | `RowHandle \| null` | 마지막 상호작용(행/셀 클릭) 행. 앵커 없으면 선택 행 마지막 폴백. traversal 앵커 |
+| `selection.getSelectedCells()` | `{ row: RowHandle; columnId }[]` | 현재 선택된 셀들 |
+| `selection.getActiveCell()` | `{ row: RowHandle; columnId } \| null` | 마지막 상호작용 셀. traversal 컬럼 유지용 |
+
+
+#### 선택 일괄
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `deleteSelectedRows()` | `Promise<number>` | 선택 행 삭제 (건수 반환) |
+| `updateSelectedRows(field, value)` | `Promise<number>` | 선택 **행**들의 지정 필드 일괄 업데이트 |
+| `discardSelectedRows()` | `Promise<number>` | 선택 행 변경 취소 |
+
+#### 데이터 행 고정 (기존 데이터 행을 상단/하단에 고정)
+
+> `pinTop`/`pinBottom`은 **데이터 행 객체**를 받아 그 행을 고정하는 메서드입니다 (`enableReferCache` 필요). 새로운 행/구성을 추가하려면 [구조적 행 고정](#구조적-행-고정) 섹션의 `addPinnedTop` / `addPinnedBottom`을 사용하세요.
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `pinTop(row)` | `Row` | 데이터 행 객체로 상단 고정 (`enableReferCache` 필요) |
+| `pinTopById(rowId)` | `Row` | ID로 기존 데이터 행을 상단에 고정 |
+| `pinTopByIndex(sourceIndex)` | `Row` | sourceIndex로 기존 데이터 행을 상단에 고정 |
+| `pinBottom(row)` | `Row` | 데이터 행 객체로 하단 고정 (`enableReferCache` 필요) |
+| `pinBottomById(rowId)` | `Row` | ID로 기존 데이터 행을 하단에 고정 |
+| `pinBottomByIndex(sourceIndex)` | `Row` | sourceIndex로 기존 데이터 행을 하단에 고정 |
+
+#### 구조적 행 고정
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `addPinnedTop(row \| RowConfig)` | `Row` | 새 행/설정으로 상단 고정 행 추가 |
+| `addPinnedBottom(row \| RowConfig)` | `Row` | 새 행/설정으로 하단 고정 행 추가 |
+| `addGrandTotal(aggregates)` | `Row` | 전체 합계 행 추가 |
+| `addFilter()` | `Row` | 필터 행 추가 |
+
+#### 고정 관리
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `unpin(row)` | `boolean` | `Row` 인스턴스로 고정 해제 |
+| `unpinById(rowId)` | `boolean` | ID로 행 고정 해제 |
+| `getPinned()` | `{ top: Row[]; bottom: Row[] }` | 고정된 행 조회 |
+| `clearPinned()` | `void` | 전체 고정 해제 |
+| `refreshPinned()` | `void` | 고정 행 표시 갱신 |
+
+---
+
+### grid.columns — 컬럼 API
+
+#### 위치 / 너비 / 가시성 (per-column 빠른 setter)
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `pinLeft(colId)` | `void` | 왼쪽 고정 |
+| `pinRight(colId)` | `void` | 오른쪽 고정 |
+| `unpin(colId)` | `void` | 고정 해제 |
+| `setWidth(colId, width)` | `void` | 너비 설정 |
+| `autoFit(colId, auto)` | `void` | 자동 너비 |
+| `autoFitAll(options?)` | `void` | 전체 자동 너비. `options` 는 `boolean`(= `persistent`, 하위호환) 또는 `{ persistent?, lazyOnScroll? }` 객체. `lazyOnScroll: true` 면 off-screen 컬럼은 처음 노출 시 1회만 측정 |
+| `setOrder(order, options?)` | `void` | 컬럼 순서 설정 (일반/컬럼 그룹 모두 지원) |
+| `move(columnId, targetId, position?)` | `void` | 단일 컬럼 이동 (`'before'` \| `'after'`, 기본 `'before'`) |
+| `moveGroup(groupId, targetGroupId, position?)` | `void` | 그룹 통째로 이동 (같은 레벨 형제 간) |
+| `hide(colId)` | `void` | 컬럼 숨김 |
+| `show(colId)` | `void` | 컬럼 표시 |
+| `setHidden(colId, hidden)` | `void` | 숨김 상태 설정 |
+| `toggle(colId)` | `void` | 가시성 토글 |
+
+> 위 4개는 모두 `setHidden` 한 경로로 수렴하며, 대상 컬럼이 [`lockVisible`](#정렬표시) 이면 **거부**되고 `console.warn` 을 남깁니다(요청값이 현재값과 같으면 조용한 no-op). 가시성 잠금은 UI/API 를 가리지 않는 하드 불변식입니다.
+
+#### 통합 변경 / 복원 — `update` · `reset` · `resetAll`
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `update(colId, partial, options?)` | `void` | FieldDef/ColumnDef 키들을 런타임 부분 갱신. 변경 키별 적절한 렌더 경로 자동 발화 |
+| `reset(colId)` | `void` | 1개 컬럼을 초기 스냅샷으로 복귀 (정적 + 런타임 상태 양쪽). 컬럼 순서는 복원하지 않음 |
+| `resetAll()` | `void` | 모든 컬럼을 초기 스냅샷으로 복귀. 컬럼 그룹이 없을 때 컬럼 순서도 함께 복원 |
+| `captureSnapshot()` | `void` | 현재 모든 컬럼의 상태를 새 baseline 스냅샷으로 박음. 이후 `reset/resetAll` 은 이 시점으로 복귀 |
+
+**`update(colId, partial, options?)` — 키 카테고리별 동작**
+
+| 키 카테고리 | 처리 방식 |
+|---|---|
+| `width` / `hidden` / `pinned` / `frozen` / `autoFit` | 기존 setter 위임 (per-column DOM 패치, refresh 불필요) |
+| `header` / `label` / `headerAttributes` / `headerRenderer` | def mutate → 헤더 재렌더 (전체 refresh) |
+| `align` / `mask` / `cellAttributes` / `cellRenderer` / `decimalFormat` / `useThousandsSeparator` / `dataType` / `type` | def mutate → body 셀 재페인트 |
+| `aggregate` / `mergeStrategy` | def mutate → 재집계/재머지 |
+| `flex` / `minWidth` / `maxWidth` | def mutate → 레이아웃 재계산 |
+| `sortable` / `filterable` / `editable` / `readonly` / `editableWhen` / `validation` / `editor` / `editorResolver` / `formula` | mutate-only (다음 인터랙션 시 자동 반영) |
+| `id` / `pivotValueField` / `pivotValueFieldConfig` | warn + skip (변경 위험 키) |
+| 알 수 없는 키 | 보수적으로 mutate-only |
+
+**Satellite 키 자동 동기화** — `update` 가 내부적으로 동시에 mutate 하는 짝:
+- `pinned` ↔ `frozen` (서로 alias)
+- `header` ↔ `label` (header 입력 시 label 도 함께 세팅)
+- `dataType` → `type`
+
+**`options.updateSnapshot: true`** — 변경분을 초기 스냅샷에도 미러합니다. 이후 `reset(colId)` 호출 시 이번 변경을 **포함한** 새 baseline 으로 복귀. 사용자 UI 의 임시 오버레이가 아닌 "**새 영구 baseline 으로 승격**" 의도일 때 사용합니다.
+
+```ts
+// 임시 오버레이 (reset 시 사라짐)
+grid.columns.update('amount', {
+  cellAttributes: { class: 'user-yellow', style: 'background:#fffbe6' },
+});
+
+// 새 baseline 으로 승격 (reset 후에도 유지)
+grid.columns.update('amount', { header: '판매금액' }, { updateSnapshot: true });
+```
+
+#### 조회 (모두 `ColumnInfo` shape 통일)
+
+`getById / getAll / getMap / getVisibleColumns / getState` 5종은 **모두 동일한 `ColumnInfo` shape** 을 반환합니다. 정적 ColumnDef + 런타임 ColumnState 합본 한 객체. 차이는 어떤 집합/순서로 묶어주는지뿐:
+
+| 메서드 | 반환 | 어떤 컬럼 / 어떤 순서 |
+|--------|------|------------------------|
+| `getById(columnId)` | `ColumnInfo \| null` | 단건 |
+| `getAll()` | `ColumnInfo[]` | 전체, **컬럼 정의 순서** |
+| `getMap()` | `ColumnInfo[]` | `getAll` 의 별칭 (하위호환) |
+| `getVisibleColumns()` | `ColumnInfo[]` | 보이는 것만, **`order` 오름차순** |
+| `getState()` | `ColumnInfo[]` | 전체, **state 배열 순서** (정렬 X) |
+
+**충돌 키 정책** — state(런타임)가 승:
+- `width` / `pinned` / `visible` / `autoFit` → 현재값 (state)
+- `hidden` → `!visible` 로 파생
+- `header` → `def.header ?? def.label ?? def.id` 로 항상 비어있지 않음
+
+#### 저장/복원 (직렬화)
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `save()` | `string` | 컬럼 상태 JSON 저장 |
+| `load(json)` | `void` | 컬럼 상태 JSON 복원 |
+| `getInitialSnapshotDefs()` | `ColumnDef[]` | 현재 initial snapshot 의 ColumnDef[] 복사본. `PureSheet.getConfig()` 가 내부적으로 호출해서 `GridConfigExport.snapshot.fields` 에 담음. 외부 직렬화/공유용 |
+| `setInitialSnapshotDefs(defs)` | `void` | 외부 ColumnDef[] 로 initial snapshot 일괄 교체. `PureSheet.applyConfig({ snapshot })` 가 내부적으로 호출. 이후 `reset/resetAll` 의 복귀 기준이 됨 |
+
+#### 기타
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `syncSelectionColumnOrder()` | `void` | SelectionManager 컬럼 인덱스 맵 동기화 (컬럼 가시성/순서를 직접 조작한 뒤 호출) |
+
+#### 발화 이벤트
+
+| 이벤트 | payload | 발화 시점 |
+|---|---|---|
+| `column:resize` | `{ columnId, width }` | `setWidth` / `update({width})` / **헤더 드래그 리사이즈** (마우스로 컬럼 경계를 끌어 너비 변경) |
+| `column:pin` | `{ columnId, position }` | `pinLeft` / `pinRight` / `unpin` / `update({pinned})` |
+| `column:reorder` | `{ order, source?, sourceId? }` | `setOrder` / `move` / `moveGroup` / **헤더 드래그 재정렬** |
+| `column:visibility` | `{ columnId, visible }` | `hide` / `show` / `setHidden` / `toggle` |
+| `column:update` | `{ columnId, changedKeys: string[] }` | `update(...)` |
+| `column:reset` | `{ columnId: string \| null }` | `reset` / `resetAll` (resetAll 시 `columnId: null`) |
+
+> **드래그 vs API**: 드래그 경로는 코어 내부에서 `GridRenderer.handleColumnResize / handleColumnReorder` → `PureSheet.handleColumnResize / handleColumnReorder` 콜백을 통해 위 이벤트를 emit. API 경로 (`columns.setWidth` 등) 와 동일한 페이로드 — wrapper 가 한 번만 listen 하면 두 경로 모두 받음.
+
+#### 어떤 도구를 언제 쓰나 — 의사결정 가이드
+
+컬럼 관련 작업은 여러 도구로 가능. 시나리오별 권장:
+
+| 의도 | 권장 도구 | 이유 |
+|---|---|---|
+| 설계 시점에 컬럼 옵션 고정 | `FieldDef` (config) | 정적, 직렬화 자동 |
+| 런타임 1회 변경 (예: 사용자가 헤더 라벨 변경) | `columns.update(id, partial)` | 단일 진입점, 부분 갱신 |
+| 런타임 변경을 **새 baseline 으로 영구화** | `columns.update(id, partial, { updateSnapshot: true })` | reset 후에도 유지 |
+| 컬럼 초기 상태로 복귀 | `columns.reset(id)` / `resetAll()` | 스냅샷 기반 복귀 |
+| **사용자 UI 의 컬럼별 서식** (body 셀) — 자주 변함 | `formatRow.addHandler` | 스크롤 친화, multi-owner 공존 |
+| **사용자 UI 의 컬럼별 서식** (헤더) — 자주 변함 | `formatHeader.addHandler` | 헤더 라이프사이클 매칭, multi-owner 공존 |
+| 행 데이터 기반 동적 셀 서식 (예: 음수=빨강) | `cellAttributes(fn)` 또는 `formatRow` | 행 컨텍스트 접근 가능 |
+| 정렬/필터 메타 기반 헤더 시각 마커 | `formatHeader.addHandler` | ctx.sortStates / filterStates / cell.sortState 활용 |
+| 컬럼 표시/숨김·순서·너비·핀 토글 | per-column setter (`setHidden / setOrder / setWidth / pinLeft`) | 가장 가볍고 직관적 |
+| 전체 레이아웃 저장·복원 | `save()` / `load(json)` (단일 컬럼) 또는 `getConfig() / applyConfig()` (전체) | 직렬화 가능 |
+
+**일반 원칙**:
+- 정적 / 1회성 → **`columns.update` 또는 setter**
+- 자주 변하는 동적 서식 → **formatRow / formatHeader hook**
+- 사용자 wrapper UI 가 만드는 서식 → **hook + addHandler** (wrapper-managed)
+- baseline 의미를 가진 변경 → **`updateSnapshot: true`**
+- 임시 오버레이 (reset 으로 사라져야 함) → **`updateSnapshot` 옵션 X**
+
+---
+
+### grid.changes — 변경 추적 API
+
+#### CRUD (Dirty State)
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `addRow(row, idx?)` | `Promise<string \| number>` | 행 추가 (dirty) |
+| `updateCell(row, field, value)` | `Promise<void>` | 행 객체로 셀 수정 (`enableReferCache` 필요) |
+| `updateCellById(id, field, value, sourceIndex?)` | `Promise<void>` | ID로 셀 수정. 호출자가 sourceIndex를 알고 있으면 4번째 인자로 전달하여 idMap fallback을 회피할 수 있음 |
+| `updateCellByIndex(idx, field, value)` | `Promise<void>` | sourceIndex로 셀 수정 O(1) |
+| `deleteRow(row)` | `Promise<void>` | 행 객체로 삭제 마킹 (`enableReferCache` 필요) |
+| `deleteRowById(id, sourceIndex?, originalDataHint?)` | `Promise<void>` | ID로 행 삭제 마킹. 선택적 hint 인자로 idMap O(N) lookup 회피 가능 |
+| `deleteRowByIndex(idx)` | `Promise<void>` | sourceIndex로 행 삭제 마킹 O(1) |
+| `undeleteRow(row)` | `Promise<void>` | 행 객체로 삭제 복원 (`enableReferCache` 필요) |
+| `undeleteRowById(id)` | `Promise<void>` | ID로 삭제 복원 |
+| `undeleteRowByIndex(idx)` | `Promise<void>` | sourceIndex로 삭제 복원 O(1) |
+| `undeleteRows(rows)` | `Promise<number>` | 행 객체 배열로 다중 삭제 복원 |
+| `undeleteRowsById(ids)` | `Promise<number>` | ID 배열로 다중 삭제 복원 |
+| `deleteSelectedRows()` | `Promise<number>` | 선택 행 삭제 (삭제된 건수 반환). 참고: `grid.rows.deleteSelectedRows()`와 동작은 동일하지만 ChangesAPI 쪽 메서드 이름은 `deleteSelectedRows`로 다르다 |
+
+#### 변경 취소
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `discard(row)` | `Promise<void>` | 행 객체로 변경 취소 (`enableReferCache` 필요) |
+| `discardById(id)` | `Promise<void>` | ID로 단일 행 변경 취소 |
+| `discardByIndex(idx)` | `Promise<void>` | sourceIndex로 변경 취소 O(1) |
+| `discardSelectedRows()` | `Promise<number>` | 선택 행 변경 취소 |
+| `discardImmediate(row)` | `Promise<void>` | 행 객체로 즉시 취소 (`enableReferCache` 필요) |
+| `discardImmediateById(id)` | `Promise<void>` | ID로 즉시 취소 (undo 스택 미경유) |
+| `discardImmediateByIndex(idx)` | `Promise<void>` | sourceIndex로 즉시 취소 O(1) |
+| `discardAll()` | `Promise<void>` | 전체 변경 취소 |
+
+#### 커밋
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `commit(options?)` | `Promise<void>` | 전체 변경 커밋 |
+
+**`CommitOptions`**
+
+| 필드 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `allowInvalid` | `boolean` | `false` | `true`면 유효성 검사를 건너뛰고 강제 commit. 데이터 정합성은 사용자 책임. |
+
+**commit 가드 흐름**
+
+1. **keyField 충돌 검증** — ADR-105 `KeyIndex.validateAllKeys()`가 모든 dirty 행의 키 중복을 단일 pass로 검사. 충돌 발생 시 해당 행의 **모든 keyField 셀**에 에러 마킹 (양방향).
+2. **사용자 validation rule 검증** — `commit` trigger가 붙은 규칙을 전체 visible row에 대해 재실행.
+3. **에러 집합 체크** — `validationManager.hasErrors()`가 `true`면:
+   - `deps.jumpToFirstInvalid?.()` 호출 → 첫 invalid 셀로 자동 스크롤 + 선택
+   - `PS715` throw (`"유효하지 않은 셀이 {count}개 있습니다..."`)
+4. 에러 없으면 `update → delete → add` 순으로 실제 `sourceData` 반영.
+
+**`allowInvalid: true`로 우회**
+
+```js
+// 정상: invalid가 있으면 PS715 throw + 첫 invalid로 이동
+await grid.changes.commit();
+
+// 우회: validation 전체 skip (key 충돌 검사도 skip)
+await grid.changes.commit({ allowInvalid: true });
+```
+
+#### 조회
+
+| 속성/메서드 | 반환 | 설명 |
+|-------------|------|------|
+| `hasChanges` | `boolean` | 변경 사항 존재 여부 |
+| `getAll()` | `ChangesSummary` | 전체 변경 요약 |
+| `getRowState(row)` | `RowState` | 행 객체로 변경 상태 조회 (`enableReferCache` 필요) |
+| `getRowStateById(id)` | `RowState` | ID로 행 변경 상태 조회 |
+| `getRowStateByIndex(idx)` | `RowState` | sourceIndex로 행 변경 상태 조회 O(1) |
+
+#### 대량 업데이트
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `bulkUpdate(columnId, value, scope?)` | `Promise<number>` | 일괄 셀 업데이트 |
+
+#### 행 재정렬
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `reorderRow(from, to)` | `Promise<void>` | 행 순서 변경 |
+| `getRowOrder()` | `(string \| number)[] \| null` | 행 순서 조회 |
+| `isReordered()` | `boolean` | 재정렬 여부 |
+
+---
+
+### grid.undoManager — Undo/Redo API
+
+| 메서드/속성 | 반환 | 설명 |
+|-------------|------|------|
+| `undo()` | `boolean` | 실행 취소 (스택 top 1개) |
+| `redo()` | `boolean` | 다시 실행 |
+| `undoThrough(commandId)` | `CommandId[]` | **특정 command까지 cascade undo** — 낙관적 파이프라인 롤백용. 아래 참조 |
+| `canUndo` | `boolean` | Undo 가능 여부 |
+| `canRedo` | `boolean` | Redo 가능 여부 |
+| `beginBatch(desc?, opts?)` | `void` | 배치 시작 |
+| `endBatch()` | `Promise<void>` | 배치 종료 |
+| `batch(fn, opts?)` | `Promise<void>` | 콜백 배치 |
+| `getStack()` | `UndoStack` | 내부 스택 조회 |
+
+> **`undoThrough(commandId): CommandId[]`** — target command와 **그 위(더 최신)의 모든 command**를 top→target 순으로 cascade undo합니다 (target 포함). 되돌린 command id 배열(top→target 순)을 동기 반환합니다.
+> - **용도**: 낙관적(optimistic) 백엔드 동기화에서 여러 reorder가 파이프라인(in-flight)일 때, 그중 하나가 **실패**하면 롤백해야 합니다. 위치 기반 `undo()`는 스택 top(엉뚱한 최신 작업)을 되돌리지만, `undoThrough(실패한 commandId)`는 그 작업과 그 위에 쌓인 것 전부를 정확히 되돌립니다 (그 위 작업들은 실패한 작업 위에 놓였으므로 함께 무효).
+> - **correlation key**: `commandId`는 `row:reordered` / `changes:undone` / `changes:redone` 이벤트가 주는 값을 그대로 넘깁니다. 이 값은 reorder를 감싼 **BatchCommand.id**입니다 (R1 — inner command id 아님).
+> - **idempotent**: 미존재 id / 빈 스택 / 열린 batch / inner(child) id → `[]` 반환 (throw 없음). 이미 롤백된 id를 또 불러도 안전.
+> - cascade는 command마다 `changes:undone`을 재발화하므로, 그 작업들의 **백엔드 롤백도 자동으로 함께 태워집니다** (핸들러 무수정).
+>
+> ```js
+> const pending = new Map();
+> grid.on('row:reordered', async (e) => {
+>   pending.set(e.commandId, e);
+>   try {
+>     await api.applyReorder(e.patches);   // 낙관적: UI는 이미 반영됨
+>     pending.delete(e.commandId);
+>   } catch {
+>     // 실패한 그 작업 + 그 위 전부 cascade 롤백
+>     const rolledBack = grid.undoManager.undoThrough(e.commandId);
+>     rolledBack.forEach((id) => pending.delete(id));
+>     // 백엔드 롤백은 changes:undone이 cascade 개수만큼 자동 발화 → 별도 핸들러가 처리
+>   }
+> });
+> ```
+
+---
+
+### grid.rowGroup — 그룹화 API
+
+> 정식 네임스페이스는 `grid.rowGroup`입니다. 구 `grid.group`은 **deprecated 별칭**으로 계속 동작하나(하위호환, 다음 major에서 제거 예정) 신규 코드는 `grid.rowGroup`을 사용하세요.
+
+> `getConfig()`는 내부 상태와 동일 참조를 반환합니다. `aggregates`에 커스텀 함수가 포함될 수 있어 `structuredClone`을 사용하지 않습니다 (DataCloneError 방지). 반환값을 직접 수정하지 마세요 (변경은 `setConfig()` 사용).
+> 그룹화 미설정 시 `getConfig()`는 `null` 반환.
+
+> **토글 이벤트** — 헤더 클릭 및 프로그래매틱 토글 모두 이벤트를 발화합니다: 단일 토글(`toggle`/`expand`/`collapse`)은 `rowGroup:toggle`, 여러 그룹 일괄 토글은 `rowGroup:batchToggle` 하나로 통합되어 `scope` 필드로 구분합니다 — 동일 depth 일괄(`expandAtLevel`/`collapseAtLevel`)은 `scope:'level'`, 특정 depth까지 누적(`expandToLevel`/`collapseToLevel`)은 `scope:'toLevel'`, 전체(`expandAll`/`collapseAll`)는 `scope:'all'`. 프로그래매틱 호출은 payload `source:'api'`로 발화되므로 핸들러에서 `if (e.source === 'api') return;`으로 재진입 무한루프를 막을 수 있습니다 (→ [이벤트](#이벤트)).
+> **참고**: `expandToLevel`/`collapseToLevel`(레벨까지 누적)은 `rowGroup:batchToggle`을 `scope:'toLevel'`로 발화합니다.
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `setConfig(config)` | `Promise<void>` | 그룹화 설정 (`null`로 해제) |
+| `groupBy(columns)` | `Promise<void>` | 컬럼으로 그룹화 |
+| `clear()` | `Promise<void>` | 그룹화 해제 |
+| `getConfig()` | `GroupingConfig \| null` | 현재 그룹화 설정 조회 (내부 참조) |
+| `toggle(groupId)` | `Promise<void>` | 그룹 접힘/펼침 토글 |
+| `expand(groupId)` | `Promise<void>` | 특정 그룹 펼침 |
+| `collapse(groupId)` | `Promise<void>` | 특정 그룹 접힘 |
+| `expandAll()` | `Promise<void>` | 전체 그룹 펼침 |
+| `collapseAll()` | `Promise<void>` | 전체 그룹 접힘 |
+| `isCollapsed(groupId)` | `boolean` | 접힘 상태 조회 |
+| `addColumn(columnId)` | `Promise<void>` | 그룹 컬럼 추가 |
+| `removeColumn(columnId)` | `Promise<void>` | 그룹 컬럼 제거 |
+| `expandToLevel(level)` | `Promise<void>` | 특정 레벨까지 펼침 (`level < 0` 시 경고) |
+| `collapseToLevel(level)` | `Promise<void>` | 특정 레벨까지 접힘 (`level < 0` 시 경고) |
+| `expandAtLevel(level)` | `Promise<void>` | 정확히 그 레벨의 그룹만 펼침 — 다른 레벨 보존 (Ctrl/Cmd+클릭 제스처와 동일, `level < 0` 시 경고) |
+| `collapseAtLevel(level)` | `Promise<void>` | 정확히 그 레벨의 그룹만 접힘 — 다른 레벨 보존 (`level < 0` 시 경고) |
+| `getGroupRows(groupId)` | `RowId[]` | 그룹에 속한 데이터 행 rowId 목록. `groupId`는 `"col:val/col:val"` 경로 문자열(= `GroupRowContext.groupId`). 소스 전체 스캔이라 **접힘/필터 무관**, 중첩 그룹이면 하위 전체 포함. 미존재/규약 위반 시 `[]` |
+| `expandToRow(rowId)` | `Promise<void>` | 특정 data 행이 보이도록 그 행의 **조상 그룹을 모두 펼친다**(`tree.expandPath`의 그룹 대칭). `grid.rows.getDisplayedIndexById(rowId)`가 `-1`(접힘으로 숨김)일 때 이 메서드로 조상을 펼친 뒤 재조회하면 유효한 displayed 인덱스를 얻는다. 그룹 모드 아님/행 없음 시 no-op. O(그룹 depth) |
+
+> **`getGroupRows(groupId)`** — 그룹 행에서 하위 멤버 전체를 일괄 조작할 때 사용합니다 (예: 그룹 단위 선택·체크박스 cascade). 멤버십은 그룹 컬럼 값 기준 매칭(`String(row[col]) === value`)이며, `groupId`의 각 세그먼트는 **첫 `:` 만** 구분자로 사용하므로 값에 `:`가 포함돼도 안전합니다(값에 `/` 포함은 경로 모호성 — 규약상 한계). `grid.rows.getByIds(getGroupRows(id))` 조합으로 일괄 수정하세요.
+
+---
+
+### grid.tree — 트리 API
+
+> 트리 미설정 시 `getConfig()`는 `null` 반환.
+> `expandToLevel`/`collapseToLevel`에 음수 전달 시 `psWarn(PS311)` 경고 후 무시.
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `setConfig(config)` | `Promise<void>` | 트리 설정 (`null`로 해제) |
+| `getConfig()` | `TreeConfig \| null` | 트리 설정 조회 |
+| `loadData(data, config)` | `Promise<void>` | 중첩 데이터 로드 → flat 변환 |
+| `toggle(nodeId)` | `Promise<void>` | 노드 접힘/펼침 |
+| `expand(nodeId)` | `Promise<void>` | 노드 펼침 |
+| `collapse(nodeId)` | `Promise<void>` | 노드 접힘 |
+| `expandAll()` | `Promise<void>` | 전체 펼침 |
+| `collapseAll()` | `Promise<void>` | 전체 접힘 |
+| `expandToLevel(level)` | `Promise<void>` | 특정 레벨까지 펼침 |
+| `collapseToLevel(level)` | `Promise<void>` | 특정 레벨까지 접힘 |
+| `expandAtLevel(level)` | `Promise<void>` | 정확히 그 레벨의 노드만 펼침 — 다른 레벨 보존 (Ctrl/Cmd+클릭 제스처와 동일) |
+| `collapseAtLevel(level)` | `Promise<void>` | 정확히 그 레벨의 노드만 접힘 — 다른 레벨 보존 |
+| `isCollapsed(nodeId)` | `boolean` | 접힘 상태 조회 |
+| `expandPath(nodeId)` | `Promise<void>` | 조상 전체 펼치기 (검색 결과 표시용) |
+| `moveNode(nodeId, newParentId, newIndex?)` | `Promise<void>` | **프로그램 방식 트리 노드 이동** (드래그 없이 코드로). flat 그리드 `changes.reorderRow`의 tree 대칭 API. 아래 참조 |
+| `getChildren(nodeId)` | `RowId[]` | 직계 자식 rowId 목록 (소스 순서). 리프/미존재 시 `[]` |
+| `getDescendants(nodeId)` | `RowId[]` | 모든 자손 rowId (BFS — 얕은 레벨 먼저). 순환 데이터에도 종료 보장 |
+| `getParent(nodeId)` | `RowId \| null` | 부모 rowId. root/미존재 시 `null` |
+| `getAncestors(nodeId)` | `RowId[]` | 조상 rowId 목록 (가까운 부모부터 root 방향). root/미존재 시 `[]` |
+
+> **트래버설 (`getChildren` / `getDescendants` / `getParent` / `getAncestors`)** — `treeConfig.idField`/`parentField` 값 기준으로 **소스 전체를 스캔**하므로 접힘·필터·정렬 상태와 무관하게 논리적 트리 구조를 반환합니다. 반환값은 rowId 배열(원형 유지)이며 `grid.rows.getByIds(...)`와 조합해 일괄 수정에 사용합니다 (부모↔자손 체크박스 cascade 등). `treeConfig` 미설정 시 모두 빈 결과. 조회당 O(N) — 프레임 내 반복 호출은 피하세요.
+
+> **`moveNode(nodeId, newParentId, newIndex?)`** — `nodeId`를 `newParentId`의 `newIndex`번째 자식으로 이동합니다.
+> - `newIndex`는 **이동 완료 후 최종 위치**(0-based). 같은 부모 안 forward 이동의 off-by-one은 내부에서 보정됩니다.
+> - `newParentId = null` → root 레벨로 승격. `newIndex` 생략 → 대상 부모의 맨 끝에 append. 범위 밖 값은 `[0, 자식수]`로 clamp.
+> - 드래그 경로와 **동일한 공통 코어**를 타므로 하나의 원자 undo 단위(Ctrl+Z 1회 복원)로 커밋되고 `row:reordered {kind:'tree'}` 이벤트를 발화합니다 (`commandId` 포함).
+> - **드래그와 달리 조용한 no-op이 아니라 명시적 throw** — 프로그래머 실수를 표면화합니다: `PS401`(nodeId 부재), `PS402`(newParentId 부재), `PS403`(cycle — 자기 자신 또는 자기 후손으로 이동).
+> - 트리 미설정(`treeConfig` 부재) 시 호출하면 동작하지 않습니다.
+>
+> ```js
+> // [A, B, C, D]에서 A를 최종 index 2로 → [B, C, A, D]
+> await grid.tree.moveNode('A', null, 2);
+> // 자식 노드를 다른 부모의 맨 끝으로
+> await grid.tree.moveNode('leaf1', 'folder2');
+> ```
+
+---
+
+### grid.pivot — 피벗 API
+
+> 피벗 미설정 시 `getConfig()`, `getResult()`, `getState()` 모두 `null` 반환.
+> `setConfig(config)`에 빈 `rowFields`/`valueFields` 전달 시 `psWarn(PS201/PS202)` 경고만 출력하고 throw 하지 않습니다 — 피벗을 유지한 채 결과를 비워 렌더합니다(플랫 전환 X).
+> `getConfig()`는 내부 객체와 동일 참조를 반환합니다. `mask`에 함수가 포함될 수 있어 `structuredClone`을 사용하지 않습니다. 반환값을 직접 수정하지 마세요 (필요하면 호출 측에서 복사).
+
+#### 모드 관리
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `getMode()` | `'flat' \| 'pivot'` | 현재 모드 |
+| `setMode(mode)` | `Promise<void>` | 모드 전환 |
+
+#### 설정
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `setConfig(config)` | `Promise<void>` | 피벗 설정 |
+| `getConfig()` | `PivotConfig \| null` | 피벗 설정 조회 (내부 참조) |
+| `getResult()` | `PivotResult \| null` | 피벗 결과 |
+| `setSubTotals(options)` | `Promise<void>` | 행/열 소계 설정 (show, fields, position) |
+| `setGrandTotals(options)` | `Promise<void>` | 행/열 총합계 설정 (show, position) |
+| `setRowFields(fields)` | `Promise<void>` | 행 필드만 변경 |
+| `setColumnFields(fields)` | `Promise<void>` | 열 필드만 변경 |
+| `setValueFields(fields)` | `Promise<void>` | 값 필드만 변경 |
+
+#### 상태 저장/복원
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `getState()` | `{ config, collapsedRowNodes: string[], collapsedColumnNodes: string[] } \| null` | 피벗 상태 |
+| `setState(state)` | `Promise<void>` | 피벗 상태 복원 (`collapsedRowNodes` / `collapsedColumnNodes`는 선택) |
+
+#### 노드 네비게이션 (Row 축)
+
+> 행/열을 독립적으로 접기 위해 각각 `Row` / `Column` 접미사가 붙은 메서드를 사용합니다.
+>
+> **`PivotConfig.rowCollapsible` / `columnCollapsible`** 옵션 (default `true`) 으로 사용자 클릭 토글을 끌 수 있습니다 — 옵션 `false` 면 chevron 미표시 + 클릭/키보드 토글 무시. 단 **아래 프로그래매틱 API 는 옵션과 무관하게 작동** (개발자가 직접 호출하는 path 는 유지). "사용자 클릭만 막기" 가 의도.
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `toggleRow(nodeId)` | `Promise<void>` | 행 노드 토글 |
+| `expandRow(nodeId)` | `Promise<void>` | 행 노드 펼침 |
+| `collapseRow(nodeId)` | `Promise<void>` | 행 노드 접힘 |
+| `expandAllRows()` | `Promise<void>` | 모든 행 노드 펼침 |
+| `collapseAllRows()` | `Promise<void>` | 모든 행 노드 접힘 |
+| `expandRowAtLevel(level)` | `Promise<void>` | 해당 레벨의 노드만 펼침 |
+| `collapseRowAtLevel(level)` | `Promise<void>` | 해당 레벨의 노드만 접힘 |
+| `expandRowToLevel(level)` | `Promise<void>` | 지정 레벨까지 펼침 |
+| `collapseRowToLevel(level)` | `Promise<void>` | 지정 레벨까지 접힘 |
+| `isRowCollapsed(nodeId)` | `boolean` | 행 접힘 상태 |
+| `getRowViewIndex(nodeId)` | `Promise<number \| null>` | nodeId 의 현재 가시(view) 행 인덱스. 없거나 숨김이면 `null` (인덱스 기반 스크롤 앵커용) |
+| `getCollapsedRowNodes()` | `ReadonlySet<string>` | 접힌 행 노드 목록 |
+
+#### 노드 네비게이션 (Column 축)
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `toggleColumn(nodeId)` | `Promise<void>` | 열 노드 토글 |
+| `expandColumn(nodeId)` | `Promise<void>` | 열 노드 펼침 |
+| `collapseColumn(nodeId)` | `Promise<void>` | 열 노드 접힘 |
+| `expandAllColumns()` | `Promise<void>` | 모든 열 노드 펼침 |
+| `collapseAllColumns()` | `Promise<void>` | 모든 열 노드 접힘 |
+| `expandColumnAtLevel(level)` | `Promise<void>` | 해당 레벨의 노드만 펼침 |
+| `collapseColumnAtLevel(level)` | `Promise<void>` | 해당 레벨의 노드만 접힘 |
+| `expandColumnToLevel(level)` | `Promise<void>` | 지정 레벨까지 펼침 |
+| `collapseColumnToLevel(level)` | `Promise<void>` | 지정 레벨까지 접힘 |
+| `isColumnCollapsed(nodeId)` | `boolean` | 열 접힘 상태 |
+| `getCollapsedColumnNodes()` | `ReadonlySet<string>` | 접힌 열 노드 목록 |
+
+#### 소스 행 매핑 / 차트 보조
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `getSourceRowsForCell(rowIdx, colId)` | `Promise<number[]>` | 셀의 소스 행 (`trackSourceRows: true` 필요) |
+| `getSourceRowsForRow(rowIdx)` | `Promise<number[]>` | 행의 소스 행 (`trackSourceRows: true` 필요) |
+| `getSourceRowsForSelection()` | `Promise<number[]>` | 선택 영역의 소스 행 (`trackSourceRows: true` 필요) |
+| `getGrandTotals()` | `Promise<PivotGrandTotal[]>` | 값 필드별 전체 총합계(코너). 현재 필터 반영, 표시 on/off 무관 상시 계산. 비피벗이면 `[]` |
+| `getColumnGrandTotals(columnIds?)` | `Promise<PivotColumnGrandTotal[]>` | 컬럼별 행 총합계. `columnIds` 생략 시 전체 데이터 컬럼. 표시 on/off 무관. 비피벗이면 `[]` |
+| `getFieldValues(fieldId, options?)` | `Promise<CellValue[]>` | 필드의 값 목록 (행/열 자동 판별). `options.unique` 기본 `true` |
+| `getAllRows()` | `Promise<PivotRow[]>` | lazy 모드에서도 전체 피벗 행을 가져옴 |
+| `getDataMatrix(options?)` | `Promise<DataMatrix \| null>` | 피벗 결과를 2D 표로 변환 |
+| `getPivotMeta()` | `PivotMeta \| null` | 읽기 전용 경량 메타 스냅샷 (필드/행수/열수) |
+| `getSeriesData(options?)` | `Promise<PivotSeriesData>` | 차트/대시보드용 그룹 시리즈 데이터 |
+| `getRowHeaderPath(rowHeaders, categoryField?)` | `string` | 행 rowHeaders → 행 헤더 경로(= 차트 카테고리 라벨). `getSeriesData`와 동일 규칙(SSOT). leaf+다중 행필드면 "부모 › 잎" 경로, 그 외엔 해당 필드 값. (sync) |
+
+#### getFieldValues
+
+```typescript
+// 행 필드 값 조회 (async — Promise<CellValue[]>)
+const regions = await grid.pivot.getFieldValues('region');
+// → ['서울', '부산', '대구', ...]
+
+// 열 필드 값 조회
+const quarters = await grid.pivot.getFieldValues('quarter');  // → ['Q1', 'Q2', 'Q3', 'Q4']
+
+// 중복 포함 (순서 유지)
+const raw = await grid.pivot.getFieldValues('quarter', { unique: false });
+// → ['Q1','Q2','Q3','Q4','Q1','Q2','Q3','Q4'] (연도별 반복)
+```
+
+#### getDataMatrix
+
+피벗 결과를 CSV 내보내기, 차트, 외부 연동에 적합한 2D 표로 변환합니다.
+
+```typescript
+const matrix = await grid.pivot.getDataMatrix();
+// → {
+//   headers: ['지역', '제품', 'Q1', 'Q2', 'Q3', 'Q4'],
+//   rows: [
+//     ['서울', '노트북', 5000, 3000, 4000, 6000],
+//     ['서울', '마우스', 2000, 1500, 1800, 2200],
+//     ...
+//   ],
+//   rowTypes: ['data', 'data', 'subtotal', ...]
+// }
+
+// 소계/총합계 제외 (전부 빼기)
+await grid.pivot.getDataMatrix({ subtotals: 'none', grandTotals: 'none' });
+
+// 토글 OFF로 숨겨진 소계/총합계까지 전부 포함 (raw)
+await grid.pivot.getDataMatrix({ subtotals: 'all', grandTotals: 'all' });
+
+// 열 소계/총합계 컬럼 제외
+await grid.pivot.getDataMatrix({ excludeStructuralColumns: true });
+```
+
+| 옵션 | 타입 | 기본 | 설명 |
+|------|------|------|------|
+| `subtotals` | `'all' \| 'visible' \| 'none'` | `'visible'` | 소계 행 노출 (all=숨김 포함 raw, visible=토글 ON만, none=제외) |
+| `grandTotals` | `'all' \| 'visible' \| 'none'` | `'visible'` | 총합계 행 노출 (값 의미는 `subtotals` 와 동일) |
+| `excludeStructuralColumns` | `boolean` | `false` | 열 소계/총합계 컬럼 제외 |
+| `formatted` | `boolean` | `false` | mask 적용된 문자열로 반환 |
+
+#### getPivotMeta / getSeriesData
+
+```typescript
+// 읽기 전용 경량 메타 스냅샷
+const meta = grid.pivot.getPivotMeta();
+// → { rowFields: [{ field, header }, ...], columnFields, valueFields, rowCount, columnCount }
+
+// 차트용 시리즈 데이터
+const series = await grid.pivot.getSeriesData({
+  categoryField: 'region',      // 기본: 첫 번째 rowField
+  columnFieldLevel: 0,          // X축 레벨 (기본: 모든 열 필드 조합)
+  valueFields: ['sales'],       // 기본: 모든 valueFields
+  subtotals: 'all',             // 기본 'all' — 부모 카테고리 차트가 소계 토글 무관 동작
+  grandTotals: 'none',          // 기본 'none' — 총합계 카테고리는 'all'/'visible' 지정 시 추가
+});
+// → { xLabels: ['Q1','Q2','Q3','Q4'], categories: [{ name: '서울', series: [{ name:'sales', data:[...] }, ...] }, ...] }
+```
+
+---
+
+### grid.masterDetail — 마스터-디테일 API
+
+> 디테일 미설정 시 `getConfig()`는 `null` 반환.
+> `singleExpand` 모드에서 `expandAll()` 호출 시 `psWarn(PS310)` 경고 후 무시.
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `setConfig(config)` | `Promise<void>` | 디테일 설정 (`null`로 해제, 모든 cleanup 실행) |
+| `getConfig()` | `MasterDetailConfig \| null` | 디테일 설정 조회 |
+| `toggle(dataIndex)` | `Promise<void>` | 디테일 토글 |
+| `expand(dataIndex)` | `Promise<void>` | 디테일 펼침 |
+| `collapse(dataIndex)` | `Promise<void>` | 디테일 접힘 |
+| `expandAll()` | `Promise<void>` | 전체 디테일 펼침 (singleExpand 시 무시) |
+| `collapseAll()` | `Promise<void>` | 전체 디테일 접힘 |
+| `isExpanded(dataIndex)` | `boolean` | 확장 상태 조회 |
+
+---
+
+### grid.validation — 검증 API
+
+#### 검증 실행 / 전역 상태
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `validateAll(trigger?)` | `ValidationError[]` | 전체 검증 실행. `trigger`는 `'blur' \| 'commit' \| 'change' \| 'input'` (기본 `'commit'` — 내부적으로 `['blur', 'commit']` 둘 다 실행) |
+| `getErrors()` | `ValidationError[]` | 현재 `errorMap`에 쌓인 모든 검증 에러 (`[{ rowId, field, messages }, ...]`) |
+| `hasErrors()` | `boolean` | 에러 존재 여부 (O(1)) |
+| `clear()` | `Promise<void>` | 전체 에러 초기화 + refresh |
+
+#### 셀/행 단위 조회
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `getCellErrors(rowId, field)` | `string[] \| undefined` | 특정 셀의 에러 메시지 배열 (에러 없으면 `undefined`) |
+| `hasCellError(rowId, field)` | `boolean` | 특정 셀 에러 존재 여부 (O(1)) |
+| `getRowErrors(rowId)` | `Map<string, string[]> \| undefined` | 한 행의 모든 에러를 `field → messages` 맵으로 반환 (에러 없으면 `undefined`). 내부 상태의 안전한 복사본이라 mutate해도 원본에 영향 없음 |
+
+#### 외부 에러 주입
+
+커스텀 validation rule만으로는 표현하기 어려운 제약(예: "이미 등록된 이메일", "재고 초과" 등 **서버 측 검증 결과**)을 그리드에 반영할 때 사용합니다. 한번 주입된 에러는 `ps-cell-invalid` 클래스 자동 적용, `nextInvalid/prevInvalid` 탐색 포함, `commit()` 가드의 차단 대상으로 동일하게 처리됩니다.
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `setCellErrors(rowId, field, messages)` | `void` | 특정 셀의 에러 메시지를 설정. 빈 배열(`[]`)을 넘기면 해당 셀의 에러가 제거됨 |
+| `clearCellErrors(rowId, field)` | `void` | 특정 셀의 에러만 초기화 |
+| `clearRowErrors(rowId)` | `void` | 특정 행의 모든 에러 초기화 |
+
+#### Invalid 셀 네비게이션
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `nextInvalid(options?)` | `InvalidCell \| null` | 현재 선택 셀 **이후**의 첫 invalid 셀로 스크롤 + 선택 후 좌표 반환 |
+| `prevInvalid(options?)` | `InvalidCell \| null` | 현재 선택 셀 **이전**의 첫 invalid 셀로 스크롤 + 선택 후 좌표 반환 |
+
+**`NavigateInvalidOptions`**
+
+| 필드 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `wrap` | `boolean` | `true` | 끝에 도달하면 반대쪽으로 순환 |
+| `fromStart` | `boolean` | `false` | `true`면 현재 선택 셀을 무시하고 `next`는 첫 invalid, `prev`는 마지막 invalid부터 시작 |
+
+**`InvalidCell` 반환 타입**
+
+```typescript
+interface InvalidCell {
+  rowId: string | number;
+  field: string;
+}
+```
+
+**특징**
+
+- **visible order 준수** — 필터/정렬/컬럼 재정렬/숨김 상태를 모두 반영한 화면 순서로 순회합니다.
+- **rowId → effectiveIndex 변환** — 내부적으로 `BaseEngine.getReverseEffectiveMap()`을 사용해 O(1) 좌표 해석.
+- **dirty 추가 행 지원** — `dirtyAdded`의 row에 발생한 invalid도 정상 좌표로 포함.
+- **숨겨진 컬럼/필터된 행은 자동 제외** — hidden column의 invalid는 네비게이션 대상에서 빠집니다.
+- **commit 실패 시 자동 점프** — `grid.changes.commit()`이 invalid를 감지하면 `nextInvalid({ fromStart: true })`를 내부적으로 호출합니다.
+
+**엣지 케이스**
+
+- invalid가 0개 → `null`
+- anchor 셀 없음 → `next`는 첫 번째 invalid, `prev`는 마지막 invalid 반환
+- anchor가 invalid 셀 자체 → `next`는 **건너뛰고** 다음 invalid로 이동 (strict greater)
+- anchor 행이 필터로 사라진 경우 → `fromStart`와 동일한 동작
+- `wrap: false`에서 끝 도달 → `null`
+
+---
+
+### grid.clipboard — 클립보드 API
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `copy()` | `Promise<string \| null>` | 선택 셀 복사 |
+| `copy({ includeHeaders: true })` | `Promise<string \| null>` | 헤더 포함 복사 |
+| `paste()` | `Promise<number>` | 클립보드에서 붙여넣기 (셀 수 반환) |
+
+#### 키보드 단축키
+
+| 단축키 | 설명 |
+|--------|------|
+| `Ctrl+C` | 선택 셀 복사 |
+| `Ctrl+Shift+C` | 헤더 포함 복사 |
+| `Ctrl+V` | 붙여넣기 |
+
+---
+
+### grid.headers — 컬럼 그룹 API
+
+> **용어**: "컬럼 그룹"(`columnGroups`)은 여러 컬럼을 하나의 상위 헤더로 묶는 **다단계 컬럼 헤더(밴딩)**입니다. 데이터 행을 접는 **행 그룹화**(`grid.rowGroup`, `type:'group-row'`)와는 별개 기능입니다. (구 명칭 `headerGroups`/`HeaderGroupDef` → `columnGroups`/`ColumnGroupDef`.)
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `setColumnGroups(defs)` | `void` | 컬럼 그룹 정의(`ColumnGroupDef[]`)를 런타임에 설정/교체. `undefined` 전달 시 해제 |
+| `hasGroups()` | `boolean` | 컬럼 그룹이 설정되어 있는지 여부 |
+| `collapse(groupId)` | `void` | 컬럼 그룹 접힘 |
+| `expand(groupId)` | `void` | 컬럼 그룹 펼침 |
+| `toggle(groupId)` | `void` | 컬럼 그룹 토글 |
+| `isCollapsed(groupId)` | `boolean` | 접힘 상태 |
+| `collapseAll()` | `void` | 전체 접힘 |
+| `expandAll()` | `void` | 전체 펼침 |
+| `collapseAtLevel(level)` | `void` | 특정 레벨(정확히 그 레벨)의 컬럼 그룹만 접힘 (Ctrl/Cmd+클릭 "같은 depth 일괄" 제스처와 동일 의미) |
+| `expandAtLevel(level)` | `void` | 특정 레벨(정확히 그 레벨)의 컬럼 그룹만 펼침 |
+
+---
+
+### grid.io — Excel Import/Export API
+
+**외부 라이브러리 의존성 없이** XLSX 스트리밍 Import/Export를 제공합니다. 500만 행 이상의 대용량도 Worker 기반 스트리밍으로 처리하며, File System Access API를 통한 디스크 직접 저장도 지원합니다.
+
+**v0.4.2 이후 지원**:
+- **피벗 export** — 다단계 컬럼 헤더(`columnHeaderTree`) + rowHeader/rowMerge + 컬럼 subtotal / grand total을 Excel `<mergeCells>`로 완전 보존
+- **플랫 셀 병합** — `MergeStrategy` 결과(`meta.merge`)를 스트리밍 중 감지해 `<mergeCells>`로 누적
+- **플랫 컬럼 그룹** — `columnGroups` 트리를 다단계 헤더로 복원
+- **플랫 행 그룹화** — 그룹 행 포함/제외 3 모드
+- **원본 데이터 export** — 피벗/그룹 상태 유지하면서 loadData 원본만 추출
+
+#### 메서드
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `toExcel(options?)` | `Promise<Blob>` | XLSX로 export하여 메모리에 Blob 반환 |
+| `saveExcelToFile(options?)` | `Promise<SaveExcelToFileResult>` | FSA로 디스크에 직접 스트리밍 저장 (미지원 환경에서는 다운로드로 폴백) |
+| `fromExcel(file, options?)` | `Promise<ImportResult>` | XLSX 파일을 그리드로 import (dirty 모드 단일 경로) |
+| `getSheetInfo(file)` | `Promise<SheetInfo[]>` | 시트 목록과 예상 행 수 조회 (import 전 미리보기용) |
+| `previewExcel(file, options?)` | `Promise<PreviewResult>` | 헤더 + 첫 N행 반환 (그리드에 로드하지 않음) |
+
+#### Export 옵션 — `ExcelExportOptions`
+
+| 필드 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `scope` | `'all' \| 'visible' \| 'selected'` | `'all'` | 데이터 범위 |
+| `columns` | `string[]` | 보이는 컬럼 전체 | 특정 컬럼 ID만 |
+| `includeHeaders` | `boolean` | `true` | 헤더 행 포함 |
+| `sheetName` | `string` | `'Sheet1'` | 시트 이름 |
+| `preserveFormatting` | `boolean` | `false` | mask/decimalFormat → Excel numFmt 매핑 |
+| `dateFormat` | `string` | `'yyyy-mm-dd'` | 날짜 서식 |
+| `chunkSize` | `number` | `10000` | 청크당 행 수 |
+| `compression` | `'deflate' \| 'store'` | `'deflate'` | 압축 방식 |
+| `freezeHeader` | `boolean` | `false` | 헤더 행 고정 (freeze pane) |
+| `autoFilter` | `boolean` | `false` | 자동 필터 적용 |
+| `sheetSplit` | `false \| 'auto' \| number` | `false` | 시트 분할 (Excel 100만행 한계 대응). `'auto'`면 1,048,576 직전 자동 분할, `number`면 지정 행 수마다 분할 |
+| `sheetNamePattern` | `string` | `'{base} ({n})'` | 분할 시트 이름 패턴 (`{base}`, `{n}` placeholder) |
+| `useWorker` | `boolean` | auto (50K행 초과) | Worker 사용 여부 |
+| `signal` | `AbortSignal` | — | 취소 signal |
+| `onProgress` | `(ExportProgress) => void` | — | 진행률 콜백 |
+
+##### 원본 데이터 export 옵션
+
+| 필드 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `exportSource` | `boolean` | `false` | 피벗/그룹/트리/병합을 모두 무시하고 `grid.getAllDataSync()` 원본 데이터를 그대로 내보냄. **모든 그리드 모드**(flat/pivot/tree/grouping)에서 동작. 이 옵션이 `true`면 아래의 모든 모드별 옵션은 무시됨 |
+| `sourceColumns` | `'all' \| 'used'` | `'all'` | `exportSource: true`일 때만 유효. `'all'`: 원본의 모든 컬럼(flat은 `fields` 전체, pivot은 첫 source 행 `Object.keys` + `rowFields/columnFields`의 `header` 라벨 enrichment + 값 기반 type 추론). `'used'`: 피벗에 참여하는 필드만(`rowFields + columnFields + valueFields`의 `field` 기준, flat에서는 `'all'`과 동일) |
+| `sourceFields` | `Array<{ field: string; header?: string; dataType?: string }>` | — (`originalConfig.fields`로 폴백) | `exportSource: true`(특히 pivot `sourceColumns: 'all'`)에서 원본 컬럼의 header/type 라벨링에 쓰는 **소스 필드 카탈로그**. 피벗 행/열/값에 **배치되지 않은** 필드도 raw id 대신 `header` 라벨로 export되게 한다 — 피벗 모드는 배치된 필드(`rowFields`/`columnFields`)에만 header가 있어 미배치 필드가 id로 새던 문제를 해결. 우선순위: 카탈로그(`sourceFields`, 없으면 `originalConfig.fields`)가 header/type을 시드 → 피벗 `rowFields`/`columnFields`의 `header`가 override(valueFields는 집계 라벨이라 제외), type은 카탈로그의 `dataType` 우선·없으면 첫 행 값으로 추론. 소비처가 자신의 소스 필드 카탈로그를 export 시 넘길 수 있다 |
+
+##### 피벗 export 옵션
+
+| 필드 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `pivotExpandCollapsed` | `boolean` | `true` | 피벗 모드에서 접힌 행/열을 펼친 상태로 내보냄. `true`면 `pivot.getAllRows()`로 collapse 상태와 무관하게 전수 export하고 다단계 컬럼 헤더 + `rowMergeInfo` 병합까지 복원. `false`면 `getVisibleDataAsync` 경로로 "화면에 보이는 것만" export하되 row merge는 생략 (v1 안전 가드). flat 모드에서는 무시 |
+
+##### 플랫 병합 / 컬럼 그룹 옵션
+
+| 필드 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `preserveMerges` | `boolean` | `true` | 셀 병합 보존 여부. `true`면 플랫 모드의 `MergeStrategy` 결과(`meta.merge`)와 피벗의 `rowMergeInfo`를 Excel `<mergeCells>`로 내보냄. `false`면 기존 평탄 export. 플랫 경로는 `writeChunk` 도중 각 행의 `__merge`를 스트리밍으로 감지해 누적 |
+| `preserveColumnGroups` | `boolean` | `true` | 플랫 모드 `columnGroups` 트리를 다단계 헤더 + `<mergeCells>` 병합으로 보존. 피벗 모드에서는 자체 다단계 헤더가 이 옵션과 독립으로 동작. flat 모드에 `columnGroups`가 없으면 무시 |
+
+##### 그룹 행 export 옵션
+
+| 필드 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `groupRowMode` | `'include' \| 'visible' \| 'dataOnly'` | `'include'` | 플랫 행 그룹화(`grid.rowGroup.setConfig`) 활성 시 export 동작. `'include'`: 접힘 상태 무시하고 모든 그룹 행 + data를 펼친 상태로 export. `'visible'`: 현재 접힘 상태 그대로 (collapsed 자식 제외). `'dataOnly'`: 그룹 행 제외하고 data 행만 |
+| `groupOutline` | `boolean` | `true` | Excel 네이티브 outline (+/- 버튼) 생성. 그룹 행을 summary row로, 데이터 행에 `outlineLevel`을 부여. `groupRowMode: 'dataOnly'`이면 무시. 중첩 그룹(`columns: ['dept','role']`)은 depth별 outlineLevel 자동 계산 |
+
+##### 트리 그리드 export 옵션
+
+| 필드 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `treeRowMode` | `'include' \| 'visible'` | `'include'` | 트리 그리드(`grid.tree.setConfig`) 활성 시 export 동작. `'include'`: 모든 트리 노드를 펼친 상태로 내보냄(collapsed 무시). `'visible'`: 현재 접힘 상태 그대로 (collapsed 자식 제외). 원본 평탄 데이터만 원하면 `exportSource: true` 사용 |
+| `treeOutline` | `boolean` | `true` | Excel 네이티브 outline (+/- 버튼) 생성. 트리 depth를 `outlineLevel`로 변환. Excel outline은 최대 7단계까지 지원 |
+
+> **경로 우선순위**: `exportSource` > 피벗 > 트리 > 그룹 > 병합 > 기본. 상위 경로가 활성이면 하위 옵션은 무시됩니다.
+
+> **조합 매트릭스**: 플랫의 columnGroups + grouping + merge는 서로 직교 조합 가능.
+> 피벗 경로가 활성이면 flat 옵션들은 무시되고 피벗 자체의 다단계 헤더 + `rowMergeInfo`가 우선 적용됩니다.
+> 트리와 그룹은 상호배타 — 트리 모드가 활성이면 그룹 옵션은 무시됩니다.
+
+> **Multi-Row(`rowTemplate`) export**: 현재 논리 행 1개 = xlsx 행 1개로 평탄화되며 `console.warn`이 1회 발생합니다. 논리 행 → 물리 행 N개 확장 + subRow cell placement 지원은 Phase 2 후속 작업.
+
+#### `saveExcelToFile` 전용 옵션 — `SaveExcelToFileOptions extends ExcelExportOptions`
+
+| 필드 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `suggestedName` | `string` | `'export.xlsx'` | 저장 다이얼로그 기본 파일명 |
+| `fallbackToDownload` | `boolean` | `true` | FSA 미지원 환경에서 `toExcel` + 다운로드로 폴백. `false`면 에러 throw |
+| `onFileNameResolved` | `(fileName: string) => void` | – | 저장 파일명이 **확정된 시점**(FSA는 사용자가 저장 클릭 직후 `handle.name`, 폴백은 즉시 `suggestedName`) 호출. 스트리밍 시작 전이라 호스트가 진행률 알림을 실제 파일명으로 띄울 수 있다. 다이얼로그 취소 시 미호출 |
+
+`SaveExcelToFileResult`: `{ mode: 'fileSystemAccess' \| 'download', fileName: string, fileSize?: number }`
+
+#### Import 옵션 — `ExcelImportOptions`
+
+##### 기본 옵션
+
+| 필드 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `sheetIndex` | `number` | `0` | 가져올 시트 인덱스 |
+| `sheetName` | `string` | — | 시트 이름 (sheetIndex 대신) |
+| `mergeSheets` | `boolean \| 'auto'` | `false` | 모든 시트 합치기 (분할 export된 파일용). `'auto'`면 시트 2개 이상이면 자동 |
+| `columnMapping` | `Record<string, string> \| 'auto'` | `'auto'` | Excel 헤더 → grid columnId 매핑. `'auto'`는 헤더 텍스트 기반 자동 매칭 |
+| `headerRow` | `number` | `0` | 헤더 행 번호 |
+| `startRow` | `number` | `headerRow + 1` | 데이터 시작 행 |
+| `typeCoercion` | `boolean` | `true` | 자동 타입 감지 |
+| `dateColumns` | `string[]` | — | 날짜 컬럼 강제 지정 |
+| `preview` | `number` | — | 첫 N행만 로드 (미리보기) |
+| `batchSize` | `number` | `10000` | 배치당 행 수 |
+| `useWorker` | `boolean` | auto (50MB 초과) | Worker 사용 여부 |
+| `signal` | `AbortSignal` | — | 취소 signal |
+| `onProgress` | `(ImportProgress) => void` | — | 진행률 콜백 |
+| `validate` | `boolean` | `false` | import 후 즉시 validation rule을 실행하고 결과를 `ImportResult`에 포함 |
+
+##### Dirty 모드 옵션 (93369b4 커밋)
+
+모든 import는 **dirty 상태**로 반영되며, 사용자가 `grid.changes.commit()`으로 확정해야 합니다 (`autoCommit` 옵션 제외). 기존 dirty 상태가 있으면 `PS711`로 거부됩니다.
+
+| 필드 | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| `mode` | `'replace' \| 'append' \| 'upsert'` | `'replace'` | 기존 데이터 처리 방식 |
+| `conflictStrategy` | `'error' \| 'skip' \| 'update'` | `'error'` | `mode: 'append'`에서 키 충돌 처리. `replace`/`upsert`에선 무시 |
+| `autoCommit` | `boolean` | `false` | import 완료 후 자동 `commit()` 호출 |
+| `dryRun` | `boolean` | `false` | ChangeTracker에 실제 반영 없이 변경 요약만 반환 (대용량 preview) |
+
+**`mode` 상세**
+
+- **`'replace'`** — 기존 committed 전체를 Excel 데이터로 대체.
+  - Phase 1: committed N행 전체를 `dirtyDeleted`로 pre-mark
+  - Phase 2: 각 Excel row의 키가 committed와 hit이면 `undeleteRow` + 필드별 `updateCell` (값 동일 시 pristine 유지). Miss이면 `addRow`
+  - Excel에 **없는** committed 행은 `deletedCount`로 남음
+- **`'upsert'`** — 키 있으면 update, 없으면 add. Excel에 없는 기존 행은 **그대로 유지**. `mode: 'append'` + `conflictStrategy: 'update'`와 의미는 같지만 이름으로 의도 명확화
+- **`'append'`** — 기존 유지 + 끝에 추가. 키 충돌은 `conflictStrategy`로 처리
+
+**`conflictStrategy` 상세** (`mode: 'append'` 전용)
+
+- **`'error'`** — 충돌 발생 즉시 `PS712` throw + 전체 dirty 롤백
+- **`'skip'`** — 충돌 행 무시 + `skippedCount++` + `conflicts[]`에 기록 (최대 100개)
+- **`'update'`** — 기존 행을 Excel 값으로 업데이트 (`sameValue` diff로 동일 값은 pristine 유지)
+
+#### Import 결과 — `ImportResult`
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `rowCount` | `number` | Excel에서 읽은 총 행 수 (파싱 기준) |
+| `columnCount` | `number` | import된 컬럼 수 |
+| `columns` | `ImportColumnInfo[]` | 컬럼 매핑 결과 `{ excelHeader, mappedTo, type }` |
+| `errors` | `ImportError[]` | 치명적이지 않은 에러 (warning/error) |
+| `duration` | `number` | 소요 시간 (ms) |
+| `addedCount` | `number` | dirty로 추가된 행 수 |
+| `updatedCount` | `number` | 실제 값이 다른 경우만 카운트 (sameValue diff 통과) |
+| `skippedCount` | `number` | skip 전략 또는 키 누락 |
+| `deletedCount` | `number` | `replace` 모드에서 dirtyDeleted 표시된 행 수 |
+| `unchangedCount` | `number` | 값이 완전 동일해서 pristine 유지 |
+| `committed` | `boolean` | `autoCommit` 실행 여부 |
+| `conflicts?` | `ImportConflict[]` | 충돌 목록 (최대 100개). `{ row, key, reason: 'duplicate' \| 'missing_key' }` |
+| `conflictsTruncated?` | `boolean` | 100개 초과로 잘렸는지 |
+| `warnings?` | `string[]` | 경고 목록 (`'LARGE_IMPORT'`, `'DRY_RUN'` 등) |
+
+#### 진행률 — `ImportProgress` / `ExportProgress`
+
+**`ImportProgress`**
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `phase` | `'reading' \| 'parsing' \| 'loading' \| 'diffing' \| 'committing' \| 'validating'` | 현재 단계 |
+| `rowsProcessed` | `number` | 처리된 행 수 |
+| `totalRows?` | `number` | 스트리밍 중에는 `undefined` |
+| `percent` | `number` | 0~100 |
+
+**`ExportProgress`**
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `phase` | `'preparing' \| 'generating' \| 'compressing' \| 'finalizing'` | 현재 단계 |
+| `rowsProcessed` | `number` | 처리된 행 수 |
+| `totalRows` | `number` | 전체 행 수 |
+| `percent` | `number` | 0~100 |
+| `currentSheet?` | `number` | 분할 시에만 (1-based) |
+| `totalSheets?` | `number` | 분할 시에만 |
+
+#### 에러 코드
+
+| 코드 | 경로 | 설명 |
+|------|------|------|
+| `PS700` | export | export 일반 실패 |
+| `PS701` | import | import 일반 실패 |
+| `PS702` | import | 유효하지 않은 XLSX 파일 |
+| `PS703` | import | 시트를 찾을 수 없음 |
+| `PS704` | import | 컬럼 매핑 실패 |
+| `PS705` | export | `CompressionStream` 미지원 (STORE로 fallback, warning) |
+| `PS706` | export | AbortSignal 취소 |
+| `PS707` | import | AbortSignal 취소 |
+| `PS708` | import | Worker 생성 실패 (메인 스레드로 fallback, warning) |
+| `PS709` | export | 시트당 최대 행 수 초과 (`sheetSplit` 미사용 시) |
+| `PS710` | export | 시트당 최대 컬럼 수 초과 |
+| `PS711` | import | 기존 dirty 상태가 있어 import 거부 |
+| `PS712` | import | `append` 모드 키 충돌 (`conflictStrategy: 'error'`) |
+| `PS713` | import | 키 컬럼이 Excel에 없음 |
+| `PS714` | import | `autoCommit` 단계 실패 (dirty는 보존) |
+
+#### 이벤트
+
+| 이벤트 | 페이로드 | 설명 |
+|--------|---------|------|
+| `io:export:complete` | `{ rowCount, columnCount, fileSize }` | XLSX export 완료 |
+| `io:import:complete` | `{ rowCount, columnCount, duration }` | XLSX import 완료 |
+
+#### 예제
+
+```typescript
+// 기본 export (메모리)
+const blob = await grid.io.toExcel({ scope: 'visible', includeHeaders: true });
+
+// 디스크 직접 저장 (FSA)
+const result = await grid.io.saveExcelToFile({
+  suggestedName: 'report.xlsx',
+  scope: 'all',
+  sheetSplit: 'auto',
+  preserveFormatting: true,
+  onProgress: (p) => console.log(`${p.phase}: ${p.percent}%`),
+});
+
+// 대량 import with replace + autoCommit
+const importResult = await grid.io.fromExcel(file, {
+  mode: 'replace',
+  autoCommit: false,            // false이면 dirty 상태로 검토 가능
+  signal: abortController.signal,
+  onProgress: (p) => updateProgressBar(p.percent),
+});
+
+console.log(`추가 ${importResult.addedCount}, 수정 ${importResult.updatedCount}, ` +
+            `삭제 ${importResult.deletedCount}, 동일 ${importResult.unchangedCount}`);
+
+// 검토 후 수동 확정
+if (importResult.warnings?.includes('LARGE_IMPORT')) {
+  if (confirm('20만 행 이상 import됩니다. 계속?')) {
+    await grid.changes.commit();
+  } else {
+    await grid.changes.discardAll();
+  }
+}
+
+// append + skip 전략
+await grid.io.fromExcel(file, {
+  mode: 'append',
+  conflictStrategy: 'skip',
+  autoCommit: true,
+});
+
+// dry-run으로 변경 요약만 확인
+const summary = await grid.io.fromExcel(file, { mode: 'upsert', dryRun: true });
+console.log(`변경 예상: +${summary.addedCount} ~${summary.updatedCount} -${summary.deletedCount}`);
+```
+
+---
+
+### grid.dragDrop — 드래그앤드롭 API
+
+행 단위 드래그앤드롭(같은 그리드 내 reorder, 크로스-그리드 드롭 등)을 제어합니다. 그리드 생성 시 `dragDropConfig`로 초기 설정을 전달할 수 있으며, 런타임에 `setConfig`로 전체 교체가 가능합니다.
+
+| 메서드 | 반환 | 설명 |
+|--------|------|------|
+| `setConfig(config)` | `Promise<void>` | 새 `DragDropConfig`로 교체 (전체 교체 — partial update 아님) |
+| `getConfig()` | `Readonly<DragDropConfig>` | 현재 설정 조회 |
+| `isActive()` | `boolean` | drag-drop 기능 중 하나라도 활성화되어 있는지 |
+
+> 관련 이벤트: `row:reordered` (같은 그리드 내 reorder), `row:dragOut` / `row:dragIn` (크로스-그리드 이동 — ADR-108).
+
+```typescript
+// 초기 설정 (생성자)
+new PureSheet(container, {
+  dragDropConfig: {
+    rowOrderField: { field: 'displayOrder', strategy: 'dense' },
+    mutateOnDirty: (row) => ({ updatedAt: new Date().toISOString() }),
+    // crossGridDragGroup: 'tasks',  // 같은 그룹의 다른 그리드로 행 이동
+    // onRowDragOut: (e) => true, onRowDragIn: (e) => true,  // 거부 시 false 반환
+  },
+});
+
+// 런타임 변경
+await grid.dragDrop.setConfig({
+  rowOrderField: { field: 'sortOrder', strategy: 'sparse' },
+});
+
+if (grid.dragDrop.isActive()) {
+  console.log('drag-drop config:', grid.dragDrop.getConfig());
+}
+```
+
+#### 드래그 시작 위치 — `dragTrigger`
+
+| 값 | 설명 |
+|---|---|
+| `'handle'` (default) | drag 핸들 컬럼에서만 reorder 시작. row 본문은 기존 동작(cell/row 드래그 선택) |
+| `'row'` | row 본문 어디서나 reorder 시작. mousedown → 5px 이상 이동 시 drag, 그 미만은 click(선택)으로 처리 (Shift/Ctrl+click 정상). **trade-off**: cell/row 드래그 선택은 비활성. 보통 `showDragHandleColumn: false`와 함께 사용 |
+
+#### 트리 드래그 reorder — `treeReorder`
+
+`treeConfig` + `reorderableRows: true`가 함께 설정되면 **트리 인식 드래그 reorder**가 자동 활성화됩니다. 형제 순서 변경 + 다른 부모로 재부모화(reparent)를 드래그로 처리하며, 부모를 드래그하면 후손이 함께 이동합니다(Policy B). `dragDropConfig.treeReorder`(`TreeReorderConfig`)로 세부 조정하거나 `false`로 비활성화합니다.
+
+```typescript
+new PureSheet(container, {
+  treeConfig: { idField: 'id', parentField: 'parentId', treeColumn: 'name' },
+  dragDropConfig: {
+    reorderableRows: true,
+    dragTrigger: 'row',            // 행 본문 어디서나 드래그 (파일 탐색기 UX)
+    showDragHandleColumn: false,
+    treeReorder: {
+      allowReparent: true,          // as-child 드롭(재부모화) 허용 (@default true)
+      // 폴더 위 dwell → drop-onto(자식화), 파일 위 → insert-between(형제)
+      resolveDropMode: (row) => (row.type === 'folder' ? 'drop-onto' : 'insert-between'),
+      isDroppableAsChild: (row) => row.type === 'folder',  // 자식 수용 가능 행 제한
+    },
+  },
+});
+```
+
+**`TreeReorderConfig` 필드**
+
+| 필드 | 타입 | 기본 | 설명 |
+|------|------|------|------|
+| `allowReparent` | `boolean` | `true` | as-child 드롭(다른 부모로 재부모화) 허용 |
+| `expandOnHover` | `number \| false` | `700` | collapsed 부모 위 hover 시 자동 펼침 지연(ms). `false`면 비활성 |
+| `isDroppableAsChild` | `(row) => boolean` | — | 특정 행이 자식을 받을 수 있는지 (예: 폴더만). 미설정 시 모두 허용 |
+| `resolveDropMode` | `(row, ctx) => DropMode \| Promise<DropMode>` | — | 행별 드롭 모드 결정. `'insert-between'`(형제 line) vs `'drop-onto'`(행 highlight 자식화). 비동기 가능 |
+| `dropModeDwellMs` | `number` | `500` | `resolveDropMode` 호출 전 cursor가 같은 행 위에 머물러야 하는 dwell(ms) |
+| `dropOntoEdgeThreshold` | `number \| { px?, ratio? }` | `2` | drop-onto 모드여도 행 위/아래 가장자리 이 범위 안이면 insert-between으로 fall-back (폴더-폴더 사이 삽입용). 낮은 rowHeight 대응 위해 작게 |
+| `indentSize` | `number` | `20` | 드롭 인디케이터 indent 계산에 쓰는 레벨당 px |
+| `indicatorStartOffset` | `number` | `10` | 인디케이터 시작 X 오프셋(px) |
+| `mapCrossGridParent` | `(sourceRow, sourceGrid) => RowId \| null` | — | 크로스-그리드 트리 드롭 시 source parentId → target parentId 변환 |
+
+> **프로그램 방식 이동**은 드래그 없이 [`grid.tree.moveNode(nodeId, newParentId, newIndex?)`](#gridtree--트리-api)로 수행합니다 (flat의 `changes.reorderRow` 대칭).
+> **완료 통지**는 `row:reordered {kind:'tree'}` 이벤트로 발화하며 `commandId` / `patches` / `dropMode`를 담습니다.
+> **낙관적 백엔드 동기화**는 `row:reordered` + `changes:undone`/`changes:redone` 3종 구독 + 실패 시 `undoManager.undoThrough(commandId)` 패턴을 쓰세요 ([Undo/Redo 이벤트](#undoredo) 참조).
+
+---
+
+## Reactive API (반응형 구독)
+
+moz-ui-grid-core는 React `useSyncExternalStore` 호환 반응형 구독 시스템을 제공합니다.
+
+### grid.select()
+
+```typescript
+grid.select<T>(selector: (state: GridState) => T): Subscribable<T>
+```
+
+GridState에서 파생 상태를 구독합니다. selector 결과가 변경될 때만 구독자에게 알림.
+
+#### Subscribable 인터페이스
+
+```typescript
+interface Subscribable<T> {
+  subscribe(onStoreChange: () => void): Unsubscribe;
+  getSnapshot(): T;
+}
+```
+
+#### React에서 사용
+
+```typescript
+// React Hook
+function useGridState<T>(grid: PureSheet, selector: (state: GridState) => T): T {
+  const subscribable = useMemo(() => grid.select(selector), [grid, selector]);
+  return useSyncExternalStore(subscribable.subscribe, subscribable.getSnapshot);
+}
+
+// 사용 예시
+const rowCount = useGridState(grid, s => s.visibleRowCount);
+const isEditing = useGridState(grid, s => s.isEditing);
+const canUndo = useGridState(grid, s => s.canUndo);
+```
+
+#### Vanilla JS에서 사용
+
+```typescript
+const sub = grid.select(s => s.selectedRowCount);
+const unsubscribe = sub.subscribe(() => {
+  console.log('선택된 행 수:', sub.getSnapshot());
+});
+```
+
+### grid.store
+
+```typescript
+get store(): Store<GridState>
+```
+
+`grid.select()` 내부에서 사용하는 Store 인스턴스에 직접 접근합니다. 첫 접근 시 lazy 초기화되며 GridCore 이벤트 + ChangeTracker 이벤트가 자동 연결됩니다. `createGridStore`를 수동 호출할 필요는 없습니다.
+
+```typescript
+const store = grid.store;
+
+// 1) 즉시 스냅샷 조회 — selector 없이 전체 상태
+const { columnStates, visibleRowCount } = store.getState();
+
+// 2) 다중 selector 구성 시 동일 store 재사용
+const a = store.select(s => s.canUndo);
+const b = store.select(s => s.canRedo);
+```
+
+> 단발성 조회는 `grid.select(s => …).getSnapshot()`이 더 간결합니다. `store.getState()`는 여러 필드를 한 번에 꺼내거나 디버깅 콘솔에서 전체 상태를 들여다볼 때 유용합니다.
+
+### GridState 필드
+
+`grid.select(s => s.필드명)` 으로 구독 가능한 전체 상태:
+
+#### 데이터 & 컬럼
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `columns` | `readonly ColumnDef[]` | 현재 컬럼 정의 |
+| `columnStates` | `readonly ColumnState[]` | 컬럼 UI 상태 (너비, 가시성, 고정, 순서) |
+
+#### 행 수
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `totalRowCount` | `number` | 전체 행 수 (필터 전) |
+| `visibleRowCount` | `number` | 표시 행 수 (필터 후) |
+
+#### 뷰 상태
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `viewState` | `Readonly<ViewState>` | 정렬, 필터, 그룹 설정 |
+#### Feature 모듈 설정 (반응형 관측 계약)
+
+사용자 변경 가능한 feature 모듈(`setConfig`류 API 보유)의 live config를 **대칭적으로** 반응형 노출합니다. 외부 소비자가 자신의 설정 UI를 `getConfig()` 폴링 없이 구독으로 바인딩할 수 있습니다. 각 필드는 변경 시에만 새 참조로 교체되며(shallowEqual 호환), 미설정 모듈은 `null`(또는 `pivotMode`는 `'flat'`)로 노출됩니다. 노출된 config는 내부 mutable 참조이므로 직접 수정하지 말고 해당 `setConfig`류 API를 사용하세요.
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `pivotConfig` | `Readonly<PivotConfig> \| null` | 현재 피벗 설정 (피벗 모드가 아니어도 보존될 수 있음 → 모드 판별은 `pivotMode` 사용) |
+| `pivotMode` | `'flat' \| 'pivot'` | 현재 피벗 모드 (`setMode()`의 권위 있는 신호) |
+| `treeConfig` | `Readonly<TreeConfig> \| null` | 현재 트리 설정 |
+| `masterDetailConfig` | `Readonly<MasterDetailConfig> \| null` | 현재 마스터-디테일 설정 |
+| `groupConfig` | `Readonly<GroupingConfig> \| null` | 현재 그룹화 설정 (`viewState.groups`는 이로부터 합성됨) |
+| `dragDropConfig` | `Readonly<DragDropConfig> \| null` | 현재 드래그-드롭 설정 |
+| `mergeConfig` | `Readonly<MergeConfig> \| null` | 현재 셀 병합 설정 |
+
+
+#### 변경 추적
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `hasChanges` | `boolean` | 미커밋 변경 존재 여부 |
+| `changeVersion` | `number` | 변경 버전 카운터 (변경 감지용) |
+
+#### 비동기 상태
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `activity` | `GridActivity` | 현재 실행 중인 비동기 작업 (중첩 시 가장 바깥쪽만 노출) |
+| `isSearching` | `boolean` | 검색 진행 중 여부 (background 작업, `activity`와 독립) |
+
+`GridActivity` 전체 값:
+
+| 범주 | 값 |
+|---|---|
+| Idle | `'idle'` |
+| 데이터 로딩 | `'loadData'`, `'loadTreeData'`, `'refreshLoaderData'` |
+| 뷰 변경 | `'sort'`, `'filter'`, `'setMode'`, `'setPivotConfig'`, `'setMergeConfig'`, `'updateFields'` |
+| Committed CRUD | `'addRow'`, `'updateRow'`, `'removeRow'` |
+| Dirty CRUD | `'addRowDirty'`, `'updateCellDirty'`, `'deleteRowDirty'`, `'deleteSelectedRowsDirty'`, `'undeleteRowsDirty'`, `'undeleteRowDirty'`, `'discardRowDirty'`, `'discardSelectedRowsDirty'`, `'reorderRow'` |
+| 트랜잭션 | `'applyTransaction'`, `'flushAsyncTransactions'` |
+| 커밋/리프레시 | `'commitChanges'`, `'refresh'` |
+| 클립보드 | `'copyToClipboard'`, `'pasteFromClipboard'` |
+| 선택 일괄 | `'deleteSelectedRows'`, `'updateSelectedCells'` |
+| 검색 | `'search'` |
+| IO | `'exportExcel'`, `'importExcel'` |
+
+#### 선택
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `selectedRowCount` | `number` | 선택된 행 수 |
+| `selectedCellCount` | `number` | 선택된 셀 수 |
+
+#### 편집
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `isEditing` | `boolean` | 셀 편집 중 여부 |
+| `editingCell` | `Readonly<CellPosition> \| null` | 편집 중인 셀 위치 |
+
+#### Undo/Redo
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `canUndo` | `boolean` | Undo 가능 여부 |
+| `canRedo` | `boolean` | Redo 가능 여부 |
+
+#### 검증
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `hasValidationErrors` | `boolean` | 검증 에러 존재 여부 |
+| `validationErrorCount` | `number` | 검증 에러 수 |
+
+#### 검색
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `isSearching` | `boolean` | 검색 background 작업 진행 중 여부 |
+
+#### 스크롤
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `scrollTop` | `number` | 수직 스크롤 위치 (px) |
+| `visibleStartIndex` | `number` | 보이는 첫 행 인덱스 (overscan 포함) |
+| `visibleEndIndex` | `number` | 보이는 마지막 행 인덱스 (overscan 포함) |
+
+---
+
+### grid.rows.observeById()
+
+```typescript
+grid.rows.observeById(id: string | number): ReactiveRow
+grid.rows.observeByIndex(sourceIndex: number): ReactiveRow
+```
+
+특정 행을 반응형으로 관찰합니다. 해당 행의 데이터, 선택 상태, CRUD 상태 변경 시 알림.
+`observeById`는 ID 기반, `observeByIndex`는 sourceIndex 기반으로 접근합니다.
+
+> `observe(row)`는 행 객체를 받아 같은 효과를 내지만 `enableReferCache: true`가 필요합니다.
+
+### ReactiveRow
+
+`Subscribable<Row | undefined>` 인터페이스를 구현하며, 추가 속성/메서드를 제공합니다.
+
+#### 구독
+
+```typescript
+const row = grid.rows.observeById('row-1');
+const unsub = row.subscribe(() => {
+  console.log('행 변경:', row.data);
+});
+```
+
+#### 속성 (getter)
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `id` | `string \| number` | 행 식별자 |
+| `data` | `Record<string, unknown>` | 현재 행 데이터 |
+| `exists` | `boolean` | 행 존재 여부 |
+| `state` | `RowState` | CRUD 상태 (`'pristine' \| 'added' \| 'modified' \| 'deleted'`) |
+| `selected` | `boolean` | 선택 여부 |
+| `readOnly` | `boolean` | 읽기 전용 여부 |
+| `visible` | `boolean` | 가시성 여부 |
+| `pinned` | `'top' \| 'bottom' \| null` | 고정 상태 |
+| `cssClass` | `string \| null` | CSS 클래스 |
+| `height` | `number \| null` | 행 높이 (px) |
+| `changedFields` | `string[] \| null` | 변경된 필드 목록 |
+
+#### 쓰기 메서드
+
+| 메서드 | 설명 |
+|--------|------|
+| `setValue(field, value)` | 단일 필드 값 갱신 (내부적으로 dirty 셀 수정 — `updateCellDirty`로 위임) |
+| `setValue(patch)` | 여러 필드를 객체로 일괄 갱신 (2개 이상이면 `beginBatch`/`endBatch`로 묶여 Undo 1단위) |
+| `setProps(props)` | 행 속성(고정, CSS 클래스, 높이 등) 갱신 |
+
+#### 셀 접근
+
+```typescript
+const cell = row.cell('name');
+```
+
+### ReactiveCell
+
+| 메서드 | 설명 |
+|--------|------|
+| `subscribe(cb)` | 셀 값 변경 구독 |
+| `getSnapshot()` | 현재 셀 값 |
+| `set(value)` | 셀 값 설정 |
+
+```typescript
+// React에서 사용
+function useCellValue(grid: PureSheet, rowId: string, field: string) {
+  const cell = useMemo(() => grid.rows.observeById(rowId).cell(field), [grid, rowId, field]);
+  return useSyncExternalStore(cell.subscribe, cell.getSnapshot);
+}
+```
+
+---
+
+## 이벤트
+
+### 이벤트 구독
+
+```typescript
+const unsubscribe = grid.on('cell:click', (payload) => {
+  console.log(payload.columnId, payload.value);
+});
+
+// 구독 해제
+unsubscribe();
+// 또는
+grid.off('cell:click', handler);
+```
+
+### 이벤트 목록
+
+#### 데이터
+
+| 이벤트 | 페이로드 | 설명 |
+|--------|---------|------|
+| `data:loaded` | `{ rowCount, columnCount }` | 데이터 로드 완료 |
+
+#### 행
+
+| 이벤트 | 페이로드 | 설명 |
+|--------|---------|------|
+| `row:click` | `{ row, rowIndex, event }` | 행 클릭 |
+| `row:dblclick` | `{ row, rowIndex, event }` | (예약) 현재 코드 경로에서는 발행되지 않음 — `cell:dblclick`을 사용하세요 |
+| `row:pinned` | `{ row, position }` | 행 고정 |
+| `row:unpinned` | `{ rowId, position? }` | 행 고정 해제 |
+| `row:reordered` | `RowReorderedEvent` (discriminated, 아래) | 행/노드 재정렬 완료 (드래그 또는 프로그램 API) |
+| `row:dragOut` | `{ row, sourceGridId, ... }` | 다른 그리드로 드래그아웃 (ADR-108, 크로스-그리드 드롭) |
+| `row:dragIn` | `{ row, targetGridId, ... }` | 다른 그리드에서 드래그인 (ADR-108) |
+
+**`RowReorderedEvent`** — `kind`로 분기하는 discriminated union (flat 그리드 vs 트리 그리드).
+
+| `kind` | 필드 | 설명 |
+|--------|------|------|
+| `'flat'` | `commandId`, `fromIndex`, `toIndex` | 평탄 그리드 행 재정렬 |
+| `'tree'` | `commandId`, `rowIds`, `patches`, `dropMode` | 트리 노드 재정렬. `patches`=`TreeMovePatch[]`(promoted root만, old/new parent+sibling 포함), `dropMode`=`'before'\|'after'\|'asChild'` |
+
+> `commandId`는 이 재정렬을 감싼 **BatchCommand.id**입니다 — [`undoManager.undoThrough(commandId)`](#gridundomanager--undoredo-api)의 correlation key로 그대로 사용하세요 (낙관적 파이프라인 실패 롤백).
+> `row:reordered`는 **정방향(드래그/`moveNode`)에서만** 발화합니다. undo/redo 시엔 발화하지 않으므로, 백엔드 동기화는 [`changes:undone`/`changes:redone`](#undoredo)도 함께 구독해야 합니다.
+
+#### 셀
+
+| 이벤트 | 페이로드 | 설명 |
+|--------|---------|------|
+| `cell:click` | `{ row, columnId, value, event }` | 셀 클릭 |
+| `cell:dblclick` | `{ row, columnId, value, event }` | 셀 더블클릭 |
+| `cell:change` | `{ rowIndex, rowId, columnId, oldValue, newValue }` | 셀 값 변경. `rowId`는 정렬/필터 무관 안정 식별자(정규화된 문자열) — cascade 등 rowId 기반 로직의 트리거로 사용 |
+| `cell:beforeEdit` | `{ ..., cancel() }` | 편집 시작 전 (취소 가능) |
+| `cell:editCommitting` | `{ ..., cancel() }` | 편집 커밋 전 (취소 가능) |
+| `cell:editCommitted` | `{ rowIndex, rowId, dataIndex, columnId, oldValue, newValue }` | 편집 커밋 완료. `rowId` 포함 (위와 동일) — boolean 셀 즉시 토글도 이 이벤트로 발화되어 체크박스 cascade 트리거로 쓰인다 |
+| `cell:tooltip` | `CellTooltipPayload` (아래 참조) | 셀·컬럼 헤더 호버 시 툴팁 표시 요청 (`tooltipMode` 로 발행 제어) |
+
+**`CellTooltipPayload`** (26cd68a 커밋에서 validation 정보 통합)
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `area` | `'cell' \| 'columnHeader'` | 영역 — **셀뿐 아니라 컬럼 헤더 호버 시에도 발행** |
+| `rowIndex?` | `number` | 행 인덱스 (dataIndex 기준). 헤더에선 `undefined` |
+| `rowId?` | `string \| number` | 행 ID (피벗 모드/헤더에선 `undefined` 가능) |
+| `columnId?` | `string` | 컬럼 ID. 그룹/멀티레벨 헤더 셀에선 `undefined` 가능 |
+| `groupId?` | `string` | 그룹/멀티레벨/피벗 헤더 그룹 식별자 (`columnHeader` 에서만) |
+| `value?` | `unknown` | 원본 셀 값. 헤더에는 없음 |
+| `formattedValue` | `string` | 렌더링된 텍스트 (헤더는 컬럼 라벨) |
+| `tooltipText?` | `string` | 컬럼 커스텀 툴팁 문구(`ColumnDef.headerTooltip`/`cellTooltip`). 있으면 `formattedValue` 대신 표시에 우선 |
+| `isOverflowing` | `boolean` | 셀 내용이 잘려서 표시되는지 |
+| `cellRect` | `DOMRect` | 셀/헤더 DOM 영역 |
+| `element` | `HTMLElement` | 셀/헤더 DOM 요소 |
+| `errors?` | `string[]` | 유효성 검사 에러 메시지 (없으면 `undefined`). **셀 전용** |
+| `hasError?` | `boolean` | 에러 존재 여부 빠른 플래그. **셀 전용**(헤더엔 없음) |
+
+> **컬럼 헤더 툴팁**: `area: 'columnHeader'` 페이로드는 헤더 호버 시 발행됩니다(셀 전용 필드 `rowId`/`value`/`errors`/`hasError`는 비어 있음). `tooltipText`가 있으면(= `ColumnDef.headerTooltip`/`cellTooltip` 지정) 내장 툴팁·커스텀 렌더러 모두 `formattedValue` 대신 이 문구를 표시하며, overflow 여부와 무관하게 항상 표시합니다. (발행 자체는 `tooltipMode !== 'none'` 필요.)
+
+**tooltipMode 옵션** (PureSheetConfig)
+
+| 값 | 설명 |
+|---|---|
+| `'none'` (default) | 이벤트 발행 안 함 |
+| `'overflow'` | 셀 내용이 잘리는 경우에만 |
+| `'always'` | 모든 셀 호버마다 |
+
+커스텀 툴팁 구현 시 `errors` 필드로 바로 에러 메시지를 렌더링할 수 있습니다:
+
+```js
+grid.on('cell:tooltip', ({ element, cellRect, value, errors, hasError }) => {
+  if (hasError) {
+    showCustomTooltip(element, cellRect, {
+      type: 'error',
+      lines: errors,
+    });
+  } else {
+    showCustomTooltip(element, cellRect, { text: String(value) });
+  }
+});
+```
+
+**컬럼별 커스텀 툴팁 문구** — `ColumnDef.headerTooltip`(헤더, 고정 문자열)과 `cellTooltip`(셀, 행별 동적 함수)을 컬럼 정의에 지정하면 `payload.tooltipText`로 전달돼 내장 툴팁·커스텀 렌더러 모두 라벨/값 대신 이 문구를 표시합니다(overflow 무관 항상 표시, `tooltipMode !== 'none'` 필요). `cellTooltip`은 **hover 시점에만** 호출되어(렌더/스크롤 시 전 셀 호출 아님) 대용량에서도 성능 부담이 없습니다.
+
+```js
+{
+  fields: [
+    {
+      id: 'salary', header: '급여', dataType: 'number',
+      headerTooltip: '세전 월 급여 기준',                          // 헤더 hover 시
+      cellTooltip: ({ value, row }) => `${row.name}: ${value}원`,  // 셀 hover 시 (행별)
+    },
+  ],
+  tooltipMode: 'always', // 또는 'overflow' — 'none' 이면 툴팁 이벤트 자체가 발행 안 됨
+}
+```
+
+#### 선택
+
+| 이벤트 | 페이로드 | 설명 |
+|--------|---------|------|
+| `selection:changed` | `{ selectedRows, selectedCells }` | 선택 변경 |
+
+#### 컬럼
+
+| 이벤트 | 페이로드 | 설명 |
+|--------|---------|------|
+| `column:resize` | `{ columnId, width }` | 컬럼 너비 변경 |
+| `column:reorder` | `{ order, source, sourceId? }` | 컬럼 순서 변경 (`source`: `'order'` \| `'column'` \| `'group'` \| `'groupOrder'`) |
+| `column:pin` | `{ columnId, position }` | 컬럼 고정 변경 |
+| `column:visibility` | `{ columnId, visible }` | 컬럼 가시성 변경 |
+| `column:update` | `{ columnId, changedKeys: string[] }` | `columns.update()` 호출 — `changedKeys` 는 사용자가 넘긴 partial 의 키 목록 |
+| `column:reset` | `{ columnId: string \| null }` | `columns.reset(id)` 또는 `resetAll()` (resetAll 시 `columnId: null`) |
+
+#### 정렬/필터
+
+| 이벤트 | 페이로드 | 설명 |
+|--------|---------|------|
+| `sort:changed` | `{ sorts }` | 정렬 상태 변경 |
+| `filter:changed` | `{ filters }` | 필터 상태 변경 |
+| `header:click` | `{ columnId, event, nodeId? }` | 헤더 **셀 본체**(텍스트/여백) 클릭. `event`는 원본 DOM `MouseEvent` — 소비처가 `event.shiftKey` / `ctrlKey` / `altKey` / `metaKey` 모디파이어를 직접 읽음. **core는 이 이벤트만 발행하고 자동 정렬하지 않음** — 정렬은 소비처가 `grid.toggleSort(columnId, { additive: event.shiftKey })`를 호출해 처리 |
+| `header:sortClick` | `{ columnId, event, element }` | 헤더 **정렬 아이콘**(`.ps-sort-icon`) 클릭 (ITSM-2026-002185). `element`는 아이콘 DOM — 팝오버 앵커로 씀 |
+| `header:filterClick` | `{ columnId, event, element }` | 헤더 **필터 아이콘**(`.ps-filter-icon`) 클릭 (ITSM-2026-002185). `element`는 아이콘 DOM — 값 목록/조건식 팝오버 앵커로 씀 |
+
+> **헤더 아이콘 클릭은 셀 본체 클릭과 분리됩니다 (ITSM-2026-002185).** 아이콘 클릭은 `HeaderCell` 에서 `stopPropagation` 되므로 `header:click` 과 **동시에 발생하지 않습니다**. 세 이벤트는 배타적이며, 소비처(wrapper)는 각각을 정렬 토글 / 정렬 패널 / 필터 팝오버로 배선합니다.
+>
+> ⚠️ 필드에 `showFilterIcon: false` 를 주면 아이콘 span 자체가 생성되지 않으므로 그 컬럼에서는 `header:filterClick` 이 **발생하지 않습니다**(→ [FieldDef 정렬/필터](#정렬필터)).
+
+#### 스크롤
+
+| 이벤트 | 페이로드 | 설명 |
+|--------|---------|------|
+| `scroll` | `ScrollPayload` | 세로 range 변경 시 발행. `scrollTop`, `scrollLeft`, `startIndex`, `endIndex`, `viewportHeight`, `contentHeight`, `maxScrollTop`, `totalRows`/`rowCount`, `isAtEnd` 포함 |
+| `scroll:endReached` | `ScrollEndReachedPayload` | 끝(또는 `endReachedThresholdRows` 이내) 도달 시 데이터셋 경계별 1회 발행. `boundaryRowCount`는 append로 행 수가 증가하면 재발화 가능한 새 경계를 나타냄 |
+
+> **동작 변경 (정렬 정책 이관).** 이전에는 헤더 클릭 시 core가 자동으로 정렬을 토글했지만, 이제 core는 `header:click`만 발행합니다. "헤더 클릭 = 정렬"이 자동으로 동작하던 통합 코드는 `header:click`을 구독해 [`toggleSort()`](#puresheet-최상위-api)를 직접 호출하도록 변경해야 합니다.
+>
+> **헤더 필터 인디케이터.** 활성 필터가 걸린 컬럼의 헤더에는 필터 아이콘이 표시됩니다(필터 상태가 정렬 화살표 동기화와 동일한 패턴으로 헤더에 동기화됨).
+
+#### Undo/Redo
+
+| 이벤트 | 페이로드 | 설명 |
+|--------|---------|------|
+| `undo:stateChange` | UndoStack 상태 | Undo/Redo **버튼 활성화** 상태 변경 (`canUndo`/`canRedo`) |
+| `changes:undone` | `ChangesUndoneEvent` (아래 참조) | Undo 완료 — 되돌린 변경의 구조화 payload (`direction: 'undo'`) |
+| `changes:redone` | `ChangesRedoneEvent` (아래 참조) | Redo 완료 — 다시 적용한 변경의 구조화 payload (`direction: 'redo'`) |
+
+> **`row:reordered`만 구독하면 undo/redo 시 백엔드와 어긋납니다.** `row:reordered`는 사용자의 정방향 드래그에서만 발화하고, 이후 Ctrl+Z(undo)/Ctrl+Y(redo)로 상태가 되돌아가도 **재발화하지 않습니다**. 서버 상태를 그리드와 동기화하려면 `changes:undone` / `changes:redone`을 함께 구독하세요 (ADR-115).
+
+**`ChangesUndoneEvent` / `ChangesRedoneEvent` payload** (공통 베이스 `UndoRedoEventBase`)
+
+| 필드 | 타입 | 설명 |
+|------|------|------|
+| `direction` | `'undo' \| 'redo'` | 이벤트가 undo 완료인지 redo 완료인지. 하나의 공통 핸들러로 두 이벤트를 처리 가능 |
+| `commandType` | `CommandType` | 처리된 command 타입 (`command.type`) |
+| `description` | `string` | command 설명 (로그/디버깅용) |
+| `canUndo` | `boolean` | 발화 시점의 undo 가능 여부 |
+| `canRedo` | `boolean` | 발화 시점의 redo 가능 여부 |
+| `change` | `UndoRedoChange` | 구조화된 변경 내역 (discriminated union, `kind` discriminator) |
+
+**`change.kind`별 variant**
+
+| `kind` | 발생 command | 주요 필드 |
+|--------|-------------|----------|
+| `'cell-edit'` | `updateCell` | `rowId`, `field`, `oldValue`, `newValue` |
+| `'flat-move'` | `reorderRow` | `rowId`, `beforeRowId`, `previousBeforeRowId`, `finalBeforeRowId` (방향별 최종 anchor, `null`=맨 끝) |
+| `'tree-reorder'` | `treeReorderRow` | `patches`(원본 `TreeMovePatch[]`, old/new 양쪽 포함), `siblingsAfterFinal`(방향별 최종 sibling 순서), `dropMode` |
+| `'add-row'` | `addRow` | `rowId`, `rowData`, `index`. undo=제거, redo=추가 |
+| `'delete-row'` | `deleteRow` | `rowId`, `rowData`, `index`. undo=복원, redo=삭제 |
+| `'undelete-row'` | `undeleteRow` | `rowId`, `rowData`, `index`. `delete-row`의 방향 반대 |
+| `'discard-row'` | `discardRow` | `rowId`, `wasAdded`/`wasModified`/`wasDeleted`, `restoredData`(undo 복원 스냅샷, 없으면 `null`) |
+| `'batch'` | `batch` | `children: UndoRedoChange[]` (flatten 없음 — `length===1`이어도 유지). **이미 direction-ordered**(undo면 내부에서 reverse 완료)이므로 **순차 적용, 재-reverse 금지** |
+
+> **direction별 "현재 값" 해석.** `patches` swap이 없으므로(old/new 양쪽 포함) 소비처가 `direction`으로 선택합니다. `cell-edit`: undo→`oldValue`, redo→`newValue`. `tree-reorder`: undo→`patch.oldParentId`, redo→`patch.newParentId`. `siblingsAfterFinal` / `finalBeforeRowId`는 방향 분기 없이 곧바로 쓸 수 있게 **이미 방향별 최종값**으로 계산되어 담깁니다.
+>
+> `describeChange`를 구현하지 않은 command는 `changes:undone`/`changes:redone`을 **발화하지 않습니다** (`change`가 non-null 계약).
+>
+> **⚠️ 실질 변경(tree/flat reorder 등)은 거의 항상 `kind: 'batch'`로 래핑되어 옵니다.** `TreeReorderCoordinator`가 항상 batch로 감싸고 mutator가 추가 cell-edit(`updatedAt` 등)까지 넣기 때문입니다. `e.change.kind === 'tree-reorder'`처럼 **직접 비교하면 대부분 no-op**(조용한 실패)이 됩니다. 반드시 `@solasheet/core`의 `iterateLeafChanges(e.change)` / `findAllChangesByKind(e.change, kind)` / `findChangeByKind(e.change, kind)`로 batch를 평탄화한 뒤 분기하세요. 같은 kind가 여러 개 담길 수 있으므로(여러 tree-reorder + cell-edit) 하나만 필요한 게 아니면 `findAllChangesByKind`로 전부 수집해 유실을 막습니다.
+>
+> **⚠️ `batch.children`은 이미 direction-ordered입니다.** `BatchCommand.describeChange`가 undo 방향일 때 내부에서 이미 역순 정렬을 마칩니다. 소비처가 undo에서 다시 역순으로 순회하면 **이중 reverse**가 되어 순서가 깨집니다. 헬퍼가 방출한 순서를 **그대로 순차(pre-order) 적용**하세요.
+
+```js
+// row:reordered(정방향) + changes:undone + changes:redone 3종 구독 = 완전한 백엔드 동기화
+import { iterateLeafChanges } from '@solasheet/core';
+
+// leaf(=batch 아님) 단위 분기. batch/nested-batch는 헬퍼가 평탄화한다.
+function syncLeaf(change, direction) {
+  switch (change.kind) {
+    case 'cell-edit':
+      if (change.field === 'order') break; // order는 siblingsAfterFinal 파생 → skip
+      api.patch(change.rowId, {
+        [change.field]: direction === 'undo' ? change.oldValue : change.newValue,
+      });
+      break;
+    case 'flat-move':
+      api.moveRow(change.rowId, { before: change.finalBeforeRowId });
+      break;
+    case 'tree-reorder':
+      for (const p of change.patches) {
+        api.setParent(p.rowId, direction === 'undo' ? p.oldParentId : p.newParentId);
+      }
+      for (const [parentId, order] of change.siblingsAfterFinal) {
+        api.reorderChildren(parentId, order); // 이미 방향별 최종 순서 (order의 canonical)
+      }
+      break;
+    case 'add-row':
+      direction === 'undo'
+        ? api.deleteRow(change.rowId)
+        : api.insertRow(change.rowData, change.index);
+      break;
+    case 'delete-row':
+      direction === 'undo' ? api.undeleteRow(change.rowId) : api.deleteRow(change.rowId);
+      break;
+    case 'undelete-row':
+      direction === 'undo' ? api.deleteRow(change.rowId) : api.undeleteRow(change.rowId);
+      break;
+    case 'discard-row':
+      if (direction === 'undo' && change.restoredData) api.upsert(change.rowId, change.restoredData);
+      break;
+    // 'batch'는 여기 오지 않는다 — iterateLeafChanges가 이미 평탄화했다.
+  }
+}
+
+// ⚠️ children은 이미 direction-ordered → 헬퍼가 방출한 순서 그대로 순차 적용. 재-reverse 금지.
+function syncChange(rootChange, direction) {
+  for (const leaf of iterateLeafChanges(rootChange)) syncLeaf(leaf, direction);
+}
+grid.on('changes:undone', (e) => syncChange(e.change, 'undo'));
+grid.on('changes:redone', (e) => syncChange(e.change, 'redo'));
+```
+
+#### 클립보드
+
+| 이벤트 | 페이로드 | 설명 |
+|--------|---------|------|
+| `clipboard:copy` | `{ text, rowCount, colCount }` | 복사 |
+| `clipboard:paste` | `{ cellCount }` | 붙여넣기 |
+
+#### 그룹 (로우 그룹)
+
+> 로우 그룹 토글 이벤트는 헤더 클릭(`source: 'user'`)과 프로그래매틱 API(`grid.rowGroup.*`, `source: 'api'`) 모두에서 발화됩니다. 프로그래매틱 호출이 다시 이벤트를 발생시키므로, 핸들러 안에서 재진입 무한루프를 막으려면 `if (e.source === 'api') return;`를 사용하세요.
+> **참고**: `grid.rowGroup.expandToLevel`/`collapseToLevel`(레벨까지 누적)은 `rowGroup:batchToggle`을 `scope:'toLevel'`로 발화합니다. (`expandAtLevel`/`collapseAtLevel`은 `scope:'level'`, `expandAll`/`collapseAll`은 `scope:'all'`.)
+
+| 이벤트 | 페이로드 | 설명 |
+|--------|---------|------|
+| `rowGroup:toggle` | `{ groupId, collapsed, source }` | 단일 로우 그룹 토글. 헤더 클릭 또는 `grid.rowGroup.toggle/expand/collapse`. `source`=`'user'`(클릭)/`'api'`(프로그래매틱) |
+| `rowGroup:batchToggle` | `{ scope, collapsed, groupIds, level?, source }` | 여러 그룹 일괄 토글. 영향 그룹이 N개여도 **이벤트 1회로 요약 통지**(`groupIds`에 화면 밖 포함 전체 그룹 ID). `scope`로 구분: `'level'`(같은 depth 일괄 — Ctrl/Cmd+클릭 또는 `grid.rowGroup.expandAtLevel/collapseAtLevel`, `level` 포함), `'toLevel'`(특정 depth까지 누적 — `grid.rowGroup.expandToLevel/collapseToLevel`, `level` 포함), `'all'`(전체 — `grid.rowGroup.expandAll/collapseAll`, `level` undefined). `source`=`'user'`/`'api'` |
+| `rowGroup:checkbox` | `{ groupId, columnId, checked, memberCount }` | 그룹 체크박스 cascade — 그룹 헤더 체크박스로 하위 멤버 전체를 일괄 토글. `memberCount`=영향받은 데이터 행 수. (구 `group:checkbox`에서 리네임) |
+
+#### 검증
+
+| 이벤트 | 페이로드 | 설명 |
+|--------|---------|------|
+| `validation:changed` | 검증 에러 정보 | 검증 상태 변경 |
+
+#### 컬럼 그룹
+
+| 이벤트 | 페이로드 | 설명 |
+|--------|---------|------|
+| `columnGroup:toggle` | `{ groupId, collapsed, source? }` | 컬럼 그룹 토글 (구 `headerGroup:toggle`). 헤더 클릭 시 `source: 'user'` 포함, `grid.headers`의 프로그래매틱 토글 시엔 `source` 없음(`{ groupId, collapsed }`) |
+
+#### 스크롤
+
+| 이벤트 | 페이로드 | 설명 |
+|--------|---------|------|
+| `scroll` | `{ scrollTop, scrollLeft }` | (예약) 현재 코드 경로에서는 발행되지 않음. 스크롤 상태는 `grid.select(s => s.scrollTop / visibleStartIndex / visibleEndIndex)`로 구독하세요 |
+
+#### 검색 / 구조 변경
+
+| 이벤트 | 페이로드 | 설명 |
+|--------|---------|------|
+| `search:highlighted` | `{ keyword }` | 검색 매칭 셀 하이라이트가 갱신됨 (검색 실행/이동/취소 시 모두 발행). 빈 `keyword`는 해제 의미 |
+| `view:structureChanged` | `{ reason: 'sort' \| 'filter' \| 'group' \| 'hide' \| 'pin' \| 'expand' \| 'pivot-collapse' \| string }` | 뷰 구조가 변경됨 — 외부 의존 레이아웃(예: 별도 차트)의 재계산 트리거. `'pivot-collapse'`는 피벗 행/열 collapse·expand 시 발화 |
+
+#### 컨텍스트 메뉴
+
+| 이벤트 | 페이로드 | 설명 |
+|--------|---------|------|
+| `contextmenu` | `{ area, rowIndex?, dataIndex?, rowId?, columnId?, value?, rowData?, selectedRowIds, selectedCells, selectedPinnedCells, originalEvent }` | 우클릭 메뉴. `area`: `'cell' \| 'header' \| 'rowHeader' \| 'empty'`. `rowData`는 cell/rowHeader에서, `selectedPinnedCells`는 pinned 영역 좌표 |
+
+---
+
+## 타입 정의
+
+### ColumnGroupDef
+
+> 여러 컬럼을 하나의 상위 헤더로 묶는 **다단계 컬럼 헤더(밴딩)** 정의. flat 모드 `columnGroups` 및 `grid.headers.setColumnGroups(defs)`에 사용. (구 명칭 `HeaderGroupDef`.)
+
+```typescript
+interface ColumnGroupDef {
+  id: string;                    // 그룹 고유 ID
+  header: string;                // 헤더에 표시할 이름
+  collapsible?: boolean;         // 접기/펼치기 가능 여부 (기본: false)
+  collapseTo?: string;           // 접혔을 때 보이는 대표 컬럼 ID (미지정 시 첫 번째 리프)
+  collapsed?: boolean;           // 초기 접힘 상태 (기본: false)
+  lockToGroup?: boolean;         // 자식 컬럼을 그룹에 잠금 (기본: true)
+                                 //   true: 자식 컬럼이 그룹 밖으로 드래그 이동 불가
+                                 //   false: 그룹 경계를 넘어 자유롭게 이동 가능
+  children: (string | ColumnGroupDef)[];  // 하위 자식 (필드 ID 또는 하위 그룹)
+  headerAttributes?: CellAttributes;       // 컬럼 그룹 헤더 셀 HTML 속성 (class, style 등)
+}
+```
+
+### TreeConfig
+
+```typescript
+interface TreeConfig {
+  idField?: string;           // 노드 ID 필드 (기본: 'id')
+  parentField?: string;       // 부모 ID 필드 (기본: 'parentId')
+  childrenField?: string;     // 자식 배열 필드 (중첩 구조용)
+  treeColumn?: string;        // 트리 아이콘 표시 컬럼 (기본: 첫 컬럼)
+  defaultCollapsed?: boolean; // 기본 접힘 상태
+  defaultExpandLevel?: number; // 기본 확장 레벨 (0=루트만, Infinity=전체)
+  aggregates?: Record<string, AggregateFn>; // 집계 설정
+  lazyLoad?: boolean;         // 서버 lazy loading
+  fetchChildren?: (nodeId: string | number) => Promise<Row[]>; // 자식 fetch 함수
+}
+```
+
+### MasterDetailConfig
+
+```typescript
+interface MasterDetailConfig {
+  renderer: (
+    container: HTMLElement,
+    parentData: Row,
+    dataIndex: number,
+  ) => (() => void) | void;                  // 디테일 렌더러 (cleanup 반환 가능)
+  minHeight?: number;                         // 최소 높이 (기본: 100)
+  maxHeight?: number;                         // 최대 높이
+  singleExpand?: boolean;                     // 단일 확장 모드 (기본: false)
+  keepExpandedOnDataChange?: boolean;         // 데이터 변경 시 확장 유지 (기본: false)
+  isExpandable?: (data: Row, dataIndex: number) => boolean; // 확장 가능 조건
+  expandColumn?: string;                      // 확장 아이콘 컬럼 (기본: 첫 컬럼)
+  keepMasterDetailRows?: boolean;             // DOM 캐시 유지 (기본: true)
+  keepMasterDetailRowsCount?: number;         // LRU 캐시 크기 (기본: 10)
+}
+```
+
+### GroupConfig
+
+초기 그리드 생성 시 `FlatModeConfig.rowGroup`으로 전달하는 가벼운 설정 (구 `group` 필드는 deprecated 별칭). *런타임*에는 `grid.rowGroup.setConfig()`로 더 풍부한 [GroupingConfig](#groupingconfig)를 사용합니다.
+
+```typescript
+interface GroupConfig {
+  /** 그룹핑 기준 컬럼 (계층 순서) */
+  columns: string[];
+  /** 소계 표시할 컬럼 ID 목록 — 각 컬럼의 FieldDef.aggregate 함수를 사용 */
+  subtotals?: string[];
+}
+```
+
+#### 그룹 행 rowHeader 체크박스
+
+`rowSelection.trigger === 'checkbox'` 와 함께 쓰면 그룹 행 rowHeader 에도 체크박스가 표시됩니다(기본 활성).
+옵션은 **`rowSelection.groupRowCheckbox`** 입니다 — 그룹핑 설정이 아니라 선택 동작의 확장이므로
+트리 모드의 `selectChildren` 과 같은 자리에 둡니다.
+
+| 멤버 선택 상태 | 그룹 체크박스 |
+|---|---|
+| 전부 선택됨 | `checked` |
+| 일부만 선택됨 | `indeterminate` |
+| 아무것도 선택 안 됨 | `unchecked` |
+
+클릭하면 그룹 멤버 전체를 선택/해제하며(다른 그룹의 선택은 보존), `rowGroup:checkbox` 이벤트가
+`columnId: '_rowHeader'` 로 발행됩니다.
+
+그룹 행 자체는 선택 집합에 들어가지 않습니다 — `getSelectedRowIds()` 에는 데이터 행 id 만 담기고,
+그룹 체크 표시는 멤버 선택으로부터의 **파생값**입니다(상태를 따로 저장하지 않으므로 행 재사용/스크롤
+후에도 어긋나지 않습니다).
+
+```typescript
+rowSelection: { mode: 'multi', trigger: 'checkbox', groupRowCheckbox: false }  // 끄면 그룹 행 rowHeader 가 비워짐
+```
+
+끄는 경우: 그룹 상태 판정이 그룹당 멤버 수에 비례하므로, 그룹 하나에 수만 행이 들어가는 초대용량
+화면에서 opt-out 용도로 씁니다(선택 Set 대조라 데이터 조회는 없습니다).
+
+⚠️ `rowHeader.cellRenderer` 로 커스텀 렌더러를 지정하면 이 기능은 비활성입니다 — 그 칸의 내용은
+소비처 소유이므로 그리드가 덮어쓰지 않습니다.
+
+### GroupingConfig
+
+`grid.rowGroup.setConfig(config)`로 런타임에 사용. 집계 함수와 기본 접힘 상태를 직접 지정할 수 있습니다.
+
+```typescript
+interface GroupingConfig {
+  /** 그룹화할 컬럼 키들 (계층 순서) */
+  columns: string[];
+  /** 집계 설정 (컬럼 키 → 집계 함수). AggregateFn은 문자열 또는 콜백 */
+  aggregates?: Record<string, AggregateFn>;
+  /** 기본 접힘 상태 */
+  defaultCollapsed?: boolean;
+}
+```
+
+### EditorConfig
+
+```typescript
+interface EditorConfig {
+  type: EditorType;
+  // 'text' | 'number' | 'date' | 'select' | 'checkbox'
+  // | 'dropdown' | 'datepicker' | 'multiselect' | 'custom'
+  options?: EditorOption[];    // dropdown/select 옵션
+  searchable?: boolean;        // 검색 활성화 (dropdown, multiselect)
+  placeholder?: string;        // placeholder 텍스트
+  dateFormat?: string;         // datepicker 포맷 (기본: 'yyyy-MM-dd')
+  separator?: string;          // multiselect 구분자 (기본: ',')
+  renderer?: (params: CustomEditorParams) => HTMLElement; // 커스텀 에디터 렌더러
+  getValue?: (el: HTMLElement) => CellValue;              // 커스텀 값 추출
+  destroy?: (el: HTMLElement) => void;                     // 커스텀 정리
+}
+```
+
+### MaskConfig
+
+5종 discriminated union. 공통 필드(`type`, `pattern`, `prefix?`, `suffix?`) + 타입별 추가 필드.
+
+```typescript
+type MaskConfig =
+  | NumericMaskConfig | StringMaskConfig | DateMaskConfig
+  | SecureMaskConfig  | FunctionMaskConfig;
+
+interface NumericMaskConfig {
+  type: 'numeric';
+  /** 0: 필수 숫자 / #: 선택 숫자 / ,: 천단위 / .: 소수점 */
+  pattern: string;
+  prefix?: string;
+  suffix?: string;
+}
+
+interface StringMaskConfig {
+  type: 'string';
+  /** 0: 필수 숫자 / A: 필수 문자 / *: 아무 문자 / 기타: 리터럴 (-, /, . 등) */
+  pattern: string;
+  prefix?: string;
+  suffix?: string;
+}
+
+interface DateMaskConfig {
+  type: 'date';
+  /** YYYY/YY (년) MM (월) DD (일) HH/hh (시) mm (분) ss (초) A (AM/PM) */
+  pattern: string;
+  prefix?: string;
+  suffix?: string;
+}
+
+interface SecureMaskConfig {
+  type: 'secure';
+  pattern: string;                 // StringMask와 같은 문법
+  /** 마스킹 문자 @default '*' */
+  maskChar?: string;
+  /** 앞에서 N자리 표시 */
+  visibleFirst?: number;
+  /** 뒤에서 N자리 표시 */
+  visibleLast?: number;
+  prefix?: string;
+  suffix?: string;
+}
+
+interface FunctionMaskConfig {
+  type: 'function';
+  /** 포맷 함수 — 추가 context(rowData, columnKey)는 피벗 등에서 자동 전달 */
+  formatter: (value: unknown, ...context: any[]) => string;
+  /** 역변환 함수 (스마트 필터링용, 선택) */
+  parser?: (displayValue: string) => unknown;
+}
+```
+
+```typescript
+// numeric — 1234.5 → "$1,234.50"
+{ type: 'numeric', pattern: '#,###.00', prefix: '$' }
+
+// string — "01012345678" → "010-1234-5678"
+{ type: 'string', pattern: '000-0000-0000' }
+
+// date — Date → "2024-01-15"
+{ type: 'date', pattern: 'YYYY-MM-DD' }
+
+// secure — "1234567890123456" → "1234-****-****-3456"
+{ type: 'secure', pattern: '0000-0000-0000-0000', visibleFirst: 4, visibleLast: 4 }
+
+// secure with custom mask char — "9501011234567" → "950101-#######"
+{ type: 'secure', pattern: '000000-0000000', visibleFirst: 6, maskChar: '#' }
+
+// function with parser — 1234567 ↔ "1,234,567원"
+{
+  type: 'function',
+  formatter: (v) => `${(v as number)?.toLocaleString()}원`,
+  parser: (str) => Number(str.replace(/[,원]/g, '')),
+}
+```
+
+### 피벗 필드 타입
+
+#### PivotRowField
+
+```typescript
+interface PivotRowField {
+  field: string;           // 원본 데이터 키 — 값을 **읽을** 때 쓴다
+  id?: string;             // 식별자 — 미지정 시 field. 이 필드를 **가리킬** 때 쓴다 (ITSM-2026-002188)
+  header?: string;         // 표시명
+  width?: number;          // 너비
+  minWidth?: number;
+  maxWidth?: number;
+  dataType?: 'string' | 'number' | 'date' | 'boolean'; // 데이터 타입
+  formula?: string | ((row: Record<string, unknown>) => unknown); // 계산된 그룹 축 (집계 전)
+  headerAttributes?: CellAttributes;
+  cellAttributes?: CellAttributes | CellAttributesFn;
+}
+// 참고: 피벗 정렬은 field-level 옵션이 아니라 viewState 단일 진입점(SSOT)으로 적용한다 —
+//   grid.sort([{ id: 'region', direction: 'asc', sequence: 1 }]). PivotRowField 에 sort/descending
+//   같은 필드를 넣어도 silently 무시된다.
+```
+
+#### PivotColumnField
+
+```typescript
+interface PivotColumnField {
+  field: string;
+  id?: string;             // 식별자 — 미지정 시 field
+  header?: string;
+  width?: number;
+  minWidth?: number;
+  maxWidth?: number;
+  dataType?: 'string' | 'number' | 'date' | 'boolean'; // 데이터 타입
+  formula?: string | ((row: Record<string, unknown>) => unknown); // 계산된 열 축 (집계 전)
+  headerAttributes?: CellAttributes;
+}
+// 참고: 열 축 정렬도 viewState 단일 진입점으로 — grid.sort([{ id, direction, sequence }]).
+//   PivotColumnField 에 sort/sortByValue 를 넣어도 무시된다.
+```
+
+> **`PivotFieldBase.id` — 값 필드 중복 시 필수 (ITSM-2026-002188)**
+> 플랫 그리드는 `FieldDef.id` 가 식별자인데 피벗은 `field` 가 그 역할을 겸해 왔습니다. 그런데 **같은 `field` 를 값 필드로 여러 번 넣을 수 있어서**(합계·평균 등) 식별자로서 깨집니다.
+>
+> `id` 는 **optional** 이며 미지정 시 `field` 로 읽힙니다 — 기존 설정은 그대로 동작합니다. 중복이 필요한 쪽에서만 불변 `id` 를 명시하세요. 자세한 규칙과 폴백 경고는 [컬럼 식별자 유틸](#컬럼-식별자-유틸--columnkeys) 참조.
+
+#### PivotValueField
+
+```typescript
+interface PivotValueField {
+  field: string;
+  id?: string;                     // 식별자 — 같은 field 를 여러 번 쓸 때 **반드시** 지정
+  header?: string;
+  width?: number;
+  minWidth?: number;
+  maxWidth?: number;
+  aggregate?: AggregateFunc;       // 집계 함수
+  dataType?: 'string' | 'number' | 'date' | 'boolean';
+  showValueAs?: ShowValueAs;       // 값 표시 변환
+  showOriginalValue?: boolean;     // 원본 값 병행 표시
+  recalculateShowValueAs?: boolean; // 행 sort/filter 시 재계산 여부 (미지정 시 메트릭별 default)
+  decimalFormat?: { places: number; mode?: 'round' | 'floor' | 'ceil' | 'truncate' };
+  /**
+   * showValueAs 변환값에도 컬럼의 `decimalFormat`을 강제 적용할지.
+   * 기본 `false` — percent/rank 등 파생 metric에는 메트릭별 default 소수점 자리수 사용
+   * (예: percent → 2자리). `true`이면 사용자 `decimalFormat`이 변환값에도 적용됨.
+   * 단위(unit)와 정밀도(precision)의 분리 정책. ADR-112 참조.
+   */
+  useColumnDecimalForShowValueAs?: boolean;
+  useThousandsSeparator?: boolean; // 천단위 구분자 (기본: true)
+  mask?: MaskConfig;
+  autoFit?: boolean;
+  align?: CellAlign;
+  cellAttributes?: CellAttributes | CellAttributesFn;
+  headerAttributes?: CellAttributes;
+}
+```
+
+#### ShowValueAs
+
+| 값 | 설명 |
+|----|------|
+| `'none'` | 원본 집계값 |
+| `'differenceFromPrevRow'` | 이전 행과의 차이 |
+| `'percentDifferenceFromPrevRow'` | 이전 행 대비 % 차이 |
+| `'differenceFromPrevCol'` | 이전 열과의 차이 |
+| `'percentDifferenceFromPrevCol'` | 이전 열 대비 % 차이 |
+| `'percentOfGrandTotal'` | 총합 대비 % |
+| `'percentOfRowTotal'` | 행 합계 대비 % |
+| `'percentOfColumnTotal'` | 열 합계 대비 % |
+| `'percentOfPrevRow'` | 이전 행 값 대비 % |
+| `'percentOfPrevCol'` | 이전 열 값 대비 % |
+| `'runningTotal'` | 누적합 |
+| `'percentOfRunningTotal'` | 누적합 대비 % |
+| `'percentOfParentRow'` | 부모 행 대비 % |
+| `'percentOfParentCol'` | 부모 열 대비 % |
+| `'rankAsc'` | 오름차순 순위 |
+| `'rankDesc'` | 내림차순 순위 |
+| `'index'` | 인덱스 계산 (cell × grand / (row × col)) |
+
+#### PivotConfig
+
+`PivotConfig`의 전체 속성은 [PivotModeConfig](#pivotmodeconfig) 및 [grid.pivot — 피벗 API](#gridpivot--피벗-api) 섹션을 참조하세요.
+
+주요 속성:
+
+| 속성 | 타입 | 설명 |
+|------|------|------|
+| `rowFields` | `PivotRowField[]` | 행 축 필드 (필수) |
+| `columnFields` | `PivotColumnField[]` | 열 축 필드 |
+| `valueFields` | `PivotValueField[]` | 값 필드 (필수) |
+| `showRowSubTotals` | `boolean` | 행 소계 표시 |
+| `showRowGrandTotals` | `boolean` | 행 총합계 표시 |
+| `showColumnSubTotals` | `boolean` | 열 소계 표시 |
+| `showColumnGrandTotals` | `boolean` | 열 총합계 표시 |
+| `rowSubTotalPosition` | `'before' \| 'after'` | 행 소계 위치 (기본: `'after'`) |
+| `rowGrandTotalPosition` | `'before' \| 'after'` | 행 총합계 위치 |
+| `columnSubTotalPosition` | `'before' \| 'after'` | 열 소계 위치 |
+| `columnGrandTotalPosition` | `'before' \| 'after'` | 열 총합계 위치 |
+| `filterFields` | `PivotFilterField[]` | 화이트리스트 사전 필터 — 행/열 축에 넣지 않고 소스를 축소 (`{ field, values }`) |
+| `trackSourceRows` | `boolean` | 드릴스루/원본 export 용 소스 행 추적 (opt-in, 기본 `false`). 값 필터의 소계/총합 재집계는 이 옵션과 무관하게 동작 |
+| `showZeros` | `boolean` | 값이 없는(null/undefined) 셀을 `0`으로 표시 (기본: `false`) |
+| `rowDisplayMode` | `'tabular' \| 'outline'` | 피벗 행 표시 모드 (기본: `'tabular'`) |
+| `outlineColumnWidth` | `number` | outline 모드의 단일 rowHeader 컬럼 너비 |
+| `outlineIndentSize` | `number` | outline 모드의 레벨당 들여쓰기 픽셀 (기본: 20) |
+| `rowCollapsible` | `boolean` | **행** 그룹 접기/펼치기 허용 여부 (기본: `true`). `false` 면 행 헤더 chevron 미표시 + 사용자 클릭/키보드 토글 무시. `PivotAPI.expandAllRows / collapseAllRows / collapseRow / expandRow` 등 프로그래매틱 호출은 옵션과 무관하게 작동 (사용자 클릭만 막는 의도) |
+| `columnCollapsible` | `boolean` | **열** 그룹 접기/펼치기 허용 여부 (기본: `true`). `false` 면 열 헤더 chevron 미표시 + 클릭 무반응. `expandAllColumns / collapseAllColumns` 등은 옵션과 무관하게 작동 |
+
+### 열거형/유니온 타입
+
+| 타입 | 값 |
+|------|-----|
+| `DataType` | `'string' \| 'number' \| 'boolean' \| 'date' \| 'array'` |
+| `AggregateFunc` | `'sum' \| 'avg' \| 'min' \| 'max' \| 'count' \| 'countAll' \| 'first' \| 'last' \| 'range' \| 'stdev' \| 'stdevPop' \| 'variance' \| 'variancePop' \| 'countNumbers'` (FieldDef.aggregate / 피벗 valueField에서 사용). `count`=컬럼 non-null 값 수, `countAll`=그룹 전체 행 수(null 포함), `countNumbers`=숫자 타입 값 수 |
+| `AggregateType` | `'sum' \| 'avg' \| 'count' \| 'countAll' \| 'min' \| 'max' \| 'first' \| 'last'` (그룹화/트리 aggregates에서 사용) |
+| `AggregateFn` | `AggregateType \| ((values: CellValue[]) => CellValue)` |
+| `ValidationTrigger` | `'input' \| 'change' \| 'blur' \| 'commit'` |
+| `FilterOperator` | `'eq' \| 'neq' \| 'gt' \| 'gte' \| 'lt' \| 'lte' \| 'contains' \| 'notContains' \| 'startsWith' \| 'endsWith' \| 'between' \| 'isNull' \| 'isNotNull' \| 'arrayContains' \| 'arrayNotContains' \| 'arrayContainsAny' \| 'arrayContainsAll' \| 'in' \| 'notIn' \| 'formula' \| 'custom'` |
+| `ComparisonFilterOperator` | `FilterOperator` 에서 `'in'`/`'notIn'`/`'formula'`/`'custom'` 을 뺀 것 — 스칼라 `filterValue` 를 쓰는 연산자 집합 (→ [SortState / FilterState](#sortstate--filterstate)) |
+| `FilterGroupType` | `'conditional' \| 'values' \| 'formula'` |
+| `ValueListMode` | `'exclude' \| 'include'` — 값 목록의 저장 방향 (기본 `'exclude'`) |
+| `RowVariant` | `'data' \| 'group-row' \| 'subtotal' \| 'grandtotal' \| 'filter' \| 'masterDetail' \| 'custom'` |
+| `RowSelectionMode` | `'none' \| 'single' \| 'multi'` |
+| `CellSelectionMode` | `'none' \| 'single' \| 'range'` |
+| `RowSelectionTrigger` | `'cellClick' \| 'rowHeader' \| 'checkbox' \| ReadonlyArray<'rowHeader' \| 'checkbox'>` |
+| `Theme` | `'light' \| 'dark' \| 'auto' \| 'excel' \| 'sheets' \| 'material' \| (string & {})` |
+| `CellAlign` | `'left' \| 'center' \| 'right'` |
+| `PinPosition` | `'left' \| 'right' \| 'none'` |
+| `RowState` | `'pristine' \| 'added' \| 'modified' \| 'deleted'` |
+| `CellState` | `'pristine' \| 'modified'` |
+| `EditorType` | `'text' \| 'number' \| 'date' \| 'select' \| 'checkbox' \| 'dropdown' \| 'datepicker' \| 'multiselect' \| 'custom'` |
+| `EngineType` | `'native'` — **`'aq'`(Arquero)는 제거됨.** 단일 엔진화로 유니온에 값이 하나만 남았습니다(ITSM-2026-002190) |
+| `TotalPosition` | `'before' \| 'after'` |
+
+> **`AggregateFunc` vs `AggregateFn` 구분**: `AggregateFunc`는 FieldDef/PivotValueField에서 사용하는 **문자열 enum**(14종). `AggregateFn`은 GroupingConfig/TreeConfig의 `aggregates` 맵에서 사용하며 **문자열 + 콜백** 모두 허용 (8종 enum + 커스텀 함수).
+
+---
+
+## 공용/내부 타입 레퍼런스
+
+위 섹션들에서 시그니처로 등장하는 모든 보조 타입의 정의입니다.
+
+### 데이터 기본 타입
+
+#### CellValue
+
+```typescript
+type CellValue = string | number | boolean | Date | null | undefined | CellValue[];
+```
+
+#### Row / RowData
+
+```typescript
+interface Row {
+  [columnId: string]: CellValue;
+  /** 내부 예약 필드 — PureSheet가 자동 관리, 사용자 수정 금지 (ADR-105) */
+  __psRowId?: string | number;
+}
+type RowData = Row;
+```
+
+#### ColumnDef
+
+```typescript
+interface ColumnDef {
+  id: string;
+  label?: string;                 // 헤더 표시명 (FieldDef.header와 동일 역할)
+  type?: 'string' | 'number' | 'boolean' | 'date' | 'array';
+  width?: number;
+  minWidth?: number;
+  maxWidth?: number;
+  flex?: number;
+  hidden?: boolean;
+  lockVisible?: boolean;          // 가시성 하드 잠금 (UI/API 모두 거부)
+  pinned?: 'left' | 'right';
+  sortable?: boolean;
+  filterable?: boolean;
+  align?: CellAlign;
+  // ... FieldDef와 거의 동일 (FieldDef는 사용자 입력용, ColumnDef는 정규화된 내부 형태)
+}
+```
+
+> 사용자 코드에선 보통 `FieldDef`만 작성합니다. `ColumnDef`는 내부 정규화 타입이며, **`grid.columns.*` get류 API 의 반환은 `ColumnInfo`** (ColumnDef + ColumnState 합본) 입니다.
+
+#### ColumnState
+
+```typescript
+interface ColumnState {
+  id: string;
+  width: number;
+  pinned: 'left' | 'right' | 'none';
+  visible: boolean;
+  order: number;
+  offset?: number;
+  autoFit?: boolean;
+  renderedWidth?: number;   // 디바이스 픽셀 보정된 렌더링 너비
+  renderedLeft?: number;    // 섹션 내 누적 left 오프셋
+}
+```
+
+> `grid.select(s => s.columnStates)` 등 GridState 직접 구독 시에만 노출됩니다. **`grid.columns.*` API 반환에선 `ColumnInfo` 로 합쳐져 나옵니다.**
+
+#### ColumnInfo
+
+`grid.columns.getById / getAll / getMap / getVisibleColumns / getState` 모두가 반환하는 **단일 통합 shape**. 정적 `ColumnDef` + 런타임 `ColumnState` 합본.
+
+```typescript
+interface ColumnInfo {
+  // ── 식별 ──
+  id: string;
+
+  // ── 데이터 타입 / 라벨 / 헤더 ──
+  type?: ColumnType;
+  label?: string;
+  /** def.header ?? def.label ?? def.id 로 합성 — 항상 비어있지 않음 */
+  header?: string;
+
+  // ── 크기 (state 우선) ──
+  width: number;
+  minWidth?: number;
+  maxWidth?: number;
+  flex?: number;
+  autoFit?: boolean;
+
+  // ── 가시성 / 순서 (state 우선) ──
+  visible: boolean;
+  /** !visible 로 파생 */
+  hidden: boolean;
+  order: number;
+  /** ColumnDef.lockVisible — true 면 표시/숨김 변경이 UI·API 모두 거부됨 */
+  lockVisible?: boolean;
+
+  // ── 고정 ──
+  /** state 우선 — 'left' | 'right' | 'none' */
+  pinned: 'left' | 'right' | 'none';
+  /** ColumnDef.frozen — pinned 의 alias */
+  frozen?: 'left' | 'right';
+
+  // ── 정렬 / 표시 형식 ──
+  align?: CellAlign;
+  mask?: MaskConfig;
+  decimalFormat?: DecimalFormat;
+  useThousandsSeparator?: boolean;
+
+  // ── 셀 / 헤더 렌더링 ──
+  cellRenderer?: CellRenderer;
+  cellAttributes?: CellAttributes | CellAttributesFn;
+  headerAttributes?: CellAttributes;
+  headerRenderer?: (params: { columnId: string; header: string }) => HTMLElement | string;
+
+  // ── 동작 플래그 ──
+  sortable?: boolean;
+  filterable?: boolean;
+  editable?: boolean;
+  readonly?: boolean;
+  editableWhen?: (params: { rowData; rowState; rowId }) => boolean;
+
+  // ── 수식 / 에디터 ──
+  formula?: string | ((row) => unknown);
+  editor?: EditorConfig;
+  editorResolver?: (params) => EditorConfig | null;
+
+  // ── 집계 / 병합 ──
+  aggregate?: AggregateFunc;
+  mergeStrategy?: 'same-value' | 'none';
+
+  // ── 유효성 ──
+  validation?: ValidationRule[];
+
+  // ── 피벗 전용 ──
+  pivotType?: 'data' | 'subtotal' | 'grandtotal';
+  structural?: boolean;
+  pivotValueField?: string;
+  pivotValueFieldConfig?: { ... };
+
+  // ── 런타임 전용 (가상화/렌더 내부) ──
+  offset?: number;
+  renderedWidth?: number;
+  renderedLeft?: number;
+}
+```
+
+**충돌 키 정책**: state(런타임)가 승.
+- `width` / `pinned` / `visible` / `autoFit` → 현재값 (state)
+- `hidden` → `!visible` 로 파생
+- `header` → `def.header ?? def.label ?? def.id` 로 fallback 합성 (항상 truthy)
+- `frozen` → ColumnDef 의 alias 그대로 노출 (정식 사용은 `pinned`)
+
+#### CellPosition
+
+```typescript
+interface CellPosition {
+  /** 행 인덱스 (뷰 기준 - 그룹 행 포함). pinned 셀은 -1 */
+  rowIndex: number;
+  columnId: string;
+  /** 실제 데이터 인덱스 (그룹 행 제외) */
+  dataIndex?: number;
+  rowId?: string | number;
+  /** pinned 셀일 때만 채워짐 */
+  pinnedPosition?: 'top' | 'bottom';
+  pinnedIndex?: number;
+}
+```
+
+#### SortState / FilterState
+
+```typescript
+interface SortState {
+  /** 컬럼 ID (피벗에선 행/열 필드 ID도 가능) */
+  id: string;
+  direction: 'asc' | 'desc';
+  /** 우선순위 (낮을수록 먼저 적용) */
+  sequence: number;
+  /** 피벗 전용: 값 필드 기준 정렬 (레이블 대신 집계 값 기준) */
+  byValue?: string;
+  /** 커스텀 정렬 키 함수 — 셀 값을 정렬 가능한 키로 변환 */
+  sortKey?: (value: CellValue) => number | string;
+  /**
+   * (피벗 전용) 정렬 적용 단계 override. 플랫 그리드에서는 무시.
+   * 생략(기본) = `'post'`: 피벗된 행/열을 재정렬 (집계값 불변 — 인터랙티브 정렬의 일반 케이스).
+   * `'pre'` = 소스 ORDER BY: 집계 **전** 원본을 정렬 (`first`/`last` 등 순서-민감 집계 결과를 결정할 때만, 니치).
+   */
+  mode?: 'pre' | 'post';
+}
+
+interface FilterStateBase {
+  /** 필터링할 컬럼 ID (플랫: 컬럼 ID, 피벗: 행/열 필드 ID) */
+  id: string;
+  /** 필터 우선순위 (낮을수록 먼저 적용) */
+  sequence: number;
+  /** 필터 간 논리 연산 (기본 'and') */
+  logical?: 'or' | 'and';
+  /**
+   * 이 필터가 속한 그룹 키 — 평탄화 시 자동 부착. **그룹 경계는 괄호다.**
+   * 같은 키끼리 먼저 접고 그룹 결과끼리 AND 로 합친다.
+   */
+  groupKey?: string;
+  /** 스마트 필터링용 mask (보통 컬럼의 mask가 자동 주입됨 — 직접 지정 불필요) */
+  mask?: MaskConfig;
+  /**
+   * (피벗 전용) 필터 적용 단계 override. 플랫 그리드에서는 무시.
+   * 생략(기본) = core 자동 분류: 행/열 필드(차원) 필터 → `'pre'`(소스 축소 후 재집계 = 소계/총합까지 반영),
+   * 값(measure) 필터 → `'post'`(피벗된 값 기준 행 필터 + 살아남은 source 로 소계/총합 재집계).
+   */
+  mode?: 'pre' | 'post';
+  /**
+   * (피벗 값 필터 전용) 조건을 만족하는 셀이 하나도 없는 리프 컬럼을 결과에서 제외 (기본 `false`).
+   */
+  excludeUnmatchedColumns?: boolean;
+}
+
+/** 값 하나를 비교 — 스칼라 filterValue */
+type ComparisonFilterOperator =
+  | 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte'
+  | 'contains' | 'notContains' | 'startsWith' | 'endsWith'
+  | 'between' | 'isNull' | 'isNotNull'
+  | 'arrayContains' | 'arrayNotContains' | 'arrayContainsAny' | 'arrayContainsAll';
+
+interface ComparisonFilterState extends FilterStateBase {
+  operator: ComparisonFilterOperator;
+  filterValue: CellValue;
+  filterValue2?: CellValue;   // between 전용
+}
+
+/** 값 집합(엑셀식 체크박스) — filterValue 는 **원본값 배열** */
+interface ValueSetFilterState extends FilterStateBase {
+  operator: 'in' | 'notIn';
+  filterValue: CellValue[];
+}
+
+/** 수식 — **행 전체**를 판정. id 는 관례상 '__formula__' */
+interface FormulaFilterState extends FilterStateBase {
+  operator: 'formula';
+  /** 문자열 식 (함수 아님 — Worker 복제 + 레이아웃 JSON 저장을 위해) */
+  expression: string;
+  filterValue?: null;
+}
+
+/** 사용자 술어 — 함수라 직렬화되지 않음(레이아웃 프리셋에 안 담김) */
+interface CustomFilterState extends FilterStateBase {
+  operator: 'custom';
+  predicate: (value: CellValue) => boolean;
+  filterValue?: CellValue;
+}
+
+/** `operator` 로 갈라지는 **판별 유니온** */
+type FilterState =
+  | ComparisonFilterState
+  | ValueSetFilterState
+  | FormulaFilterState
+  | CustomFilterState;
+```
+
+> **⚠️ `FilterState` 는 이제 판별 유니온입니다 (ITSM-2026-002188).** 단일 인터페이스로 두면 잘못된 조합이 타입을 통과한 뒤 런타임에서 **조용히 "필터 없음"** 이 됩니다(실측):
+> - `operator:'formula'` 인데 `expression` 없음 → 빈 식 → 전 행 통과
+> - `operator:'in'` 인데 `filterValue` 가 스칼라 → `Array.isArray` 실패 → 전 행 통과
+>
+> **직렬화 모양(JSON)은 바뀌지 않습니다** — 기존 저장본은 그대로 유효합니다. `if (f.operator === 'formula')` 안에서 `f.expression` 이 `string` 으로 좁혀집니다.
+>
+> 종류를 가리지 않고 필드를 읽어야 하는 곳(해시·직렬화)은 core 가 export 하는 `filterField(f, key)` 를 쓰세요.
+
+#### 필터 그룹 — FilterGroup / FilterGroupMap
+
+필터 상태를 **소스별로** 나눠 담는 구조입니다 (ITSM-2026-002182).
+
+```typescript
+type FilterGroupType = 'conditional' | 'values' | 'formula';
+
+interface FilterGroup {
+  /** 그룹 종류 — 소비처가 어떤 UI 로 편집할지 판단 */
+  type: FilterGroupType;
+  /** 적용 순서(작을수록 먼저). 그룹 간은 AND 라 결과는 순서와 무관하지만 쿼리 해시 안정성에 필요 */
+  priority: number;
+  /** false 면 상태는 남지만 필터링에 참여하지 않음(임시 끄기·편집 중 초안) */
+  applied: boolean;
+  /** 이 그룹이 소유한 필터들. 그룹 **안**에서는 각 항목의 `logical` 로 결합 */
+  states: FilterState[];
+}
+
+/** 소스 키 → 그룹. 키는 소비처가 임의로 정한다 (예: 'toolbar', 'headerPopover:amount') */
+type FilterGroupMap = Record<string, FilterGroup>;
+```
+
+**함께 export 되는 헬퍼**
+
+| Export | 설명 |
+|---|---|
+| `flattenFilterGroups(groups)` | 그룹 맵 → 엔진에 넘길 평면 `FilterState[]`. `applied:false` 제외, `priority` 오름차순, 각 그룹 첫 항목의 `logical` 을 `'and'` 로 강제, `groupKey` 부착 |
+| `toFilterGroupMap(filters, key?)` | 평면 배열 → 그룹 맵 (하위 호환 승격). 기본 키 `DEFAULT_FILTER_GROUP_KEY = 'default'` |
+| `isFilterGroupMap(value)` | 그룹 맵인지 판별(배열이면 옛 형태) |
+| `DEFAULT_FILTER_GROUP_KEY` | `'default'` |
+
+> **왜 그룹인가 (ITSM-2026-002182)**
+> 필터가 평면 배열 하나였을 때 컬럼 헤더 팝오버와 툴바 필터 창이 **같은 배열을 공유**했고, 각 UI 가 자기 것만 보여주려 배열을 슬라이싱하면서 다음이 반복해 깨졌습니다(모두 실측 버그): 값 목록에서 13개 고르면 조건식 창에 13줄 노출 / 팝오버를 열었다 닫는 것만으로 다른 UI 필터가 삭제 / 검색으로 좁힌 상태에서 해제하면 검색 밖 항목까지 해제.
+>
+> **그룹 간 결합은 AND 고정**입니다. OR 을 허용하면 그룹 경계를 넘는 결합이 생겨 "자기 그룹만 보면 안전하다"는 전제가 깨집니다(AG Grid 도 컬럼 필터끼리는 암묵적 AND). 컬럼 간 OR 이 필요하면 **수식 그룹**(`type: 'formula'`)이 담당합니다 — 식 안에서 괄호로 표현합니다.
+>
+> **`groupKey` 가 없으면 좌→우 fold 가 그룹을 넘나듭니다.** 실측: `dept=Sales` + `name∈{강호동,김태희}` 에서 `(dept=Sales AND name=강호동) OR name=김태희` 로 접혀 HR/김태희가 누출됐습니다. `groupKey` 가 있으면 `(dept=Sales) AND (name=강호동 OR name=김태희)` 로 올바르게 접힙니다.
+
+#### 수식 필터 — FormulaFilterState
+
+컬럼 간 비교·괄호·함수를 **식 하나**로 표현합니다 (ITSM-2026-002180). 문법은 **조건부 서식과 동일한 `FormulaEngine`** 을 공유합니다.
+
+```typescript
+await grid.filter([{
+  id: '__formula__', sequence: 0, operator: 'formula',
+  expression: '([급여] > 50000 AND [부서] == "Engineering") OR [도시] == "서울"',
+}]);
+```
+
+| Export | 설명 |
+|---|---|
+| `FORMULA_FILTER_OPERATOR` | `'formula'` |
+| `FORMULA_FILTER_ID` | `'__formula__'` — 수식 필터의 관례적 `id`(컬럼이 아니므로 엔진은 보지 않음) |
+| `evaluateFormulaFilter(row, expression, columns)` | 행 하나를 식으로 판정 |
+| `formulaFilterDependencies(expression)` | 식이 참조하는 컬럼 목록 |
+| `validateFilterFormula(expression)` | 유효성 검사 — 오류 문구 또는 `null` |
+| `clearFormulaFilterCache()` | 컴파일 캐시 비우기 |
+
+> **왜 평면 배열이 아니라 식인가** — 기존 `FilterState[]` 는 precedence 없는 좌→우 fold 라 괄호를 표현할 수 없어 `(A AND B) OR C` 와 `A AND (B OR C)` 를 구분하지 못합니다. 수식은 **식 하나가 필터 하나**라 fold 에 끼어들 여지가 없습니다.
+>
+> **왜 문자열인가** — `predicate`(함수)는 Worker 구조화 복제가 안 되고 레이아웃 JSON 으로 저장할 수 없습니다. 문자열이면 Worker 전송·`getConfig()` 저장·옛 버전 호환이 전부 됩니다.
+>
+> **성능** — 파싱은 **식당 1회**(컴파일 캐시). 실측(5M 행): 평면 fold 62ms / 수식(캐시) 94ms / 수식(행마다 파싱) 297ms ← 반드시 피해야 하는 경로.
+
+#### 레거시 조건식 → 수식 마이그레이션
+
+소유자 개념이 없던 시절의 조건식 저장본을 고급 필터 수식으로 옮깁니다 (ITSM-2026-002183). core 는 **변환 함수만** 제공하고, 언제 태울지는 wrapper 의 마이그레이션 스텝이 정합니다.
+
+| Export | 설명 |
+|---|---|
+| `conditionFiltersToFormula(filters)` | 조건식 배열 → 수식 문자열 (`ConditionFilterConversion`) |
+| `conditionFiltersToFormulaState(...)` | 조건식 배열 → `FormulaFilterState` |
+
+#### ChangesSummary
+
+`grid.changes.getAll()` 반환 타입:
+
+```typescript
+interface ChangesSummary {
+  added: AddedRow[];
+  modified: ModifiedRow[];
+  deleted: DeletedRow[];
+  /** 재정렬된 행 순서 (null이면 변경 없음) */
+  reorderedOrder?: (string | number)[] | null;
+}
+
+interface AddedRow {
+  rowId: string | number;
+  data: Row;
+  insertIndex: number;
+}
+
+interface ModifiedRow {
+  rowId: string | number;
+  originalData: Row;
+  currentData: Row;
+  changedFields: Map<string, ChangedField>;
+  sourceIndex?: number;
+}
+
+interface ChangedField {
+  originalValue: CellValue;
+  currentValue: CellValue;
+}
+
+interface DeletedRow {
+  rowId: string | number;
+  originalData: Row;
+  originalIndex: number;
+}
+```
+
+#### PerformanceTiming
+
+```typescript
+interface PerformanceTiming {
+  name: string;
+  duration: number;  // ms
+}
+```
+
+---
+
+### 데이터 로더 — LoaderConfig
+
+Web Worker에서 직접 데이터를 페칭하는 모듈을 지정합니다. 메인스레드 비경유로 UI 블로킹 없음.
+
+```typescript
+interface LoaderConfig {
+  /** DataLoader를 default export하는 ES 모듈 URL */
+  module: URL | string;
+  /** 초기 파라미터 (직렬화 가능한 plain object). 런타임에 grid.updateLoaderParams()로 갱신 */
+  params?: Record<string, unknown>;
+}
+```
+
+```typescript
+// my-loader.ts
+import { DataLoader } from '@vmscloud/moz-ui-grid-core';
+export default class MyLoader extends DataLoader {
+  async fetchData(): Promise<Row[]> {
+    const res = await fetch(`/api/data?token=${this.params.authToken}`);
+    return res.json();
+  }
+}
+
+// 그리드 생성
+new PureSheet(container, {
+  loader: {
+    module: new URL('./my-loader.ts', import.meta.url),
+    params: { authToken: 'abc' },
+  },
+  fields: [...],
+});
+```
+
+---
+
+### Drag-Drop — DragDropConfig (ADR-110)
+
+행 드래그 재정렬 + 크로스-그리드 드롭 + drop validator + dirty mutator를 단일 객체로.
+
+```typescript
+interface DragDropConfig {
+  /**
+   * 행 드래그 재정렬 활성화.
+   * **flat 모드에서 `dragDropConfig`를 제공하면 기본 `true`**(opt-out) — `dragDropConfig`의
+   * 존재 자체를 드래그 사용 의도로 간주한다. 내부 reorder를 끄려면 명시적으로 `false`
+   * (예: cross-grid 드롭만 쓰고 그리드 내부 순서 변경은 차단). @default true (dragDropConfig 제공 시)
+   */
+  reorderableRows?: boolean;
+  /** 드래그 핸들 컬럼 표시 (reorderableRows 활성 시). @default true */
+  showDragHandleColumn?: boolean;
+  /** reorder 드래그 시작 위치. 'row'면 행 본문 어디서나 (보통 showDragHandleColumn:false와 함께). @default 'handle' */
+  dragTrigger?: 'handle' | 'row';
+
+  /** Cross-grid 드래그 그룹 — 같은 값 그리드끼리 행 이동 가능 */
+  crossGridDragGroup?: string;
+  /** 행이 다른 그리드로 빠져나가기 직전. false 반환 시 거부 */
+  onRowDragOut?: (e: DragOutEvent) => boolean | Promise<boolean>;
+  /** 다른 그리드의 행이 들어오기 직전. false 반환 시 거부 */
+  onRowDragIn?: (e: DragInEvent) => boolean | Promise<boolean>;
+
+  /** Drop 가능 여부 검증 (mousemove마다 호출). string 반환 시 거부 + tooltip */
+  canDrop?: (e: CanDropEvent) => boolean | string;
+
+  /** 행 순서 필드 자동 관리 (flat reorder + tree reorder 모두 지원) */
+  rowOrderField?: RowOrderFieldConfig;
+  /** Dirty 작업 직후 행을 수정할 hook */
+  mutateOnDirty?: MutateOnDirty;
+
+  /**
+   * 트리 인식 드래그 reorder 옵션. `treeConfig` + `reorderableRows: true`일 때 자동 활성.
+   * `false`면 비활성(평탄 reorder 강제). 세부 필드는 grid.dragDrop API 섹션의 TreeReorderConfig 표 참조.
+   * @requires treeConfig
+   */
+  treeReorder?: false | TreeReorderConfig;
+}
+
+interface RowOrderFieldConfig {
+  /** 정렬 순서를 저장할 필드 (예: 'displayOrder') */
+  field: string;
+  /** 'dense'(0..N-1 연속) | 'sparse'(큰 간격, 1024 기본) @default 'dense' */
+  strategy?: 'dense' | 'sparse';
+  /** sparse 전용: 초기 간격 @default 1024 */
+  spacing?: number;
+  /** sparse 전용: 인접 gap이 이 값 이하면 rebalance 신호 @default 1 */
+  rebalanceThreshold?: number;
+}
+
+interface DragOutEvent { targetGrid: unknown; rowId: RowId; rowData: Row; }
+interface DragInEvent { sourceGrid: unknown; sourceRowId: RowId; rowData: Row; targetIndex: number; }
+interface CanDropEvent { sourceGrid: unknown; sourceRowIds: RowId[]; rowsData: Row[]; targetIndex: number; }
+
+type MutateContext =
+  | { type: 'add'; rowId: RowId }
+  | { type: 'update'; rowId: RowId; changedField: string; oldValue: unknown; newValue: unknown }
+  | {
+      type: 'reorder';        // flat 그리드 행 재정렬
+      rowId: RowId;
+      newIndex: number;
+      oldIndex: number;
+      isDirectlyMoved: boolean;
+      neighbors: { prev?: Row; next?: Row };
+    }
+  | {
+      type: 'tree-reorder';   // 트리 노드 재정렬 (드래그 또는 moveNode)
+      rowId: RowId;
+      oldParentId: RowId | null;
+      newParentId: RowId | null;
+      oldSiblingIndex: number;
+      newSiblingIndex: number;
+      isDirectlyMoved: boolean;              // 직접 이동한 promoted root면 true (밀려난 형제는 false)
+      neighbors: { prev?: Row; next?: Row };  // 같은 새 부모 안 인접 형제
+    };
+
+// rowOrderField(dense/sparse) 및 mutateOnDirty는 tree-reorder에서도 동작한다.
+// 직접 이동한 노드 + 같은 부모 안에서 sibling index가 바뀐 형제 모두에 호출된다 (자손 제외).
+
+/** 반환된 Partial<Row>가 dirty modified로 자동 적용. 동기 함수만 지원 (v1) */
+type MutateOnDirty = (row: Row, ctx: MutateContext) => Partial<Row> | void;
+```
+
+---
+
+### 셀 병합 — MergeConfig
+
+3가지 모드의 discriminated union.
+
+```typescript
+type MergeConfig = BuiltInMergeConfig | CustomMergeConfig;
+
+interface BuiltInMergeConfig {
+  /** 'content': 인접한 같은 값 / 'hierarchical': 상위 컬럼 범위 내에서만 하위도 병합 */
+  type: 'content' | 'hierarchical';
+  /** 병합 대상 컬럼 (순서대로 계층) */
+  columns: string[];
+  /** 'lazy'(동적 탐색) | 'eager'(사전 계산) @default 'lazy' */
+  strategy?: 'lazy' | 'eager';
+  /** Lazy 모드 최대 탐색 깊이 @default 500 */
+  maxSearchDepth?: number;
+}
+
+interface CustomMergeConfig {
+  type: 'custom';
+  columns: string[];
+  /** Worker 모드에서 getRowData 행 데이터 버퍼 범위 @default 500 */
+  maxSearchDepth?: number;
+  /** 셀별 병합 범위 콜백 (null 반환 = 병합 없음) */
+  getMergedRange?: (params: MergeRangeContext) => MergeRangeResult | null;
+  /** 배치 콜백 (여러 셀 한 번에) — getMergedRange보다 우선 */
+  getMergedRanges?: (contexts: MergeRangeContext[]) => (MergeRangeResult | null)[];
+}
+
+// 세로(행)/가로(컬럼) 탐색이 대칭으로 제공된다.
+//   세로: rowIndex / getRowData / totalRowCount
+//   가로: colIndex / columnsInOrder / totalColumnCount
+//   2D 공용: getCellValue(rowIndex, columnId)
+interface MergeRangeContext {
+  rowIndex: number;
+  /** 현재 컬럼의 렌더(가시) 순서 인덱스 — `rowIndex`의 가로 대칭. `columnsInOrder` 기준 */
+  colIndex: number;
+  columnId: string;
+  /** columns(설정) 배열 내 인덱스 (계층 레벨) */
+  columnLevel: number;
+  value: CellValue;
+  /** 인접 행 데이터 조회 (세로 경계 탐색용) */
+  getRowData: (index: number) => Row | null;
+  /** 임의 셀 값 조회 (2D 경계 탐색용) — `getRowData(rowIndex)?.[columnId]`와 동치 */
+  getCellValue: (rowIndex: number, columnId: string) => CellValue;
+  /** 렌더(가시) 순서의 전체 컬럼 ID 목록 (가로 경계 탐색용) */
+  columnsInOrder: readonly string[];
+  totalRowCount: number;
+  /** 전체(가시) 컬럼 수 — `totalRowCount`의 가로 대칭 (= columnsInOrder.length) */
+  totalColumnCount: number;
+  /** 이전 컬럼의 병합 범위 (계층적 커스텀용) */
+  parentRange?: { startRow: number; endRow: number };
+}
+
+// 2D 사각형(세로/가로 대칭 절대범위). startCol/endCol 생략 시 현재 컬럼만 → 세로 병합.
+interface MergeRangeResult {
+  startRow: number;        // inclusive
+  endRow: number;          // inclusive
+  startCol?: number;       // inclusive, 렌더 컬럼 인덱스. 생략 시 현재 컬럼(세로 전용)
+  endCol?: number;         // inclusive, 렌더 컬럼 인덱스. 생략 시 현재 컬럼
+}
+```
+
+> **세로 / 가로 / 2D 병합** — `startCol`/`endCol`을 **생략하면 세로 병합**(현재 컬럼만, 기존 `{ startRow, endRow }` 계약 그대로), **지정하면 가로/2D 병합**입니다. 컬럼 인덱스는 `columnsInOrder`(렌더/가시 순서) 기준이며, 가로 병합은 **같은 파티션(center/pinned) 내 연속 컬럼**만 시각적으로 올바릅니다. 영역 내 아무 셀에서 같은 사각형을 반환해도 전략이 anchor=`(startRow, startCol)`를 잡고 나머지를 숨김 처리합니다. `null` 또는 단일 셀(`startRow===endRow && startCol===endCol`)이면 병합 없음.
+
+> **Worker 모드 제약**: `type: 'custom'`은 함수 직렬화 불가로 worker에서 사용 불가. content/hierarchical만 worker 호환.
+
+---
+
+### 스트리밍 — StreamingOptions
+
+`grid.setStreamingOptions(opts)`로 설정.
+
+```typescript
+interface StreamingOptions {
+  /** 비동기 트랜잭션 배치 간격 (ms). @default 50 */
+  asyncTransactionWaitMillis?: number;
+  /** 셀 플래시 활성화. @default false */
+  enableCellFlash?: boolean;
+  /** 플래시 지속 시간 (ms). @default 500 */
+  cellFlashDuration?: number;
+  /** 페이드 지속 시간 (ms). @default 1000 */
+  cellFadeDuration?: number;
+}
+```
+
+---
+
+### 트랜잭션 — RowTransaction / TransactionOptions / TransactionResult
+
+`grid.applyTransaction(tx, options?)` / `applyTransactionAsync(tx, callback?)`에서 사용.
+
+```typescript
+interface RowTransaction {
+  add?: Row[];
+  /** 삭제할 행 ID 목록 */
+  remove?: (string | number)[];
+  /** 수정할 행 (keyFields로 식별 가능한 필드 필수 포함) */
+  update?: Row[];
+}
+
+interface TransactionOptions {
+  /** update 후 정렬 재적용 @default true (증분 연산) */
+  applySort?: boolean;
+  /** update 후 필터 재적용 @default true (증분 연산) */
+  applyFilter?: boolean;
+}
+
+interface TransactionResult {
+  addedCount: number;
+  removedCount: number;
+  updatedCount: number;
+}
+
+type TransactionCallback = (results: TransactionResult[]) => void;
+```
+
+```typescript
+// 동기 트랜잭션
+const result = await grid.applyTransaction({
+  add: [{ id: 'TSLA', price: 250 }],
+  remove: ['GOOG'],
+  update: [{ id: 'AAPL', price: 183 }],
+});
+console.log(result.addedCount, result.removedCount, result.updatedCount);
+
+// 비동기 큐잉 (고빈도 업데이트)
+grid.applyTransactionAsync(
+  { update: [{ id: 'AAPL', price: 184 }] },
+  (results) => console.log('batch flushed:', results),
+);
+await grid.flushAsyncTransactions();
+```
+
+---
+
+### Multi-Row 레이아웃 — RowTemplate
+
+한 데이터 행을 여러 시각 행으로 표시 (대시보드/카드 스타일).
+
+```typescript
+interface RowTemplate {
+  /** 한 데이터 행이 차지할 시각적 행 수 */
+  rowCount: number;
+  /** 각 행의 셀 배치 — layout[rowIdx][cellIdx] */
+  layout: RowTemplateCell[][];
+}
+
+interface RowTemplateCell {
+  /** 필드 ID */
+  id: string;
+  /** 가로 병합 */
+  colSpan?: number;
+  /** 세로 병합 */
+  rowSpan?: number;
+}
+```
+
+```typescript
+// 2-row 레이아웃: 첫 행은 name이 2칸 차지, 둘째 행은 description이 한 줄
+rowTemplate: {
+  rowCount: 2,
+  layout: [
+    [{ id: 'name', colSpan: 2 }, { id: 'status' }],
+    [{ id: 'description', colSpan: 3 }],
+  ],
+}
+```
+
+---
+
+### 구조적 행 — RowConfig
+
+`grid.rows.addPinnedTop(row | RowConfig)`, `addPinnedBottom`, 또는 `new Row(config)`에서 사용.
+
+```typescript
+interface RowConfig {
+  id?: string;
+  /** 구조적 행 여부 (선택/인덱스 제외) @default false */
+  structural?: boolean;
+  /** 행 변형 (렌더링 힌트) @default 'data' */
+  variant?: RowVariant;
+  /** 고정 위치 @default null */
+  pinned?: 'top' | 'bottom' | null;
+  /** 행 높이 (null이면 기본값) */
+  height?: number | null;
+  /** 행 데이터 (variant: 'data' / 'subtotal' 등) */
+  data?: Record<string, unknown>;
+  /** 그룹 정보 (variant: 'group-row' / 'subtotal') */
+  group?: GroupInfo;
+  /** 집계 설정 (variant: 'subtotal' / 'grandtotal') */
+  aggregates?: AggregateConfig[];
+  /** 커스텀 렌더러 (variant: 'custom') */
+  render?: (container: HTMLElement, context: RowRenderContext) => void;
+  /** 추가 CSS 클래스 */
+  className?: string;
+}
+```
+
+#### AggregateConfig
+
+`grid.rows.addGrandTotal(aggregates)` 등에서 사용.
+
+```typescript
+interface AggregateConfig {
+  /** 대상 컬럼 ID */
+  columnId: string;
+  /**
+   * 집계 함수. 14종 명명 함수(sum/avg/min/max/count/countAll/countNumbers/first/last/
+   * range/stdev/stdevPop/variance/variancePop) 또는 커스텀 콜백 — AggregateFunc 타입.
+   * 미지정 시 컬럼의 FieldDef.aggregate 사용, 그것도 없으면 'sum'
+   */
+  func?: AggregateFunc;
+  /** 표시 포맷터 */
+  formatter?: (value: CellValue) => string;
+  /** 라벨 (선택) */
+  label?: string;
+}
+```
+
+```typescript
+grid.rows.addGrandTotal([
+  { columnId: 'salary', formatter: v => '$' + v?.toLocaleString() },
+  { columnId: 'bonus' },                           // FieldDef.aggregate 사용
+  { columnId: 'score', func: 'avg' },              // 이 행에서만 avg
+]);
+```
+
+---
+
+### 검증 — ValidationRule / ValidationError
+
+```typescript
+interface ValidationRule {
+  /** 검사 실패 시 표시할 에러 메시지 */
+  message: string;
+  /** 검사 실행 시점 */
+  type: ValidationTrigger;  // 'input' | 'change' | 'blur' | 'commit'
+  /** 검사 함수: true면 유효, false면 에러 */
+  validator: (value: CellValue, rowData?: Record<string, CellValue>) => boolean;
+}
+
+interface ValidationError {
+  rowId: string | number;
+  field: string;
+  /** 동일 셀에서 여러 규칙이 실패하면 메시지가 누적 */
+  messages: string[];
+}
+```
+
+```typescript
+fields: [
+  {
+    id: 'email',
+    header: '이메일',
+    validation: [
+      { type: 'change', message: '필수', validator: v => v != null && v !== '' },
+      { type: 'commit', message: '이메일 형식 오류', validator: v => /^.+@.+\..+$/.test(String(v)) },
+    ],
+  },
+];
+```
+
+---
+
+### 셀 에디터 — EditorOption / CustomEditorParams
+
+```typescript
+interface EditorOption {
+  /** 실제 데이터 값 */
+  value: CellValue;
+  /** 표시할 라벨 */
+  label: string;
+}
+
+interface CustomEditorParams {
+  value: CellValue;
+  column: ColumnDef;
+  rowData: Record<string, unknown>;
+  /** 값을 확정하고 에디터 닫기 */
+  onCommit: (newValue: CellValue) => void;
+  /** 편집 취소하고 에디터 닫기 */
+  onCancel: () => void;
+}
+```
+
+```typescript
+// 드롭다운 (검색 가능)
+{
+  id: 'grade', editable: true,
+  editor: {
+    type: 'dropdown',
+    searchable: true,
+    options: [
+      { value: 'S', label: 'S 등급' },
+      { value: 'A', label: 'A 등급' },
+      { value: 'B', label: 'B 등급' },
+    ],
+  },
+}
+
+// 커스텀 에디터
+{
+  id: 'color', editable: true,
+  editor: {
+    type: 'custom',
+    renderer: (params: CustomEditorParams) => {
+      const input = document.createElement('input');
+      input.type = 'color';
+      input.value = String(params.value ?? '#000000');
+      input.addEventListener('change', () => params.onCommit(input.value));
+      input.addEventListener('blur', () => params.onCancel());
+      return input;
+    },
+    getValue: (el) => (el as HTMLInputElement).value,
+  },
+}
+```
+
+---
+
+### 셀 렌더러 (Lifecycle 포함)
+
+`FieldDef.cellRenderer`는 두 가지 시그니처를 지원하며 `function.length`로 자동 분기:
+
+```typescript
+interface CellRendererParams {
+  value: CellValue;
+  rowData: Record<string, unknown>;
+  columnId: string;
+  rowId?: string | number;
+  /**
+   * 행 선택 상태 — rowHeader 셀(`rowHeader.cellRenderer`) 렌더 시에만 채워짐. 일반 데이터 셀은 undefined.
+   * 렌더 시점 스냅샷이라 선택 "변경"만으로는 재렌더되지 않는다 — CSS(`.ps-row.ps-selected`) /
+   * `ps-row-header-checkbox-input` 클래스 / `repaintRows`로 반영.
+   */
+  selected?: boolean;
+}
+
+/** Simple (arity 1) — vanilla JS 사용자 */
+type SimpleCellRenderer = (params: CellRendererParams) => HTMLElement | string;
+
+/** Lifecycle (arity 2) — React/Vue 등 framework wrapper용 */
+type LifecycleCellRenderer = (
+  container: HTMLElement,
+  params: CellRendererParams,
+) => CellRendererInstance | void;
+
+interface CellRendererInstance {
+  /**
+   * 셀이 재사용되며 데이터가 바뀔 때 호출.
+   * - 반환 `false`: instance가 처리 못함 → 그리드가 destroy 후 re-mount
+   * - 반환 `void`/`true`: instance가 자체 갱신함
+   * 미정의 시: 첫 mount만 실행, 이후 framework reactivity에 위임.
+   */
+  update?: (params: CellRendererParams) => boolean | void;
+  /** 셀이 사라질 때 호출 — pool release / 컬럼 제거 / grid destroy 시 */
+  destroy?: () => void;
+}
+```
+
+```typescript
+// Simple 형태 — 매 렌더마다 새 요소 반환
+{ id: 'status', cellRenderer: ({ value }) => `<span class="badge-${value}">${value}</span>` }
+
+// Lifecycle 형태 — React adapter 예시
+{
+  id: 'chart',
+  cellRenderer: (container, params) => {
+    const root = createRoot(container);
+    root.render(<Chart data={params.value} />);
+    return {
+      update: (next) => root.render(<Chart data={next.value} />),
+      destroy: () => root.unmount(),
+    };
+  },
+}
+```
+
+---
+
+### 설정 스냅샷 — GridConfigExport / GridConfigSnapshot
+
+`grid.getConfig()` 가 반환하고 `applyConfig(cfg)` 가 받는 직렬화 가능 타입.
+
+```typescript
+/** Export bundle — 현재 상태 + reset baseline */
+interface GridConfigExport {
+  /**
+   * 저장 스키마 버전 (예: `'0.3'`).
+   * `getConfig()` 가 항상 현재 버전(`GRID_CONFIG_VERSION`)을 실어 내보낸다.
+   * 없으면 **버전 도입 이전 저장본**이므로 `applyConfig` 가 `'0.1'` 로 간주하고
+   * 마이그레이션을 처음부터 태운다 (ITSM-2026-002191).
+   */
+  version?: string;
+
+  /** 현재 그리드 상태 (런타임) */
+  current: GridConfigSnapshot;
+  /**
+   * Reset 기준 baseline. 현재는 컬럼 정적 정의(`fields`) 만 반영됨.
+   * 없으면 `applyConfig` 가 기존 baseline 유지.
+   */
+  snapshot?: GridConfigSnapshot;
+}
+
+/** 단일 layer 의 직렬화된 상태 — `current` / `snapshot` 양쪽 모두 이 형식 */
+interface GridConfigSnapshot {
+  mode: 'flat' | 'pivot';
+
+  // Flat 모드 ↓
+  fields?: FieldDef[];           // 런타임 width/visible/order/pinned 반영됨
+  group?: GroupConfig;
+  rowTemplate?: RowTemplate;
+  columnGroups?: ColumnGroupDef[];
+
+  // Pivot 모드 ↓
+  rowFields?: PivotRowField[];
+  columnFields?: PivotColumnField[];
+  valueFields?: PivotValueField[];
+  showRowSubTotals?: boolean;
+  showRowGrandTotals?: boolean;
+  showColumnSubTotals?: boolean;
+  showColumnGrandTotals?: boolean;
+  rowSubTotalFields?: string[];
+  columnSubTotalFields?: string[];
+  rowSubTotalPosition?: TotalPosition;     // 'before' | 'after'
+  rowGrandTotalPosition?: TotalPosition;
+  columnSubTotalPosition?: TotalPosition;
+  columnGrandTotalPosition?: TotalPosition;
+  filterFields?: PivotFilterField[];
+  trackSourceRows?: boolean;
+  showZeros?: boolean;
+  rowDisplayMode?: 'tabular' | 'outline';
+  outlineColumnWidth?: number;
+  outlineIndentSize?: number;
+  rowCollapsible?: boolean;       // 행 그룹 접기/펼치기 허용 (default true)
+  columnCollapsible?: boolean;    // 열 그룹 접기/펼치기 허용 (default true)
+
+  // 공통 view 상태 ↓
+  sorts?: SortState[];
+  filters?: FilterState[];        // 평탄화된 파생값 (옛 소비처 호환)
+  filterGroups?: FilterGroupMap;  // 소스별 그룹 — 있으면 이것이 우선 (ITSM-2026-002182)
+
+  // 트리/마스터-디테일 ↓
+  treeConfig?: TreeConfig;
+  masterDetailConfig?: MasterDetailConfig;
+
+  // UI / 동작 옵션 ↓ (PureSheetConfigBase에서 직렬화 가능한 항목만)
+  theme?: Theme;
+  rowHeight?: number;
+  headerHeight?: number;
+  rowSelection?: RowSelectionConfig;
+  cellSelection?: CellSelectionConfig;
+  cellSelectionImpliesRows?: boolean;
+  editable?: boolean;
+  tooltipMode?: 'none' | 'overflow' | 'always';
+  alternatingRows?: boolean;
+  showHeader?: boolean;
+  resizableColumns?: boolean;
+  reorderableColumns?: boolean;
+  rowHeader?: boolean | RowHeaderConfig;   // 구 showRowHeader (deprecated alias 유지)
+  reorderableRows?: boolean;
+  showDragHandleColumn?: boolean;
+  autoFitColumns?: boolean;
+  showStatusBar?: boolean;
+  locale?: string;
+  translations?: PartialTranslationMap;
+  keyFields?: string[];
+}
+```
+
+**`snapshot` 의 의미** — `columns.reset / resetAll` 의 복귀 기준. `applyConfig` 는 `cfg.snapshot?.fields` 가 있으면 `columns.setInitialSnapshotDefs(...)` 호출로 baseline 재구성. `options.applySnapshot: false` 면 무시.
+
+**제외되는 항목** (직렬화 불가):
+- `data` — `loadData()`로 별도 관리
+- 모든 함수 (`cellRenderer`, `cellTooltip`, `formatHeader`, validator, mask formatter, `formatRow` 등) — 사용자 코드에서 재등록
+- DOM/객체 참조 (`undoStack`, `loader.module`, `dragDropConfig` 등)
+- dirty 상태 (`grid.changes.getAll()`로 별도 저장)
+
+**현재 직렬화 안 되는 옵션 (향후 추가 여지)**:
+- `engine`, `useWorker`, `dynamicRowHeights`, `rowHeightChangeThreshold`
+- `enableReferCache`, `preventKeyEdit`
+- `rowStyle`, `headerStyle` (CSS 문자열 — `rowHeight`/`headerHeight` 와 일부 중복)
+- `PivotConfig.sorts` / `PivotConfig.filters` (피벗 전용 — `GridConfigSnapshot.sorts/filters` 와 별개)
+
+---
+
+### 저장 스키마 버전 — GridConfigMigrator
+
+저장본(`getConfig()`/`applyConfig()`)에 **스키마 버전**이 붙습니다 (ITSM-2026-002191).
+
+| Export | 값/시그니처 | 설명 |
+|---|---|---|
+| `GRID_CONFIG_VERSION` | `'0.3'` | 현재 저장 스키마 버전. `getConfig()` 가 항상 이 값을 실어 내보냄 |
+| `LEGACY_CONFIG_VERSION` | `'0.1'` | 버전 필드가 없는 저장본을 읽을 때 가정하는 버전 |
+| `compareConfigVersion(a, b)` | `number` | 버전 비교 — **숫자 단위**로 봄(`a<b` 음수, 같으면 0, `a>b` 양수) |
+| `GridConfigMigrator` | `(config: GridConfigExport, fromVersion: string) => GridConfigExport` | 하위호환 변환기 타입. `PureSheetConfig.migrateConfig` 로 주입 |
+
+**버전 이력**
+
+| 버전 | 내용 |
+|---|---|
+| `0.1` | 버전 필드가 없던 시절. `preFilters`/`preSorts` 사용, 수식은 `[라벨]` 참조 |
+| `0.2` | 수식 컬럼 참조가 `$id` 기준. `preFilters`/`preSorts` 폐지 |
+| `0.3` | 필터 소유권(`filterGroups`) 도입. 소유자 없는 옛 조건식을 고급 필터 수식으로 이관 |
+
+> **왜 키 존재 여부로는 부족한가** — 지금까지 하위호환은 키 존재 여부로 감지했습니다(`preFilters` 가 있으면 구버전). 그런데 **키는 그대로인데 값의 의미만 바뀌는** 변경에서는 통하지 않습니다:
+> ```
+> "formula": "[급여] > 100"   ← 옛 저장본 (라벨 참조)
+> "formula": "$salary > 100"  ← 새 저장본 (id 참조)
+> ```
+> 둘 다 같은 키에 문자열이라 추측할 수밖에 없습니다. 버전이 있으면 **확실히** 압니다.
+>
+> **버전을 올리는 기준** — 올린다: 필드의 **의미**가 바뀔 때(`[라벨]` → `$id`), 필드가 **삭제/이름 변경**될 때. 올리지 않는다: 옵셔널 필드 **추가**(없으면 기본값이 적용되므로 옛 저장본이 그대로 유효).
+>
+> **마이그레이션은 누적 적용입니다.** `0.1` 저장본이 들어오면 `0.1 → 0.2 → …` 를 **순서대로 전부** 거칩니다. 최신 변환만 돌리면 중간 단계를 건너뛰어 조용히 어긋납니다.
+>
+> **변환 내용은 소비처(wrapper) 소유입니다.** core 는 호출 시점과 순서만 책임집니다 — core 가 변환까지 들고 있으면 소비처 고유 필드(`customCellConfig` 등)를 다룰 수 없고, 소비처마다 다른 진화 속도를 강제하게 됩니다. 변환기가 없거나 이미 최신이면 받은 것을 그대로 돌려줍니다(부작용 없음). 변환 중 예외가 나도 복원 자체는 막지 않고 경고(`PS901`)만 남깁니다.
+
+```typescript
+const grid = new PureSheet(el, {
+  fields,
+  migrateConfig: (cfg, fromVersion) => {
+    let out = cfg;
+    if (compareConfigVersion(fromVersion, '0.2') < 0) out = to02(out);
+    if (compareConfigVersion(fromVersion, '0.3') < 0) out = to03(out);
+    return { ...out, version: GRID_CONFIG_VERSION };
+  },
+});
+```
+
+---
+
+### 컬럼 식별자 유틸 — columnKeys
+
+`FieldDef.id`(가리킬 때) 와 `FieldDef.field`(읽을 때) 를 정규화합니다 (ITSM-2026-002188).
+
+| Export | 시그니처 | 설명 |
+|---|---|---|
+| `normalizeColumnKeys(input, context?)` | `ColumnKeys` | `{ id, field }` 를 채워 반환. `field` 미지정 시 `field = id` |
+| `getColumnId(input)` | `string` | 식별자만 |
+| `getColumnField(input)` | `string` | 데이터 키만 |
+| `resolveFieldKey(...)` | `string` | 컬럼 목록에서 id → 데이터 키 해석 |
+| `ColumnKeyInput` / `ColumnKeys` | 타입 | 입력/출력 형태 |
+
+> **읽을 때 `field`, 가리킬 때 `id`.** 원본 행에서 값을 꺼내는 자리(`row[...]`)는 반드시 `field`, 정렬/필터/저장/DOM dataset 처럼 *컬럼을 지목*하는 자리는 `id` 입니다.
+
+**피벗 쪽 대응** — `PivotFieldBase.id?` 가 추가됐습니다(미지정 시 `field`). 값 필드는 같은 `field` 를 합계·평균으로 **여러 번** 넣을 수 있어 `field` 만으로는 식별이 깨집니다.
+
+| Export | 설명 |
+|---|---|
+| `getPivotFieldId(f)` | 피벗 필드의 식별자 — `f.id ?? f.field`. ⚠️ **데이터 접근 키가 아님** — 값은 `row[f.field]` |
+| `getValueFieldKey(vf, allValueFields)` | 값 필드 키. 우선순위: ① `vf.id` → ② `field` 중복 없으면 `field` → ③ 중복인데 id 미지정이면 `'sales-0'` 같은 **순서 기반 폴백 + 경고** |
+
+> ⚠️ **③ 순서 기반 폴백은 위험합니다.** 값 필드 순서를 바꾸거나 하나를 지우면 인덱스가 밀려 **같은 저장본이 다른 필드를 가리킵니다**. 수식 필터/조건부 서식이 이 키를 참조하면 조건이 조용히 달라집니다. 같은 `field` 를 여러 번 쓸 거면 **불변 `id` 를 명시**하세요(자동 생성으로는 불변성을 보장할 수 없습니다).
+>
+> ```typescript
+> // 중복 없음 — id 불필요 (id = 'sales')
+> valueFields: [{ field: 'sales', aggregate: 'sum' }]
+>
+> // 같은 field 를 여러 번 — id 명시
+> valueFields: [
+>   { field: 'sales', aggregate: 'sum', id: 'sales_sum' },
+>   { field: 'sales', aggregate: 'avg', id: 'sales_avg' },
+> ]
+> ```
+
+---
+
+### 수식 엔진 — FormulaEngine
+
+조건부 서식과 필터가 **같은 문법**을 씁니다. wrapper 에 있던 엔진을 core 로 이관했습니다 (ITSM-2026-002187) — 필터는 core 에서 평가되므로 wrapper 를 볼 수 없기 때문입니다.
+
+**문법**
+
+| 요소 | 표기 |
+|---|---|
+| 컬럼 참조 | `[컬럼헤더]`(표시) / `$id`(저장) — 공백·한글 헤더 지원 |
+| 논리 | `AND` / `OR` / `NOT` 또는 `&&` / `\|\|` / `!` |
+| 비교 | `==` `!=` `>` `>=` `<` `<=` |
+| 문자열 | `CONTAINS` `NOT_CONTAINS` `STARTS_WITH` `ENDS_WITH` `LIKE` `IS_EMPTY` `IS_NOT_EMPTY` |
+| 숫자 | `ABS` `ROUND` `FLOOR` `CEIL` `MIN` `MAX` |
+| 텍스트 | `LEN` `UPPER` `LOWER` `TRIM` `LEFT` `RIGHT` `CONCAT` |
+| 날짜 | `NOW` `TODAY` `DAYS`, `#2025-09-05#` 날짜 리터럴 |
+| 기타 | `IF` `COALESCE` |
+
+**Export**
+
+| Export | 설명 |
+|---|---|
+| `FormulaEngine`, `FormulaLexer`, `FormulaParser`, `FormulaEvaluator`, `TokenType` | 엔진 클래스/토큰 |
+| `evaluateFormula(...)` / `validateFormula(...)` | 평가 / 유효성 검사(→ AST) |
+| `toFriendlyFormulaError(err)` | 파서 원문 → 사용자 문구. **수식을 입력받는 UI 는 모두 이걸 거쳐야** 창마다 다른 말이 나오지 않음 |
+| `toFormulaDataType(dataType)` | `FieldDef.dataType`(문자열) → 엔진의 숫자 dataType. 안 실으면 타입 검사가 꺼짐 |
+| `astToFormula(node)` | AST → 수식 문자열 **역변환**. 고급 필터의 트리 탭이 편집 결과를 다시 수식으로 저장할 때 사용(수식 → AST 는 `validateFormula`) |
+| 타입 | `ASTNode`, `ParseResult`, `EvaluateResult`, `Token`, `LiteralNode`, `ColumnRefNode`, `BinaryOpNode`, `UnaryOpNode`, `FunctionCallNode`, `PostfixOpNode`, `FormulaColumnInfo`(core 의 `ColumnInfo` 와 이름 충돌을 피한 별칭) |
+
+**컬럼 참조 변환 — 저장은 `$id`, 표시는 `[현재 라벨]`**
+
+| Export | 설명 |
+|---|---|
+| `formulaToStorage(formula, columns)` | 표시 표기 → 저장 표기 |
+| `formulaToDisplay(formula, columns)` | 저장 표기 → 표시 표기 |
+| `migrateFormulaToStorage(formula, columns)` | 옛 라벨 참조 저장본 → `$id` 표기 |
+| `UNRESOLVED_REF_PREFIX` | `'?'` — 해석되지 않은 참조 접두사 |
+| `FormulaConversion`, `FormulaRefIssue` | 변환 결과/이슈 타입 |
+
+> 라벨이 바뀌어도(다국어·헤더 편집) **같은 저장본이 늘 현재 라벨로 보입니다.** 필터 평가는 저장 표기(`$id`)를 그대로 쓰므로 라벨 변경이 조건을 깨뜨리지 않습니다.
+
+---
+
+### 값 목록 위젯 — ValueCheckList
+
+엑셀식 값 필터의 값 선택 UI. 소비처가 팝오버 등에 직접 mount 합니다 (ITSM-2026-002179).
+
+```typescript
+import { ValueCheckList, VALUE_LIST_BLANK_KEY, DEFAULT_VALUE_LIST_LIMIT } from '@vmscloud/moz-ui-grid-core';
+
+const list = new ValueCheckList(container, {
+  mode: 'exclude',
+  onSelectionChange: (keys) => { /* 적용 시점은 소비처가 정한다 */ },
+  onKeywordChange: async (kw) => {           // 지정하면 검색을 소비처가 소유
+    const r = await grid.getFilterValues(columnId, { keyword: kw });
+    list.setValues(r.values, selectedKeys, { truncated: r.truncated, rawValues: r.rawValues });
+  },
+});
+list.setLoading(true);
+const r = await grid.getFilterValues(columnId);
+list.setValues(r.values, /* selectedKeys 생략 = 모드 기본 체크 */ undefined,
+               { truncated: r.truncated, limit: DEFAULT_VALUE_LIST_LIMIT, rawValues: r.rawValues });
+list.getSelectedKeys();                       // 선택 키
+list.getSelectedItems();                      // 적용 시점에 읽어간다
+list.setMode('include');                      // 저장 방향 전환 (체크가 뒤집힌다)
+list.destroy();
+```
+
+**주요 메서드**
+
+| 메서드 | 설명 |
+|---|---|
+| `setValues(values, selectedKeys?, meta?)` | 목록 채우기. `meta`: `{ truncated?, limit?, rawValues?, offListPicks? }`. `selectedKeys` 생략 시 **모드 기본 체크**(`'exclude'`=전체 선택, `'include'`=전체 해제) |
+| `setLoading(loading)` | 로딩 표시 |
+| `getSelectedKeys()` / `getSelectedItems()` | 현재 선택 |
+| `setMode(mode)` | 저장 방향 전환 — 지목 집합은 유지하고 의미만 뒤집으므로 **체크가 반전**됩니다 |
+| `destroy()` | 해제 |
+
+**`ValueCheckListOptions`**
+
+| 속성 | 타입 | 기본값 | 설명 |
+|---|---|---|---|
+| `mode` | `ValueListMode` (`'exclude' \| 'include'`) | `'exclude'` | 저장 방향. `'exclude'` 는 전체 체크로 시작하는 엑셀 AutoFilter 동작 |
+| `onSelectionChange` | `(selectedKeys: string[]) => void` | — | 선택 상태 변경 시 호출 |
+| `onKeywordChange` | `(keyword: string) => void` | — | 검색어 변경 시(디바운스 후). **지정하면 검색을 소비처가 소유** — 상한 초과로 목록이 잘린 경우 로컬 필터링으로는 상한 밖 값을 찾을 수 없으므로 엔진에 keyword 를 넘겨 재조회. 미지정이면 받은 목록 안에서만 로컬 필터링 |
+| `i18n` | `I18nManager` | 영문 기본 문구 | 다국어 |
+| `height` | `number` | `260` | 목록 영역 높이(px) |
+
+**`ValueListMode` — 저장 방향**
+
+| 모드 | 초기 체크 | 지목(picked) | core 연산자 |
+|---|---|---|---|
+| `'exclude'` (기본) | 전체 체크 | **체크 해제한 값** | `notIn` |
+| `'include'` | 전체 해제 | **체크한 값** | `in` |
+
+> **왜 모드가 필요한가 — 한쪽만 두면 반대쪽에서 터집니다.**
+> `include` 만 있으면 고유값 3만짜리 컬럼에서 **하나만 해제해도** 나머지 29,999개를 담아야 합니다. 게다가 목록 수집에는 상한이 있어 그 배열이 상한까지밖에 안 차고, **수집되지 않은 값의 행이 조용히 사라집니다**(실측: 고유값 30,000 · 상한 10,000 에서 1개 해제 → 기대 29,999행 / 실제 9,999행, 20,000행 유실). `exclude` 만 있으면 반대로 "3개만 골라 보기"에서 29,997개를 담게 됩니다.
+>
+> 그래서 **사용자가 의도를 고릅니다.** 상용 그리드의 표준 패턴입니다 — DevExtreme DataGrid 는 헤더 필터에 `filterType: 'include' | 'exclude'` 가 있고, Tableau 는 필터 카드 메뉴에 Include values / Exclude values 를 둡니다.
+
+**`ValueListItem`**
+
+| 속성 | 타입 | 설명 |
+|---|---|---|
+| `key` | `string` | 선택 상태 관리용 키(문자열화된 값, 빈 값은 `VALUE_LIST_BLANK_KEY`) |
+| `label` | `string` | 화면 표시 라벨 |
+| `value` | `CellValue` | 필터에 실을 **원본값**(빈 값은 `null`) |
+| `pinned` | `boolean?` | 현재 후보 목록에는 없지만 사용자가 지목해 **목록 맨 위에 고정 표시 중**인 항목 |
+
+> **`pinned` 가 왜 필요한가** — 고유값이 수집 상한을 넘으면 목록이 잘립니다. 사용자가 검색으로 상한 밖 값을 찾아 조작한 뒤 검색어를 지우면 그 값은 기본 목록에 없어 화면에서 사라지는데 **지목은 살아 있습니다**. 그러면 필터에는 실려 있는데 화면 어디에도 없는 값이 되어 되돌릴 방법이 없습니다.
+>
+> 위젯은 팝오버가 닫힐 때 파괴되므로 지목도 함께 사라집니다. 다시 열 때 소비처가 저장된 필터에서 "현재 후보 목록에 없는 지목"을 추려 **`setValues(..., { offListPicks })`** 로 넘겨야 고정 표시가 이어집니다.
+
+| 상수 | 값 | 설명 |
+|---|---|---|
+| `DEFAULT_VALUE_LIST_LIMIT` | `10_000` | 값 수집 기본 상한 (Excel AutoFilter 와 동일) |
+| `VALUE_LIST_BLANK_KEY` | — | 빈 값(null/undefined/'')을 나타내는 선택 키 |
+
+**수집 결과 타입** (`grid.getFilterValues` 반환)
+
+```typescript
+interface ColumnValuesResult {
+  values: CellValue[];      // 표시 라벨 (mask 적용)
+  rawValues: CellValue[];   // values[i] 에 대응하는 **원본값** — 필터는 이걸로 만든다
+  total: number;
+  truncated: boolean;       // 상한 도달로 조기 종료 → "검색으로 좁혀 주세요" 안내
+}
+
+interface ColumnValuesProgress {
+  values: CellValue[];      // **이번 청크의 델타** — 소비처가 누적 목록에 append
+  rawValues: CellValue[];
+  total: number;            // 누적 고유값 개수
+  truncated: boolean;
+  done: boolean;
+}
+```
+
+> **왜 `rawValues` 를 함께 돌려주나** — 표시값으로 필터링하면 행마다 `applyMask` 를 불러야 하는데 `toLocaleString()` 자체가 비싸서 5M 행에서 **1,903ms(전체의 92%)** 를 먹습니다(실측). 원본끼리 비교하면 62ms 로 **30.6배** 빠릅니다. 게다가 함수형 mask 는 Worker 로 복제되지 않아 워커 모드가 크래시합니다. 문자열 `parser` 역변환은 mask 가 다대일이라 왕복이 깨집니다(실측: `NaN` → `"NaN"` → `0`).
+
+---
+
+### formatRow 컨텍스트 — FormatRowInfo
+
+`formatRow` 콜백과 `formatRow.addHandler(id, cb)`에 전달되는 정보. Discriminated union이므로 `info.type`으로 분기합니다.
+
+```typescript
+type FormatRowInfo =
+  | { type: 'data';       ctx: DataRowContext }
+  | { type: 'group-row';  ctx: GroupRowContext }
+  | { type: 'subtotal';   ctx: SubtotalContext }
+  | { type: 'grand-total'; ctx: SubtotalContext };
+
+type FormatRowCallback = (info: FormatRowInfo) => void;
+
+interface DataRowContext {
+  viewIndex: number;                    // 가상화 기준 인덱스
+  dataIndex: number;                    // 원본 데이터 기준
+  rowId?: string | number;
+  data: Row;
+  groupPath: string[];
+  rowState: RowState;                   // 'pristine' | 'added' | 'modified' | 'deleted'
+  originalData?: Row;                   // modified일 때만
+  changedFields?: Set<string>;          // modified일 때만
+  rowElement: HTMLElement;
+  /** 컬럼 ID → 셀 정보 맵 */
+  cells: Record<string, CellInfo>;
+}
+
+interface GroupRowContext {
+  viewIndex: number;
+  groupId: string;                       // 토글용 ID (= grid.rowGroup.getGroupRows 인자)
+  column: string;
+  value: CellValue;
+  level: number;
+  itemCount: number;
+  collapsed: boolean;
+  aggregates: Record<string, CellValue>;
+  element: HTMLElement;
+}
+
+interface SubtotalContext {
+  viewIndex: number;
+  level: number;
+  aggregates: Record<string, CellValue>;
+  element: HTMLElement;
+  cells: Record<string, CellInfo>;
+}
+
+interface CellInfo {
+  element: HTMLElement;
+  value: CellValue;
+  originalValue?: CellValue;            // modified일 때만
+  isModified: boolean;
+}
+```
+
+```typescript
+// addHandler 등록 옵션
+grid.formatRow.addHandler('highlight', (info) => {
+  if (info.type !== 'data') return;
+  const { data, cells, rowElement } = info.ctx;
+  if ((data.price as number) > 80000) {
+    rowElement.style.backgroundColor = 'rgba(255, 193, 7, 0.12)';
+  }
+  if (data.stock as number <= 20) {
+    cells['stock']?.element.style.color = '#d32f2f';
+  }
+}, { priority: 50 });
+```
+
+---
+
+### formatHeader 컨텍스트 — FormatHeaderContext
+
+`formatHeader` 콜백과 `formatHeader.addHandler(id, cb)` 에 전달되는 정보.
+`formatRow` 의 헤더 카운터파트.
+
+#### 타입
+
+```typescript
+type FormatHeaderCallback = (ctx: FormatHeaderContext) => void;
+
+interface FormatHeaderContext {
+  /**
+   * columnId → 헤더 셀 정보 맵.
+   * - Flat: 모든 컬럼 헤더 셀
+   * - Pivot: rowHeader 컬럼 셀 + center leaf 셀 (valueField 리프 컬럼)
+   * 중간 그룹 셀(예: year, quarter 노드)은 여기 들어가지 않고 `pivotMeta.allCells` 에서 접근.
+   */
+  cells: Record<string, HeaderCellInfo>;
+  /** 헤더 컨테이너 DOM */
+  element: HTMLElement;
+  /** 현재 전체 정렬 상태 (다중 정렬 시 우선순위 순서, sequence enrich 됨) */
+  sortStates: SortState[];
+  /** 현재 전체 필터 상태 */
+  filterStates: FilterState[];
+  /**
+   * Pivot 전용 메타 (Flat 에서는 undefined).
+   * `allCells` 는 rowHeader + center leaf + center 그룹(non-leaf) 셀 전체.
+   * 그룹 셀 서식은 `cell.nodeId` 매칭으로 찾는다 (`data-column-node-id` 와 동일).
+   */
+  pivotMeta?: {
+    /** rowHeader + center 모든 셀 (leaf + non-leaf 그룹 셀 포함) */
+    allCells: HeaderCellInfo[];
+    /** 헤더 총 레벨 수 (columnFields.length + 1[valueField 레벨]) */
+    levelCount: number;
+  };
+}
+
+interface HeaderCellInfo {
+  /** 컬럼 ID — leaf 셀(Flat/rowHeader/center-leaf)에서만 의미. Pivot 그룹 셀은 빈 문자열 */
+  columnId: string;
+  /** 표시되는 헤더 텍스트 (label ?? header ?? id 합성 — 항상 비어있지 않음) */
+  header: string;
+  /** 헤더 셀 DOM (인터랙티브 요소 포함, 정렬 아이콘 등 자식 노드 있음) */
+  element: HTMLElement;
+  /** 핀 위치 */
+  pinned: 'left' | 'right' | 'none';
+  /** 이 컬럼의 현재 정렬 상태 (없으면 undefined). index 는 다중 정렬 시 우선순위 */
+  sortState?: { direction: 'asc' | 'desc'; index?: number };
+
+  // ─── Pivot 전용 메타 (Flat 에서는 undefined) ───
+  /** PivotHeaderNode.columnNodeId (= `data-column-node-id`). 중간 그룹 노드 셀에만 설정 */
+  nodeId?: string;
+  /** leaf 셀 여부 — Flat / rowHeader / center leaf 는 true, 그룹 셀만 false */
+  isLeaf?: boolean;
+  /** Pivot 헤더 레벨 (0-based) — Flat 에서는 undefined */
+  level?: number;
+  /** colspan (Pivot 그룹 셀의 자식 leaf 수). Flat / leaf 는 1 */
+  colspan?: number;
+  /** rowspan (Pivot rowHeader 셀은 levelCount, 레벨 갭 셀은 갭 크기). Flat / 일반 leaf 는 1 */
+  rowspan?: number;
+}
+```
+
+#### 발화 매트릭스 — 정확히 언제 호출되나
+
+| 액션 | invoke 호출? | 비고 |
+|---|---|---|
+| `new PureSheet(...)` 후 `loadData()` | ✓ | 초기 렌더 |
+| 헤더 클릭으로 정렬 변경 | ✓ | sort 아이콘/`ps-sorted` 갱신 |
+| `columns.sort(...)` 호출 | ✓ | 위와 동일 |
+| `columns.filter(...)` | ✓ | 필터 인디케이터 갱신 |
+| `columns.pinLeft / pinRight / unpin` | ✓ | 헤더 cell 재구성 (`render`) — 자동 invoke |
+| `columns.setWidth` / 사용자 헤더 드래그 리사이즈 | ✓ | per-column path (`render` 없이 인라인 width 패치) — `GridRenderer.setColumnWidth` 끝에서 명시 invoke |
+| `columns.setOrder / move / moveGroup` | ✓ | 헤더 cell 재구성 (`render`) — 자동 invoke |
+| `columns.hide / show / setHidden / toggle` | ✓ | 헤더 cell 재구성 (`render`) — 자동 invoke |
+| `columns.update(...)` (헤더 영향 키 — 아래 표 참고) | ✓ | refresh 동반 |
+| `columns.update(...)` (예: `width`만 변경) | ✓ | refresh 안 거치지만 헤더 재렌더는 됨 |
+| `columns.reset / resetAll` | ✓ | refresh 동반 |
+| `headers.toggle(...)` (컬럼 그룹 접기/펼치기) | ✓ | |
+| `grid.refresh()` | ✓ | 풀 리렌더 |
+| 테마 변경 (`setTheme`) | ✓ | |
+| 로케일 변경 | ✓ | |
+| **수직 스크롤** (body 가상화) | ✗ | 헤더 sticky — 재렌더 없음 |
+| **수평 스크롤** (center 가상화 범위 변경) | ✓ | `renderCenterHeader` 끝에서 invoke (center 영역 재생성 시 사용자 서식 보존) |
+| 셀 편집/CRUD/Undo | ✗ | body 만 영향 |
+
+> **per-column setter 의 자동 invoke**: `setColumnWidth` 는 헤더 cell DOM 을 재구성하지 않고 인라인 width 만 패치 → `HeaderRenderer.render()` 가 호출되지 않으므로 일반 경로로는 `formatHeader` 가 발화되지 않습니다. 코어가 setter 끝에서 명시적으로 `headerRenderer.invokeFormatHeader()` 를 호출해서 사용자 layer (예: 사용자 컬럼 서식) 가 헤더 inline style/class 를 잃지 않도록 보장합니다.
+>
+> **수평 가상화**: `renderCenterHeader` 도 끝에서 invoke 를 호출하므로 가상화된 center 컬럼 헤더에 사용자 서식이 보존됩니다. 컬럼 가시성 변경 시 stale 한 `horizontalVirtualRange` 로 인한 center 비어 보이는 이슈 방지를 위해 `HeaderRenderer.updateColumns` 가 진입 시 range 를 invalidate 함.
+
+#### `columns.update` 의 어떤 키가 헤더 재렌더를 일으키나
+
+| 키 | 헤더 재렌더? | 헤더 서식에 영향? |
+|---|---|---|
+| `header` / `label` / `headerAttributes` / `headerRenderer` | ✓ refresh | 직접 영향 — 핸들러 재계산 필요 |
+| `align` / `mask` / `cellAttributes` / `cellRenderer` / `aggregate` / 등 body 영향 | ✓ refresh | 헤더 메타는 그대로지만 invoke 는 됨 (헤더도 같이 재렌더되므로) |
+| `width` / `pinned` / `hidden` / `autoFit` | ✓ per-column path 만 | 헤더 셀 위치/크기/표시 영향 |
+| `sortable` / `filterable` / `editable` 등 mutate-only | ✗ | 다음 인터랙션 시 자동 반영 |
+
+#### 다중 owner 패턴 — wrapper / plugin / 검색 하이라이트 공존
+
+```typescript
+// 1) wrapper UI — 사용자 정의 헤더 서식 (정적 객체)
+const userHeaderFmt = new Map<string, { class?: string; style?: string }>();
+
+grid.formatHeader.addHandler('user-header-fmt', (ctx) => {
+  for (const [colId, cell] of Object.entries(ctx.cells)) {
+    const fmt = userHeaderFmt.get(colId);
+    if (!fmt) continue;
+    if (fmt.class) cell.element.classList.add(...fmt.class.split(' '));
+    if (fmt.style) cell.element.style.cssText += ';' + fmt.style;
+  }
+}, { priority: 80 });
+
+// 2) 검색 하이라이트 plugin — 검색 매칭 컬럼 헤더에 인디케이터
+const matchedColumns = new Set<string>();
+
+grid.formatHeader.addHandler('search-match', (ctx) => {
+  for (const [colId, cell] of Object.entries(ctx.cells)) {
+    cell.element.classList.toggle('search-matched', matchedColumns.has(colId));
+  }
+}, { priority: 60 });
+
+// 3) 정렬 시각 강조 — 다중 정렬 순위 뱃지
+grid.formatHeader.addHandler('sort-rank', (ctx) => {
+  for (const [colId, cell] of Object.entries(ctx.cells)) {
+    cell.element.dataset.sortRank = cell.sortState
+      ? String((cell.sortState.index ?? 0) + 1)
+      : '';
+  }
+}, { priority: 50 });
+```
+
+세 핸들러 모두 등록 시 priority 순(50 → 60 → 80)으로 실행. 각 owner 는 자기 key 로 add/remove 독립 관리.
+
+#### priority 가이드
+
+`formatRow` 와 동일한 체계를 공유합니다 (RenderHookManager 같은 클래스).
+
+| 범위 | 용도 |
+|---|---|
+| 0–9 | Core 초기화 (스타일/속성 리셋) |
+| 10–29 | 정렬 아이콘, 필터 인디케이터 등 core 시각 마커 |
+| 30–69 | 일반 기능 (사용자 코드 권장) |
+| 70–89 | wrapper-managed user UI (CellSettings 등) |
+| 90–99 | 최종 오버라이드 (디버그/QA 도구) |
+
+핸들러는 모두 **같은 ctx 객체**를 공유하므로, 같은 cell 의 `style`/`class` 를 여러 핸들러가 누적할 수 있습니다.
+
+#### cleanup 패턴 — Row pool 누수 방지
+
+`formatRow` 와 달리 헤더 셀은 가상화로 인한 재사용이 적어 누수 위험이 작지만, **핸들러 자체에서 idempotent 하게 작성**하는 게 안전합니다.
+
+```typescript
+// 안티패턴 — 누적되어 누수
+grid.formatHeader.addHandler('bad', (ctx) => {
+  for (const cell of Object.values(ctx.cells)) {
+    cell.element.classList.add('mark');  // 매 호출마다 add (한 번이면 OK이지만 toggle 가시성 등엔 누적)
+  }
+});
+
+// 권장 — 상태 토글
+grid.formatHeader.addHandler('good', (ctx) => {
+  for (const [colId, cell] of Object.entries(ctx.cells)) {
+    cell.element.classList.toggle('mark', shouldMark(colId));
+  }
+});
+```
+
+핸들러 제거 시 잔존 스타일은 wrapper 가 명시 정리:
+
+```typescript
+function cleanup() {
+  grid.formatHeader.removeHandler('user-header-fmt');
+  // 잔존 인라인 스타일 제거 (한 번 적용해두면 핸들러 제거해도 남아있음)
+  for (const c of grid.columns.getAll()) {
+    const cell = grid.columns.getById(c.id);
+    // 또는 직접 DOM 조회
+    document.querySelector(`[data-column-id="${c.id}"]`)?.removeAttribute('style');
+  }
+  grid.refresh();  // 핸들러 제거 후 1회 재렌더
+}
+```
+
+#### `formatHeader` vs `columns.update({ headerAttributes })` — 언제 어느 걸?
+
+| 시나리오 | 권장 |
+|---|---|
+| 사용자 UI 가 컬럼별 동적 헤더 서식 (자주 변함) | **formatHeader.addHandler** — wrapper state 자동 추적, devSnap 불필요 |
+| 컬럼 옵션을 영구 변경 (label, title 등) | **columns.update({ header / headerAttributes })** + `updateSnapshot: true` — config snapshot 에 반영 |
+| 정렬/필터 메타 기반 시각 마커 | **formatHeader.addHandler** — sortState/filterState 가 ctx 에 들어옴 |
+| 1회성 외부 attr 부여 (분석 도구 data-*) | **columns.update({ headerAttributes })** — 정적이라 hook 불필요 |
+| dev 정적 attr 보존하면서 user 변경분 얹기 | **formatHeader.addHandler** — owner 분리, 충돌 없음 |
+
+#### 직렬화 / Config Snapshot 관계
+
+`formatHeader` 콜백은 **함수**이므로 직렬화 불가:
+- `grid.getConfig()` 가 반환하는 `GridConfigSnapshot` 에 **포함되지 않음**
+- `applyConfig(snapshot)` 후에는 핸들러 재등록 필요
+- 사용자 헤더 서식 데이터(`userHeaderFmt` Map 등)는 wrapper 가 별도 저장 (localStorage 등)
+
+`columns.update({ headerAttributes })` 로 박은 정적 객체는 `GridConfigSnapshot.fields[*].headerAttributes` 에 직렬화됩니다.
+
+#### `formatRow` 와의 비교
+
+| | `formatRow` | `formatHeader` |
+|---|---|---|
+| 발화 빈도 | 분당 수천 회 (스크롤마다) | 분당 0~20회 (사용자 액션) |
+| 발화 트리거 | 스크롤, 데이터 변경, 행 dirty | 사용자 헤더 관련 액션 |
+| 가상화 대상 | ✓ viewport 내 행만 | ✗ 모든 헤더 셀 (헤더 sticky) |
+| ctx 행 데이터 | ✓ `data`, `originalData`, `cells[].value` | ✗ 행 데이터 없음 (헤더 메타만) |
+| ctx type 분기 | data/group-row/subtotal/grand-total 4종 | 1종 (flat) |
+| 직렬화 | ✗ | ✗ |
+| Render hook 패턴 | RenderHookManager | RenderHookManager (동일 클래스) |
+
+라이프사이클이 다르니 분리된 hook 으로 노출. 같은 일을 두 곳에서 하지 마세요.
+
+---
+
+### RowHeaderConfig
+
+좌측 **행 헤더 컬럼**(`_rowHeader`)의 설정. `config.rowHeader`에 `boolean` 대신 객체를 주면
+너비·본문 셀·헤더(코너) 셀을 커스터마이즈합니다. 행 헤더는 일급 컬럼(`ROW_HEADER_COLUMN_ID = '_rowHeader'`)이며
+본문 셀은 `formatRow`의 `data` 행 `cells['_rowHeader']`, 코너(좌상단) 셀은 `formatHeader`의 `cells['_rowHeader']`로 접근합니다.
+
+```typescript
+interface RowHeaderConfig {
+  /** 행 헤더 컬럼 너비(px). @default 40 */
+  width?: number;
+  /**
+   * 본문 행 헤더 셀 렌더러. 일반 컬럼 cellRenderer와 동일 시그니처(Simple | Lifecycle).
+   * params.selected 로 해당 행 선택 상태 스냅샷을 받아 체크박스 등을 그릴 수 있다
+   * (선택 "변경" 반영은 CSS `.ps-selected` / `repaintRows` 중 하나로 — CellRendererParams.selected JSDoc 참조).
+   * 실제 <input>을 그린다면 `ps-row-header-checkbox-input` 클래스를 붙이면 built-in 선택 동기화가
+   * checked를 자동 갱신한다. rowSelection.trigger 'checkbox' 활성 시 이 renderer가 built-in 체크박스를 대체한다.
+   */
+  cellRenderer?: CellRenderer;
+  /** 코너(좌상단) 헤더 셀 렌더러. 반환은 HTMLElement 또는 문자열 */
+  headerRenderer?: (params: { columnId: string; header: string }) => HTMLElement | string;
+}
+```
+
+**셀 접근 헬퍼** (import 가능 — `ROW_HEADER_COLUMN_ID`, `getRowHeaderCell`, `getCornerCell`)
+
+| 헬퍼 | 시그니처 | 설명 |
+|------|----------|------|
+| `ROW_HEADER_COLUMN_ID` | `'_rowHeader'` | 행 헤더 컬럼 ID 상수 |
+| `getRowHeaderCell(ctx)` | `(DataRowContext) => CellInfo \| undefined` | `formatRow`의 data 행 컨텍스트에서 행 헤더 본문 셀 |
+| `getCornerCell(ctx)` | `(FormatHeaderContext) => HeaderCellInfo \| undefined` | `formatHeader` 컨텍스트에서 좌상단 코너 셀 |
+
+```js
+import { getRowHeaderCell, getCornerCell } from '@vmscloud/moz-ui-grid-core';
+
+// 본문: 행마다 상태 배지 그리기
+grid.formatRow.addHandler('rh', (info) => {
+  if (info.type !== 'data') return;
+  const cell = getRowHeaderCell(info.ctx);
+  if (cell) cell.element.dataset.state = info.ctx.rowState;
+});
+// 코너: 좌상단에 전체선택 체크박스 등
+grid.formatHeader.addHandler('corner', (ctx) => {
+  const corner = getCornerCell(ctx);
+  if (corner) corner.element.classList.add('my-corner');
+});
+```
+
+> 참고: `cellRenderer`를 주면 커스텀 렌더가 그려집니다(예: 체크박스 컬럼 대체). `rowHeader: true`(구 `showRowHeader: true`)는 **빈 셀**(너비 40, 체크박스 트리거 시 체크박스)만 그리는 축약형입니다 — 행 번호를 렌더하지 않습니다.
+
+---
+
+### 셀 속성 — CellAttributes / CellAttributesFn
+
+`FieldDef.cellAttributes`, `FieldDef.headerAttributes`에 사용.
+
+```typescript
+/** HTML 속성 맵 (정적) */
+type CellAttributes = Record<string, string>;
+
+/** 동적 셀 속성 콜백 — undefined 반환 시 속성 미적용 */
+type CellAttributesFn = (params: CellAttributeParams) => CellAttributes | undefined;
+
+interface CellAttributeParams {
+  value: CellValue;
+  rowData: Row;
+  rowIndex: number;
+  columnId: string;
+  rowId?: string | number;
+}
+```
+
+```typescript
+// 정적 속성
+{ id: 'name', cellAttributes: { class: 'cell-name', 'data-priority': 'high' } }
+
+// 동적 속성
+{
+  id: 'amount',
+  cellAttributes: ({ value }) => ({
+    style: Number(value) < 0 ? 'color: red' : 'color: blue',
+    class: 'amount-cell',
+  }),
+}
+```
+
+---
+
+### DataLoader 클래스 — 워커 기반 커스텀 데이터 로딩
+
+`LoaderConfig.module`이 default export하는 클래스의 베이스. 워커 안에서 실행되므로 DOM/localStorage 접근은 불가하고, `fetch`/`WebSocket`/`XMLHttpRequest` 등 네트워크 API는 사용 가능.
+
+```typescript
+abstract class DataLoader {
+  /** 메인스레드에서 전달받은 파라미터 (this.params로 접근) */
+  protected params: Record<string, unknown>;
+
+  /** 라이브러리 내부에서 호출 — grid.updateLoaderParams() 시 자동 동기화 (Object.assign 머지) */
+  updateParams(newParams: Record<string, unknown>): void;
+
+  /** [필수] 초기 데이터 로드. 플랫/트리 공통 */
+  abstract fetchData(): Promise<Row[]>;
+
+  /** [선택] 트리 자식 노드 lazy load (TreeConfig.lazyLoad=true 시 호출) */
+  fetchChildren?(nodeId: string | number): Promise<Row[]>;
+}
+```
+
+```typescript
+// my-loader.ts (별도 ES 모듈)
+import { DataLoader } from '@vmscloud/moz-ui-grid-core';
+import type { Row } from '@vmscloud/moz-ui-grid-core';
+
+export default class MyLoader extends DataLoader {
+  async fetchData(): Promise<Row[]> {
+    const res = await fetch('https://api.example.com/data', {
+      headers: { Authorization: `Bearer ${this.params.authToken}` },
+    });
+    return res.json();
+  }
+
+  async fetchChildren(nodeId: string | number): Promise<Row[]> {
+    const res = await fetch(`/api/tree/${nodeId}/children`);
+    return res.json();
+  }
+}
+
+// 그리드 생성
+new PureSheet(container, {
+  loader: {
+    module: new URL('./my-loader.ts', import.meta.url),
+    params: { authToken: getToken() },
+  },
+  fields: [...],
+});
+
+// 런타임 파라미터 갱신 (예: 토큰 리프레시)
+await grid.updateLoaderParams({ authToken: newToken });
+await grid.refreshLoaderData();
+```
+
+> **`InlineDataLoader`**: 동일 모듈 내 인라인 클래스를 사용하고 싶을 때(URL이 아닌 클래스 자체 전달) 내부적으로 사용되는 변형. 일반 사용 시에는 `LoaderConfig.module` URL 패턴 권장.
+
+---
+
+### UndoStack 클래스 — 공유 Undo/Redo
+
+`PureSheetConfig.undoStack`으로 외부 인스턴스를 주입할 때 사용. 여러 그리드가 하나의 스택을 공유 가능.
+
+```typescript
+class UndoStack {
+  constructor(options?: { maxSize?: number });  // @default 100
+
+  // ── Undo/Redo ──
+  undo(): boolean;
+  redo(): boolean;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  readonly undoCount: number;
+  readonly redoCount: number;
+  peekUndo(): Command | undefined;
+  peekRedo(): Command | undefined;
+  clear(): void;
+
+  // ── Batch 모드 ──
+  beginBatch(description?: string, options?: { skipUndo?: boolean }): void;
+  endBatch(options?: { silent?: boolean }): void;
+  readonly isBatching: boolean;
+
+  // ── 키보드 바인딩 ──
+  /** 컨테이너에 Ctrl+Z/Y 바인딩 (편집 중인 input/textarea/contenteditable에선 무시) */
+  attachKeyboard(container: HTMLElement): void;
+  detachKeyboard(): void;
+
+  // ── 라이프사이클 ──
+  destroy(): void;
+
+  // ── 이벤트 구독 ──
+  on(event: 'push' | 'undo' | 'redo' | 'clear' | 'stateChange' | 'batchEnd', handler: Function): Unsubscribe;
+  subscribe(handlers: Partial<UndoStackEvents>): Unsubscribe;
+}
+```
+
+```typescript
+// 여러 그리드 간 공유
+const sharedUndo = new UndoStack({ maxSize: 200 });
+sharedUndo.attachKeyboard(document.getElementById('page'));
+
+const grid1 = new PureSheet(el1, { undoStack: sharedUndo, fields, data });
+const grid2 = new PureSheet(el2, { undoStack: sharedUndo, fields, data });
+
+// 한 곳에서 Ctrl+Z → 어느 그리드든 마지막 작업 복원
+// 두 그리드에서 일어난 변경이 동일 시간순으로 스택에 쌓임
+```
+
+> 외부 주입 시 그리드의 개별 Ctrl+Z/Y는 비활성됨 — 공유 스택의 `attachKeyboard`로 일원화 권장. 공유 emitter 안전 규칙은 [docs/RULES.md](docs/RULES.md) 참조.
+
+---
+
+### Row 클래스 정적 팩토리
+
+`new Row(config)`로 인스턴스를 만들 수 있지만, 흔한 패턴은 정적 팩토리 메서드입니다.
+
+```typescript
+class Row {
+  constructor(config: RowConfig);
+
+  /** 집계 행 생성 (variant: 'subtotal' | 'grandtotal'). 데이터 변경 시 자동 재계산 */
+  static createAggregateRow(
+    aggregates: AggregateConfig[],
+    options?: {
+      id?: string;
+      pinned?: 'top' | 'bottom';                          // @default 'bottom'
+      variant?: 'subtotal' | 'grandtotal';                // @default 'subtotal'
+      height?: number;
+      className?: string;
+      labelColumn?: string;                                // 라벨 표시 컬럼
+      label?: string;                                      // @default '소계' | '총합계'
+    }
+  ): Row;
+
+  /** 총합계 행 단축 (variant='grandtotal' 고정) */
+  static createGrandTotalRow(aggregates: AggregateConfig[], options?: …): Row;
+
+  /** 소계 행 단축 (variant='subtotal' 고정) */
+  static createSubtotalRow(aggregates: AggregateConfig[], options?: …): Row;
+
+  // 인스턴스 속성
+  readonly id: string;
+  readonly variant: RowVariant;
+  readonly structural: boolean;
+  pinned: 'top' | 'bottom' | null;
+  data: Record<string, unknown>;
+  height: number | null;
+  // ... (그 외 내부 메서드는 BodyRenderer가 호출)
+}
+```
+
+```typescript
+import { Row, PureSheet } from '@vmscloud/moz-ui-grid-core';
+
+const totalRow = Row.createGrandTotalRow([
+  { columnId: 'salary', formatter: v => '$' + (v?.toLocaleString() ?? '0') },
+  { columnId: 'bonus' },                                  // FieldDef.aggregate 사용
+  { columnId: 'performance', func: 'avg' },
+], { pinned: 'bottom', labelColumn: 'name', label: '총합계' });
+
+grid.rows.addPinnedBottom(totalRow);
+
+// 또는 `grid.rows.addGrandTotal(aggregates)` 단축 API 사용 시 위 코드가 내부에서 호출됨
+```
+
+---
+
+### 에러 코드 전체 레퍼런스
+
+`psError(code)` / `psWarn(code)`로 발생하는 에러/경고. 자동완성 지원을 위한 상수는 `PS` 열거형.
+
+```typescript
+import { PS, psError, psWarn, ErrorMessages } from '@vmscloud/moz-ui-grid-core';
+```
+
+| 코드 | PS 키 | 의미 |
+|---|---|---|
+| **파라미터 검증 (PS001~)** | | |
+| `PS001` | `PS.REQUIRED` | 필수 값 누락 |
+| `PS002` | `PS.INVALID_TYPE` | 타입 불일치 |
+| `PS003` | `PS.EMPTY_FIELD` | 빈 문자열 거부 |
+| `PS004` | `PS.NON_EMPTY_ARRAY` | 비어있지 않은 배열 요구 |
+| `PS005` | `PS.INVALID_ENUM` | 허용 값 외 |
+| `PS006` | `PS.NON_NEGATIVE_INT` | 0 이상 정수 요구 |
+| `PS007` | `PS.POSITIVE_NUMBER` | 양수 요구 |
+| **데이터 (PS101~)** | | |
+| `PS101` | `PS.DATA_NOT_ARRAY` | data가 배열이 아님 |
+| `PS102` | `PS.ROW_NOT_OBJECT` | row가 객체가 아님 |
+| `PS103` | `PS.ROWID_REQUIRED` | rowId 필수 |
+| `PS104` | `PS.UPDATES_NOT_OBJECT` | updates가 객체가 아님 |
+| **피벗 (PS201~)** | | |
+| `PS201` | `PS.PIVOT_ROW_FIELDS` | rowFields 빈 배열 |
+| `PS202` | `PS.PIVOT_VALUE_FIELDS` | valueFields 빈 배열 |
+| **설정/충돌 (PS301~)** | | |
+| `PS301` | `PS.CONFIG_CONFLICT` | columnGroups + rowTemplate 충돌 |
+| `PS302~306` | `PS.SORTS_NOT_ARRAY` 등 | sorts/filters/rowIds/columnId/columns 검증 |
+| `PS307` | `PS.NO_COLUMN_GROUPS` | moveGroup인데 columnGroups 없음 |
+| `PS308` | `PS.SETORDER_NEEDS_GROUPS` | setOrder에 그룹 ID 누락 |
+| `PS309` | `PS.PIVOT_CONFIG_NULL` | pivotConfig 없음 |
+| `PS310` | `PS.SINGLE_EXPAND_ALL` | singleExpand에서 expandAll 호출 |
+| `PS311` | `PS.INVALID_LEVEL` | level < 0 |
+| **Worker (PS501~)** | | |
+| `PS501` | `PS.WORKER_SYNC_API` | Worker에서 getAllDataSync 호출 |
+| `PS502` | `PS.WORKER_DATA_DIRECT` | Worker 모드에서 `data` 직접 전달 불가 — `loader`를 사용할 것 |
+| **행 ID / 캐시 (PS601~)** | | |
+| `PS601` | `PS.ROW_ID_REQUIRED` | keyFields 미지정 + id 필드 없음 |
+| `PS602` | `PS.REFER_CACHE_REQUIRED` | 행 객체 API에 enableReferCache 필요 |
+| `PS603` | `PS.KEY_CONFLICT_COMMITTED` | 커밋된 데이터와 키 중복 |
+| `PS606` | `PS.KEY_LOAD_DUPLICATES` | loadData 중복 키 |
+| **IO (PS700~)** | | |
+| `PS700~715` | `PS.IO_*` / `PS.COMMIT_INVALID_CELLS` | export/import/commit 가드 (→ [grid.io 에러 코드 표](#에러-코드)) |
+
+```typescript
+// 자체 코드에서 PS 발화
+import { psError, psWarn, PS } from '@vmscloud/moz-ui-grid-core';
+
+if (!rowId) {
+  psError(PS.REQUIRED, 'myUpdate', { name: 'rowId' });
+  // throws Error('[PureSheet] PS001 myUpdate: \'rowId\'은(는) 필수 값입니다.')
+}
+```
+
+---
+
+### 기타 export 항목
+
+| Export | 위치 | 용도 |
+|---|---|---|
+| `createReactiveRow(deps, rowId)` | `@vmscloud/moz-ui-grid-core` | `ReactiveRow` 직접 생성 (래퍼/테스트용). 보통 `grid.rows.observeById(id)` 사용 권장 |
+| `InlineDataLoader` | `@vmscloud/moz-ui-grid-core` | 클래스 자체를 인라인 전달하는 변형 (URL 모듈 대신). 일반적으론 `LoaderConfig.module` 권장 |
+| `fieldToColumn(fieldDef)` | `@vmscloud/moz-ui-grid-core` | `FieldDef` → 내부 `ColumnDef` 변환. 외부 컬럼 메타 생성용 |
+| `configToInternalOptions(config)` | `@vmscloud/moz-ui-grid-core` | 외부 `PureSheetConfig` → 내부 옵션 객체 변환 |
+| `getGridMode(config)` | `@vmscloud/moz-ui-grid-core` | `'flat' \| 'pivot'` 판별 |
+| `getPivotConfig(config)` | `@vmscloud/moz-ui-grid-core` | `PivotConfig \| null` 추출 |
+| `RenderHookManager` | `@vmscloud/moz-ui-grid-core` | `grid.formatRow`이 반환하는 핸들러 매니저 클래스 (직접 사용 드뭄) |
+| `BatchCommand` | `@vmscloud/moz-ui-grid-core` | UndoStack 배치용 Command. 보통 `undoStack.batch()` 사용 권장 |
+| `MergedRange`, `CellMergeInfo` | `@vmscloud/moz-ui-grid-core` | 셀 병합 결과 메타 타입. `__merge` sidecar 필드 형태 |
+| `ClipboardCopyPayload`, `ClipboardPastePayload` | `@vmscloud/moz-ui-grid-core` | clipboard 이벤트 페이로드 타입 |
+| `TranslationMap`, `TranslationKey`, `PartialTranslationMap` | `@vmscloud/moz-ui-grid-core` | i18n 번역 키/맵 타입 (전체 키 목록은 `packages/core/src/i18n/translations/` 참조) |
+| `VirtualScroller`, `GridRenderer`, `BodyRenderer`, `HeaderRenderer`, `RowPool`, `HeaderCell`, `SelectionManager`, `EditorManager`, `ColumnManager`, `ClipboardManager`, `GroupManager`, `TreeManager`, `MasterDetailManager`, `MultiRowRenderer`, `PivotHeaderRenderer` | `@vmscloud/moz-ui-grid-core` | 저수준 UI 클래스. 보통 그리드가 내부에서 자체 인스턴스화 — 직접 인스턴스 생성은 매우 드문 고급 케이스 |
+| `grid.getDragReorderManager()` | PureSheet 인스턴스 | 저수준 DragReorder 매니저 직접 접근 (escape hatch). 보통 `grid.dragDrop.setConfig()` 사용 권장 |
+
+---
+
+## API 네이밍 규칙
+
+moz-ui-grid-core의 행 조작 API는 3가지 변형(variant) 패턴을 따릅니다:
+
+| 접미사 | 인자 | 설명 | 요구사항 |
+|--------|------|------|----------|
+| (없음) | 행 객체 (`Row`) | 행 객체 참조 기반 | `enableReferCache: true` 필수 |
+| `ById` | `rowId` (`string \| number`) | rowId 기반 | — |
+| `ByIndex` | `sourceIndex` (`number`) | 원본 데이터 인덱스 기반 O(1) | — |
+
+#### 예시
+
+```typescript
+// 행 객체 기반 (enableReferCache 필요)
+const row = await grid.getRowById('row-1');
+await grid.changes.updateCell(row, 'name', '수정됨');
+await grid.changes.deleteRow(row);
+await grid.changes.discard(row);
+const state = grid.changes.getRowState(row);
+
+// ById — rowId 기반
+await grid.changes.updateCellById('row-1', 'name', '수정됨');
+await grid.changes.deleteRowById('row-1');
+await grid.changes.discardById('row-1');
+const state2 = grid.changes.getRowStateById('row-1');
+
+// ByIndex — sourceIndex O(1)
+await grid.changes.updateCellByIndex(0, 'name', '수정됨');
+await grid.changes.deleteRowByIndex(0);
+await grid.changes.discardByIndex(0);
+const state3 = grid.changes.getRowStateByIndex(0);
+```
+
+> `enableReferCache`를 켜면 내부적으로 행 객체 → sourceIndex 매핑 캐시를 유지합니다. 이 캐시는 `loadData()` 호출 시 자동으로 재구성됩니다.
+
+> **참고 — ChangesAPI vs RowsAPI 선택 행 삭제 이름 차이**: `grid.changes.deleteSelectedRows()` ↔ `grid.rows.deleteSelectedRows()`. 동작은 동일하지만 두 네임스페이스의 컨벤션 차이로 이름이 다릅니다.
+
+---
+
+## 사용 예제
+
+다양한 시나리오의 코드 예제는 별도 파일로 분리되어 있습니다:
+
+➡ **[examples.md](examples.md)** — 약 30개 시나리오 (기본 그리드, Sub-API별 사용, Reactive React 통합, 이벤트, 선택 모드, 셀 병합, 피벗, Excel I/O 등)
+