시작하기

API 레퍼런스와 문제 해결

공개 컴포넌트·콜백·controller·서버 함수의 계약과 주요 오류의 해결 방법을 정리합니다.

reopt design업데이트 2026년 11월 1일

Deck Studio에서 바로 편집하기 →디자인 컬렉션 보기

1. DeckEditorProps

기본 문서는 Editorial 컬렉션이고 locale 기본값은 ko입니다. defaultValue와 value의 사용 방식은 시작하기 가이드를 참고하세요.

value?: DeckDocument: Controlled 문서. 다른 내용의 문서로 교체하면 내부 history가 초기화됩니다.
defaultValue?: unknown: 최초 문서. v1/v2 입력을 마이그레이션·검증합니다.
onChange?(document): void: 내부 편집으로 갱신된 v2 문서. 서버 저장은 호스트가 수행합니다.
historyLimit?: number: 보관할 history 한도. 기본값 100.
locale?: "ko" | "en": 편집기 UI 언어. 기본값 ko. 문서 콘텐츠를 자동 번역하지 않습니다.
runtime?: DeckRuntimeOptions: CanvasKit 인스턴스·자산 경로·자산 fetch 설정.
className? / style?: 편집기 컨테이너 스타일. 캔버스 높이가 확보되어야 합니다.
status?: string: 호스트의 저장 상태 문구. 저장 자체를 수행하지 않습니다.
extensions?: readonly DeckExtension[]: 커스텀 요소 확장 목록. 같은 ID·버전으로 등록된 요소의 삽입·재편집을 지원하며, 나머지는 저장된 스냅샷으로 표시합니다.
onBack?() / headerActions?: ReactNode: onBack을 제공하면 뒤로가기 버튼을 표시합니다. headerActions로 호스트 링크와 동작을 같은 헤더에 배치합니다. 이동 경로와 저장 확인은 호스트가 처리합니다.
readOnly?: boolean: 에디터 UI로 문서를 바꿀 수 없게 합니다. 선택·슬라이드 이동·확대·발표·내보내기는 그대로 동작하고, value와 ref 핸들을 통한 변경은 계속 적용됩니다.
ref?: Ref<DeckEditorHandle>: 마운트된 에디터의 명령형 핸들. getDocument·dispatch·replace·undo·redo·getSelection·select·getSlideId·goToSlide·fit·focus를 제공합니다. dispatch는 수동 편집과 같은 이력과 onChange 경로를 사용합니다.

1. DeckEditorProps
항목	동작과 사용 기준
value?: DeckDocument	Controlled 문서. 다른 내용의 문서로 교체하면 내부 history가 초기화됩니다.
defaultValue?: unknown	최초 문서. v1/v2 입력을 마이그레이션·검증합니다.
onChange?(document): void	내부 편집으로 갱신된 v2 문서. 서버 저장은 호스트가 수행합니다.
historyLimit?: number	보관할 history 한도. 기본값 100.
locale?: "ko" \| "en"	편집기 UI 언어. 기본값 ko. 문서 콘텐츠를 자동 번역하지 않습니다.
runtime?: DeckRuntimeOptions	CanvasKit 인스턴스·자산 경로·자산 fetch 설정.
className? / style?	편집기 컨테이너 스타일. 캔버스 높이가 확보되어야 합니다.
status?: string	호스트의 저장 상태 문구. 저장 자체를 수행하지 않습니다.
extensions?: readonly DeckExtension[]	커스텀 요소 확장 목록. 같은 ID·버전으로 등록된 요소의 삽입·재편집을 지원하며, 나머지는 저장된 스냅샷으로 표시합니다.
onBack?() / headerActions?: ReactNode	onBack을 제공하면 뒤로가기 버튼을 표시합니다. headerActions로 호스트 링크와 동작을 같은 헤더에 배치합니다. 이동 경로와 저장 확인은 호스트가 처리합니다.
readOnly?: boolean	에디터 UI로 문서를 바꿀 수 없게 합니다. 선택·슬라이드 이동·확대·발표·내보내기는 그대로 동작하고, value와 ref 핸들을 통한 변경은 계속 적용됩니다.
ref?: Ref<DeckEditorHandle>	마운트된 에디터의 명령형 핸들. getDocument·dispatch·replace·undo·redo·getSelection·select·getSlideId·goToSlide·fit·focus를 제공합니다. dispatch는 수동 편집과 같은 이력과 onChange 경로를 사용합니다.

