Build & Operate

앱 조합 가이드

페이지 골격은 opt-ui에 두고, 생성·편집·변환이 필요한 본문 영역만 opt-editor로 분리하는 기준을 정리합니다.

reopt designUpdated Jun 26, 2026

1. 경계 설정 기준

문제 영역	Owner	판단 기준
페이지 레이아웃, toolbar, surrounding form, review panel	opt-ui	상위 화면 구조와 navigation은 Shell/Surface가 관리하고 editor는 본문 영역으로 주입합니다.
블록 스키마, inline mark, stream apply, slash command	opt-editor	문서 상태 모델과 authoring interaction은 opt-editor의 spec/store가 직접 소유합니다.
AI generation, NDJSON patch stream, retry/resume	opt-editor	LLM 응답을 안전하게 적용하는 프로토콜과 patch compiler는 editor 문서 기준으로 설계합니다.
간단한 설명 필드나 설정 메모	opt-ui	블록 편집이나 markdown round-trip이 없으면 일반 form field나 shell 편집기로 충분합니다.

2. 추천 조합 패턴

콘텐츠 관리 화면 + Editor

리스트, 필터, 액션 바는 opt-ui가 맡고 본문 작성/검수 영역만 Editor로 위임합니다.

ProjectOverview Authoring 플레이북 AI 연동

생성 후 검수 워크벤치

좌측 메타데이터 폼은 opt-ui, 중앙 본문은 Editor, 우측 승인 패널도 opt-ui로 두는 구조입니다.

SettingsForm 스트리밍 Markdown 변환

커스텀 작성 도구

브랜드 전용 블록과 편집 규칙은 Editor 카탈로그에 넣고, 바깥 조립은 opt-ui로 유지합니다.

AppShell 커스텀 블록 핵심 개념

3. 화면 조립 예제

메타데이터 폼과 페이지 액션은 opt-ui에 두고, 실제 콘텐츠 본문만 Editor store에 연결하는 패턴이 가장 안정적입니다.

tsx

import { AppShell, Card, SettingsForm } from "@reopt-ai/opt-ui";
import { Editor, defaultCatalog } from "@reopt-ai/opt-editor";

export default function ArticleWorkbenchPage() {
  return (
    <AppShell header={<Toolbar title="Article Review" />}>
      <section className="grid gap-4 xl:grid-cols-[320px_1fr]">
        <SettingsForm fields={fields} values={meta} onChange={setMeta} />

        <Card>
          <Editor
            store={editorStore}
            catalog={defaultCatalog}
            mode={mode}
          />
        </Card>
      </section>
    </AppShell>
  );
}

4. 위임 규칙

1. 일반 폼인지 authoring surface인지 먼저 구분합니다. 블록 편집이 아니면 opt-ui form 계열을 유지합니다.
2. 본문 상태는 editor spec으로 분리 합니다. page state에 nested JSON으로 억지로 묻지 않습니다.
3. AI 생성은 editor protocol 기준 으로 붙입니다. 텍스트 전체 치환보다 patch stream을 우선합니다.
4. export는 마지막 단계에서만 수행 합니다. 작업 중 내부 canonical state는 spec으로 유지합니다.

5. 통합 체크리스트

- 페이지 툴바, 검수 패널, 승인 버튼은 opt-ui Shell에서 관리합니다.

- 본문 상태는 opt-editor spec/store로 분리하고 page form state와 섞지 않습니다.

- AI 응답은 markdown raw text 대신 NDJSON patch stream으로 적용합니다.

- publish/export 직전에만 markdown 또는 최종 포맷으로 serialize합니다.

- toolbar, editor, review panel 사이 포커스 진입/이탈 규칙을 명시합니다.