@vmscloud/moz-ui-grid-vue 0.2.9 → 0.2.10

package/docs/manual/reference.md

@@ -6,6 +6,12 @@
 
 > 📋 **사용 예제 코드는 별도 파일**: [examples.md](examples.md) — Sub-API별 사용, Reactive React 통합, 이벤트, 선택 모드, Excel I/O 등 약 30개 시나리오
 
+## 런타임 일반 옵션
+
+`await grid.setRuntimeOptions({ timeZone, preventKeyEdit, rowHeightChangeThreshold, migrateConfig })`는 지정한 키만 갱신합니다. 명시적 `undefined`는 각각 시간대 미지정, `true`, `2`, 콜백 없음으로 되돌립니다. React/Vue `coreConfig`에서도 이 키의 변경·제거는 공통 설정 큐에서 같은 인스턴스에 적용합니다. 열린 편집은 기존 설정으로 먼저 확정하며 확정 불가 시 변경을 거절합니다. 높이 임계값 변경은 측정된 높이를 지우지 않고 다음 측정부터 적용합니다. `preventKeyEdit`는 기존 옵션 의미만 바꾸며 keyFields identity 이전을 제공하지 않습니다.
+
+`keyFields`, `enableReferCache`, `engine`, `useWorker`, `workerFactory`, `undoStack` 등 생성/소유권 경계의 runtime 지원을 뜻하지 않습니다. 실제 인스턴스 교체 시에는 어댑터가 `GridChrome.captureReinitStateAsync()`를 기다린 뒤 이전 인스턴스를 파기합니다. 동기 `captureReinitState()`는 기존 직접 호출자용으로 남습니다.
+
 ## 날짜 시간대 계약 (`timeZone`)
 
 ```ts
@@ -21,7 +27,7 @@ await grid.io.fromExcel(legacyFile, { timeZone: 'UTC' });
 - 날짜만 표시하는 mask는 **시간 값을 자르지 않습니다**. XLSX 소수부에 시·분·초·밀리초가 유지됩니다. 임의의 날짜 문자열은 호스트 의존 파싱을 하지 않고 원문으로 남깁니다.
 - DST 해석은 Temporal `compatible`: 중복 시각은 **더 이른 instant**, 존재하지 않는 시각은 **gap 길이만큼 앞으로** 이동합니다. 따라서 DST 중복 시각의 두 instant를 Excel serial만으로 구분할 수 없습니다. 필요하면 UTC IO override를 사용하세요.
 - 잘못된 zone(빈 문자열 포함)은 `RangeError`입니다. UTC나 브라우저 zone으로 조용히 폴백하지 않습니다.
-- 코어에서는 생성 설정입니다. React/Vue provider 및 `coreConfig.timeZone` 변경은 기존 상태보존 재생성 경로로 반영됩니다.
+- 코어의 `await grid.setRuntimeOptions({ timeZone })` 및 React/Vue provider/`coreConfig.timeZone` 변경은 같은 인스턴스에 반영됩니다. 데이터 원본·dirty·undo 소유권은 교체하지 않습니다. 명시적 `undefined`는 기존 시간대 기본값으로 되돌립니다.
 
 ## 목차
 
@@ -202,6 +208,7 @@ grid.on('row:click', ({ rowIndex }) => {
 | **엔진** | | | |
 | `engine` | `'native'` | `'native'` | 데이터 처리 엔진. **`'aq'`(Arquero)는 제거됨** — 단일 엔진(native)만 남았습니다(ITSM-2026-002190) |
 | `useWorker` | `boolean` | `false` | Web Worker 사용 여부 |
+| `workerFactory` | `() => Worker` | — | `useWorker: true`에서 앱이 빌드한 신뢰 Worker entry 생성. `@vmscloud/moz-ui-grid-core/worker`의 `registerWorkerFunctions`와 `installProcessorWorker`로 함수·loader를 정적으로 등록한다. |
 | **저장본 호환** | | | |
 | `migrateConfig` | `GridConfigMigrator` | — | `applyConfig()` 가 옛 버전 저장본을 받았을 때 호출할 변환기. core 는 **호출 시점·순서만** 책임지고 변환 내용은 소비처(wrapper)가 소유 (→ [저장 스키마 버전](#저장-스키마-버전--gridconfigmigrator)) |
 | **UI** | | | |
@@ -215,8 +222,8 @@ grid.on('row:click', ({ rowIndex }) => {
 | `showStatusBar` | `boolean` | `true` | 상태 바 표시 |
 | `summaryRow` | `'none' \| 'pinnedTop' \| 'pinnedBottom'` | `'none'` | 집계(총합계) 행 표시 위치. `FieldDef.aggregate` 가 지정된 컬럼을 모아 core 가 행을 직접 소유하며, `getConfig()` 에 실려 레이아웃 프리셋으로 저장·복원된다 |
 | `alternatingRows` | `boolean` | `false` | 줄무늬 행 스타일 |
-| `rowStyle` | `string` | — | 행 CSS 스타일 |
-| `headerStyle` | `string` | — | 헤더 CSS 스타일 |
+| `rowStyle` | `string` | — | 행 높이 alias: `height:Npx`만 추출 (일반 CSS 적용 아님). truthy `rowHeight`가 우선 |
+| `headerStyle` | `string` | — | 헤더 높이 alias: `height:Npx`만 추출 (일반 CSS 적용 아님). truthy `headerHeight`가 우선 |
 | **컬럼 동작** | | | |
 | `resizableColumns` | `boolean` | `true` | 컬럼 리사이즈 허용 |
 | `reorderableColumns` | `boolean` | `true` | 컬럼 재정렬 허용 |
@@ -251,6 +258,10 @@ grid.on('row:click', ({ rowIndex }) => {
 
 #### 행 identity: 업무 키와 자동 ID
 
+- 명시한 `keyFields`는 비어 있지 않은 문자열 배열이어야 합니다. `null`, 배열 아닌 값, 빈 문자열 원소, 비문자열 원소, sparse hole은 초기화 오류입니다. 문자열을 trim하지 않으며 공백도 실제 원본 필드명입니다. 화면 `fields`에 없는 source-only 키도 허용합니다.
+- 자동 ID 전체 교체 성공 시 행·셀·그룹 선택과 active/focus를 비우며 core `data:loaded` 관찰자도 초기화된 상태를 봅니다. 실패하거나 stale인 load 완료로 현재 선택을 재초기화하지 않습니다. 같은 세션의 정렬·필터와는 다른 경계입니다.
+- `captureDataSession()` / `restoreDataSession(token)`은 일반 loadData와 다른 세션 이전 API입니다. [지원 범위와 실패 조건](runtime-contracts.md)을 참조하세요.
+
 - **업무 키 모드**: `keyFields: ['id']`처럼 비어 있지 않은 배열을 명시합니다. `enableReferCache` 기본값은 `false`이며, 자동 ID 모드가 누락된 업무 키 값을 대신 채워주지는 않습니다.
 - **자동 ID 모드**: `keyFields`를 **생략**하고 `enableReferCache: true`를 지정합니다. `keyFields: []`는 캐시 설정과 관계없이 초기화 오류이며, 키 생략 + 캐시 미지정/`false`도 빈 데이터부터 초기화 오류입니다. 생성 후 `await grid.waitForReady()`로 초기화 성공/실패를 확인하세요.
 - ID는 값이나 원본 객체가 아니라 **행 occurrence(배열에 등장한 각각의 행)** 에 속합니다. 값이 같거나 동일 객체를 두 번 넣어도 서로 다른 ID가 발급됩니다. frozen 원본 객체에도 ID 필드를 주입하지 않습니다.
@@ -737,7 +748,7 @@ interface GridConfigExport {
 
 `getConfig()` 는 아래 옵션의 **현재 값**을 싣고 `applyConfig()` 는 런타임에 실제로 되돌립니다: `theme`, `rowHeight`(가상 스크롤·동적 높이 캐시·Multi-Row·고정 행·병합 float 재계산), `headerHeight`, `rowSelection`/`cellSelection`/`cellSelectionImpliesRows`(바뀔 때만 재설정 — 현재 선택은 비움), `rowHeader`(행 헤더 컬럼 추가/제거, 선택 트리거가 요구하면 자동 활성), `editable`(편집기·붙여넣기·Delete 단축키), `tooltipMode`, `alternatingRows`, `showHeader`, `resizableColumns`/`reorderableColumns`(헤더 재빌드), `autoFitColumns`, `showStatusBar`, `summaryRow`, `locale`, `translations`.
 
-현재 값만 내보내고 **적용하지 않는** 키(값이 다르면 경고 `PS905`): `reorderableRows`/`showDragHandleColumn`(드래그 재정렬 배선이 생성 시점 전용 — `dragDropConfig` 소유), `keyFields`(행 식별자 — 바꾸려면 데이터 재적재 필요), `rowTemplate`(Multi-Row 런타임 전환 API 없음).
+`rowTemplate`은 `setRowTemplate(template | null)` 또는 `applyConfig`로 flat 레이아웃만 교체하고 데이터·원본·변경 기록·undo를 유지한다. `reorderableRows`/`showDragHandleColumn`은 `dragDrop.setConfig` 또는 `applyConfig`로 현재 인스턴스에 반영한다. 현재 값만 내보내고 적용하지 않는 키(값이 다르면 경고 `PS905`)는 `keyFields`이며, 행 식별자 변경 정책은 별도 검토 대상이다.
 
 **피벗 왕복** (F01) — flat → pivot 진입 직전의 flat 런타임 상태(컬럼 너비·고정·숨김·순서, 정렬/필터, 행 그룹)를 저장해 두었다가 flat 복귀(`pivot.setMode('flat')`, pivot→flat `applyConfig`) 시 그대로 되살리고 컬럼 그룹 헤더도 재빌드합니다. flat 저장본을 함께 적용하면 저장본 값이 이깁니다.
 
@@ -961,6 +972,7 @@ PureSheet 인스턴스는 기능별 Sub-API 네임스페이스를 제공합니
 | `getSelectedCellIds()` | `{rowId, columnId}[]` | 선택된 셀 목록 (셀 API 에는 `selected()` 가 없다 — 행 API `grid.rows.selected()` 와 다름) |
 | `getSelectedCells()` | `SelectedCell[]` | 선택된 셀 상세 (행 핸들·값 포함) |
 | `getActiveCell()` | `SelectedCell \| null` | 현재 활성 셀 — `selection.getActiveCell()`과 같음(화면 자리 기준, 아래 표 참고) |
+| `getFocusCell()` | `SelectedCell \| null` | 논리적 선택 끝점 — `selection.getFocusCell()`과 같음. [끝점·데이터 세션 상세](runtime-contracts.md) |
 | `getSelectedCellRowIds()` | `string[]` | 선택된 셀이 걸친 행 rowId 목록(중복 제거) |
 | `getSelectedCellColumnIds()` | `string[]` | 선택된 셀이 걸친 컬럼 columnId 목록(중복 제거) |
 | `getSelectedCellIndices()` | `number[]` | 선택된 셀이 걸친 행 sourceIndex 목록(중복 제거) |
@@ -977,6 +989,7 @@ rowSelection(선택된 행들)·cellSelection(선택된 셀 range)은 서로 다
 | `selection.getActiveRow()` | `RowHandle \| null` | 마지막 상호작용(행/셀 클릭) 행. 앵커 없으면 선택 행 마지막 폴백. traversal 앵커. **클릭한 행(rowId)을 계속 가리킨다** — 정렬·필터·접기 뒤에도 같은 행(`getActiveCell`과 다를 수 있음) |
 | `selection.getSelectedCells()` | `{ row: RowHandle; columnId }[]` | 현재 선택된 셀들 |
 | `selection.getActiveCell()` | `{ row: RowHandle; columnId } \| null` | 마지막 상호작용 셀. traversal 컬럼 유지용. 행은 **화면 자리 기준** — 셀 선택(`getSelectedCellIds`)·화면 강조·키보드 이동과 같은 행이다. 정렬·필터·그룹/트리 접기·디테일 펼침·드래그 재정렬로 그 자리에 다른 행이 오면 그 행, 자리가 그룹 배너·디테일 행이거나 사라지면 `null`. 행 선택 모드(셀 선택 없음)의 앵커와 고정(pinned) 행은 클릭한 행 그대로 |
+| `selection.getFocusCell()` | `SelectedCell \| null` | 현재 유효한 논리적 선택 끝점 `{ row: RowHandle, columnId }`. traversal 앵커인 `getActiveCell()`과 별개. 전체 선택 열거·비동기 fetch 없이 조회하며 확인 불가능한 identity는 null. [상세 계약](runtime-contracts.md) |
 | `selection.getSelectedGroups()` | `{ groupId: string; rowIds: RowId[] }[]` | 선택된 그룹 (`rowGroupConfig.selectable` — [그룹 배너 선택](#그룹-배너-선택-selectable)). `rowIds`는 리프 멤버 전체(접힘 무관, 중첩이면 하위 리프 전부). 옵션이 꺼져 있으면 `[]`. 행 선택 결과와 별개 |
 | `selection.selectGroupsByIds(groupIds, { addToExisting? })` | `string[]` | 그룹을 코드로 선택 — 배너 본문 클릭과 같은 의미([그룹 배너 선택](#그룹-배너-선택-selectable)). 적용된 groupId(입력 순서, 중복 제거)를 반환. 화면에 없는 그룹·옵션 꺼짐은 무시 |
 | `selection.selectGroupsByViewIndices(viewIndices, { addToExisting? })` | `string[]` | viewIndex로 그룹 선택. 그룹행이 아닌 위치는 무시. 나머지는 `selectGroupsByIds`와 같음 |
@@ -1173,7 +1186,7 @@ grid.columns.update('amount', { header: '판매금액' }, { updateSnapshot: true
 
 | 메서드 | 반환 | 설명 |
 |--------|------|------|
-| `addRow(row, idx?)` | `Promise<string \| number>` | 행 추가 (dirty) |
+| `addRow(row, idx?)` | `Promise<string \| number>` | 행 추가 (dirty). idx는 기존 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) |
@@ -1402,7 +1415,7 @@ interface AggregateContext {
 - `ctx.sum('x')` 등은 엔진이 계산한 값을 읽으므로 **그 조합이 선언돼 있어야** 합니다 — 컬럼 정의 `aggregate: 'sum'`(숨김 컬럼 가능) 또는 `rowGroupConfig.aggregates`의 `{ column: 'x', func: 'sum' }`. 선언되지 않은 조합을 읽으면 `PS312` 오류입니다(그룹행: `refresh()`가 거절, 고정 합계 행: `console.error` 후 빈 값). 고정 합계 행은 컬럼 정의 `aggregate`만 선언으로 봅니다.
 - 다단 그룹은 단계마다 그 단계 집계로 다시 계산하고, 필터·편집·행 추가 후에도 다시 계산합니다.
 - 결과가 `null`/`undefined`/`NaN`이면 그룹행 칸은 빈 칸(고정 합계 행은 기존 null 표기 `-`). 0 나누기는 함수에서 처리합니다.
-- 함수는 Worker로 보낼 수 없어 엔진(Main/Worker)은 문자열 집계만 계산하고 함수는 메인 스레드에서 그 결과로 실행합니다. **`values`는 메인 스레드에 멤버 행이 있을 때만 채워지고 Worker 모드에서는 빈 배열**입니다 — 두 모드 모두에서 맞으려면 `ctx`를 쓰세요.
+- 일반 Main 모드는 기존 inline 함수를 그대로 사용합니다. Worker 모드는 `{ workerFunction: 'app:aggregate', params: ... }` 참조를 사용하며, 앱 Worker entry에 정적으로 등록된 함수가 실제 멤버 `values`와 `ctx`를 Worker 안에서 받습니다. 메인 계산 왕복·fallback은 없고 inline 함수·미등록 ID는 오류입니다. 함수의 마지막 인수는 descriptor의 `params`입니다.
 - 함수형 컬럼 aggregate가 하나라도 있으면 선언된 문자열 컬럼 aggregate를 모두(숨김·배너 아래 컬럼 포함) 계산만 합니다. 이 값들은 배너 글자에 나오지 않습니다.
 - 함수형 aggregate는 프리셋(JSON)에 저장되지 않고 코드가 소유합니다 — `applyConfig`가 지우거나 문자열로 바꾸지 않으며, wrapper 집계 탭은 "사용자 함수"로 표시하고 변경을 막습니다.
 - **선택 영역 집계**(`rows.selectionAggregates()`·`selection:changed`의 `aggregates`·컨텍스트 메뉴): 함수형 컬럼은 그 컬럼 셀이 선택된 행들을 **하나의 그룹처럼** 보고 함수를 적용합니다. `columns[]` 항목은 `aggregate: 'custom'`, `value` = 함수 값(`formattedValue`는 그 컬럼 mask 적용), `count` = 숫자 셀 수(기존 의미)입니다. `ctx.sum('x')` 등은 선택 범위에 `x` 셀이 없어도(숨김 컬럼 포함) 선택된 **행** 기준이고 `ctx.group`은 없습니다. 읽을 수 있는 조합은 고정 합계 행과 같이 컬럼 정의의 문자열 `aggregate`이며, 미선언 조합은 `console.error`(PS312) 후 빈 값입니다. 화면 밖 선택 행·그룹/트리 모드(데이터 행만)·Worker 모드 모두 같은 값이고, 컬럼 전체 선택(Ctrl+Space/Ctrl+A)은 표시 중인 전체 데이터 행으로 계산합니다(이때만 행을 한 번 받아 옵니다). `total`(합계·평균·개수·최소·최대)은 기존대로 **선택 셀 값** 기준입니다. wrapper 컨텍스트 메뉴는 `custom`에 함수 라벨 없이 `헤더 값`만 표시합니다.
@@ -2425,7 +2438,7 @@ const unsub = row.subscribe(() => {
 | `visible` | `boolean` | 가시성 여부 |
 | `pinned` | `'top' \| 'bottom' \| null` | 고정 상태 |
 | `cssClass` | `string \| null` | CSS 클래스 |
-| `height` | `number \| null` | 행 높이 (px) |
+| `height` | `number \| null` | 행별 높이(px). 본문·데이터 고정 행 및 가상 스크롤 좌표에 적용. `null`은 기본/자동 측정 높이로 복원 |
 | `changedFields` | `string[] \| null` | 변경된 필드 목록 |
 
 #### 쓰기 메서드
@@ -2487,6 +2500,7 @@ grid.off('cell:click', handler);
 
 | 이벤트 | 페이로드 | 설명 |
 |--------|---------|------|
+| `tree:stateChanged` | `{ collapsedNodes: string[], source: 'user' \| 'api' }` | 네이티브 트리 접기·펼치기 완료 후 최종 접힘 상태. 단일/전체/깊이/경로 및 setState 복원을 포함하며 같은 상태는 통지하지 않음. 사용자 클릭·키보드는 user, 공개 API는 api. 구독 반환 함수로 해제. |
 | `row:click` | `{ row, rowId, viewIndex, sourceIndex, rowIndex, event }` | 행 클릭. 좌표는 아래 **셀·행 이벤트 좌표** 참조 (`rowIndex`는 하위호환 값 — 원본 위치 아님) |
 | `row:dblclick` | `{ row, rowIndex, event }` | (예약) 현재 코드 경로에서는 발행되지 않음 — `cell:dblclick`을 사용하세요 |
 | `row:pinned` | `{ row, position }` | 행 고정 |
@@ -2867,7 +2881,7 @@ interface MasterDetailConfig {
 
 - 유지할 때도 디테일 내용은 `renderer`로 **다시 그립니다**(이전 cleanup 실행 후 호출) — 바뀐 데이터를 반영하기 위해서입니다. 디테일 안의 입력값·스크롤 같은 DOM 상태는 남지 않습니다.
 - `keyFields` 없이 자동 행 ID(`enableReferCache: true`)를 쓰면 `loadData`마다 ID가 새로 붙으므로 재조회 뒤에는 접힙니다. 재조회 후에도 펼침을 유지하려면 `keyFields`를 지정하세요.
-- 그룹·트리 노드를 접어 안 보이게 된 행의 디테일은 지금처럼 접힙니다(이 옵션과 무관).
+- `visible:false`·Ctrl+H·데이터 행 고정·그룹/트리 접힘으로 안 보이는 동안 디테일은 표시하지 않습니다. 기본(`true`)은 행 키의 펼침 상태를 기억하여 다시 보일 때 복원하고, `false`는 기존처럼 접습니다.
 - `singleExpand: true`와 함께 쓰면 마지막으로 펼친 한 행만 유지됩니다.
 
 ### GroupConfig
@@ -3700,11 +3714,13 @@ interface PerformanceTiming {
 
 ### 데이터 로더 — LoaderConfig
 
+> 현재 Worker는 런타임 임의 URL import가 아니라 **앱 Worker entry의 정적 loader map**을 사용합니다. `module`은 map의 정확한 키입니다. [Worker 등록·데이터 세션 계약](runtime-contracts.md)을 먼저 확인하세요.
+
 Web Worker에서 직접 데이터를 페칭하는 모듈을 지정합니다. 메인스레드 비경유로 UI 블로킹 없음.
 
 ```typescript
 interface LoaderConfig {
-  /** DataLoader를 default export하는 ES 모듈 URL */
+  /** 앱 Worker entry의 loaders map에 등록한 키 (URL이면 문자열 표현과 일치해야 함) */
   module: URL | string;
   /** 초기 파라미터 (직렬화 가능한 plain object). 런타임에 grid.updateLoaderParams()로 갱신 */
   params?: Record<string, unknown>;
@@ -3724,8 +3740,10 @@ export default class MyLoader extends DataLoader {
 // 그리드 생성
 new PureSheet(container, {
   enableReferCache: true,
+  useWorker: true,
+  workerFactory: () => new Worker(new URL('./app-grid.worker.ts', import.meta.url), { type: 'module' }),
   loader: {
-    module: new URL('./my-loader.ts', import.meta.url),
+    module: 'app:data', // worker entry: installProcessorWorker({ loaders: { 'app:data': MyLoader } })
     params: { authToken: 'abc' },
   },
   fields: [...],
@@ -4347,7 +4365,7 @@ interface GridConfigSnapshot {
 **현재 직렬화 안 되는 옵션 (향후 추가 여지)**:
 - `engine`, `useWorker`, `dynamicRowHeights`, `rowHeightChangeThreshold`
 - `enableReferCache`, `preventKeyEdit`
-- `rowStyle`, `headerStyle` (CSS 문자열 — `rowHeight`/`headerHeight` 와 일부 중복)
+- `rowStyle`, `headerStyle` (`height:Npx` 추출 alias — 일반 CSS 적용 아님)
 - `PivotConfig.sorts` / `PivotConfig.filters` (피벗 전용 — `GridConfigSnapshot.sorts/filters` 와 별개)
 
 ---
@@ -5006,7 +5024,7 @@ interface CellAttributeParams {
 
 ### DataLoader 클래스 — 워커 기반 커스텀 데이터 로딩
 
-`LoaderConfig.module`이 default export하는 클래스의 베이스. 워커 안에서 실행되므로 DOM/localStorage 접근은 불가하고, `fetch`/`WebSocket`/`XMLHttpRequest` 등 네트워크 API는 사용 가능.
+앱 Worker entry의 `installProcessorWorker({ loaders })` map에 등록하는 클래스의 베이스. 워커 안에서 실행되므로 DOM/localStorage 접근은 불가하고, `fetch`/`WebSocket`/`XMLHttpRequest` 등 네트워크 API는 사용 가능.
 
 ```typescript
 abstract class DataLoader {
@@ -5046,8 +5064,10 @@ export default class MyLoader extends DataLoader {
 // 그리드 생성
 new PureSheet(container, {
   enableReferCache: true,
+  useWorker: true,
+  workerFactory: () => new Worker(new URL('./app-grid.worker.ts', import.meta.url), { type: 'module' }),
   loader: {
-    module: new URL('./my-loader.ts', import.meta.url),
+    module: 'app:data', // worker entry: installProcessorWorker({ loaders: { 'app:data': MyLoader } })
     params: { authToken: getToken() },
   },
   fields: [...],
@@ -5058,7 +5078,7 @@ await grid.updateLoaderParams({ authToken: newToken });
 await grid.refreshLoaderData();
 ```
 
-> **`InlineDataLoader`**: 동일 모듈 내 인라인 클래스를 사용하고 싶을 때(URL이 아닌 클래스 자체 전달) 내부적으로 사용되는 변형. 일반 사용 시에는 `LoaderConfig.module` URL 패턴 권장.
+> **Worker loader 경계**: `LoaderConfig.module`에 클래스나 임의 URL을 전달해 동적 실행시키는 방식은 지원하지 않습니다. 앱에서 loader 클래스를 정적으로 import하고 등록하세요. `InlineDataLoader`라는 export의 존재가 런타임 클래스 전달 지원을 뜻하지 않습니다.
 
 ---
 

package/docs/manual/reference_vue.md

@@ -251,6 +251,9 @@ type MozGridCoreProps =
 
 ### 초기화·편집·XLSX 설정 전달
 
+- `sourceRevision?: unknown`은 wrapper prop입니다. 외부 데이터셋 교체 때만 바꾸며 `coreConfig` 안에 넣지 않습니다. `ready`의 두 번째 인수 `chrome.getReadyContext()`에서 `{ reason, dataRestored, sourceRevision }`를 확인하세요. [세션 보존·Worker·끝점 API 상세](runtime-contracts.md).
+- 같은 소스 재생성은 지원되는 Main flat/tree 세션의 baseline·dirty·undo/redo를 복원한 뒤 ready를 다시 발생시킵니다. Worker/active pivot(깨끗하거나 미로드 상태도 포함)·미지원 custom history는 차단됩니다. busy capture 실패는 기존 인스턴스를 유지하지만 **자동 대기·재시도하지 않습니다**. 정책 확대는 별도 결정 사항입니다.
+
 - **행 식별 설정은 필수**입니다. 업무 키가 있으면 `coreConfig.keyFields`를 명시하고, 키 없이 시작하려면 `coreConfig.enableReferCache: true`를 설정하세요(기본 `false`). 두 설정 모두 생략하거나 `keyFields: []`를 전달하면 초기화할 수 없습니다. 원본 `id` 필드를 자동으로 키로 선택하지 않습니다. 자동 ID 수명과 행 객체 참조 계약은 [코어 Config](reference.md#config-설정)를 참조하세요.
 - 내장 숫자/날짜시간 편집기는 별도 래퍼 prop이 아니라 `coreConfig.fields[].editor`로 전달합니다. 아래 설정을 기존 `coreConfig`에 병합하세요.
 
@@ -606,6 +609,9 @@ const xAxisLabelFormatter = (label: string) => (label.startsWith('#') ? label.sl
 
 ### 준비 완료·재생성·서식 콜백
 
+- 높이 alias `rowStyle`/`headerStyle` 변경도 동일 인스턴스에 적용합니다. 일반 CSS가 아니라 기존 `height:Npx` 추출만 지원합니다. wrapper의 숫자 높이 기본값은 32이므로 생략/undefined에서는 alias가 가려집니다. 명시적 숫자 0은 기존 PS007 경고 후 유효한 alias를 사용하지만, 0을 남기고 alias만 제거해 유효 높이가 0이면 기존 applyConfig 검증(PS903)으로 거절합니다. 숫자 높이와 alias를 함께 생략/undefined로 되돌리면 32로 복원합니다. 가려진 alias만 변경하면 imperative 높이를 덮지 않습니다.
+- 일반 런타임 설정(`rowHeight`, `headerHeight`, `editable`, `rowTemplate`, 행 drag 등)은 공통 coordinator가 진행 작업 종료를 기다리고 최신 요청으로 병합해 동일 인스턴스에 적용합니다. 이 경우 원본·dirty·undo를 유지하고 `ready`를 다시 발생시키지 않습니다. 실제 인스턴스 교체의 capture/restore 경로는 별개입니다. `reconcileCoreConfig` 결과의 선택적 `completion: Promise<void>`는 설정 적용 완료/실패를 나타내며 어댑터가 이를 기다립니다.
+
 - `@ready(grid, chrome)`는 현재 인스턴스의 코어 초기화와 reinit 상태 복원 뒤에 발생합니다. unmount나 다음 reinit으로 폐기된 인스턴스의 대기 작업은 복원·emit을 이어서 실행하지 않습니다. 현재 인스턴스의 초기화 실패는 콘솔 오류로 보고하고 `ready`를 발생시키지 않습니다.
 - 설정 watch는 mount 훅 안에서 **동기 등록**됩니다. 첫 `ready`를 기다리는 동안의 prop 변경도 반영하며, unmount 시 Vue의 컴포넌트 scope와 함께 해제됩니다.
 - `ready()`는 `waitForReady()`의 초기화 완료를 뜻하며 `coreConfig.data`로 시작된 모든 비동기 데이터 로딩 완료를 보장하지 않습니다. 데이터 완료는 `@data:loaded` 또는 직접 호출한 `await grid.loadData(rows)`로 확인하세요.
@@ -785,9 +791,10 @@ g.chrome                            // 원시 GridChrome | null (legacy 호환)
 |--------|----------|------|
 | `ready` | `async ready(): Promise<void>` | 코어 `waitForReady` 대기 → `isDataLoaded=true` → 카운트/푸터/빈 상태 갱신. 생성 후 1회 호출 |
 | `on` | `on(event, handler): Unsubscribe` | 코어 이벤트 구독 + chrome 구독 목록에 추적(destroy 시 자동 정리). `Unsubscribe` 반환 |
-| `reconcileCoreConfig` | `reconcileCoreConfig(next: PureSheetConfig): { reinitRequired: boolean }` | 변경된 코어 설정 키만 타겟 setter로 적용. 런타임 setter 없는 키(rowHeight/headerHeight/keyFields/selection/editable/mode/locale/...) 변경 시 `{ reinitRequired: true }` 반환 → 어댑터가 상태 보존 reinit. disposed 시 early-return |
-| `captureReinitState` | `captureReinitState(): GridChromeReinitState` | 소멸 직전 인스턴스에서 `{ core: getConfig(), customCell, columnFormat }` 스냅샷(래퍼 전용 상태 포함) |
-| `restoreReinitState` | `async restoreReinitState(state): Promise<void>` | 새 인스턴스에서 `applyConfig(core)` 후 `columnFormat`(base) → `customCell`(override) 재적용. 절대 reject 안 함(부분 복원 허용) |
+| `reconcileCoreConfig` | `reconcileCoreConfig(next: PureSheetConfig, sourceRevision?: unknown): { reinitRequired: boolean }` | 변경된 코어 설정 키만 타겟 setter로 적용. 런타임 setter 없는 키(rowHeight/headerHeight/keyFields/selection/editable/mode/locale/...) 변경 시 `{ reinitRequired: true }` 반환 → 어댑터가 상태 보존 reinit. disposed 시 early-return |
+| `getReadyContext` | `getReadyContext(): Readonly<GridChromeReadyContext>` | `{ reason: 'initial' \| 'configuration' \| 'source-replacement', dataRestored: boolean, sourceRevision?: unknown }`. 복원 성공 여부와 데이터 교체 경계 확인 |
+| `captureReinitState` | `captureReinitState(next?: PureSheetConfig, sourceRevision?: unknown): GridChromeReinitState` | destroy 전에 core/layout·dataSession·wrapper 상태 캡처. 같은 소스 capture 실패는 throw하여 기존 인스턴스를 보존. 소스 교체는 이전 세션 capture 생략 |
+| `restoreReinitState` | `async restoreReinitState(state): Promise<void>` | 새 인스턴스에서 `applyConfig(core)` 후 `columnFormat`(base) → `customCell`(override) 재적용. 실패는 reject하며 성공 ready를 내보내지 않음. dataSession을 포함한 GridChromeReinitState를 새 GridChrome 생성자의 네 번째 인수로도 전달 |
 | `getCoreConfig` | `getCoreConfig(base?: PureSheetConfig): PureSheetConfig` | INPUT 형태의 현재 코어 설정 빌드(`update:coreConfig` 역류용). 라이브 mode/group/pivot 키만 오버레이, `fields`/`data` 참조 보존, sorts/filters 뷰 상태 미포함 |
 | `onConfigChange` | `onConfigChange(cb: () => void): Unsubscribe` | 내부 코어 변경(pivotConfig + groupConfig.columns) 구독 → `update:coreConfig` 역류. UI 옵션/차트/커스텀 셀은 미포함. 반환 unsub도 destroy 추적 |
 | `syncAppliedConfig` | `syncAppliedConfig(next: PureSheetConfig): void` | reconcile 기준선(`appliedConfig`) 강제 동기화 → 직후 prop-back reconcile을 no-op으로(중복 피벗 재계산 회피) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vmscloud/moz-ui-grid-vue",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "MozGrid - Vue 3 wrapping library for @vmscloud/moz-ui-grid-core",
   "license": "ISC",
   "type": "module",
@@ -81,7 +81,7 @@
   },
   "dependencies": {
     "@vmscloud/moz-ui-grid-core": "^0.1.47",
-    "@vmscloud/moz-ui-grid-wrapper": "^0.1.21",
+    "@vmscloud/moz-ui-grid-wrapper": "^0.1.23",
     "bytebuffer": "^5.0.1",
     "crypto-js": "^4.2.0",
     "echarts": "^5.5.0",