2. 호스트 콜백

onAIEdit(request): SceneTransaction 또는 DeckDocument를 비동기로 반환합니다. request에는 mode·prompt·document·slideId·selection·signal이 있습니다. 후보는 기본 검토 UI를 거쳐 적용합니다.
onAssetUpload(file, signal): DeckAsset을 비동기로 반환합니다. 콜백이 없으면 로컬 파일을 문서에 포함합니다.
onAssetPick(signal): 호스트 자산 보관함을 열고 저장된 DeckAsset 또는 취소 시 null을 반환합니다. signal 중단 시 선택기를 닫습니다. 삽입은 undo/redo에 포함됩니다.
onPresent(document, slideId): void. 기본 발표 진입 대신 앱의 발표 화면을 엽니다.
onExport(format, document, signal): pdf/pptx/mp4/portable 작업이 끝나면 완료되는 Promise를 반환합니다. 완료·다운로드·취소 처리는 호스트가 소유합니다.
onShare(document): void. 공유 링크나 권한 UI를 호스트에서 엽니다.
onCreateVariant(document): 편집기에서 만든 파생 문서를 저장합니다. 비동기 작업이면 완료 Promise를 반환합니다.
onLoadSource(id, signal): 고객별 자료의 원본 DeckDocument를 비동기로 조회합니다.

2. 호스트 콜백
항목	동작과 사용 기준
onAIEdit(request)	SceneTransaction 또는 DeckDocument를 비동기로 반환합니다. request에는 mode·prompt·document·slideId·selection·signal이 있습니다. 후보는 기본 검토 UI를 거쳐 적용합니다.
onAssetUpload(file, signal)	DeckAsset을 비동기로 반환합니다. 콜백이 없으면 로컬 파일을 문서에 포함합니다.
onAssetPick(signal)	호스트 자산 보관함을 열고 저장된 DeckAsset 또는 취소 시 null을 반환합니다. signal 중단 시 선택기를 닫습니다. 삽입은 undo/redo에 포함됩니다.
onPresent(document, slideId)	void. 기본 발표 진입 대신 앱의 발표 화면을 엽니다.
onExport(format, document, signal)	pdf/pptx/mp4/portable 작업이 끝나면 완료되는 Promise를 반환합니다. 완료·다운로드·취소 처리는 호스트가 소유합니다.
onShare(document)	void. 공유 링크나 권한 UI를 호스트에서 엽니다.
onCreateVariant(document)	편집기에서 만든 파생 문서를 저장합니다. 비동기 작업이면 완료 Promise를 반환합니다.
onLoadSource(id, signal)	고객별 자료의 원본 DeckDocument를 비동기로 조회합니다.

3. DeckViewerProps

document: DeckDocument: 필수 v2 문서. 입력 경계에서 검증합니다.
slideId? / onSlideChange?(id): 현재 슬라이드와 변경 통지. 둘을 함께 연결해 controlled 탐색을 구성합니다.
controls?: boolean: 탐색 컨트롤 표시. 기본값 true.
showNotes?: boolean: 노트 패널의 초기 표시 여부. 기본값 false.
autoPlay?: boolean: 자동 재생. 기본값 false이며 브라우저 미디어 정책의 영향을 받습니다.
onClose?(): void: 뷰어 닫기 UI를 호스트에 연결합니다.
autoFocus?: boolean: 마운트 시 키보드 포커스를 가져옵니다. 기본값은 onClose가 있을 때만 true이며, 뷰어가 페이지 전체일 때 지정합니다.
locale? / runtime? / className? / style?: 언어·렌더 런타임·컨테이너 스타일. 편집기와 같은 런타임 옵션을 사용합니다.

