@reopt-ai/opt-ui 1.5.0 → 1.7.0

package/dist/docs/02-components/03-shells.md

@@ -1,11 +1,11 @@
 ---
 title: "Shell Components"
-description: "75 Shell layer components — props, examples, keyboard shortcuts."
-version: "1.4.1"
+description: "80 Shell layer components — props, examples, keyboard shortcuts."
+version: "1.6.0"
 generated: true
 ---
 
-# Shell Components (75)
+# Shell Components (80)
 
 ## Navigation & Layout
 
@@ -483,6 +483,15 @@ import { DataTable } from "@reopt-ai/opt-ui";
 
 **Import:** `import { ConnectionIndicator } from "@reopt-ai/opt-ui"`
 
+| Prop        | Type                                                        | Required | Default | Description                                                           |
+| ----------- | ----------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------------- |
+| `status`    | `"connected" \| "connecting" \| "disconnected" \| "error"`  |          |         | 연결 상태 프리셋. tone과 pulse의 기본값을 정함                        |
+| `tone`      | `"neutral" \| "success" \| "warning" \| "danger" \| "info"` |          |         | status로 표현되지 않는 도메인 상태의 색을 직접 지정 (status보다 우선) |
+| `label`     | `string`                                                    |          |         | 상태 문구                                                             |
+| `showLabel` | `boolean`                                                   |          |         | 문구 표시 여부                                                        |
+| `pulse`     | `boolean`                                                   |          |         | 점 애니메이션. 생략하면 status 프리셋을 따름                          |
+| `className` | `string`                                                    |          |         | 기본 스타일 오버라이드                                                |
+
 ### EventIcon
 
 > 이벤트 아이콘. semantic key 또는 ReactNode 아이콘과 배경색을 표시합니다.
