Build & Operate

Debugging Guide

`Ctrl+Shift+F`로 여는 opt-devtool overlay를 기준으로 focus, keyboard, component boundary 문제를 점검하는 방법을 정리합니다.

reopt designUpdated Jun 26, 2026

1. 기본 마운트

overlay는 앱 루트에 한 번만 마운트합니다. 기존 `opt-ui` 전용 debugger와 달리, 같은 패널 안에 module bridge 탭까지 같이 들어옵니다. `opt-editor` bridge가 있으면 상단에 전용 `opt-editor` 탭이 추가됩니다.

tsx

import { OptDevtool, OptDevtoolProvider } from "@reopt-ai/opt-devtool";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="ko">
      <body>
        <OptDevtoolProvider>
          {children}
          {process.env.NODE_ENV === "development" ? <OptDevtool /> : null}
        </OptDevtoolProvider>
      </body>
    </html>
  );
}

2. 주요 토글

토글	역할
Tab 순서 표시	모든 tabbable 요소에 순서 뱃지를 올리고 현재 포커스와 이전/다음 대상의 위치를 바로 확인합니다.
포커스 가이드	현재 요소에서 Tab, Shift+Tab, 방향키, spatial navigation 후보로 이어지는 관계선을 그립니다.
인스펙트 모드	마우스로 특정 요소를 고정해 aria/data 속성, component chain, trapped context를 읽습니다.
이벤트 로그	focusin, focusout, keydown을 타임라인으로 기록해 unexpected preventDefault나 focus jump를 확인합니다.
컴포넌트 라벨 / Composite 경계	opt-ui component chain과 roving/spatial container 경계를 overlay 위에 직접 표시합니다.

3. 데모/문서에서 강제 열기

문서 페이지나 showcase에서는 config event를 보내 overlay를 자동으로 열어둘 수 있습니다.

tsx

import { OPT_DEVTOOL_CONFIGURE_EVENT } from "@reopt-ai/opt-devtool";

window.dispatchEvent(
  new CustomEvent(OPT_DEVTOOL_CONFIGURE_EVENT, {
    detail: {
      visible: true,
      showGuide: true,
      showTabOrder: true,
      showSpatialNav: true,
      showEventLog: true,
      showComponentLabels: true,
      showCompositeBounds: true,
    },
  }),
);

4. 문제 진단 워크플로우

Tab 순서가 어긋날 때

Tab 순서 표시를 켜고 번호를 본 뒤, tabindex 양수 사용 여부와 DOM 순서를 먼저 확인합니다.

방향키 이동이 멈출 때

Composite 경계를 켜서 현재 요소가 composite 내부인지 확인하고, 이벤트 로그에서 keydown이 소비되는 지점을 찾습니다.

Spatial Navigation이 예상과 다를 때

포커스 가이드를 켜서 후보 선과 protected direction을 확인하고, trapped context(dialog/menu/listbox) 여부를 같이 봅니다.

컴포넌트 계층이 복잡할 때

인스펙트 모드로 특정 요소를 고정하고 component chain과 data/aria 속성을 한 번에 읽습니다.