Merge pull request #16 from sjsjsj1246/codex/harden-promise-api

[-]: Promise API 계약 안정화

Author: sjsjsj1246

README.md

@@ -88,11 +88,12 @@ const App = () => {
 };
 ```
 
-`tutorial.open()` returns `Promise<{ reason: 'completed' | 'skipped' | 'closed' }>`:
+`tutorial.open()` returns `Promise<{ reason: 'completed' | 'skipped' | 'closed' | 'replaced' }>`:
 
 - `completed`: the user finished the last step.
 - `skipped`: the user clicked the built-in `건너뛰기` button.
-- `closed`: the tutorial was closed externally, such as `tutorial.close()`, `Escape`, backdrop click, or opening a new tutorial while another promise is still pending.
+- `closed`: the tutorial was closed externally, such as `tutorial.close()`, `Escape`, or backdrop click.
+- `replaced`: a newer `tutorial.open()` call replaced a tutorial whose promise was still pending.
 
 To start from a specific step, pass `startAt` to `tutorial.open()`:
 
@@ -138,7 +139,7 @@ The info box automatically flips and clamps itself to stay inside the viewport w
 
 For accessibility, the info box is exposed as a labeled `dialog`. When the tutorial opens, focus moves into the info box controls, and when it closes, focus returns to the element that was active before open. The library does not currently trap focus inside the overlay.
 
-`options.onClose` still runs whenever the tutorial closes. Use the returned Promise when you need async flow control after the tutorial ends.
+`options.onClose` still runs whenever the active tutorial closes, including replacement by a newer `tutorial.open()` call. Use the returned Promise when you need async flow control after the tutorial ends.
 
 Mount `<TutorialOverlay />` once near the root of your app, then trigger `tutorial.open({ steps, options, startAt })` from any event handler or effect.
 

docs/plans/2026-03-24-project-restart.md

@@ -21,6 +21,7 @@
 - 완료: `codex/add-promise-api` 병합 완료
 - 완료: `codex/improve-accessibility` 병합 완료
 - 완료: `codex/add-progress-control-api` 병합 완료
+- 완료: `codex/harden-promise-api` 병합 완료
 - 반영된 내용:
   - `packages/main/test/setup.ts` 추가
   - `packages/main/jest.config.js` 정상화
@@ -45,10 +46,13 @@
   - `input` / `textarea` / `select` / `contenteditable` 포커스 중 단축키 무시 처리 추가
   - backdrop click close를 opt-in 동작으로 추가하고 highlight / info box 클릭과 구분
   - keyboard / overlay close 관련 README 및 docs 예제 업데이트
-  - `tutorial.open()`이 `Promise<{ reason: 'completed' | 'skipped' | 'closed' }>`를 반환하도록 확장
-  - 마지막 step 완료, built-in 건너뛰기, 외부 close 경로별 resolve reason 구분 추가
-  - 새 tutorial open 시 이전 pending promise를 `closed`로 정리하도록 보정
+  - `tutorial.open()`이 `Promise<{ reason: 'completed' | 'skipped' | 'closed' | 'replaced' }>`를 반환하도록 확장
+  - 마지막 step 완료, built-in 건너뛰기, 외부 close 경로, replacement open 경로별 resolve reason 계약 고정
+  - 새 tutorial open 시 이전 pending promise를 `replaced`로 정리하도록 보정
   - Promise API와 `onClose`의 역할을 분리하고 기존 callback 계약 유지
+  - 이미 settle된 뒤의 중복 `tutorial.close()` 호출이 Promise 계약이나 `onClose` 호출 횟수를 깨뜨리지 않도록 보강
+  - `Escape` / backdrop click / replacement open Promise resolve reason 테스트 추가
+  - README 및 docs에 Promise resolve 정책과 `replaced` reason 명시
   - `tutorial.open()`에 `startAt` 추가로 시작 step을 명시적으로 제어 가능
   - `tutorial.goTo(index)` 추가로 active tutorial의 step index를 외부에서 이동 가능
   - `tutorial.getState()` 추가로 open 여부, 현재 index, step 수, current step snapshot 조회 가능
@@ -88,6 +92,8 @@
 
 첫 기능 확장 작업으로 권장했던 `codex/add-keyboard-and-close-controls`, `codex/add-highlight-padding-and-overlay-click-behavior`, `codex/add-promise-api`는 모두 완료 및 병합됐다.
 
+Promise API 후속 안정화 작업으로 진행한 `codex/harden-promise-api`도 완료 및 병합됐다. 현재 Promise contract는 `completed`, `skipped`, `closed`, `replaced`를 구분하고, replacement open과 중복 close edge case까지 테스트로 고정된 상태다.
+
 후속 접근성 안정화 작업으로 권장했던 `codex/improve-accessibility`도 완료 및 병합됐다. 현재 overlay는 dialog semantics와 open/close focus lifecycle까지는 안정화됐고, focus trap과 background inert는 다음 접근성 확장 후보로 남겨둔다.
 
 첫 progress control 확장 후보였던 `codex/add-progress-control-api`도 완료 및 병합됐다. 이제 외부 제어는 `startAt`, `goTo(index)`, `getState()`까지 포함하는 수준으로 정리됐고, 다음 확장 후보는 richer state subscription이나 callback surface가 필요한지 여부를 별도 계획 문서에서 다시 판단하면 된다.
@@ -399,9 +405,10 @@ Expected:
 **Goal:** 튜토리얼 완료/취소 시점을 소비자가 await할 수 있도록 Promise 기반 API를 추가한다.
 
 **Result:**
-- `tutorial.open()`이 `Promise<{ reason: 'completed' | 'skipped' | 'closed' }>`를 반환하도록 변경
-- 마지막 step 완료 시 `completed`, built-in `건너뛰기` 버튼 경로에서 `skipped`, 외부 `tutorial.close()` / `Escape` / backdrop close / replacement open 경로에서 `closed` resolve 추가
+- `tutorial.open()`이 `Promise<{ reason: 'completed' | 'skipped' | 'closed' | 'replaced' }>`를 반환하도록 변경
+- 마지막 step 완료 시 `completed`, built-in `건너뛰기` 버튼 경로에서 `skipped`, 외부 `tutorial.close()` / `Escape` / backdrop close 경로에서 `closed`, replacement open 경로에서 `replaced` resolve 추가
 - pending promise가 한 번만 settle되도록 중복 resolve 방지
-- 새 tutorial을 열면 기존 pending tutorial을 `closed`로 정리하고 기존 `options.onClose`도 계속 실행되도록 유지
+- 새 tutorial을 열면 기존 pending tutorial을 `replaced`로 정리하고 기존 `options.onClose`도 계속 실행되도록 유지
 - `packages/main/test/tutorial.test.tsx` 및 `packages/main/test/content.test.tsx`에 Promise API 회귀 테스트 추가
+- `packages/main/test/tutorial-overlay.test.tsx`에 `Escape` / backdrop click close reason 테스트 추가
 - README 및 docs landing/tutorial/tutorial-overlay 문서에 async usage 예제와 reason 계약 반영

packages/document/src/pages/docs/index.mdx

@@ -58,7 +58,7 @@ const App = () => {
 
 Mount `<TutorialOverlay />` once in your app. Then call `tutorial.open({ steps, options })` from any button handler or effect.
 
-`tutorial.open()` resolves with `{ reason: 'completed' | 'skipped' | 'closed' }` so you can await the end of the tutorial.
+`tutorial.open()` resolves with `{ reason: 'completed' | 'skipped' | 'closed' | 'replaced' }` so you can await the end of the tutorial.
 
 Use `startAt` to open on a specific step, `tutorial.goTo(index)` to move within an active tutorial, and `tutorial.getState()` to read `{ open, index, stepCount, currentStep }` for external progress UI.
 

packages/document/src/pages/docs/tutorial-overlay.mdx

@@ -24,7 +24,7 @@ function App() {
 
 `TutorialOverlay` does not need props for the current public API. Configure behavior through `tutorial.open({ steps, options })`.
 
-Because `tutorial.open()` returns a Promise, you can keep `<TutorialOverlay />` mounted once and await tutorial completion from any handler or effect that triggers the open call.
+Because `tutorial.open()` returns a Promise, you can keep `<TutorialOverlay />` mounted once and await tutorial completion from any handler or effect that triggers the open call. The Promise resolves with `completed`, `skipped`, `closed`, or `replaced` depending on how that run ended.
 
 The highlight frame uses `options.highLightPadding` to expand around the target. If you do not provide it, the overlay uses an `8px` padding by default.
 

packages/document/src/pages/docs/tutorial.mdx

@@ -62,7 +62,7 @@ function App() {
 
 ## Available methods
 
-- `tutorial.open({ steps, options, startAt })`: opens a tutorial and starts at `startAt` when provided. `startAt` is clamped to the available step range. Returns `Promise<{ reason: 'completed' | 'skipped' | 'closed' }>` when that tutorial ends.
+- `tutorial.open({ steps, options, startAt })`: opens a tutorial and starts at `startAt` when provided. `startAt` is clamped to the available step range. Returns `Promise<{ reason: 'completed' | 'skipped' | 'closed' | 'replaced' }>` when that tutorial ends.
 - `tutorial.next()`: moves to the next step and closes the overlay after the last step.
 - `tutorial.prev()`: moves back one step when possible.
 - `tutorial.goTo(index)`: moves the active tutorial to a specific step. The index is clamped to the available range, and calling it while closed is a no-op.
@@ -74,7 +74,8 @@ function App() {
 
 - `completed`: the last step was completed through `tutorial.next()` or the built-in `완료` button.
 - `skipped`: the built-in `건너뛰기` button was clicked.
-- `closed`: the tutorial was closed manually with `tutorial.close()`, `Escape`, backdrop click, or because a newer tutorial replaced a pending one.
+- `closed`: the tutorial was closed manually with `tutorial.close()`, `Escape`, or backdrop click.
+- `replaced`: a newer `tutorial.open()` call replaced a tutorial whose promise was still pending.
 
 ## Step fields
 
@@ -114,7 +115,7 @@ console.log(state.currentStep?.title);
 - `labels`: overrides the built-in `prev`, `next`, `skip`, and `done` button labels.
 - `keyboardNavigation`: enables `Escape`, `ArrowLeft`, and `ArrowRight` shortcuts while the overlay is open. Defaults to `true`.
 - `closeOnOverlayClick`: closes the tutorial when the backdrop itself is clicked. Defaults to `false`.
-- `onClose`: runs when the tutorial is closed.
+- `onClose`: runs when the active tutorial is closed, including replacement by a newer `tutorial.open()` call.
 
 Keyboard shortcuts are ignored while an `input`, `textarea`, `select`, or `contenteditable` element has focus.
 The info box automatically repositions itself to stay within the viewport when the target is close to an edge.

packages/main/src/core/store.ts

@@ -48,6 +48,7 @@ function settlePendingTutorial(result: TutorialResult) {
     return;
   }
 
+  // Clear the resolver before invoking it so duplicate close paths stay a no-op.
   const resolve = pendingTutorialResolver;
   pendingTutorialResolver = null;
   resolve(result);
@@ -61,6 +62,10 @@ const reducer = (state: State, action: Action): State => {
         index: clampIndex(action.payload.index, action.payload.tutorial.steps.length),
       };
     case ActionType.CLOSE:
+      if (!state.open && !hasPendingTutorialResult()) {
+        return initialState;
+      }
+
       settlePendingTutorial({ reason: action.payload.reason });
       state.tutorial.options?.onClose?.();
       return initialState;

packages/main/src/core/tutorial.ts

@@ -10,7 +10,7 @@ import type { Step, Tutorial, TutorialProgressState, TutorialResult } from './ty
 
 const open = (tutorial: Tutorial, otherState?: Omit<State, 'tutorial'>): Promise<TutorialResult> => {
   if (getStoreState().open || hasPendingTutorialResult()) {
-    dispatch({ type: ActionType.CLOSE, payload: { reason: 'closed' } });
+    dispatch({ type: ActionType.CLOSE, payload: { reason: 'replaced' } });
   }
 
   const resultPromise = createPendingTutorialResult();

packages/main/src/core/types.ts

@@ -37,7 +37,7 @@ export interface Tutorial {
   startAt?: number;
 }
 
-export type TutorialResultReason = 'completed' | 'skipped' | 'closed';
+export type TutorialResultReason = 'completed' | 'skipped' | 'closed' | 'replaced';
 
 export interface TutorialResult {
   reason: TutorialResultReason;

packages/main/test/tutorial-overlay.test.tsx

@@ -18,8 +18,10 @@ function renderOverlay() {
 }
 
 function openTutorial(options: Options = {}) {
+  let resultPromise;
+
   act(() => {
-    tutorial.open({
+    resultPromise = tutorial.open({
       steps: [
         {
           title: 'Step 1',
@@ -35,6 +37,8 @@ function openTutorial(options: Options = {}) {
       options,
     });
   });
+
+  return resultPromise;
 }
 
 function createDomRect({ left, top, width, height }: { left: number; top: number; width: number; height: number }): DOMRect {
@@ -105,6 +109,16 @@ describe('TutorialOverlay', () => {
     expect(screen.queryByText('Step 1 content')).not.toBeInTheDocument();
   });
 
+  test('Escape resolves the tutorial promise with closed', async () => {
+    renderOverlay();
+
+    const resultPromise = openTutorial();
+
+    fireEvent.keyDown(window, { key: 'Escape' });
+
+    await expect(resultPromise).resolves.toEqual({ reason: 'closed' });
+  });
+
   test('exposes the info box as a labeled dialog', () => {
     renderOverlay();
     openTutorial();
@@ -220,6 +234,16 @@ describe('TutorialOverlay', () => {
     expect(screen.queryByText('Step 1 content')).not.toBeInTheDocument();
   });
 
+  test('backdrop click resolves the tutorial promise with closed when enabled', async () => {
+    renderOverlay();
+
+    const resultPromise = openTutorial({ closeOnOverlayClick: true });
+
+    fireEvent.click(screen.getByTestId('tutorial-overlay-backdrop'));
+
+    await expect(resultPromise).resolves.toEqual({ reason: 'closed' });
+  });
+
   test('does not close on backdrop click by default', () => {
     const onClose = jest.fn();
 

packages/main/test/tutorial.test.tsx

@@ -247,7 +247,7 @@ describe('tutorial core API', () => {
     expect(onClose).toHaveBeenCalledTimes(1);
   });
 
-  test('opening a new tutorial resolves the previous pending promise with closed', async () => {
+  test('opening a new tutorial resolves the previous pending promise with replaced', async () => {
     render(<StateProbe />);
 
     let firstPromise;
@@ -268,7 +268,30 @@ describe('tutorial core API', () => {
       tutorial.close();
     });
 
-    await expect(firstPromise).resolves.toEqual({ reason: 'closed' });
+    await expect(firstPromise).resolves.toEqual({ reason: 'replaced' });
     await expect(secondPromise).resolves.toEqual({ reason: 'closed' });
   });
+
+  test('repeated close calls after the tutorial settles do not re-run onClose or change the result', async () => {
+    render(<StateProbe />);
+    const onClose = jest.fn();
+
+    let resultPromise;
+
+    act(() => {
+      resultPromise = tutorial.open({
+        steps: [{ title: 'Only step', targetIds: ['only-target'] }],
+        options: { onClose },
+      });
+    });
+
+    act(() => {
+      tutorial.next();
+      tutorial.close();
+      tutorial.close();
+    });
+
+    await expect(resultPromise).resolves.toEqual({ reason: 'completed' });
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
 });