Start
API reference and troubleshooting
Public component, callback, controller and server contracts, plus remedies for common integration errors.
reopt designUpdated
1. DeckEditorProps
The default document is the Editorial collection and locale defaults to ko. See Getting started for value and defaultValue semantics.
- value?: DeckDocument
- Controlled document. Replacing it with different content resets internal history.
- defaultValue?: unknown
- Initial document, migrated and validated from v1/v2 input.
- onChange?(document): void
- Emits the v2 document after internal edits; the host persists it.
- historyLimit?: number
- History capacity; defaults to 100.
- locale?: "ko" | "en"
- Editor UI language; defaults to ko. Does not translate document content.
- runtime?: DeckRuntimeOptions
- CanvasKit instance, asset URL and asset-fetch configuration.
- className? / style?
- Editor container styling. Provide sufficient canvas height.
- status?: string
- Host-provided save-status text; does not perform a save.
- extensions?: readonly DeckExtension[]
- Custom element extensions. Matching IDs and versions support insertion and editing; other elements display their stored snapshots.
- onBack?() / headerActions?: ReactNode
- Provide onBack to show back navigation and headerActions to place host controls in the same header. The host owns the destination and unsaved-change handling.
- readOnly?: boolean
- Prevents changes from the editor UI. Selection, slide navigation, zoom, presenting and export keep working, and changes made through value or the ref handle still apply.
- ref?: Ref<DeckEditorHandle>
- Imperative handle of the mounted editor: getDocument, dispatch, replace, undo, redo, getSelection, select, getSlideId, goToSlide, fit and focus. dispatch shares the history and onChange path of manual edits.
| Item | Behavior and usage |
|---|---|
| value?: DeckDocument | Controlled document. Replacing it with different content resets internal history. |
| defaultValue?: unknown | Initial document, migrated and validated from v1/v2 input. |
| onChange?(document): void | Emits the v2 document after internal edits; the host persists it. |
| historyLimit?: number | History capacity; defaults to 100. |
| locale?: "ko" | "en" | Editor UI language; defaults to ko. Does not translate document content. |
| runtime?: DeckRuntimeOptions | CanvasKit instance, asset URL and asset-fetch configuration. |
| className? / style? | Editor container styling. Provide sufficient canvas height. |
| status?: string | Host-provided save-status text; does not perform a save. |
| extensions?: readonly DeckExtension[] | Custom element extensions. Matching IDs and versions support insertion and editing; other elements display their stored snapshots. |
| onBack?() / headerActions?: ReactNode | Provide onBack to show back navigation and headerActions to place host controls in the same header. The host owns the destination and unsaved-change handling. |
| readOnly?: boolean | Prevents changes from the editor UI. Selection, slide navigation, zoom, presenting and export keep working, and changes made through value or the ref handle still apply. |
| ref?: Ref<DeckEditorHandle> | Imperative handle of the mounted editor: getDocument, dispatch, replace, undo, redo, getSelection, select, getSlideId, goToSlide, fit and focus. dispatch shares the history and onChange path of manual edits. |
2. Host callbacks
- onAIEdit(request)
- Asynchronously returns a SceneTransaction or DeckDocument. Request fields: mode, prompt, document, slideId, selection, signal. Candidates pass through built-in review.
- onAssetUpload(file, signal)
- Asynchronously returns a DeckAsset. Without a callback, local files are embedded.
- onAssetPick(signal)
- Open a host asset library and return a stored DeckAsset, or null on cancel. Close the picker when its signal aborts. Insertion participates in undo/redo.
- onPresent(document, slideId)
- void. Open a host presentation experience instead of the built-in one.
- onExport(format, document, signal)
- Returns a Promise that resolves when a pdf/pptx/mp4/portable job finishes. The host owns completion, download and cancellation.
- onShare(document)
- void. Open host sharing/link/permission UI.
- onCreateVariant(document)
- Persists the edition created by the editor. Return a completion Promise for asynchronous work.
- onLoadSource(id, signal)
- Asynchronously fetches the source DeckDocument for an edition.
| Item | Behavior and usage |
|---|---|
| onAIEdit(request) | Asynchronously returns a SceneTransaction or DeckDocument. Request fields: mode, prompt, document, slideId, selection, signal. Candidates pass through built-in review. |
| onAssetUpload(file, signal) | Asynchronously returns a DeckAsset. Without a callback, local files are embedded. |
| onAssetPick(signal) | Open a host asset library and return a stored DeckAsset, or null on cancel. Close the picker when its signal aborts. Insertion participates in undo/redo. |
| onPresent(document, slideId) | void. Open a host presentation experience instead of the built-in one. |
| onExport(format, document, signal) | Returns a Promise that resolves when a pdf/pptx/mp4/portable job finishes. The host owns completion, download and cancellation. |
| onShare(document) | void. Open host sharing/link/permission UI. |
| onCreateVariant(document) | Persists the edition created by the editor. Return a completion Promise for asynchronous work. |
| onLoadSource(id, signal) | Asynchronously fetches the source DeckDocument for an edition. |
3. DeckViewerProps
- document: DeckDocument
- Required v2 document. Validate at the input boundary.
- slideId? / onSlideChange?(id)
- Current slide and change notification; pair them for controlled navigation.
- controls?: boolean
- Show navigation controls; defaults to true.
- showNotes?: boolean
- Initial notes-panel visibility; defaults to false.
- autoPlay?: boolean
- Autoplay; defaults to false and remains subject to browser media policies.
- onClose?(): void
- Connect viewer close behavior to the host.
- autoFocus?: boolean
- Take keyboard focus on mount. Defaults to true only with onClose; set it when the viewer is the whole page.
- locale? / runtime? / className? / style?
- Language, rendering runtime and container styling, using the same runtime options as the editor.
| Item | Behavior and usage |
|---|---|
| document: DeckDocument | Required v2 document. Validate at the input boundary. |
| slideId? / onSlideChange?(id) | Current slide and change notification; pair them for controlled navigation. |
| controls?: boolean | Show navigation controls; defaults to true. |
| showNotes?: boolean | Initial notes-panel visibility; defaults to false. |
| autoPlay?: boolean | Autoplay; defaults to false and remains subject to browser media policies. |
| onClose?(): void | Connect viewer close behavior to the host. |
| autoFocus?: boolean | Take keyboard focus on mount. Defaults to true only with onClose; set it when the viewer is the whole page. |
| locale? / runtime? / className? / style? | Language, rendering runtime and container styling, using the same runtime options as the editor. |
4. useDeck and DeckStore
useDeck(options) accepts value, defaultValue, onChange and historyLimit. Its store is a DeckStore instance. Use the hook document, canUndo and canRedo fields for reactive UI.
- document / canUndo / canRedo
- Reactive document and history availability.
- undoLabel / redoLabel
- Labels for the next undo/redo operation.
- getSnapshot()
- On the hook, returns the latest document. store.getSnapshot() returns an object including document and history state.
- dispatch(transaction)
- Record one atomic transaction in history. Returns void.
- replace(document, baseRevision?)
- Validate and replace the document with a history entry. baseRevision defaults to the current revision.
- applyAI(patches, options)
- Check a model's json-render patches and apply them to the current document as one change (the same options as applyDeckPatches). The hook has no preview UI; the host provides review.
- undo() / redo()
- Move through history while revisions keep increasing.
| Item | Behavior and usage |
|---|---|
| document / canUndo / canRedo | Reactive document and history availability. |
| undoLabel / redoLabel | Labels for the next undo/redo operation. |
| getSnapshot() | On the hook, returns the latest document. store.getSnapshot() returns an object including document and history state. |
| dispatch(transaction) | Record one atomic transaction in history. Returns void. |
| replace(document, baseRevision?) | Validate and replace the document with a history entry. baseRevision defaults to the current revision. |
| applyAI(patches, options) | Check a model's json-render patches and apply them to the current document as one change (the same options as applyDeckPatches). The hook has no preview UI; the host provides review. |
| undo() / redo() | Move through history while revisions keep increasing. |
5. Server-safe entry point
Import these functions and types from @reopt-ai/opt-deck/server. Rendering and encoding belong to the browser runtime or a host export job. Do not import internal src paths.
- createDeckDocument / deckDesigns
- Create a sample v2 document from template options such as design and title. deckDesigns lists the available design collections.
- parseDeckDocument / deckDocumentSchema
- Validate the current v2 schema, references and hierarchy.
- migrateDeckDocument
- Migrate and validate v1/v2 input as a v2 document.
- applySceneTransaction / SceneOperation
- Pure document transformation and operation union. A store owns history.
- createDeckVariant / compareVariantSource / mergeVariantSource
- Create customer editions, compare source updates and merge accepted changes.
- createDeckPrompts / parseDeckReply / applyDeckPatches / renderDeckSpec
- Build json-render prompts, parse reply patches, apply them with scope, lock and revision checks, and render a deck spec.
- defineComponent / instantiateComponent / updateComponentInstance / detachComponent
- Build scene operations for reusable component sources and instances.
- readFontMetadata
- Read family, weight, style and embedding metadata from font bytes.
| Item | Behavior and usage |
|---|---|
| createDeckDocument / deckDesigns | Create a sample v2 document from template options such as design and title. deckDesigns lists the available design collections. |
| parseDeckDocument / deckDocumentSchema | Validate the current v2 schema, references and hierarchy. |
| migrateDeckDocument | Migrate and validate v1/v2 input as a v2 document. |
| applySceneTransaction / SceneOperation | Pure document transformation and operation union. A store owns history. |
| createDeckVariant / compareVariantSource / mergeVariantSource | Create customer editions, compare source updates and merge accepted changes. |
| createDeckPrompts / parseDeckReply / applyDeckPatches / renderDeckSpec | Build json-render prompts, parse reply patches, apply them with scope, lock and revision checks, and render a deck spec. |
| defineComponent / instantiateComponent / updateComponentInstance / detachComponent | Build scene operations for reusable component sources and instances. |
| readFontMetadata | Read family, weight, style and embedding metadata from font bytes. |
6. Troubleshooting
- Unable to load deck engine
- Check canvaskit.js at assetBaseUrl and the application CSP. Deploy WASM and bundled fonts too.
- Asset request failed
- Check asset permissions, expiry, CORS and HTTP status. Determine whether runtime.fetch is needed.
- Deck revision conflict
- A transaction or AI candidate is stale. Recompute from the current document without overwriting newer edits.
- "…" is outside the selection
- Check that the element keys (document IDs) the patches change are inside the selection; selecting a slide includes everything on it. Whole-deck generation requires generate mode and an empty selection.
- Undo history resets
- History resets when value receives a document with different content; a structurally equal copy keeps it. An edit that onChange does not apply to value in the same update is rolled back, so use defaultValue with onChange if you apply changes asynchronously.
- PPTX text wraps differently
- Check installed/substituted fonts in the receiving app and compare PDF output. PPTX does not embed fonts.
- MP4 unavailable
- Check browser WebCodecs/H.264 support or delegate export through onExport.
| Item | Behavior and usage |
|---|---|
| Unable to load deck engine | Check canvaskit.js at assetBaseUrl and the application CSP. Deploy WASM and bundled fonts too. |
| Asset request failed | Check asset permissions, expiry, CORS and HTTP status. Determine whether runtime.fetch is needed. |
| Deck revision conflict | A transaction or AI candidate is stale. Recompute from the current document without overwriting newer edits. |
| "…" is outside the selection | Check that the element keys (document IDs) the patches change are inside the selection; selecting a slide includes everything on it. Whole-deck generation requires generate mode and an empty selection. |
| Undo history resets | History resets when value receives a document with different content; a structurally equal copy keeps it. An edit that onChange does not apply to value in the same update is rolled back, so use defaultValue with onChange if you apply changes asynchronously. |
| PPTX text wraps differently | Check installed/substituted fonts in the receiving app and compare PDF output. PPTX does not embed fonts. |
| MP4 unavailable | Check browser WebCodecs/H.264 support or delegate export through onExport. |