@@ -944,17 +953,17 @@ const fields = [
 **Import:** `import { FileUploadForm } from "@reopt-ai/opt-ui"`
 **Dependencies:** form (core)
 
-| Prop              | Type                                             | Required | Default                    | Description                               |
-| ----------------- | ------------------------------------------------ | -------- | -------------------------- | ----------------------------------------- |
-| `accept`          | `string`                                         |          | "image/\*,.pdf,.doc,.docx" | 허용 파일 타입                            |
-| `showPreview`     | `boolean`                                        |          | true                       | 이미지 미리보기 표시                      |
-| `showFileInfo`    | `boolean`                                        |          | true                       | 파일 정보 표시                            |
-| `showDescription` | `boolean`                                        |          | true                       | 설명 텍스트영역 표시                      |
-| `maxFileSize`     | `number`                                         |          |                            | 최대 파일 크기 (bytes)                    |
-| `onSubmit`        | `(values: { title, description, file }) => void` |          |                            | 제출 핸들러                               |
-| `labels`          | `FileUploadFormLabels`                           |          |                            | i18n용 라벨 오버라이드                    |
-| `onPreview`       | `(file: File) => void`                           |          |                            | 파일 선택 후 프리뷰 콜백                  |
-| `columnMapping`   | `ReactNode`                                      |          |                            | CSV 컬럼 매핑 UI 슬롯 (파일 선택 후 표시) |
+| Prop              | Type                                             | Required | Default                   | Description                               |
+| ----------------- | ------------------------------------------------ | -------- | ------------------------- | ----------------------------------------- |
+| `accept`          | `string`                                         |          | "image/*,.pdf,.doc,.docx" | 허용 파일 타입                            |
+| `showPreview`     | `boolean`                                        |          | true                      | 이미지 미리보기 표시                      |
+| `showFileInfo`    | `boolean`                                        |          | true                      | 파일 정보 표시                            |
+| `showDescription` | `boolean`                                        |          | true                      | 설명 텍스트영역 표시                      |
+| `maxFileSize`     | `number`                                         |          |                           | 최대 파일 크기 (bytes)                    |
+| `onSubmit`        | `(values: { title, description, file }) => void` |          |                           | 제출 핸들러                               |
+| `labels`          | `FileUploadFormLabels`                           |          |                           | i18n용 라벨 오버라이드                    |
+| `onPreview`       | `(file: File) => void`                           |          |                           | 파일 선택 후 프리뷰 콜백                  |
+| `columnMapping`   | `ReactNode`                                      |          |                           | CSV 컬럼 매핑 UI 슬롯 (파일 선택 후 표시) |
 
 ### WizardForm
 
@@ -1099,6 +1108,25 @@ const fields = [
 **Import:** `import { SqlEditor } from "@reopt-ai/opt-ui"`
 **Dependencies:** button (core)
 
+| Prop                | Type                          | Required | Default | Description                                                                      |
+| ------------------- | ----------------------------- | -------- | ------- | -------------------------------------------------------------------------------- |
+| `value`             | `string`                      | Yes      |         | 편집 중인 SQL                                                                    |
+| `onChange`          | `(sql: string) => void`       | Yes      |         | 본문 변경 핸들러                                                                 |
+| `onRun`             | `(sql: string) => void`       |          |         | Mod+Enter 실행 핸들러                                                            |
+| `onRunAndAdvance`   | `(sql: string) => void`       |          |         | Shift+Enter — 실행 후 다음 셀/탭으로 이동                                        |
+| `schema`            | `SqlEditorSchema`             |          |         | 테이블/컬럼 자동완성 스키마. 변경 시 에디터를 다시 만들지 않고 자동완성만 재구성 |
+| `completionSources` | `SqlEditorCompletionSource[]` |          |         | 스키마 자동완성에 더할 완성 소스 (함수 시그니처, 스니펫)                         |
+| `keymap`            | `SqlEditorKeyBinding[]`       |          |         | 추가 키 바인딩. 내장 실행 바인딩보다 먼저 평가                                   |
+| `extensions`        | `SqlEditorExtension[]`        |          |         | 임의의 CodeMirror 확장. 내장 확장 뒤에 붙어 우선권을 가짐                        |
+| `height`            | `number \| "fill"`            |          |         | px 고정 높이. fill이면 부모가 정한 높이를 채움                                   |
+| `placeholder`       | `string`                      |          |         | 빈 편집기 안내 문구                                                              |
+| `readOnly`          | `boolean`                     |          |         | 편집 잠금                                                                        |
+| `ariaLabel`         | `string`                      |          |         | 편집 영역 접근성 레이블                                                          |
+| `autoFocus`         | `boolean`                     |          |         | 마운트 시 포커스                                                                 |
+| `showFooter`        | `boolean`                     |          |         | 실행 힌트/버튼 표시. 기본값은 onRun이 있을 때 표시                               |
+| `labels`            | `SqlEditorLabels`             |          |         | 문구 오버라이드                                                                  |
+| `className`         | `string`                      |          |         | 기본 스타일 오버라이드                                                           |
+
 ### EventMetaEditor
 
 > 이벤트 메타 에디터. 레이블이 연결된 IconPicker + ColorPicker + TagInput 조합으로 이벤트 메타데이터를 편집합니다.
@@ -1295,15 +1323,20 @@ const fields = [
 
 ## Other
 
-| Component       | Description                                                                | Key Exports       |
-| --------------- | -------------------------------------------------------------------------- | ----------------- |
-| PageAside       | Sticky 페이지 사이드 aside chrome. 고정 너비 + header/body/footer 3-slot.  | `PageAside`       |
-| FailureList     | 실패 목록 패널. severity별 색상 강조, 그룹핑, 액션 슬롯을 지원합니다.      | `FailureList`     |
-| KeyValueEditor  | 키-값 쌍 편집기. 동적 행 추가/삭제, 비밀값 토글, 유효성 검사를 지원합니다. | `KeyValueEditor`  |
-| AuditTimeline   | 변경 이력 타임라인. 액션별 색상 코딩 + 확장 가능한 diff 뷰.                | `AuditTimeline`   |
-| ChatSidebar     | AI 채팅 사이드바. 대화 목록, 검색, 새 대화 버튼.                           | `ChatSidebar`     |
-| ChatInput       | 채팅 입력 컴포넌트. 자동 리사이즈 textarea, 파일 첨부, 모델/스타일 Select. | `ChatInput`       |
-| ChatMessageList | 채팅 메시지 목록. 역할별 말풍선, 타이핑 인디케이터, 자동 스크롤.           | `ChatMessageList` |
+| Component        | Description                                                                                                                                    | Key Exports                                |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| PageAside        | Sticky 페이지 사이드 aside chrome. 고정 너비 + header/body/footer 3-slot.                                                                      | `PageAside`                                |
+| FailureList      | 실패 목록 패널. severity별 색상 강조, 그룹핑, 액션 슬롯을 지원합니다.                                                                          | `FailureList`                              |
+| KeyValueEditor   | 키-값 쌍 편집기. 동적 행 추가/삭제, 비밀값 토글, 유효성 검사를 지원합니다.                                                                     | `KeyValueEditor`                           |
+| AuditTimeline    | 변경 이력 타임라인. 액션별 색상 코딩 + 확장 가능한 diff 뷰.                                                                                    | `AuditTimeline`                            |
+| ChatSidebar      | AI 채팅 사이드바. 대화 목록, 검색, 새 대화 버튼.                                                                                               | `ChatSidebar`                              |
+| ChatInput        | 채팅 입력 컴포넌트. 자동 리사이즈 textarea, 파일 첨부, 모델/스타일 Select.                                                                     | `ChatInput`                                |
+| ChatMessageList  | 채팅 메시지 목록. 역할별 말풍선, 타이핑 인디케이터, 자동 스크롤.                                                                               | `ChatMessageList`                          |
+| TimeRangeControl | date math(now-7d, now/d) 기반 시간 범위 컨트롤. quick select, 프리셋/최근 사용, 명시적 Update, 자동 갱신, 창 이동·확대/축소 버튼을 제공합니다. | `TimeRangeControl`, `DEFAULT_TIME_PRESETS` |
+| TimeSeriesPanel  | 시간 범위 컨트롤과 시계열 차트를 한 단위로 묶은 패널. 드래그 줌과 줌 히스토리(되돌리기), 범례 토글을 포함합니다.                               | `TimeSeriesPanel`                          |
+| LogTable         | 계속 도착하는 로그용 윈도잉 테이블. 컬럼 정의 기반, 상단 삽입 시 스크롤 위치 보존, follow 상태 보고, 셀 값 즉시 필터, 밀도·정렬을 지원합니다.  | `LogTable`                                 |
+| QueryBar         | 검색과 필터를 한 입력으로 합친 쿼리 바. field:value, -부정, (a or b), 비교 연산, 필드·값 자동완성, 절(clause) 칩을 지원합니다.                 | `QueryBar`                                 |
+| FieldSidebar     | 데이터에 어떤 필드가 있고 각 필드가 무슨 값을 갖는지 보여주는 사이드바. 값 분포 막대, 컬럼으로 승격, 값 기준 포함/제외 필터를 제공합니다.      | `FieldSidebar`                             |
 
 ### PageAside
 
@@ -1466,3 +1499,91 @@ const messages = [
 
 <ChatMessageList messages={messages} loading={false} />;
 ```
+
+### TimeRangeControl
+
+> date math(now-7d, now/d) 기반 시간 범위 컨트롤. quick select, 프리셋/최근 사용, 명시적 Update, 자동 갱신, 창 이동·확대/축소 버튼을 제공합니다.
+
+**Import:** `import { TimeRangeControl } from "@reopt-ai/opt-ui"`
+
+| Prop                | Type                             | Required | Default | Description                              |
+| ------------------- | -------------------------------- | -------- | ------- | ---------------------------------------- |
+| `value`             | `TimeRange`                      | Yes      |         | { from, to } — date math 문자열 또는 ISO |
+| `onChange`          | `(range: TimeRange) => void`     | Yes      |         | 범위가 커밋되었을 때 호출                |
+| `presets`           | `TimeRangePreset[]`              |          |         | 자주 쓰는 범위 목록                      |
+| `recentRanges`      | `TimeRangePreset[]`              |          |         | 최근 사용한 범위 (호출자 소유)           |
+| `timeZone`          | `string`                         |          |         | 라운딩·표시에 쓸 IANA 타임존             |
+| `showUpdateButton`  | `boolean`                        |          | true    | 편집을 명시적으로 커밋                   |
+| `showWindowButtons` | `boolean`                        |          | true    | 이전/다음 창, 확대/축소 버튼             |
+| `refresh`           | `RefreshSetting`                 |          |         | { interval, paused } 자동 갱신 설정      |
+| `onRefresh`         | `() => void \| Promise<unknown>` |          |         | 갱신 요청 — 프라미스가 끝난 뒤 다음 tick |
+
+### TimeSeriesPanel
+
+> 시간 범위 컨트롤과 시계열 차트를 한 단위로 묶은 패널. 드래그 줌과 줌 히스토리(되돌리기), 범례 토글을 포함합니다.
+
+**Import:** `import { TimeSeriesPanel } from "@reopt-ai/opt-ui"`
+
+| Prop               | Type                         | Required | Default | Description                                   |
+| ------------------ | ---------------------------- | -------- | ------- | --------------------------------------------- |
+| `data`             | `TimeSeriesPoint[]`          | Yes      |         | 시계열 데이터                                 |
+| `series`           | `TimeSeriesDef[]`            | Yes      |         | 시리즈 정의                                   |
+| `range`            | `TimeRange`                  | Yes      |         | 조회 구간 — 차트 축도 여기에 고정됩니다       |
+| `onRangeChange`    | `(range: TimeRange) => void` | Yes      |         | 드래그 줌·컨트롤 변경으로 구간이 바뀔 때 호출 |
+| `showRangeControl` | `boolean`                    |          | true    | 헤더에 TimeRangeControl 렌더                  |
+| `toggleableLegend` | `boolean`                    |          | false   | 범례 클릭으로 시리즈 숨김                     |
+| `annotations`      | `TimeSeriesAnnotation[]`     |          |         | 시간축 마커/구간                              |
+| `height`           | `number`                     |          | 280     | 차트 높이                                     |
+
+### LogTable
+
+> 계속 도착하는 로그용 윈도잉 테이블. 컬럼 정의 기반, 상단 삽입 시 스크롤 위치 보존, follow 상태 보고, 셀 값 즉시 필터, 밀도·정렬을 지원합니다.
+
+**Import:** `import { LogTable } from "@reopt-ai/opt-ui"`
+
+| Prop             | Type                                     | Required | Default  | Description                      |
+| ---------------- | ---------------------------------------- | -------- | -------- | -------------------------------- |
+| `rows`           | `Row[]`                                  | Yes      |          | 표시할 행                        |
+| `columns`        | `LogColumn<Row>[]`                       | Yes      |          | 컬럼 정의 (표시 중인 것만)       |
+| `getRowId`       | `(row: Row) => string`                   | Yes      |          | 행 식별자                        |
+| `selectedId`     | `string \| null`                         |          |          | 선택된 행                        |
+| `onSelect`       | `(id: string) => void`                   |          |          | 행 선택                          |
+| `onLoadMore`     | `() => void`                             |          |          | 다음 페이지 요청                 |
+| `prepending`     | `boolean`                                |          | false    | 상단에 행이 삽입되는 라이브 목록 |
+| `onFollowChange` | `(following: boolean) => void`           |          |          | 최신 행 고정 여부 보고           |
+| `isNew`          | `(row: Row) => boolean`                  |          |          | 방금 도착한 행 강조              |
+| `sort`           | `LogSort \| null`                        |          |          | 정렬 상태                        |
+| `onSortChange`   | `(sort: LogSort) => void`                |          |          | 헤더 클릭 정렬                   |
+| `onCellAction`   | `(action: LogCellAction) => void`        |          |          | 셀 값 포함/제외 필터             |
+| `density`        | `"compact" \| "normal" \| "comfortable"` |          | "normal" | 행 높이와 글자 크기              |
+
+### QueryBar
+
+> 검색과 필터를 한 입력으로 합친 쿼리 바. field:value, -부정, (a or b), 비교 연산, 필드·값 자동완성, 절(clause) 칩을 지원합니다.
+
+**Import:** `import { QueryBar } from "@reopt-ai/opt-ui"`
+
+| Prop          | Type                     | Required | Default | Description                  |
+| ------------- | ------------------------ | -------- | ------- | ---------------------------- |
+| `value`       | `Query`                  | Yes      |         | 파싱된 쿼리                  |
+| `onChange`    | `(query: Query) => void` | Yes      |         | 커밋 시 호출 (Enter·blur)    |
+| `fields`      | `QueryField[]`           |          |         | 자동완성할 필드와 알려진 값  |
+| `showClauses` | `boolean`                |          | false   | 절을 제거 가능한 칩으로 표시 |
+| `live`        | `boolean`                |          | false   | 키 입력마다 커밋             |
+
+### FieldSidebar
+
+> 데이터에 어떤 필드가 있고 각 필드가 무슨 값을 갖는지 보여주는 사이드바. 값 분포 막대, 컬럼으로 승격, 값 기준 포함/제외 필터를 제공합니다.
+
+**Import:** `import { FieldSidebar } from "@reopt-ai/opt-ui"`
+
+| Prop                    | Type                                                                     | Required | Default | Description                    |
+| ----------------------- | ------------------------------------------------------------------------ | -------- | ------- | ------------------------------ |
+| `fields`                | `FieldSummary[]`                                                         | Yes      |         | 필드 목록                      |
+| `expandedField`         | `string \| null`                                                         |          |         | 값을 펼친 필드                 |
+| `onExpandedFieldChange` | `(field: string \| null) => void`                                        |          |         | 펼침 전환 — 호출자가 값을 조회 |
+| `values`                | `FieldValueCount[]`                                                      |          |         | 펼친 필드의 상위 값            |
+| `valuesLoading`         | `boolean`                                                                |          | false   | 값 조회 중                     |
+| `sampledRows`           | `number`                                                                 |          |         | 집계 대상 행 수 (분모)         |
+| `onToggleColumn`        | `(field: string, next: boolean) => void`                                 |          |         | 컬럼 추가/제거                 |
+| `onFilter`              | `(field: string, value: string, intent: "include" \| "exclude") => void` |          |         | 값 기준 필터                   |

package/dist/docs/02-components/04-surfaces.md

@@ -1,7 +1,7 @@
 ---
 title: "Surface Components"
 description: "0 Surface layer components — props, examples, keyboard shortcuts."
-version: "1.4.1"
+version: "1.6.0"
 generated: true
 ---
 

package/dist/docs/02-components/index.md

@@ -1,7 +1,7 @@
 ---
 title: "Component Reference"
-description: "Complete reference for 134 @reopt-ai/opt-ui components across 4 layers."
-version: "1.4.1"
+description: "Complete reference for 139 @reopt-ai/opt-ui components across 4 layers."
+version: "1.6.0"
 generated: true
 ---
 
@@ -13,9 +13,9 @@ generated: true
 | --------- | ------- |
 | Core      | 59      |
 | Visuals   | 0       |
-| Shells    | 75      |
+| Shells    | 80      |
 | Surfaces  | 0       |
-| **Total** | **134** |
+| **Total** | **139** |
 
 ## Component Selection Guide
 

package/dist/docs/03-recipes/03-layouts.md

@@ -7,7 +7,7 @@ related:
     - ../02-components/03-shells.md
 ---
 
-<!-- AI agent hint: Surface/페이지 루트에 직접 space-y-* 사용 금지. 반드시 SurfaceLayout 또는 createSurface 사용. -->
+<!-- AI agent hint: Block/페이지 루트에 직접 space-y-* 사용 금지. 반드시 BlockLayout 또는 createBlock 사용. 페이지 경계를 직접 맡으면 inset="section"을 지정. -->
 
 # Layout Recipes
 
@@ -111,14 +111,14 @@ export function AppLayout({ children }: { children: React.ReactNode }) {
 
 ## 2. Data Explorer Page
 
-FilterBar + DataTable + Pagination in a SurfaceLayout.
+FilterBar + DataTable + Pagination in a BlockLayout.
 
 ```tsx
 "use client";
 
 import { useState, useMemo } from "react";
 import {
-  SurfaceLayout,
+  BlockLayout,
   PageHeader,
   FilterBar,
   DataTable,
@@ -221,7 +221,7 @@ export function UserExplorerPage() {
   };
 
   return (
-    <SurfaceLayout>
+    <BlockLayout inset="section">
       <PageHeader
         title="사용자 관리"
         description={`총 ${filtered.length}명`}
@@ -253,20 +253,20 @@ export function UserExplorerPage() {
         currentPage={page}
         onPageChange={setPage}
       />
-    </SurfaceLayout>
+    </BlockLayout>
   );
 }
 ```
 
 ## 3. Settings Page with Vertical Tabs
 
-SurfaceLayout with VerticalTabs for section navigation and SettingsForm for each tab.
+BlockLayout with VerticalTabs for section navigation and SettingsForm for each tab.
 
 ```tsx
 "use client";
 
 import {
-  SurfaceLayout,
+  BlockLayout,
   PageHeader,
   VerticalTabs,
   SettingsForm,
@@ -391,7 +391,7 @@ const tabs: TabDef[] = [
 
 export function SettingsPage() {
   return (
-    <SurfaceLayout>
+    <BlockLayout inset="section">
       <PageHeader title="설정" description="프로젝트 설정을 관리합니다" />
 
       <VerticalTabs
@@ -399,7 +399,7 @@ export function SettingsPage() {
         defaultTabId="general"
         labels={{ ariaLabel: "설정 카테고리" }}
       />
-    </SurfaceLayout>
+    </BlockLayout>
   );
 }
 ```
@@ -408,14 +408,14 @@ export function SettingsPage() {
 
 | Element        | Approach                                                                  |
 | -------------- | ------------------------------------------------------------------------- |
-| Page root      | `SurfaceLayout` (provides `gap-section` between children)                 |
+| Page root      | `BlockLayout inset="section"` (page inset + `gap-section`)                |
 | App chrome     | `AppShell` + `AppShell.Header/Sidebar/Content/Footer`                     |
 | Sidebar nav    | `Sidebar` with `Sidebar.Header/Content/Footer` sub-components             |
-| Page title     | `PageHeader` with optional `description` and `actions` slot               |
+| Page title     | `PageHeader` with optional slots; outer inset belongs to the page root    |
 | Section grids  | `gap-group` between columns, `gap-element` for tight spacing              |
 | Tab navigation | `VerticalTabs` for left-side tabs, `ContentTabs` for horizontal           |
 | Pagination     | `Pagination` below `DataTable` with `totalItems`/`pageSize`/`currentPage` |
-| Loading state  | `SurfaceLayout loading={true}` wraps content with `LoadingOverlay`        |
+| Loading state  | `BlockLayout loading={true}` wraps content with `LoadingOverlay`          |
 
 ### Semantic Spacing Quick Reference
 
@@ -423,6 +423,10 @@ export function SettingsPage() {
 gap-section  ->  24px  (between major sections)
 gap-group    ->  16px  (between related items)
 gap-element  ->   8px  (between tightly coupled elements)
+p-section    ->  24px  (inside a page-owned content boundary)
 ```
 
 CSS variables: `--opt-space-section`, `--opt-space-group`, `--opt-space-element`.
+
+`BlockLayout`의 inset 기본값은 없음입니다. 재사용 Block이 카드나 Shell 안에 들어갈 때 이중
+여백이 생기지 않게 하고, 페이지 콘텐츠 경계를 맡는 호출부만 `inset="section"`을 명시합니다.

package/dist/docs/05-migration/01-breaking-changes.md

@@ -5,7 +5,7 @@ description: "opt-ui 버전별 Breaking/Deprecated 변경사항 레지스트리"
 
 # Breaking Changes Registry
 
-버전별 Breaking/Deprecated 변경사항 레지스트리.
+공개 디자인 패키지의 버전별 Breaking/Deprecated 변경사항 레지스트리.
 
 ## Registry Format
 
@@ -25,6 +25,51 @@ description: "opt-ui 버전별 Breaking/Deprecated 변경사항 레지스트리"
 
 ---
 
+## opt-editor Version 2.0.0
+
+### Breaking
+
+- version: "2.0.0"
+  level: B
+  component: "opt-editor/server runtime schemas"
+  change: "Zod 런타임 스키마를 /schemas 전용 엔트리로 분리"
+  detail: "patchOpSchema, patchOpsArraySchema, createEditorOperationSchema, fieldDefToZod 등 런타임 스키마가 @reopt-ai/opt-editor/server에서 제거되고 @reopt-ai/opt-editor/schemas로 이동했습니다. /ai-sdk 재노출과 type-only export는 유지됩니다."
+  scan: '@reopt-ai/opt-editor/server'
+  fix:
+  type: rename
+  from: 'import { patchOpSchema } from "@reopt-ai/opt-editor/server"'
+  to: 'import { patchOpSchema } from "@reopt-ai/opt-editor/schemas"'
+
+---
+
+## Version 1.5.0
+
+### Breaking
+
+- version: "1.5.0"
+  level: B
+  component: "Surface runtime exports"
+  change: "런타임 Surface export 제거 — opt-cli 블록 registry로 이관"
+  detail: "ChatAssistant, DataExplorer, DeploymentCenter 등 런타임 Surface와 createSurface가 @reopt-ai/opt-ui에서 더 이상 export되지 않습니다. 페이지 템플릿은 opt-cli 블록 registry(copy-paste)로 소비합니다."
+  scan: "ChatAssistant\\|DataExplorer\\|DeploymentCenter\\|createSurface"
+  fix:
+  type: manual
+  from: 'import { ChatAssistant } from "@reopt-ai/opt-ui"'
+  to: "npx @reopt-ai/opt-cli surface add <slug>"
+
+### Deprecated
+
+- version: "1.5.0"
+  level: D
+  component: "SurfaceLayout"
+  change: "SurfaceLayout deprecated → BlockLayout / createBlock"
+  detail: "SurfaceLayout이 deprecated 되었습니다. 페이지 간격·레이아웃은 BlockLayout 또는 createBlock을 사용하세요."
+  scan: "SurfaceLayout"
+  fix:
+  type: rename
+  from: "<SurfaceLayout>"
+  to: "<BlockLayout>"
+
 ## Version 1.2.0
 
 ### Breaking