3. DeckViewerProps
항목	동작과 사용 기준
document: DeckDocument	필수 v2 문서. 입력 경계에서 검증합니다.
slideId? / onSlideChange?(id)	현재 슬라이드와 변경 통지. 둘을 함께 연결해 controlled 탐색을 구성합니다.
controls?: boolean	탐색 컨트롤 표시. 기본값 true.
showNotes?: boolean	노트 패널의 초기 표시 여부. 기본값 false.
autoPlay?: boolean	자동 재생. 기본값 false이며 브라우저 미디어 정책의 영향을 받습니다.
onClose?(): void	뷰어 닫기 UI를 호스트에 연결합니다.
autoFocus?: boolean	마운트 시 키보드 포커스를 가져옵니다. 기본값은 onClose가 있을 때만 true이며, 뷰어가 페이지 전체일 때 지정합니다.
locale? / runtime? / className? / style?	언어·렌더 런타임·컨테이너 스타일. 편집기와 같은 런타임 옵션을 사용합니다.

4. useDeck과 DeckStore

useDeck(options)는 value·defaultValue·onChange·historyLimit을 받습니다. 반환한 store는 DeckStore 인스턴스입니다. UI에서 최신 결과에 반응하려면 hook의 document·canUndo·canRedo를 사용하세요.

document / canUndo / canRedo: 렌더에 구독되는 문서와 undo/redo 가능 상태.
undoLabel / redoLabel: 다음 undo/redo 작업의 이름.
getSnapshot(): hook에서는 최신 문서를 반환합니다. store.getSnapshot()은 문서와 history 상태를 포함한 객체를 반환합니다.
dispatch(transaction): 하나의 원자적 변경을 history에 기록합니다. 반환값은 void입니다.
replace(document, baseRevision?): 검증된 문서로 교체하고 history에 기록합니다. 기본 baseRevision은 호출 시점의 revision입니다.
applyAI(patches, options): 모델의 json-render patch를 검증해 현재 문서에 한 번의 변경으로 적용합니다(applyDeckPatches와 같은 옵션). hook에는 별도 미리보기 UI가 없으므로 호스트가 승인 흐름을 구성합니다.
undo() / redo(): history를 이동하며 revision은 단조 증가합니다.

4. useDeck과 DeckStore
항목	동작과 사용 기준
document / canUndo / canRedo	렌더에 구독되는 문서와 undo/redo 가능 상태.
undoLabel / redoLabel	다음 undo/redo 작업의 이름.
getSnapshot()	hook에서는 최신 문서를 반환합니다. store.getSnapshot()은 문서와 history 상태를 포함한 객체를 반환합니다.
dispatch(transaction)	하나의 원자적 변경을 history에 기록합니다. 반환값은 void입니다.
replace(document, baseRevision?)	검증된 문서로 교체하고 history에 기록합니다. 기본 baseRevision은 호출 시점의 revision입니다.
applyAI(patches, options)	모델의 json-render patch를 검증해 현재 문서에 한 번의 변경으로 적용합니다(applyDeckPatches와 같은 옵션). hook에는 별도 미리보기 UI가 없으므로 호스트가 승인 흐름을 구성합니다.
undo() / redo()	history를 이동하며 revision은 단조 증가합니다.

5. 서버 안전 진입점

아래 함수·타입은 @reopt-ai/opt-deck/server에서 가져옵니다. 실제 렌더링과 파일 인코딩은 브라우저 런타임 또는 호스트 출력 작업에서 수행하며, 내부 src 경로를 import하지 않습니다.

createDeckDocument / deckDesigns: 샘플 v2 문서 생성. design·title 등의 템플릿 옵션을 받습니다. deckDesigns는 선택할 수 있는 디자인 컬렉션 목록입니다.
parseDeckDocument / deckDocumentSchema: 현재 v2 문서의 스키마·참조·계층 검증.
migrateDeckDocument: v1/v2 입력을 v2 문서로 변환·검증.
applySceneTransaction / SceneOperation: 순수 문서 변경 함수와 명령 합집합. history는 store가 관리합니다.
createDeckVariant / compareVariantSource / mergeVariantSource: 고객별 파생 생성·원본 변경 비교·선택 병합.
createDeckPrompts / parseDeckReply / applyDeckPatches / renderDeckSpec: json-render 프롬프트 생성, 응답의 patch 파싱, 범위·잠금·revision 검증 적용, 덱 Spec 렌더.
defineComponent / instantiateComponent / updateComponentInstance / detachComponent: 재사용 구성요소와 인스턴스에 대한 장면 명령 생성.
readFontMetadata: 글꼴 파일에서 family·weight·style·임베드 메타데이터 읽기.

