open-grid 1.1.0 → 1.2.0

package/dist/types/core/CrossGridController.d.ts

@@ -0,0 +1,70 @@
+import { DataLayer } from './DataLayer.js';
+import { ColumnLayout } from './ColumnLayout.js';
+import { GridOptions, OpenGridInstance, Position, GridDropEvent } from './types.js';
+/**
+ * R7(§3.1 C8, §6-R7): 그리드 간 이동·매핑·drop 표면(`moveRowsTo`/`moveCheckedTo`/크로스변환 해석/
+ * 3단계 드롭 이벤트 발화)을 `OpenGrid` God object 에서 **동작 불변**으로 옮긴 것. `OpenGrid` 는
+ * 얇은 위임 공개 메서드만 남긴다(공개 API 불변 — R0 `public_api_surface.txt` 동결).
+ *
+ * 스트랭글러 원칙(A2): `crossGridRegistry`(프로세스 스코프 싱글턴, `CrossGridRegistry.ts`)는 지금은
+ * **AS-IS 유지**한다 — 주입 `GridRegistry` 로의 승격(C8, R-6c)은 R8 컴포지션 루트로 이연한다.
+ *
+ * cross-grid 이동은 **두 그리드**(source=this, target)를 동시에 다룬다. 각 `OpenGrid` 는 자신의
+ * CrossGridController 를 소유하므로, target 측 연산(insert/rowCount/컬럼/3단계 발화)은
+ * `getPeerController(target)` 로 얻은 상대 컨트롤러의 동명 메서드로 수행한다 — `this`(source) 와
+ * peer(target) 로 갈라 원본의 `this._x` / `targetGrid._x` 접근을 1:1 재현한다(회귀 0).
+ * **3단계 drop emit 순서(before→후 이동→after→complete, 각 source→target)는 정확히 보존한다.**
+ */
+export interface CrossGridControllerDeps<T extends Record<string, any> = any> {
+    /** GridDropEvent 의 sourceGrid/targetGrid 식별자 + 자기동일성 비교에 쓰는 소유 그리드. */
+    getSelf: () => OpenGridInstance<T>;
+    getData: () => DataLayer<T>;
+    getColLayout: () => ColumnLayout<T>;
+    getOptions: () => Required<GridOptions<T>>;
+    /** EventEmitter fan(this.emit) — 'gridDropBefore/After/Complete'/'gridDropMapping'. */
+    emit: (event: string, payload?: any) => void;
+    /** 공개 insertRow 위임(MutationService 경유) — target 삽입에 쓰인다. */
+    insertRow: (item: Partial<T>, position?: Position) => void;
+    /** 공개 deleteRow 위임(MutationService 경유) — source 제거에 쓰인다. */
+    deleteRow: (rowIndex: number | number[]) => void;
+    /** rowMgr.getChecked() — moveCheckedTo. */
+    getChecked: () => Array<{
+        rowIndex: number;
+    }>;
+    /** rowMgr.uncheckAll()(+재렌더) 공개 위임 — moveCheckedTo. */
+    uncheckAll: () => void;
+    /** 드래그 선택 집합 해석(_dragRowSet). OpenGrid 가 소유(RowDragDrop 배선과 공유). */
+    dragRowSet: (fromIndex: number) => number[];
+    /** 상대 그리드의 CrossGridController 획득(피어 연산 위임). 비 OpenGrid 대상은 undefined. */
+    getPeerController: (grid: OpenGridInstance<T>) => CrossGridController<T> | undefined;
+}
+export declare class CrossGridController<T extends Record<string, any> = any> {
+    private _deps;
+    constructor(deps: CrossGridControllerDeps<T>);
+    /** 이 그리드의 소유 인스턴스(GridDropEvent 식별자). */
+    getSelf(): OpenGridInstance<T>;
+    private _rowCount;
+    private _insertRow;
+    private _visibleLeafInfos;
+    /** 드래그 드롭 어댑터 → 공개 moveRowsTo 로 위임 */
+    handleCrossGridDrop(fromIndex: number, targetBodyEl: HTMLElement, targetIndex: number): void;
+    /**
+     * 이 그리드의 행들을 다른 그리드로 이동(move)한다. 드래그·화살표 셔틀 공통 경로.
+     * 3단계 이벤트(before→after→complete)와 crossGridMapping(필드 매핑)을 적용한다.
+     * @param target  대상 그리드
+     * @param sourceIndexes 이동할 (표시)행 인덱스들
+     * @param targetIndex 대상에서 삽입 위치 (생략 시 맨 끝에 추가)
+     * @returns 이동 성공 true, 취소/무효 false
+     */
+    moveRowsTo(target: OpenGridInstance<T>, sourceIndexes: number[], targetIndex?: number): Promise<boolean>;
+    /** 체크된 행을 다른 그리드로 이동 (화살표 셔틀용). 체크 없으면 무시. */
+    moveCheckedTo(target: OpenGridInstance<T>): Promise<boolean>;
+    /**
+     * 크로스그리드 이동의 행 변환 함수를 결정한다.
+     * 반환: null=변환 불필요(그대로) / 함수=변환 적용 / false=매핑 모달 취소(이동 중단)
+     */
+    private _resolveCrossTransform;
+    fireGridDropBefore(e: GridDropEvent<T>): boolean | void;
+    fireGridDropAfter(e: GridDropEvent<T>): void;
+    fireGridDropComplete(e: GridDropEvent<T>): void;
+}

