Usage Playbook
opt-devtool을 단순히 여는 방법이 아니라, 개발 중 어떤 탭과 snapshot을 어떤 순서로 읽어야 하는지 정리합니다.
reopt designUpdated
1. 기본 활용 루틴
- 문제가 나는 라우트에서
Ctrl+Shift+F로 overlay를 엽니다. - 먼저 Component 탭에서 현재 focus, tab order, component chain, event log를 확인합니다.
- 문제가 특정 엔진 상태와 연결되어 있으면 DataGrid plugin panel, opt-editor, Brandapp, Harness, Theme 탭으로 이동합니다.
- snapshot의 ID, 선택 상태, pending/error/status 값을 재현 전후로 비교합니다.
- 재현 문서나 테스트 라우트에서는 configure event로 overlay 상태를 고정해 스크린샷과 리뷰 기준을 맞춥니다.
2. 탭별로 읽을 것
| 탭 | 등록 경로 | 확인할 내용 |
|---|---|---|
| Component | built-in scanner + component plugins | 포커스 대상, tab order, component chain, composite boundary, event log를 확인합니다. DataGrid bridge도 이 탭의 plugin panel로 등록됩니다. |
| opt-editor | useEditorDevtoolBridge | mode, streamStatus, selectedBlockIds/types, elementCount, undo/redo, focusTarget, feature flags, lastChangedIds를 확인합니다. |
| Brandapp | useBrandappDevtoolBridge | brandappId, masked clientId, env presence, auth/EAV/AI status, routes, notes를 한 번에 확인합니다. |
| Theme | Shell theme event + useThemeDevtoolBridge | preset/generated mode, seed, harmony, radius/shadow/neutral 설정, light/dark token, contrast pair를 확인합니다. |
| Harness | useShellDevtoolBridge | manifest, density, contentWidth, navigationMode, adapter chrome, stateBoundary, diff, staleness, nav/aside/header stack 상태를 확인합니다. |
3. 상황별 점검
키보드 이동이 이상할 때
Component 탭에서 Tab order, Guide lines, Spatial nav, Event log를 켭니다. 현재 요소가 tabbable 목록에 있는지, composite 내부에서 keydown이 소비되는지, trapped context가 있는지 순서대로 확인합니다.
DataGrid 편집/원격 저장이 불안정할 때
DataGrid bridge가 등록된 Component plugin panel에서 activeCell, editingCell, selection, visibleRegion, history, draftError를 봅니다. remote datasource를 쓰는 화면이면 telemetry의 load/save/rejectedEdit/pageRetry 카운터까지 같이 확인합니다.
Editor AI stream 또는 selection이 어긋날 때
opt-editor 탭에서 mode와 streamStatus가 예상과 맞는지 먼저 확인합니다. 이어 selectedBlockIds/types, focusTarget, externalStreaming, lastChangedIds를 보고 stream patch가 어느 블록을 바꾸고 있는지 좁힙니다.
Brandapp 연동이 환경마다 다를 때
Brandapp 탭에서 environment, baseUrl, required env status, auth/EAV/AI feature status, route wiring을 확인합니다. clientId는 masked 값만 노출되므로 스크린샷 공유에도 secret이 직접 새지 않습니다.
Shell layout이나 theme drift를 잡을 때
Harness 탭에서 density, contentWidth, navigationMode, adapter chrome, stateBoundary, snapshot diff/staleness를 확인합니다. Theme 탭에서는 generated token과 contrast pair가 실제 seed 설정과 맞는지 봅니다.
4. 재현 상태 고정
데모, 문서, QA 재현 라우트에서는 OPT_DEVTOOL_CONFIGURE_EVENT를 dispatch해 overlay와 토글 상태를 고정할 수 있습니다. 이벤트는 브라우저에서만 보내야 하므로 client component의 effect 안에서 사용합니다.
"use client";
import { useEffect } from "react";
import { OPT_DEVTOOL_CONFIGURE_EVENT } from "@reopt-ai/opt-devtool/ui";
export function OpenDevtoolForRepro() {
useEffect(() => {
window.dispatchEvent(
new CustomEvent(OPT_DEVTOOL_CONFIGURE_EVENT, {
detail: {
visible: true,
showGuide: true,
showTabOrder: true,
showSpatialNav: true,
showEventLog: true,
showInspect: true,
showComponentLabels: true,
showCompositeBounds: true,
},
}),
);
}, []);
return null;
}5. 적용 체크리스트
| 항목 | 확인 기준 |
|---|---|
| Root mount | 앱 루트에서 OptDevtoolProvider로 감싸고 development 환경에서만 OptDevtool을 렌더링합니다. |
| Bridge id | 화면별 bridge id는 안정적으로 유지합니다. 같은 화면의 여러 grid/editor는 id와 label을 다르게 둡니다. |
| Inspect callback | 엔진이 제공하는 inspect prop에 bridge의 inspect 콜백을 그대로 전달합니다. snapshot은 엔진 상태 변경 때 갱신됩니다. |
| Reproduction preset | 문서나 재현 라우트에서는 configure event로 overlay와 필요한 토글을 미리 켜둘 수 있습니다. |