5. 서버 안전 진입점
항목	동작과 사용 기준
createDeckDocument / deckDesigns	샘플 v2 문서 생성. design·title 등의 템플릿 옵션을 받습니다. deckDesigns는 선택할 수 있는 디자인 컬렉션 목록입니다.
parseDeckDocument / deckDocumentSchema	현재 v2 문서의 스키마·참조·계층 검증.
migrateDeckDocument	v1/v2 입력을 v2 문서로 변환·검증.
applySceneTransaction / SceneOperation	순수 문서 변경 함수와 명령 합집합. history는 store가 관리합니다.
createDeckVariant / compareVariantSource / mergeVariantSource	고객별 파생 생성·원본 변경 비교·선택 병합.
createDeckPrompts / parseDeckReply / applyDeckPatches / renderDeckSpec	json-render 프롬프트 생성, 응답의 patch 파싱, 범위·잠금·revision 검증 적용, 덱 Spec 렌더.
defineComponent / instantiateComponent / updateComponentInstance / detachComponent	재사용 구성요소와 인스턴스에 대한 장면 명령 생성.
readFontMetadata	글꼴 파일에서 family·weight·style·임베드 메타데이터 읽기.

6. 증상별 확인 사항

Unable to load deck engine: assetBaseUrl의 canvaskit.js 응답과 CSP를 확인합니다. WASM과 번들 글꼴도 함께 배포해야 합니다.
Asset request failed: 자산 src의 권한·만료·CORS·HTTP 상태를 확인합니다. runtime.fetch가 필요한 요청인지 구분합니다.
Deck revision conflict: 오래된 트랜잭션 또는 AI 후보입니다. 최신 문서에서 다시 계산하고, 사용자의 새 편집을 덮어쓰지 않습니다.
"…" is outside the selection: patch가 바꾸는 요소 키(문서 ID)가 선택 범위 안에 있는지 확인합니다. 슬라이드를 선택하면 그 위의 모든 요소가 범위에 들어갑니다. 전체 생성은 generate 모드와 빈 선택을 사용합니다.
Undo history resets: value로 다른 내용의 문서를 넘기면 이력이 초기화됩니다. 내용이 같은 복제본은 이력을 유지합니다. onChange를 같은 업데이트에서 value에 반영하지 않으면 편집이 value로 되돌아가므로, 비동기로 반영한다면 defaultValue와 onChange를 사용하세요.
PPTX text wraps differently: 수신 앱의 글꼴 설치·대체 여부를 확인하고 PDF와 비교합니다. PPTX에는 글꼴이 내장되지 않습니다.
MP4 unavailable: 브라우저 WebCodecs와 H.264 인코더 지원을 확인하거나 onExport로 호스트 출력에 연결합니다.

6. 증상별 확인 사항
항목	동작과 사용 기준
Unable to load deck engine	assetBaseUrl의 canvaskit.js 응답과 CSP를 확인합니다. WASM과 번들 글꼴도 함께 배포해야 합니다.
Asset request failed	자산 src의 권한·만료·CORS·HTTP 상태를 확인합니다. runtime.fetch가 필요한 요청인지 구분합니다.
Deck revision conflict	오래된 트랜잭션 또는 AI 후보입니다. 최신 문서에서 다시 계산하고, 사용자의 새 편집을 덮어쓰지 않습니다.
"…" is outside the selection	patch가 바꾸는 요소 키(문서 ID)가 선택 범위 안에 있는지 확인합니다. 슬라이드를 선택하면 그 위의 모든 요소가 범위에 들어갑니다. 전체 생성은 generate 모드와 빈 선택을 사용합니다.
Undo history resets	value로 다른 내용의 문서를 넘기면 이력이 초기화됩니다. 내용이 같은 복제본은 이력을 유지합니다. onChange를 같은 업데이트에서 value에 반영하지 않으면 편집이 value로 되돌아가므로, 비동기로 반영한다면 defaultValue와 onChange를 사용하세요.
PPTX text wraps differently	수신 앱의 글꼴 설치·대체 여부를 확인하고 PDF와 비교합니다. PPTX에는 글꼴이 내장되지 않습니다.
MP4 unavailable	브라우저 WebCodecs와 H.264 인코더 지원을 확인하거나 onExport로 호스트 출력에 연결합니다.