open-grid 1.0.8 → 1.1.1

package/dist/types/core/range/ClipboardCodec.d.ts

@@ -0,0 +1,30 @@
+import { CellRange, FlatRowRefLike } from './types.js';
+export interface ClipboardQueryContext {
+    fieldAt(ci: number): string | undefined;
+    getCellValue(ri: number, field: string): any;
+    /** override 데모 정합: 있으면 표시값 우선(§5.1 주석) */
+    getDisplayText?(ri: number, field: string): string;
+}
+/** R행×C열 범위 → TSV(행마다 \t조인, 행간 \n) — 엑셀 왕복 호환(UR-4 AC). */
+export declare function rangeToTSV(rect: CellRange, ctx: ClipboardQueryContext): string;
+/** TSV 문자열 → 2D 블록(행×열 문자열 배열). 빈 문자열은 1×1 빈 블록. */
+export declare function parseTSV(text: string): string[][];
+export interface PastePlanContext {
+    resolveFlatRow(ri: number): FlatRowRefLike;
+    fieldAt(ci: number): string | undefined;
+    /** 기본 true(잠금 없음) */
+    isEditable?(rowId: string, field: string): boolean;
+}
+export interface PastePlanItem {
+    rowIndex: number;
+    field: string;
+    action: 'value' | 'skip';
+    value?: any;
+    reason?: string;
+}
+/**
+ * 붙여넣기 소스 블록(2D) + 타깃 range → 플랜.
+ * 소스가 타깃보다 작으면 타일 반복, 크면(또는 같으면) 블록 그대로 전개(타깃 크기 무시) — 엑셀 규칙(FR-4 AC).
+ * `r % blockRows`/`c % blockCols` 단일 공식으로 두 경우 모두 성립(작을 때=주기 반복, 클 때=outRows=blockRows라 항상 r 자신).
+ */
+export declare function buildPastePlan(block: string[][], target: CellRange, ctx: PastePlanContext): PastePlanItem[];

package/dist/types/core/range/FillEngine.d.ts

@@ -0,0 +1,63 @@
+import { OGDecimal } from '../OGDecimal.js';
+import { CellRange, FillAxis, FillMode, FlatRowRefLike } from './types.js';
+export interface DetectSeriesResult {
+    kind: 'copy' | 'arith' | 'text-suffix';
+    /** 자연순서(위→아래 / 왼→오) diff. arith/text-suffix에만 존재 */
+    step?: OGDecimal;
+    /** 자연순서로 파싱된 수치값(arith) 또는 접미 숫자부(text-suffix) */
+    values?: OGDecimal[];
+    /** text-suffix의 공통 접두문자열 */
+    prefix?: string;
+}
+/**
+ * 소스 라인(주축과 직교하는 한 행 또는 한 열의 값 배열, 자연순서=위→아래/왼→오) → 감지 결과.
+ * 경계 AC(REQ-24): [1,2,4]→copy, [5]→copy, ["a","b"]→copy, ["Q1","Q2"]→arith 아님 text-suffix(step=1).
+ */
+export declare function detectSeries(sourceLine: any[]): DetectSeriesResult;
+/**
+ * 감지 결과 + 자연순서 소스라인으로 target 거리 d(1..N, 소스에 가장 가까운 셀=1)의 값을 외삽.
+ * 방향 부호(§3.4.1 "위/왼쪽 채우면 step 부호 반전")는 axis에 따라 base/부호를 선택해 처리한다.
+ */
+export declare function extrapolateValue(result: DetectSeriesResult, sourceLine: any[], axis: FillAxis, d: number): any;
+export interface FillPlanItem {
+    rowIndex: number;
+    field: string;
+    action: 'value' | 'setFormula' | 'skip';
+    value?: any;
+    formula?: string;
+    reason?: string;
+}
+export interface FillPlanResult {
+    items: FillPlanItem[];
+    /** C3.2 보존된 수식 셀 수(announce용) */
+    skippedFormula: number;
+}
+export interface FillPlanContext {
+    resolveFlatRow(ri: number): FlatRowRefLike;
+    fieldAt(ci: number): string | undefined;
+    getCellValue(ri: number, field: string): any;
+    /** 기본 true(잠금 없음) */
+    isEditable?(rowId: string, field: string): boolean;
+    /** 기본 false(수식 없음) */
+    hasCellFormula?(rowId: string, field: string): boolean;
+    /** C3.1: 상대 ref 오프셋 수식 생성(F3 제공) */
+    offsetFormula?(rowId: string, field: string, dRow: number, dCol: number): string;
+    /** rangeSelection.fillOverwriteFormula(C3.2 opt-in) */
+    overwriteFormula?: boolean;
+    /** Ctrl-강제-copy: 수식 원문 복제(오프셋 없음) */
+    forceCopyFormula?: boolean;
+}
+/**
+ * 소스 rect → 타깃 rect 채우기 플랜(§3.5). 주축과 직교하는 각 라인(행 또는 열) 별로 독립 처리(§3.4.1).
+ * non-data 행(kind!=='data')은 항상 skip(C0.3/CON-5). mode==='series'가 detectSeries로 'copy'에
+ * 귀결되면(경계 케이스) 그대로 copy 타일 반복으로 처리된다(설계가 의도한 동작).
+ */
+export declare function buildFillPlan(source: CellRange, target: CellRange, axis: FillAxis, mode: FillMode, ctx: FillPlanContext): FillPlanResult;
+/**
+ * 현재 선택 rect에서 Ctrl+D(아래로)/Ctrl+R(오른쪽으로) 채우기의 source/target rect 산출(순수 함수).
+ * 1행(D)/1열(R)뿐이면 채울 대상이 없어 null.
+ */
+export declare function ctrlFillSourceTarget(rect: CellRange, axis: 'down' | 'right'): {
+    source: CellRange;
+    target: CellRange;
+} | null;