package/dist/types/core/DetailManager.d.ts

@@ -19,6 +19,8 @@ export interface DetailManagerDeps<T extends Record<string, any> = any> {
     doRenderFull: (n: number) => void;
     emit: (ev: string, payload: any) => void;
     announce: (msg: string) => void;
+    /** i18n: 깊이 한계/펼침·접힘 announce 메시지 해석. / i18n: resolve depth-limit & expand/collapse announces. */
+    t: (key: string, params?: Record<string, string | number>) => string;
     /** 이 그리드 인스턴스의 중첩 깊이(0=최상위, 부모가 자식 생성 시 depth+1 주입). */
     getDepth: () => number;
     /** masterDetail.renderer 의 DetailRenderApi.grid 에 실어줄 인스턴스. */

package/dist/types/core/ExportManager.d.ts

@@ -11,6 +11,13 @@ export interface ExportDeps<T extends Record<string, any>> {
     getWsManager: () => WorksheetManager<T> | null;
     /** Phase 2: OverrideKernel.getStrategy 주입(슬롯 cellSerializer 도달용). */
     getStrategy?: <F extends Function>(slot: string, fallback: F) => F;
+    /** i18n: 인쇄 요약행 해석(미주입 시 ko 폴백). / i18n: resolve print summary row (ko fallback when absent). */
+    t?: (key: string, params?: Record<string, string | number>) => string;
+    /** i18n: 로케일 포맷 메타(인쇄 lang·날짜 로케일·Excel 폰트). / i18n: locale format meta (print lang, date locale, Excel font). */
+    getMeta?: () => {
+        intlLocale: string;
+        exportFont?: string;
+    };
 }
 export declare class ExportManager<T extends Record<string, any> = any> {
     private _d;

package/dist/types/core/ExtensionPointRegistry.d.ts

@@ -0,0 +1,92 @@
+import { OverrideKernel } from './OverrideKernel.js';
+import { TriggerManager } from './TriggerManager.js';
+import { StrategySlot, StrategyMap, OverrideLayerFn, OverrideCallOptions, OverridePoints, TriggerHandler } from './types.js';
+/**
+ * R11(§4 T3, §3.1 C7): 커널 위 **타입드 확장점 레지스트리**.
+ *
+ * `OverrideKernel` 은 실행 엔진(가역·host-agnostic·0줄소스, 불가침 — 한 줄도 안 건드린다).
+ * 이 레지스트리는 그 위에 얹는 **타입드 정면**으로, 확장 표면을 명시·타입·발견가능하게 만든다.
+ * 확대의 부담이 "코어 편집(하드코딩 게이트 추가)" 에서 "데이터 등록" 으로 이동한다(A4).
+ *
+ * 3범주(§4.1): (a) strategy 슬롯(값·계산) · (b) 컴포넌트 registry(렌더훅 포함) · (c) lifecycle hook.
+ * 이중구조(T-ζ): "SemVer 보증 카탈로그"(타입드 좁은 문) + "best-effort 임의 인터셉트 탈출구"(UC-11,
+ * 넓은 문). 문서·타입에서 둘을 명확히 분리하되 넓은 문을 닫지 않는다.
+ */
+/**
+ * 렌더 참여 훅(§4.2). 렌더층이 셀마다 참조하는 교체가능 지점.
+ *  - `gate()` : 미설정(등록 override/strategy 없음)이면 false → 렌더층이 resolve 를 호출조차 안 함(제로코스트).
+ *  - `resolve(rowIndex, field)` : 게이트 통과 시 렌더층에 줄 값(표시문자열/클래스/aria 등). null=미참여.
+ * 첫 등록 항목 = 기존 `getDisplayValue` 표시텍스트 동작(동일 출력 → 회귀0). 이후 새 훅은 등록만으로 열린다.
+ */
+export interface RenderHook<R = string> {
+    readonly id: string;
+    gate(): boolean;
+    resolve(rowIndex: number, field: string): R | null;
+}
+/**
+ * 렌더훅 레지스트리(§4.2). 하드코딩 게이트 1개를 데이터 구동 훅 목록으로 일반화.
+ * 등록순 보존(첫 항목=표시텍스트). 렌더층은 이름을 하드코딩하지 않고 `resolve(id,…)` 로 순회 참조한다.
+ */
+export declare class RenderHookRegistry {
+    private _order;
+    private _hooks;
+    register(hook: RenderHook<any>): void;
+    get(id: string): RenderHook<any> | undefined;
+    has(id: string): boolean;
+    /** 등록순 훅 id 목록(첫 항목=표시텍스트). */
+    ids(): string[];
+    /**
+     * 훅 해석. 미등록이거나 게이트가 닫혀 있으면 resolve 를 **호출하지 않고** null 반환(제로코스트 보존).
+     */
+    resolve(id: string, rowIndex: number, field: string): any;
+    /** 게이트가 열린(활성) 훅 id — 렌더층 스윕/디버깅용. */
+    activeIds(): string[];
+}
+/** 단일 커밋 초크포인트(C5 MutationService)가 트리거로 감싸는 변경 연산. */
+export type MutationOp = 'setData' | 'insertRow' | 'deleteRow' | 'writeCell';
+/** 카탈로그(매니페스트) 엔트리 — R-3d "지원 확장점 카탈로그" 산출물. */
+export interface ExtensionCatalogEntry {
+    readonly name: string;
+    readonly category: 'strategy' | 'renderHook' | 'lifecycle' | 'override' | 'escapeHatch';
+    readonly signature: string;
+}
+export interface ExtensionRegistryDeps {
+    /** 실행 엔진(불가침). 레지스트리는 소유·위임할 뿐 내부를 건드리지 않는다. */
+    kernel: OverrideKernel;
+    /** before/after 취소가능 훅을 부착할 커밋 초크포인트의 TriggerManager(늦은-null 견딤). */
+    getTrigMgr: () => TriggerManager;
+}
+export declare class ExtensionPointRegistry<T = any> {
+    private _deps;
+    private _renderHooks;
+    constructor(deps: ExtensionRegistryDeps);
+    get renderHooks(): RenderHookRegistry;
+    /** 렌더훅 등록(코어 편집 없이 렌더층 참여 지점 추가 — OCP). */
+    registerRenderHook(hook: RenderHook<any>): void;
+    /** 렌더층이 매 셀 호출 — 미등록/게이트닫힘이면 제로코스트 null. */
+    resolveRenderHook(id: string, rowIndex: number, field: string): any;
+    /** 타입드 슬롯 등록(SemVer 보증 카탈로그). 런타임은 커널 문자열 기반(하위호환). */
+    strategy<K extends StrategySlot>(slot: K, fn: StrategyMap[K]): void;
+    strategy(slot: string, fn: Function): void;
+    /** 슬롯 조회(미등록 시 fallback — 매니저 read API, 제로코스트 철학 보존). */
+    getStrategy<F extends Function>(slot: string, fallback: F): F;
+    hasStrategy(slot: string): boolean;
+    /** 타입드 오버로드: 좁은 "지원됨" 카탈로그(IDE 발견). */
+    override<K extends keyof OverridePoints<T>>(name: K, fn: OverrideLayerFn, opts?: OverrideCallOptions): void;
+    /** 탈출구(UC-11): 임의 메서드 best-effort 인터셉트 — 넓은 문은 닫지 않는다. */
+    override(name: string, fn: OverrideLayerFn, opts?: OverrideCallOptions): void;
+    /**
+     * 취소가능 before 훅. 단일 커밋 초크포인트(C5 MutationService)가 이미 제공하는 `before:{op}`
+     * 트리거를 **타입드로 표면화**할 뿐 메커니즘을 재배선하지 않는다. 핸들러가 `ctx.cancel()` 하면 변경 취소.
+     */
+    beforeMutation(op: MutationOp, handler: TriggerHandler): void;
+    /** 관찰(취소불가) after 훅 — 커밋 완료 후 `after:{op}` 트리거를 타입드로 표면화. */
+    afterMutation(op: MutationOp, handler: TriggerHandler): void;
+    /** 등록한 MutationHook 해제. */
+    offMutation(when: 'before' | 'after', op: MutationOp, handler: TriggerHandler): void;
+    /**
+     * 타입드 확장점 카탈로그. render 훅 항목은 실제 등록분(`renderHooks.ids()`)에서 유도 —
+     * 유령 확장점(등록 없는 카탈로그 엔트리) 금지(DeMarco M9b).
+     */
+    catalog(): ExtensionCatalogEntry[];
+}

package/dist/types/core/FilterPanel.d.ts

@@ -1,6 +1,8 @@
 import { FilterItem } from './types.js';
 export type FilterApplyFn = (field: string, items: FilterItem[]) => void;
 export type FilterClearFn = (field: string) => void;
+/** i18n: 필터 라벨 로케일 해석기(주입 없으면 전역 t). / i18n: filter-label resolver (global t when not injected). */
+export type FilterPanelT = (key: string, params?: Record<string, string | number>) => string;
 /**
  * 컬럼 헤더 필터 드롭다운 패널.
  * 단일 인스턴스를 재사용(열릴 때 위치 재계산).
@@ -10,8 +12,9 @@ export declare class FilterPanel {
     private _field;
     private _onApply;
     private _onClear;
+    private _t;
     private _outsideHandler;
-    constructor(container: HTMLElement, onApply: FilterApplyFn, onClear: FilterClearFn);
+    constructor(container: HTMLElement, onApply: FilterApplyFn, onClear: FilterClearFn, t?: FilterPanelT);
     open(field: string, anchorEl: HTMLElement, currentFilters: FilterItem[]): void;
     close(): void;
     get isOpen(): boolean;

package/dist/types/core/FilterSelect.d.ts

@@ -1,4 +1,6 @@
 import { FilterItem } from './types.js';
+/** i18n: 필터 셀렉트 라벨 해석기(주입 없으면 전역 t). / i18n: filter-select label resolver (global t when not injected). */
+export type FilterSelectT = (key: string, params?: Record<string, string | number>) => string;
 export interface FilterSelectOption {
     value: string;
     text: string;
@@ -74,7 +76,8 @@ export declare class FilterSelectPanel {
     private _config;
     private _onFilter;
     private _onReset;
-    constructor(container: HTMLElement, config: FilterSelectConfig, onFilter: FilterFn, onReset: ResetFn, gridId?: string);
+    private _t;
+    constructor(container: HTMLElement, config: FilterSelectConfig, onFilter: FilterFn, onReset: ResetFn, gridId?: string, t?: FilterSelectT);
     /**
      * 컬럼의 옵션 목록을 계산한다.
      *

package/dist/types/core/FindBarManager.d.ts

@@ -9,16 +9,22 @@ export interface FindBarDeps<T extends Record<string, any>> {
     getVs: () => VirtualScroll | null;
     getPagination: () => Pagination | null;
     doRender: () => void;
+    /** i18n: 메시지 해석(라벨/placeholder/aria/카운트 배지). / i18n: resolve labels/placeholder/aria/count badge. */
+    t: (key: string, params?: Record<string, string | number>) => string;
 }
 export declare class FindBarManager<T extends Record<string, any> = any> {
     private _bar;
     private _input;
     private _count;
+    private _lbl;
+    private _close;
     private _filter;
     private _d;
     constructor(deps: FindBarDeps<T>);
     get findFilter(): string;
     init(container: HTMLElement): void;
+    /** i18n: 상주 크롬 라벨을 활성 로케일로 다시 그린다(setLocale 경로). / i18n: repaint resident chrome labels in the active locale (setLocale path). */
+    refreshLabels(): void;
     open(): void;
     close(): void;
     private _apply;

package/dist/types/core/FormulaController.d.ts

@@ -0,0 +1,81 @@
+import { DataLayer } from './DataLayer.js';
+import { ColumnLayout } from './ColumnLayout.js';
+import { FlatRowModel } from './FlatRowModel.js';
+import { GridOptions } from './types.js';
+import { RecalcCoordinator, RecalcSummary } from './formula/RecalcCoordinator.js';
+import { FormulaErrorCode, FormulaGridAccessor } from './formula/types.js';
+/**
+ * R7(§3.1 C9, §6-R7): F3 수식 표면(accessor 조립·recalc flush·에러 표현 + 공개 수식 API)을
+ * `OpenGrid` God object 에서 **동작 불변**으로 옮긴 것. `OpenGrid` 는 얇은 위임 공개 메서드만
+ * 남긴다(공개 API 불변 — R0 `public_api_surface.txt` 동결).
+ *
+ * 스트랭글러 원칙(A2): `RecalcCoordinator`(`formula/` 헤드리스 코어)는 여전히 `OpenGrid` 가
+ * 소유·재생성(setData 시 rowId 재발급 대응)하며, 이 컨트롤러에는 `*Deps` 클로저 역전 패턴으로
+ * **주입**만 된다 — `getRecalc()` 는 재할당(resetFormulaState)을 견디는 지연 getter 다.
+ * `RecalcCoordinator`/`FormulaGraph`/`FormulaEvaluator` 자체는 한 줄도 수정하지 않는다(불변 보존).
+ *
+ * ⚠️ 네이밍: root `src/core/FormulaEngine.ts` 와 `src/core/formula/` 패키지는 별개다. 이 컨트롤러는
+ * `formula/` 패키지(RecalcCoordinator)에만 배선하며 root `FormulaEngine.ts` 와는 무관하다(병합 금지).
+ */
+export interface FormulaControllerDeps<T extends Record<string, any> = any> {
+    getData: () => DataLayer<T>;
+    getColLayout: () => ColumnLayout<T>;
+    getFlatModel: () => FlatRowModel;
+    /** OpenGrid 가 소유하는 RecalcCoordinator. setData 시 재생성되므로 지연 getter 로 읽는다. */
+    getRecalc: () => RecalcCoordinator;
+    /** writeCell 이 적립한 dirty seed 집합(OpenGrid 소유). flushRecalc 가 소비·clear 한다. */
+    getDirtySeeds: () => Set<string>;
+    getOptions: () => Required<GridOptions<T>>;
+    /** EventEmitter fan(this.emit) — 'formulaRecalc'/'formulaError'/'formulaChange'. */
+    emit: (event: string, payload?: any) => void;
+    /** aria-live announce(C8.1 공용 인프라). */
+    announce: (msg: string) => void;
+    /** i18n: 수식 오류 announce/셀 라벨 해석(formulaError.* 통합 키). / i18n: resolve formula error announce/labels. */
+    t: (key: string, params?: Record<string, string | number>) => string;
+    /** 현재 가시 범위 렌더(this._doRender(...this._visRange())). afterRecalc 가 !skipRender 시 유발. */
+    doRenderWindow: () => void;
+}
+export declare class FormulaController<T extends Record<string, any> = any> {
+    private _deps;
+    constructor(deps: FormulaControllerDeps<T>);
+    /** writeCell 이 적립한 dirty seed 를 1회 onValuesChanged 로 소비하고 formulaRecalc 를 emit. */
+    flushRecalc(): void;
+    /**
+     * RecalcCoordinator 호출 결과를 표면화: formulaError 는 onFormulaError 콜백에서 이미 개별
+     * emit 되므로 여기선 배치당 1회 formulaRecalc 만 emit(C2.2 개명, `recalc`→`formulaRecalc`).
+     * Spike-A §8 교훈: 폐포가 큰 재계산은 large 플래그로 표시(가이드 문서화/모니터링용).
+     */
+    afterRecalc(summary: RecalcSummary, opts?: {
+        skipRender?: boolean;
+    }): void;
+    handleFormulaError(rowId: string, field: string, error: FormulaErrorCode): void;
+    private _formulaErrorMessageKo;
+    /** F3 accessor(C0/C0.5/C1) — FlatRowModel + ColumnLayout.visibleLeaves + DataLayer(rowId 기반)만 본다. */
+    buildAccessor(): FormulaGridAccessor;
+    setCellFormula(rowIndex: number, field: string, formula: string): void;
+    setCellFormulaByRowId(rowId: string, field: string, formula: string, rowIndexHint?: number): void;
+    getCellFormula(rowIndex: number, field: string): string | null;
+    hasCellFormula(rowIndex: number, field: string): boolean;
+    clearCellFormula(rowIndex: number, field: string): void;
+    getCellError(rowIndex: number, field: string): FormulaErrorCode | null;
+    getDependents(rowIndex: number, field: string): Array<{
+        rowIndex: number;
+        field: string;
+    }>;
+    getPrecedents(rowIndex: number, field: string): Array<{
+        rowIndex: number;
+        field: string;
+    }>;
+    recalculate(): void;
+    recalculateCell(rowIndex: number, field: string): void;
+    /** C3(F1 fill 전용): srcRowId/srcField 수식의 상대축만 dRow/dCol 오프셋한 새 수식 원문. */
+    offsetFormula(srcRowId: string, srcField: string, dRow: number, dCol: number): string;
+    /** F3 렌더 배선(§4.4/C7, §7.4/§7.5/§7.6) — 셀 수식 메타(없으면 null). */
+    getFormulaMeta(rowIndex: number, field: string): {
+        src: string;
+        error: FormulaErrorCode | null;
+        approx: boolean;
+    } | null;
+    /** F3-R13/MCCONNELL-03(P0): 정렬/필터 후 범위-보유(hasRangeRef) 수식 전부 dirty(§3.5). */
+    recalcRangeBearingFormulas(): void;
+}

package/dist/types/core/GridComposer.d.ts

@@ -0,0 +1,142 @@
+import { DataLayer } from './DataLayer.js';
+import { FlatRowModel } from './FlatRowModel.js';
+import { RowManager } from './RowManager.js';
+import { ColumnLayout } from './ColumnLayout.js';
+import { FormulaController } from './FormulaController.js';
+import { RecalcCoordinator } from './formula/RecalcCoordinator.js';
+import { CellEditManager } from './CellEditManager.js';
+import { ExportManager } from './ExportManager.js';
+import { FooterManager } from './FooterManager.js';
+import { KeyboardManager } from './KeyboardManager.js';
+import { SortFilterManager } from './SortFilterManager.js';
+import { FindBarManager } from './FindBarManager.js';
+import { CellEventHandler } from './CellEventHandler.js';
+import { RangeSelectionManager } from './RangeSelectionManager.js';
+import { GroupTreeManager } from './GroupTreeManager.js';
+import { DetailManager } from './DetailManager.js';
+import { ChartManager } from './ChartManager.js';
+import { OverrideKernel } from './OverrideKernel.js';
+import { LocaleRegistry } from './i18n/LocaleRegistry.js';
+import { GridRenderer } from './GridRenderer.js';
+import { VirtualScroll } from './VirtualScroll.js';
+import { Pagination } from './Pagination.js';
+import { WorksheetManager } from './WorksheetManager.js';
+import { GridOptions } from './types.js';
+/**
+ * R8(§3.1 C2, §3.3): GridComposer 가 조립하며 접근하는 OpenGrid 의 내부 표면.
+ *
+ * OpenGrid 의 private 필드/메서드를 구조적으로 미러링한다. 여기 열거된 멤버만이 컴포저가
+ * 조립 중 대입·참조하는 대상이며, 잘못된 이름/타입의 대입은 이 인터페이스로 인해 컴파일
+ * 타임에 잡힌다(순수 `any` host 보다 안전). `_mount` 본체(renderer/vs/pagination 등 DOM
+ * 배선)는 여전히 OpenGrid 가 소유하며, 컴포저는 mount 단계에서 `_mount()` 를 호출만 한다.
+ */
+export interface ComposerHost<T extends Record<string, any> = any> {
+    _container: HTMLElement;
+    _options: Required<GridOptions<T>>;
+    _data: DataLayer<T>;
+    _flatModel: FlatRowModel;
+    _rowMgr: RowManager<T>;
+    _colLayout: ColumnLayout<T>;
+    _formula: FormulaController<T>;
+    _recalc: RecalcCoordinator;
+    _editMgr: CellEditManager<T>;
+    _exportMgr: ExportManager<T>;
+    _footerMgr: FooterManager<T>;
+    _kbdMgr: KeyboardManager<T>;
+    _sfMgr: SortFilterManager<T>;
+    _findMgr: FindBarManager<T>;
+    _cellEvt: CellEventHandler<T>;
+    _rangeMgr: RangeSelectionManager<T>;
+    _grpMgr: GroupTreeManager<T>;
+    _detailMgr: DetailManager<T>;
+    _chartMgr: ChartManager;
+    _ovk: OverrideKernel;
+    /** i18n: per-instance 로케일 오버라이드 child(전역 localeRegistry 의 child). 미지정 시 null → 전역 직행. */
+    _locales: LocaleRegistry | null;
+    _renderer: GridRenderer | null;
+    _vs: VirtualScroll | null;
+    _pagination: Pagination | null;
+    _wsManager: WorksheetManager<T> | null;
+    _colWidths: number[];
+    _formulaDirtySeeds: Set<string>;
+    emit(event: string, ...args: any[]): any;
+    on(event: string, cb: (...args: any[]) => void): any;
+    off(event: string, cb: (...args: any[]) => void): any;
+    _announce(msg: string): void;
+    /** i18n: 메시지 해석(인스턴스 오버라이드 우선 → 활성 로케일 → ko → 키). / i18n: resolve a message. */
+    t(key: string, params?: Record<string, string | number>): string;
+    _doRender(startIndex: number, endIndex: number): void;
+    _visRange(): [number, number];
+    _renderHeader(): void;
+    _setFocusCell(ri: number, ci: number): void;
+    _handleRowDrop(fromIndex: number, toIndex: number): void;
+    _handleCellKeyEvt(name: 'cellKeyDown' | 'cellKeyUp' | 'cellKeyPress', e: KeyboardEvent): void;
+    writeCell(rowIndex: number, field: string, value: any): void;
+    writeCells(patches: Array<{
+        rowIndex: number;
+        field: string;
+        value: any;
+    }>): number;
+    getDisplayValue(rowIndex: number, field: string): string;
+    getMaskEnabled(field: string): boolean;
+    hasCellFormula(rowIndex: number, field: string): boolean;
+    getCellFormula(rowIndex: number, field: string): string | null;
+    setCellFormula(rowIndex: number, field: string, formula: string): void;
+    clearCellFormula(rowIndex: number, field: string): void;
+    /** override 커널 배선 후 컴포저가 단 1회 호출(구조적 순서 관문). */
+    _mount(): void;
+}
+/** OpenGrid 만 알아야 하는 재귀/전역 배선을 컴포저에 주입(컴포저의 OpenGrid 역-import 회피). */
+export interface ComposerHooks {
+    /** F2 서브그리드 재귀 생성(DetailManager createSubgrid). `new OpenGrid(host, {..,_detailDepth})`. */
+    createSubgrid: (host: HTMLElement, subgridOptions: any, depth: number) => any;
+}
+export interface CoreServicesToken {
+    readonly _phase: 'core';
+}
+export interface FormulaServicesToken {
+    readonly _phase: 'formula';
+}
+export interface ManagerRegistryToken {
+    readonly _phase: 'managers';
+}
+export interface OverrideKernelToken {
+    readonly _phase: 'ovk';
+}
+export interface MountedViewToken {
+    readonly _phase: 'mounted';
+}
+/** compose() 산출물 핸들. 모든 협력자는 host 에 대입되며, 이 핸들은 완료 표식이다. */
+export interface GridRuntime {
+    readonly mounted: MountedViewToken;
+}
+/**
+ * R8: 컴포지션 루트 / Phased Builder(§6-R8, §3.1 C2, §3.3).
+ *
+ * 생성자에 융합돼 있던 객체그래프 조립을 외재화한다. 각 build* 단계는 직전 단계의 산출
+ * 토큰을 매개변수로 요구하므로, 구성 순서 — 특히 `_ovk`(OverrideKernel) 생성이 `_mount()`
+ * 보다 먼저여야 한다는 불변식 — 이 **함수 시그니처의 위상정렬**로 강제된다: `mount(ovk)` 는
+ * `buildOverrideKernel()` 가 낸 토큰 없이는 호출 자체가 컴파일되지 않는다.
+ *
+ * 협력자 생성 순서는 기존 생성자와 바이트 동일(회귀0): core → formula/recalc → 11 매니저
+ * → override 커널 → mount. R2 런타임 가드는 belt-and-suspenders 로 유지된다.
+ */
+export declare class GridComposer {
+    static compose<T extends Record<string, any>>(host: ComposerHost<T>, container: string | HTMLElement, rawOptions: GridOptions<T>, hooks: ComposerHooks): GridRuntime;
+    /** Phase A: 컨테이너 해석 + 옵션 정규화 + 코어 서비스(DataLayer/FlatRowModel/RowManager/ColumnLayout). */
+    private static buildCoreServices;
+    /** Phase B: F3 수식 컨트롤러 + RecalcCoordinator(헤드리스 재계산 오케스트레이터). */
+    private static buildFormula;
+    /** Phase C: ~11 매니저(edit/export/footer/kbd/sortFilter/find/cellEvt/range/group/detail/chart). */
+    private static buildManagers;
+    /**
+     * Phase D: grid.override() 확장 커널 부착(★mount 전 — 초기 렌더의 footer/그룹/strategy 슬롯이
+     * 매니저 deps 의 getStrategy 클로저를 통해 host._ovk 를 참조하므로, _ovk 선생성이 필수다).
+     *
+     * 이 단계의 산출 토큰(OverrideKernelToken)이 mount() 의 매개변수라서, mount 는 이 단계
+     * 없이는 호출 자체가 불가능하다(§3.3-1 위상정렬 = R2 상처주석의 구조적 대체).
+     */
+    private static buildOverrideKernel;
+    /** Phase E: 배선 완료 후 단 1회 mount(§3.3-2). ovk 토큰 없이는 호출 불가 → 순서 구조적 강제. */
+    private static mount;
+}

package/dist/types/core/GridRenderer.d.ts

@@ -1,7 +1,41 @@
 import { DataLayer } from './DataLayer.js';
 import { RowDragDrop } from './RowDragDrop.js';
 import { MergeEngine } from './MergeEngine.js';
-import { ColumnDef, SortItem } from './types.js';
+import { AppearanceResolver } from './AppearanceResolver.js';
+import { ColumnDef, SortItem, CellRange, GridOptions, FilterItem } from './types.js';
+export interface RenderOptions extends Required<GridOptions> {
+    /** ColumnLayout.frozenCount — 고정 컬럼 수(헤더/본문 좌측 오프셋 계산). */
+    _frozenCount?: number;
+    /** SortFilterManager.filters — 필터 아이콘 활성 표시용. */
+    _activeFilters?: Record<string, FilterItem[]>;
+    /** DnD 핸들에 넘길 총 행수. */
+    _totalRows?: number;
+    /** CellEditManager.focusCell — 포커스 셀 하이라이트. */
+    _focusCell?: {
+        ri: number;
+        ci: number;
+    } | null;
+    /** RangeSelectionManager — 범위 선택 rect 하이라이트 재적용 재료(비-'cells' 모드면 없음). */
+    _rangeRects?: CellRange[];
+}
+export interface RenderFrame {
+    startIndex: number;
+    endIndex: number;
+    data: DataLayer<any>;
+    leaves: ColumnDef[];
+    widths: number[];
+    opts: RenderOptions;
+    offsetY: number;
+    totalHeight: number;
+    selectedRows: Set<number>;
+    checkedRows: Set<number>;
+    groupFlatRows?: Array<any> | null;
+    onGroupToggle?: ((key: string) => void) | undefined;
+    onTreeToggle?: ((nodeId: any) => void) | undefined;
+    extraOpts?: Record<string, any>;
+    mergeEngine?: MergeEngine | undefined;
+    detailApi?: DetailRenderContext | undefined;
+}
 export interface RendererCallbacks {
     onHeaderClick: (field: string, shiftKey: boolean) => void;
     onCellClick: (ri: number, ci: number, e: MouseEvent) => void;
@@ -20,11 +54,14 @@ export interface RendererCallbacks {
     onColDrop: (toIndex: number) => void;
     getColDragIdx: () => number | null;
     getDisplayText?: (rowIndex: number, field: string) => string | null;
+    resolveRenderHook?: (channel: string, rowIndex: number, field: string) => any;
+    getDisplayFormatter?: () => ((value: any, field: string, row: any) => string | null) | null;
     getFormulaMeta?: (rowIndex: number, field: string) => {
         src: string;
         error: string | null;
         approx: boolean;
     } | null;
+    t?: (key: string, params?: Record<string, string | number>) => string;
 }
 /**
  * F2(11_design_F2_v2.md §4/§5, C6/C10): renderBody 가 detail head/filler 분기·expander 셀을
@@ -53,14 +90,17 @@ export declare class GridRenderer {
     private _body;
     private _opts;
     private _cbs;
+    private _ap;
     private _cellMap;
     get bodyWrapper(): HTMLElement;
-    constructor(root: HTMLElement, opts: any, cbs: RendererCallbacks);
+    /** i18n: 렌더 로케일 해석기 — cbs.t(인스턴스 로케일) 우선, 미주입 시 전역 t. / i18n: cbs.t (instance locale) first, global t otherwise. */
+    private _t;
+    constructor(root: HTMLElement, opts: RenderOptions, cbs: RendererCallbacks, appearance?: AppearanceResolver);
     updateSize(totalHeight: number, headerHeight: number): void;
     /** 현재 렌더된 헤더 영역의 실제 높이(px). 헤더 줄바꿈으로 늘어난 높이를 레이아웃에 반영할 때 사용. */
     getHeaderHeight(): number;
-    renderHeader(headerRows: any[][], leaves: ColumnDef[], widths: number[], sortList: SortItem[], opts: any): void;
-    renderBody(startIndex: number, endIndex: number, data: DataLayer<any>, leaves: ColumnDef[], widths: number[], opts: any, offsetY: number, totalHeight: number, selectedRows: Set<number>, checkedRows: Set<number>, groupFlatRows?: Array<any> | null, onGroupToggle?: (key: string) => void, onTreeToggle?: (nodeId: any) => void, extraOpts?: Record<string, any>, mergeEngine?: MergeEngine, detailApi?: DetailRenderContext): void;
+    renderHeader(headerRows: any[][], leaves: ColumnDef[], widths: number[], sortList: SortItem[], opts: RenderOptions): void;
+    renderBody(frame: RenderFrame): void;
     getCellEl(rowIndex: number, colIndex: number): HTMLElement | undefined;
     /**
      * F2(§4.3 C6): full-width 디테일 패널을 body-absolute 로 그린다(병합 마스터셀 선례

package/dist/types/core/IconRegistry.d.ts

@@ -0,0 +1,55 @@
+/** render() 옵션. size 미지정 시 svg 는 viewBox/CSS 로 크기를 상속(width/height 속성 생략). */
+export interface IconRenderOptions {
+    /** px 정사각 크기(width=height). 미지정 시 속성 생략(CSS/컨테이너가 결정). */
+    size?: number;
+    /** 접근성 제목. 지정 시 <title> + role="img" 추가(스크린리더). 미지정 시 장식용(부모가 aria 담당). */
+    title?: string;
+    /** true → SVGElement(DOMParser) 반환. 기본 false → SVG 마크업 문자열. */
+    el?: boolean;
+}
+/**
+ * 시맨틱 ROLE → 아이콘 key(`BOOTSTRAP_ICONS` 의 symbolId) 기본 매핑.
+ * 렌더 코드는 이 역할 이름만 참조한다. key 교체는 이 표(혹은 register/setIcon)만 고치면 된다.
+ * 참고 스왑: `row.delete`→`trash3`(Bootstrap 의 표준 휴지통, task 의 'trash' 동족), `chart.line`→`graph-up`.
+ */
+export declare const DEFAULT_ICON_ROLES: Readonly<Record<string, string>>;
+/**
+ * IconRegistry — role → 글리프 본문(inner SVG markup) 해석 + svg 래핑.
+ *
+ * 저장 단위는 **글리프 본문 문자열**(<path>/<g> 마크업). register(role, svgOrKey) 는
+ *   - svgOrKey 가 `BOOTSTRAP_ICONS` 의 알려진 key 면 그 본문으로,
+ *   - 아니면 **원시 SVG 본문**(사용자 커스텀 <path…>)으로 저장한다.
+ * 부모 체인(_parent)으로 per-instance 오버라이드 레지스트리를 전역 위에 얹는다(멀티그리드 격리).
+ */
+export declare class IconRegistry {
+    private _roles;
+    private _parent;
+    constructor(seed?: Readonly<Record<string, string>>, parent?: IconRegistry);
+    /**
+     * role 에 글리프를 등록/교체. svgOrKey 가 알려진 아이콘 key 면 그 본문을, 아니면 원시 SVG
+     * 본문 마크업으로 간주한다(코어 편집 없이 아이콘 교체 — OCP).
+     */
+    register(role: string, svgOrKey: string): this;
+    /** role 이 (자신 또는 부모 체인에) 등록돼 있는가. */
+    has(role: string): boolean;
+    /** role → 글리프 본문(inner markup). 미등록이면 null(부모 체인까지 조회). */
+    resolveBody(role: string): string | null;
+    /** 이 레지스트리를 부모로 하는 자식(per-instance 오버라이드용) 생성. */
+    child(): IconRegistry;
+    /**
+     * role 을 `<svg viewBox=ICON_VIEWBOX>` 로 렌더. 기본 반환은 SVG 마크업 문자열(innerHTML 용);
+     * opts.el 이면 SVGElement. 미지원 role 은 빈 svg 폴백(never throw).
+     * 스킨 토큰: fill=currentColor(presentation attr) + stroke-linejoin=var(--og-icon-corner,miter).
+     */
+    render(role: string, opts?: IconRenderOptions): string | SVGElement;
+    /** 등록된 role 목록(자신만, 디버깅/테스트용). */
+    roles(): string[];
+}
+/**
+ * 프로세스 공유 기본 아이콘 레지스트리(시맨틱 role 시드 완료).
+ * CellRenderer 등 팩토리 생성 렌더러(인스턴스 컨텍스트 없음)가 이 초크포인트로 아이콘을 얻는다.
+ * per-instance 교체는 `grid.setIcon()`(이 레지스트리의 child) 로, 전역 확장은 `defineIconSet()` 로.
+ */
+export declare const iconRegistry: IconRegistry;
+/** 편의 정적 render — 공유 기본 레지스트리로 위임(`IconRegistry.render(role, opts)`). */
+export declare function renderIcon(role: string, opts?: IconRenderOptions): string | SVGElement;

package/dist/types/core/KeyboardManager.d.ts

@@ -24,6 +24,8 @@ export interface KeyboardDeps<T extends Record<string, any>> {
     handleRowDrop: (from: number, to: number) => void;
     doRender: () => void;
     announce: (msg: string) => void;
+    /** i18n: 행 이동 announce 해석. / i18n: resolve row-move announce. */
+    t: (key: string, params?: Record<string, string | number>) => string;
     emit: (event: string, ...args: any[]) => void;
     visRange: () => [number, number];
     handleCellKeyEvt: (eventName: 'cellKeyDown' | 'cellKeyUp' | 'cellKeyPress', e: KeyboardEvent) => void;