package/dist/types/core/range/RangeModel.d.ts

@@ -0,0 +1,53 @@
+import { CellCoord, CellRange, Direction, RangeIdentity, RangeModelHost } from './types.js';
+/** anchor/focus → 정규화된 CellRange(§2.3). 역방향 드래그(anchor>focus)도 min/max로 정규화. */
+export declare function normalize(a: CellCoord, f: CellCoord): CellRange;
+export declare class RangeModel {
+    private _host;
+    private _anchor;
+    private _focus;
+    private _identity;
+    private _rects;
+    private _hasSelection;
+    private _additive;
+    constructor(host: RangeModelHost);
+    get hasSelection(): boolean;
+    getAnchor(): CellCoord;
+    getFocus(): CellCoord;
+    getIdentity(): RangeIdentity;
+    /** 공개 API 재료(C4): 정규화 rects (없으면 []). MVP는 길이 ≤1. */
+    getRangeSelection(): CellRange[];
+    /** 공개 API 재료(C4): getRangeSelection()[0] ?? null */
+    getActiveRange(): CellRange | null;
+    /** 복사/채우기 소스 결정용 별칭(§5.1 getPrimaryRect) */
+    getPrimaryRect(): CellRange | null;
+    /** 정렬/필터 후에도 유지되는 실제 rowId 집합의 현재 flat 위치(오름차순, 화면밖=-1 제외). */
+    getProjectedFlatRows(): number[];
+    /** pointerdown. shift=true면 기존 anchor 유지(있을 때만), 아니면 새 1x1 anchor. */
+    beginDrag(ri: number, ci: number, opts?: {
+        additive?: boolean;
+        shift?: boolean;
+    }): void;
+    /** pointermove. */
+    updateFocus(ri: number, ci: number): void;
+    /** pointerup — 확정 + 정체성 스냅샷(§2.5). */
+    endDrag(): void;
+    get additive(): boolean;
+    /** 클릭(비-Shift): 새 1×1 anchor(FR-1). */
+    click(ri: number, ci: number): void;
+    /** Shift+클릭: anchor 유지, focus만 갱신. anchor 없으면 click으로 위임(UC-2 예외). */
+    shiftClickExtend(ri: number, ci: number): void;
+    /** anchor 고정, focus만 1칸 이동(격자 경계 clamp). 편집 우선순위(C9)는 호출측(KeyboardManager)이 가드. */
+    extendFocus(dir: Direction): void;
+    setRect(rect: CellRange): void;
+    /** clearRangeSelection API 재료. */
+    clear(): void;
+    /** 현재 rect를 rowId 집합 × field 집합으로 스냅샷(display-index는 렌더용 투영일 뿐). */
+    snapshotIdentity(): void;
+    /**
+     * 정렬/필터 후 호출(onModelReproject 구독 지점). rowId 집합 → 현재 flat 좌표로 재투영.
+     * 사라진 행(flatIndexOfRowId === -1)은 정체성에는 남되 투영(rects)에서는 제외된다(불연속 허용).
+     * MVP는 단일 bounding rect로 투영(§2.2 rects 길이 1 방침) — 남아있는 행들의 min/max로 계산.
+     */
+    reproject(): void;
+    private _recompute;
+}

package/dist/types/core/range/RangeQuery.d.ts

@@ -0,0 +1,16 @@
+import { CellRange } from './types.js';
+export interface RangeQueryContext {
+    fieldAt(ci: number): string | undefined;
+    getCellValue(ri: number, field: string): any;
+}
+/** rect 값 2D 배열(FR-6). */
+export declare function getRangeValues(rect: CellRange, ctx: RangeQueryContext): any[][];
+export interface RangeStats {
+    sum: string;
+    avg: string;
+    count: number;
+    min: string;
+    max: string;
+}
+/** 숫자 셀에 대해 OGDecimal 기반 sum/avg/count/min/max(FR-6). 숫자 셀이 없으면 null. */
+export declare function getRangeStats(rect: CellRange, ctx: RangeQueryContext): RangeStats | null;

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

@@ -0,0 +1,47 @@
+import { CellRange } from '../types.js';
+export type { CellRange };
+/** 방향성 원시 좌표. ri=flat/visual index(C0.2), ci=visibleLeaves index(C0.4). */
+export interface CellCoord {
+    ri: number;
+    ci: number;
+}
+export type Direction = 'up' | 'down' | 'left' | 'right';
+export type FillAxis = Direction;
+export type FillMode = 'copy' | 'series';
+/** 범위 정체성(C0.5) — display-index가 아니라 stable 집합으로 저장. */
+export interface RangeIdentity {
+    /** 선택된 data 행의 stable _ogRowId 집합 (정렬/필터를 넘어 보존) */
+    rowIds: string[];
+    /** 선택된 열의 field 집합 (visibleLeaves.field) */
+    fields: string[];
+}
+/** FlatRowModel.resolveFlatRow가 반환하는 참조(C0.3). */
+export interface FlatRowRefLike {
+    kind: 'data' | 'group' | 'tree' | 'detailHead' | 'detailFiller';
+    rowId?: string;
+    dataIndex?: number;
+    displayIndex?: number;
+}
+/**
+ * F1이 좌표 해소·재투영을 위해 필요로 하는 최소 계약 모양(C0.3 FlatRowModel + visibleLeaves).
+ * 실제 구현(baseline FlatRowModel/ColumnLayout)은 이 형태를 만족하는 어댑터를 배선 단계에서 주입한다.
+ */
+export interface RangeModelHost {
+    /** flat/visual 행 총수 */
+    count(): number;
+    /** flat index → 참조(kind/rowId 등). 없으면 kind 판별 불가 상태를 반환해야 함(C0.3) */
+    resolveFlatRow(flatIndex: number): FlatRowRefLike;
+    /** stable rowId → 현재 flat index. 없으면(접힘/필터아웃) -1 */
+    flatIndexOfRowId(rowId: string): number;
+    /** flat index → stable rowId (data/tree만, 그 외 null) */
+    rowIdOfFlat(flatIndex: number): string | null;
+    /** 현재 visibleLeaves의 field 목록(순서=ci) */
+    visibleFields(): string[];
+}
+/** 채우기 프리뷰(핸들 드래그 중) — 커밋 전 임시 상태 자료(§2.2 FillPreview). */
+export interface FillPreview {
+    source: CellRange;
+    target: CellRange;
+    axis: FillAxis;
+    mode: FillMode;
+}

package/dist/types/core/renderers/CellRenderer.d.ts

@@ -1,4 +1,4 @@
-import { ColumnDef } from '../types.js';
+import { ColumnDef, RendererDef } from '../types.js';
 export interface RenderContext<T = any> {
     value: any;
     row: T;
@@ -8,11 +8,26 @@ export interface RenderContext<T = any> {
     isSelected: boolean;
     rowState: 'none' | 'added' | 'edited' | 'removed';
     displayValue?: string | null;
+    /** R1b: per-instance displayFormatter 전략(값·필드·행 → 표시문자열|null). Number/Date 렌더러가
+     *  ctx.value 위에 적용한다(모듈전역 없이 멀티그리드 격리). null 반환/미설정 시 기본 포맷 폴백.
+     *  ※ getDisplayValue override(text 경로의 ctx.displayValue)와 달리 **전략만** 적용 — 숫자/날짜의
+     *    기본 포맷(천단위·통화·정밀도)을 보존하고 그룹모드 인덱스 불일치를 피한다. */
+    displayFormatter?: ((value: any, field: string, row: any) => string | null) | null;
+    /** C7(15_cross_contracts.md/F3-R14): 이 셀에 F3 셀 수식이 있으면 true — ColumnDef.formula 재평가를 skip. */
+    hasCellFormula?: boolean;
 }
 export interface CellRenderer {
     render(ctx: RenderContext): HTMLElement;
 }
-export declare function setDisplayFormatterResolver(resolver: ((value: any, field: string, row: any) => string | null) | null): void;
+/**
+ * R1(OOP 리팩터, DIP 수정): 과거엔 formatNumber/formatDate 가 host 참조가 없어 **모듈 전역**
+ * resolver 로 displayFormatter 슬롯에 도달했다. 그 전역은 매 OpenGrid 생성자가 덮어써,
+ * 한 페이지에 그리드가 여럿이면 마지막 그리드의 포매터가 전 그리드에 새는 P0 정합성 결함이었다.
+ * → 전역을 제거했다. 이제 displayFormatter 는 **per-instance 안전 경로 하나**로만 흐른다:
+ *   OpenGrid.getDisplayValue(슬롯 읽기) → GridRenderer 가 RenderContext.displayValue 로 주입
+ *   → 각 셀 렌더러(Text/Number/Date)가 ctx.displayValue 를 우선 사용.
+ * formatNumber/formatDate 는 전역 상태 0 의 순수 포맷 함수로 환원했다(출력 동일, 회귀 0).
+ */
 /**
  * 컬럼에 formula가 있으면 OGDecimal로 평가해 표시값(string)을 반환.
  * formula가 없으면 null 반환 → 기존 ctx.value 사용.
@@ -60,6 +75,10 @@ export declare class CheckboxRenderer implements CellRenderer {
 export interface ButtonRendererDef {
     type: 'button';
     label?: string | ((value: any, row: any) => string);
+    /** R12c: 라벨과 함께 표시할 아이콘 role/key(renderIcon). 미지정 시 라벨만(기존과 동일). */
+    icon?: string;
+    /** 아이콘 위치(기본 'left'). */
+    iconPos?: 'left' | 'right';
     buttonClass?: string;
     style?: string;
 }
@@ -147,4 +166,23 @@ export declare class HtmlRenderer implements CellRenderer {
 export declare class BarcodeRenderer implements CellRenderer {
     render(ctx: RenderContext): HTMLElement;
 }
+/**
+ * R10(§6-R10, §2.5 R-4c, §3.1 C11): `createRenderer` 이중 switch 를 `Map<typeName, factory>`
+ * 레지스트리로 대체한다. 내장 타입은 모듈 로드시 부트스트랩 등록(아래 switch 와 동일 매핑),
+ * `createRenderer` 는 레지스트리로 해석하고 미등록 타입은 기존과 동일하게 TextRenderer 로 폴백한다.
+ * `registerRenderer(typeName, factory)` 로 코어 편집 없이 커스텀 렌더러를 추가할 수 있다(OCP).
+ *
+ * 등록은 **프로세스 전역**(내장은 불변에 가깝고, 커스텀 등록은 defaultOverride 와 동형의 전역 정책).
+ * 인스턴스별 스코핑은 R11/R12(ExtensionPointRegistry)의 후속 작업으로 남긴다.
+ *
+ * 팩토리는 `(col, def)` 를 받는다. `def` 는 RendererDef 객체 경로에서만 채워지며(문자열/col.type
+ * 경로에서는 undefined), 원 switch 의 세 컨텍스트(col.type / 문자열 / 객체) 동작을 정확히 보존한다:
+ *  - image/progress/sparkline/rating/template 은 def(설정 객체) 없이는 원래 TextRenderer 로 떨어졌으므로
+ *    def 유무로 게이트한다(문자열 렌더러명만 준 미완성 설정 = 기존과 동일 폴백).
+ */
+export type RendererFactory = (col: ColumnDef, def?: RendererDef) => CellRenderer;
+/** 커스텀 셀 렌더러 타입을 코어 편집 없이 등록(OCP). 프로세스 전역. */
+export declare function registerRenderer(typeName: string, factory: RendererFactory): void;
+/** 등록 여부 조회(내부/테스트용). */
+export declare function hasRenderer(typeName: string): boolean;
 export declare function createRenderer(col: ColumnDef): CellRenderer;

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

@@ -1,3 +1,5 @@
+import { FormulaErrorCode } from './formula/types.js';
+import { RangeStats as _RangeStats } from './range/RangeQuery.js';
 export type DataType = 'string' | 'number' | 'date' | 'boolean' | 'select' | 'radio' | 'img' | 'html' | 'barcode';
 export type { MaskType, MaskDef } from './MaskingEngine.js';
 export type SelectionMode = 'single' | 'row' | 'multiple' | 'cells';
@@ -103,12 +105,144 @@ export interface SelectionEvent<T = any> {
     rowIndexes: number[];
     cells?: CellRange[];
 }
+/**
+ * CellRangeSemantics — CellRange 의미 규범(C0.4, 15_cross_contracts.md). 소유자 = F1(범위 선택).
+ * F3(수식 ref)·F4(차트 소스)는 이 의미로만 CellRange 를 소비한다.
+ *  - startRow/endRow : flat/visual index (C0.2 — FlatRowModel 이 다루는 화면 표시 순서).
+ *    group/tree pseudo-row, (F2 도입 후) detail head/filler 도 포함한 인덱스 공간이며,
+ *    display index(정렬/필터만 반영, group/tree 제외)와 다르다.
+ *  - startCol/endCol : `ColumnLayout.visibleLeaves` 인덱스(숨김 컬럼 제외). 숨김 컬럼은
+ *    좌표를 흔들지 않되, 언하이드 시 재렌더로 좌표 표시(A1 등)가 갱신된다.
+ *  - 선택 자체의 영속 정체성은 이 인덱스가 아니라 stable (rowId × field) 앵커로 저장한다
+ *    (C0.5) — CellRange 는 어디까지나 "현재 화면에 투영된" 사각형 표현이다.
+ */
 export interface CellRange {
     startRow: number;
     endRow: number;
     startCol: number;
     endCol: number;
 }
+export interface RangeSelectionOptions {
+    /** 기본 selection==='cells' 와 동치 */
+    enabled?: boolean;
+    /** 기본 true — 핸들 표시/드래그 */
+    fillHandle?: boolean;
+    /** 기본 false — Ctrl 멀티 rect(Full, 미구현) */
+    multiRange?: boolean;
+    /** 기본 24(px) — autoscroll 밴드 폭 */
+    autoScrollEdge?: number;
+    /** 기본 true — false 면 항상 copy(시리즈 감지 비활성) */
+    seriesFill?: boolean;
+    /** 기본 false — 그룹/트리 모드 범위선택(MVP 비활성) */
+    enabledInTreeGroup?: boolean;
+    /** 기본 false — 수식 대상 덮어쓰기(C3.2 opt-in) */
+    fillOverwriteFormula?: boolean;
+}
+export interface RangeFillEvent {
+    source: CellRange;
+    target: CellRange;
+    mode: 'copy' | 'series';
+    written: Array<{
+        rowIndex: number;
+        field: string;
+        oldValue: any;
+        newValue: any;
+    }>;
+    skippedFormula?: number;
+    /** before 훅에서 true 로 바꾸면 채우기 취소(현재 배선은 이벤트 emit 뒤 즉시 확인) */
+    cancel?: boolean;
+}
+export interface RangeCopyEvent {
+    range: CellRange;
+    text: string;
+}
+export interface RangeChangeEvent {
+    range: CellRange | null;
+}
+export type { FormulaErrorCode } from './formula/types.js';
+/** F3 옵션(C5.1 단일 중첩 — 최상위 flat 키 금지). */
+export interface FormulaOptions {
+    /** 셀 수식 인-셀 '=' 편집 자동 인식 on(기본 false — 회귀 0). setCellFormula API 는 이 값과 무관하게 항상 동작. */
+    enabled?: boolean;
+    /** 참조 정규화 정책(기본 'stable', §3.2). */
+    refMode?: 'stable' | 'relative';
+    /** 나눗셈 소수 자리(기본 30, FormulaEngine 계승). */
+    divisionPrecision?: number;
+    /** 수식 바 표시(P1, 기본 false — 미구현). */
+    formulaBar?: boolean;
+    /** 수식 셀 마커(기본 true — HANMS-09/R-FORMULA-MARKER). */
+    cellMarker?: boolean;
+    /** 편집 시 자동 재계산(기본 true). */
+    autoRecalc?: boolean;
+    onFormulaChange?: (e: FormulaChangeEvent) => void;
+    onFormulaRecalc?: (e: FormulaRecalcEvent) => void;
+    onFormulaError?: (e: FormulaErrorEvent) => void;
+}
+export interface FormulaChangeEvent {
+    rowIndex: number;
+    field: string;
+    formula: string;
+    oldFormula: string | null;
+}
+export interface FormulaRecalcEvent {
+    changed: string[];
+    cycles: number;
+    ms: number;
+    /** Spike-A §8 교훈: 폐포가 임계(500) 초과 시 true(가이드 문서화/모니터링용). */
+    large: boolean;
+}
+export interface FormulaErrorEvent {
+    rowIndex: number;
+    field: string;
+    error: FormulaErrorCode;
+}
+export type { RangeStats } from './range/RangeQuery.js';
+/** masterDetail.renderer 3번째 인자(§6.1). */
+export interface DetailRenderApi<T = any> {
+    grid: OpenGridInstance<T>;
+    rowId: string;
+    /** 현재 그리드의 중첩 깊이(CON-4). 0 = 최상위. */
+    depth: number;
+    collapse: () => void;
+    /** 패널 재측정(Phase2 auto 대비 자리 — MVP 는 no-op 에 가까움). */
+    refresh: () => void;
+}
+/** F2 옵션(C5.1 단일 중첩 — 구 flat `detail*`/`masterDetail:boolean` 은 이 안으로 접힘). */
+export interface MasterDetailOptions<T = any> {
+    /** 기능 on/off. 기본 false. */
+    enabled?: boolean;
+    /** 임의 HTML/컴포넌트를 host 에 주입(§5). subgridOptions 와 동시 지정 시 이 쪽이 우선. */
+    renderer?: (row: T, host: HTMLElement, api: DetailRenderApi<T>) => void | HTMLElement;
+    /** 패널 높이(px). 기본 200. MVP 는 rowHeight 배수로 양자화(EC-10). */
+    height?: number;
+    /**
+     * 'fixed'(기본)만 MVP 에서 동작. 'auto' 는 Spike-B(C12.2) 통과 전 미공개 — 지정해도
+     * DetailManager 가 'fixed' 로 무시 처리하고 1회 console.warn 한다.
+     */
+    heightMode?: 'fixed' | 'auto';
+    /** 기본 true. false = 아코디언(펼침 1개만 허용). */
+    expandMultiple?: boolean;
+    /** 기본 false. true 면 collapse 해도 host/instance 캐시를 유지(재펼침 시 재생성 생략). */
+    cache?: boolean;
+    /** 어포던스 위치. 기본 'expander-col'(전용 컬럼). */
+    toggle?: 'expander-col' | 'first-cell';
+    /** 패널 role=region 의 aria-label. 기본 '상세 내용'. */
+    ariaLabel?: string;
+    /** 중첩 깊이 한계(CON-4/FR-10). 기본 2. */
+    maxDepth?: number;
+    /** 지정 시 height 대신 이 값을 슬롯수(정수, 최소 1)로 직접 사용. */
+    detailRowCount?: number;
+    /** renderer 미지정 시: 자식 OpenGrid 를 이 옵션으로 자동 생성(§5 ②). */
+    subgridOptions?: GridOptions<any>;
+}
+/** rowExpand/rowCollapse payload(C5.2, §6.3). */
+export interface RowExpandEvent<T = any> {
+    /** flat/visual index(C0.2). */
+    rowIndex: number;
+    rowId: string;
+    row: T;
+    host: HTMLElement | null;
+}
 export interface RendererDef {
     type: RendererType;
     [key: string]: any;
@@ -281,12 +415,31 @@ export interface GridOptions<T = any> {
     autoHeight?: boolean;
     fillWidth?: boolean;
     defaultColumnWidth?: number;
+    /**
+     * 뷰포트 안전장치(옵트인, 기본 undefined = OFF = 기존 동작 완전 불변).
+     * 호스트가 그리드 컨테이너 조상 체인에 확정 높이(definite height)를 주지 않으면
+     * 내부 스페이서(totalRows×rowHeight)가 컨테이너를 전체 콘텐츠 크기로 부풀리고,
+     * ResizeObserver 되먹임으로 windowing 이 무력화되어 전 행이 DOM 렌더되는 폭주가 발생한다
+     * (대량 데이터일수록 재앙적). 이 값을 지정하면, 컨테이너가 전 콘텐츠를 다 담는 "언바운드"
+     * 상태로 감지될 때에 한해 윈도잉 뷰포트 높이를 이 값(px)으로 클램프해 폭주를 차단한다.
+     * 정상적으로 확정 높이가 있는 바운드 컨테이너에는 영향이 없다.
+     * 1순위 권장은 컨테이너/그리드에 확정 height 를 주는 것이며, 이 옵션은 안전망이다.
+     */
+    fallbackViewportHeight?: number;
     editable?: boolean;
     editMode?: 'click' | 'dblclick' | 'none';
     history?: boolean;
     historySize?: number;
     selection?: SelectionMode;
     clipboard?: boolean;
+    /** F1: 범위 선택 + 채우기 핸들(C5.1 단일 중첩 — 최상위 flat 키 금지). */
+    rangeSelection?: RangeSelectionOptions;
+    /** F3: 셀 수식(C5.1 단일 중첩). */
+    formula?: FormulaOptions;
+    /** F2: 마스터/디테일(C5.1 단일 중첩). */
+    masterDetail?: MasterDetailOptions<T>;
+    /** F4: 그리드 데이터 통합 차트(C5.1 단일 중첩). 타입은 chart/types 순환-안전 type-only import. */
+    chart?: import('./chart/types.js').ChartGlobalOptions;
     sortable?: boolean;
     multiSort?: boolean;
     filterable?: boolean;
@@ -320,6 +473,7 @@ export interface GridOptions<T = any> {
     tooltips?: boolean;
     ariaLabel?: string;
     theme?: string;
+    skin?: string;
     cssVars?: Record<string, string>;
     contextMenu?: boolean | ContextMenuItem[];
     worksheets?: WorksheetDef[];
@@ -334,6 +488,15 @@ export interface GridOptions<T = any> {
     onEditBefore?: (e: EditEvent<T>) => boolean;
     onRowClick?: (e: RowEvent<T>) => void;
     onSelectionChange?: (e: SelectionEvent<T>) => void;
+    /** F1: 범위 rects 변경 시(C4, F4 라이브 소비) */
+    onRangeChange?: (e: RangeChangeEvent) => void;
+    /** F1: 채우기 커밋 결과(§6.3) */
+    onRangeFill?: (e: RangeFillEvent) => void;
+    /** F1: 범위 복사 시(§6.3) */
+    onRangeCopy?: (e: RangeCopyEvent) => void;
+    /** F2: 행 상세 패널 펼침/접힘 시(C5.1 on* 버킷). */
+    onRowExpand?: (e: RowExpandEvent<T>) => void;
+    onRowCollapse?: (e: RowExpandEvent<T>) => void;
     onSortChange?: (e: SortEvent) => void;
     onFilterChange?: (e: FilterEvent) => void;
     onScroll?: (e: ScrollEvent) => void;
@@ -379,8 +542,15 @@ export interface OverrideCallOptions {
     /** 'fallback' → 레이어 예외 시 경고 후 원본 실행(멱등 가정, 롤백 불가). 미지정 시 strict. */
     onError?: 'fallback';
 }
-/** 등록 가능한 알고리즘 슬롯 이름(6종). */
-export type StrategySlot = 'sortComparator' | 'filterPredicate' | 'displayFormatter' | 'cellSerializer' | 'groupKeyFn' | 'summaryOp';
+/** 등록 가능한 알고리즘 슬롯 이름. */
+export type StrategySlot = 'sortComparator' | 'filterPredicate' | 'displayFormatter' | 'cellSerializer' | 'groupKeyFn' | 'summaryOp' | 'cellClassResolver' | 'ariaLabelResolver' | 'skinResolver';
+/**
+ * SKIN 토큰 이름 집합 — **형태(FORM)만** 소유(색 0). COLOR 토큰과 disjoint name set 이라
+ * 색⊥형태 직교성이 이름 충돌 부재로 물리적으로 보장된다(item3 §1.1~1.2, HANMS §4).
+ */
+export type SkinTokenName = '--og-radius-none' | '--og-radius-sm' | '--og-radius-md' | '--og-radius-lg' | '--og-radius-pill' | '--og-radius-container' | '--og-radius-control' | '--og-radius-widget' | '--og-container-radius' | '--og-border-width' | '--og-border-width-strong' | '--og-border-style' | '--og-divider-style' | '--og-divider-repeat' | '--og-elevation-sm' | '--og-elevation-md' | '--og-elevation-lg' | '--og-elevation-alpha-sm' | '--og-elevation-alpha-md' | '--og-elevation-alpha-lg' | '--og-elevation-inset' | '--og-cell-padding-x' | '--og-cell-padding-y' | '--og-density-row-height' | '--og-density-header-height' | '--og-density-footer-height' | '--og-scrollbar-size' | '--og-texture-bg' | '--og-texture-size' | '--og-texture-opacity' | '--og-focus-width' | '--og-focus-style' | '--og-focus-offset' | '--og-focus-radius' | '--og-icon-size' | '--og-icon-fill' | '--og-icon-stroke-width' | '--og-icon-corner' | '--og-transition-fast' | '--og-transition-base' | '--og-row-accent-width';
+/** FORM-only 스킨 델타. 값에 색 리터럴이 있으면 SkinRegistry 가 런타임 거부(Rule 2, 직교성). */
+export type SkinTokenDelta = Partial<Record<SkinTokenName, string>>;
 /** 단일키 정렬 비교자. dir 부호는 호출자(DataLayer)가 적용 — 슬롯은 비교만 반환. */
 export type SortComparatorFn = (a: any, b: any, field: string, dir: 'asc' | 'desc') => number;
 /** 필터 술어. true → 행 포함. */
@@ -393,6 +563,15 @@ export type CellSerializerFn = (value: any, col: any, row: any) => any;
 export type GroupKeyFn = (row: any, remainingFields: string[]) => any;
 /** 집계 연산. null 반환 시 기본 SUM/AVG/COUNT/MAX/MIN 분기로 폴백. */
 export type SummaryOpFn = (op: string, nums: any[], field: string) => number | null;
+/** R11(§4.2): 셀 클래스 렌더훅 리졸버. 렌더층이 셀 element 에 추가할 className(null=미참여). */
+export type CellClassResolverFn = (value: any, field: string, row: any) => string | null;
+/** R11(§4.2): 셀 aria-label 렌더훅 리졸버. 렌더층이 셀 aria-label 을 대체(null=기본 유지). */
+export type AriaLabelResolverFn = (value: any, field: string, row: any) => string | null;
+/**
+ * F1 채우기 시리즈 커스텀 리졸버 슬롯(C5.3, 예약). 사용자가 날짜/커스텀 시리즈를 주입할 수 있다.
+ * ⚠️ 슬롯 등록 경로만 확보되어 있으며, RangeSelectionManager/FillEngine 소비 배선은 F1-b(Full) 대상.
+ */
+export type FillSeriesResolverFn = (sourceLine: any[], k: number, axisSign: 1 | -1) => any;
 /** 슬롯명 → 시그니처 매핑. */
 export interface StrategyMap {
     sortComparator: SortComparatorFn;
@@ -401,10 +580,33 @@ export interface StrategyMap {
     cellSerializer: CellSerializerFn;
     groupKeyFn: GroupKeyFn;
     summaryOp: SummaryOpFn;
+    fillSeriesResolver: FillSeriesResolverFn;
+    cellClassResolver: CellClassResolverFn;
+    ariaLabelResolver: AriaLabelResolverFn;
+    skinResolver: SkinResolverFn;
+}
+/**
+ * R12b(item3 §6.1): 스킨 FORM 해석 인터셉트 슬롯. AppearanceResolver 가 fallback 과 함께 읽어(제로코스트)
+ * 오버라이드가 form 토큰 델타를 통째로 가로챌 수 있다. 미설정 시 내장 스킨 카탈로그가 그대로 적용.
+ */
+export type SkinResolverFn = (skinId: string) => SkinTokenDelta | null;
+/**
+ * R11(§4.3, T-ζ): SemVer 보증되는 **타입드 override 카탈로그**(좁은 "지원됨" 문).
+ * `override("anyMethod", fn)` 문자열 탈출구(UC-11, best-effort)는 그대로 열려 있고 —
+ * 이 인터페이스는 축복된(blessed) 확장점 이름을 IDE 발견가능하게 좁게 표시할 뿐, 넓은 문을 닫지 않는다.
+ * 각 항목은 소비 테스트를 동반한다(유령 확장점 금지, DeMarco M9b).
+ */
+export interface OverridePoints<T = any> {
+    /** 셀 표시 텍스트 해석(렌더훅 displayText 의 근원). */
+    getDisplayValue(rowIndex: number, field: string): string;
+    /** 원시 셀 값 접근. */
+    readCell(rowIndex: number, field: string): any;
 }
 /** 호출가능 + .strategy 멤버를 가진 하이브리드 override API. */
 export interface OverrideApi<T = any> {
-    /** 메서드 본문 무수정 런타임 래핑(C1-clean). 체이닝 위해 grid 인스턴스 반환. */
+    /** R11(§4.3): 타입드 오버로드 — 축복된 확장점 이름(IDE 발견). SemVer 보증 카탈로그. */
+    <K extends keyof OverridePoints<T>>(name: K, fn: OverrideLayerFn, opts?: OverrideCallOptions): OpenGridInstance<T>;
+    /** 메서드 본문 무수정 런타임 래핑(C1-clean, 탈출구 UC-11). 체이닝 위해 grid 인스턴스 반환. */
     (name: string, fn: OverrideLayerFn, opts?: OverrideCallOptions): OpenGridInstance<T>;
     /** 알고리즘 슬롯 등록(Phase 2 매니저 훅포인트). 체이닝 위해 grid 인스턴스 반환. */
     strategy<K extends StrategySlot>(slot: K, fn: StrategyMap[K]): OpenGridInstance<T>;
@@ -439,6 +641,21 @@ export interface OpenGridInstance<T = any> {
     getDisplayValue(rowIndex: number, field: string): string;
     writeCell(rowIndex: number, field: string, value: any): void;
     getRowAt(rowIndex: number): T;
+    /** flat/visual index ↔ data 리졸버. F1/F3/F4 는 이 모델을 경유해 대상을 해소한다. */
+    getFlatRowModel(): import('./FlatRowModel.js').FlatRowModel;
+    /** 배치 쓰기 시작 — 이후 writeCell 들의 render/dataChange 를 지연·coalesce(reentrant). */
+    beginBatch(): void;
+    /** 배치 종료 — 배치 중 쓰기가 있었으면 1회 render + 1회 coalesced dataChange. */
+    endBatch(): void;
+    /**
+     * beginBatch+루프+endBatch 래퍼. rowIndex 는 flat index — kind!=='data' 대상(group/tree/
+     * detail 의사행)은 쓰기 전에 skip 한다(C0.3 쓰기 안전). 반환값 = 건너뛴 셀 수.
+     */
+    writeCells(patches: Array<{
+        rowIndex: number;
+        field: string;
+        value: any;
+    }>): number;
     getChanges(): {
         added: T[];
         edited: T[];
@@ -480,6 +697,64 @@ export interface OpenGridInstance<T = any> {
     getActiveRow(): number;
     activate(index: number): void;
     deselect(): void;
+    /** 정규화 rects(없으면 []). MVP 는 길이 ≤1. */
+    getRangeSelection(): CellRange[];
+    /** = getRangeSelection()[0] ?? null(C4, F4 소비). */
+    getActiveRange(): CellRange | null;
+    setRangeSelection(range: CellRange | CellRange[]): void;
+    clearRangeSelection(): void;
+    /** 현재 활성 범위의 값 2D 배열(FR-6, F4 필수 계약). */
+    getRangeValues(): any[][];
+    /** 현재 활성 범위 숫자 셀의 OGDecimal 기반 통계(FR-6, F4 필수 계약). */
+    getRangeStats(): _RangeStats | null;
+    /** source→target 채우기(배치 경유, C2). axis 는 두 rect 상대 위치로 추론. */
+    fillRange(source: CellRange, target: CellRange, mode?: 'copy' | 'series'): void;
+    createChart(config: import('./chart/types.js').ChartConfig): import('./chart/types.js').ChartInstance;
+    getCharts(): import('./chart/types.js').ChartInstance[];
+    destroyCharts(): void;
+    /** "=A1+B2" 형태. rowIndex 는 flat(C0), 내부 즉시 stable rowId 로 정규화. */
+    setCellFormula(rowIndex: number, field: string, formula: string): 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;
+    }>;
+    /** 전체 수식 위상 재계산(setData/컬럼 변경 등). */
+    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;
+    /** rowRef 는 flat/visual index(C0.2) 또는 stable id. maxDepth 초과 시 거부(announce, FR-10). */
+    expandRow(rowRef: number | {
+        id: string;
+    }): void;
+    collapseRow(rowRef: number | {
+        id: string;
+    }): void;
+    toggleRow(rowRef: number | {
+        id: string;
+    }): void;
+    isRowExpanded(rowRef: number | {
+        id: string;
+    }): boolean;
+    collapseAllDetails(): void;
+    /** 펼쳐진 적 없으면 undefined. renderer 반환값 또는 자동 생성 서브그리드 인스턴스. */
+    getDetailInstance<D = any>(rowRef: number | {
+        id: string;
+    }): D | undefined;
+    /** FR-11: 컬럼/호스트 리사이즈 후 열린 패널 폭을 강제 재동기(보통은 재렌더가 자동 처리). */
+    resyncPanelWidths(): void;
     getChecked(): Array<{
         row: T;
         rowIndex: number;
@@ -526,6 +801,12 @@ export interface OpenGridInstance<T = any> {
     resize(width?: number, height?: number): void;
     setTheme(theme: string): void;
     setThemeVar(varName: string, value: string): void;
+    /** R12b: 스킨(FORM 축) 전환 — data-og-skin 설정 + 인라인 form 사이트 재해석. 색 테마와 직교. */
+    setSkin(skin: string): void;
+    /** R12b: 현재 스킨 id('default' = 오늘). */
+    getSkin(): string;
+    /** R12b: FORM 축 단일 토큰 런타임 오버라이드(setThemeVar 의 형태-축 형제). 색 값은 거부. */
+    setSkinVar(varName: string, value: string): void;
     destroy(): void;
     setOptions(opts: Partial<GridOptions<T>>): void;
     /** 컬럼 마스킹 ON/OFF. enabled=true → 마스킹 적용, enabled=false → 전체 해제 */
@@ -575,6 +856,7 @@ export interface ContextMenuItem {
     type?: 'divider';
 }
 export type { FilterSelectColumn, FilterSelectConfig } from './FilterSelect.js';
+export type { FlatRowRef } from './FlatRowModel.js';
 export interface WorksheetDef<T = any> {
     name: string;
     columns?: ColumnDef<T>[];