docs: clarify useCurrentOverlay behavior

docs/public/ai.txt

@@ -1,5 +1,5 @@
 ---
-updated: 2026-05-20
+updated: 2026-09-03
 scope: /
 parent: https://overlay-kit.slash.page
 ---
@@ -13,7 +13,7 @@ overlay-kit is a React library for declaratively managing overlays — modals, p
 - An npm package: `overlay-kit`. Install with `npm install overlay-kit`.
 - One context provider, `<OverlayProvider>`, mounted exactly once at the React root.
 - One imperative object, `overlay`, with six methods: `open`, `openAsync`, `close`, `closeAll`, `unmount`, `unmountAll`.
-- Two hooks: `useCurrentOverlay` (returns the top overlay's id), `useOverlayData` (returns the full overlay registry).
+- Two hooks: `useCurrentOverlay` (returns the current overlay id and falls back through open overlays in registration order), `useOverlayData` (returns the full overlay registry).
 - UI-library agnostic. There is no built-in dialog UI — you supply the component, overlay-kit manages mounting, async results, and lifecycle. Verified integrations: Material UI, Chakra UI v3, Ant Design. Any React-based UI library works.
 
 ## Canonical facts

docs/public/llms-full.txt

@@ -311,7 +311,13 @@ URL: https://overlay-kit.slash.page/en/docs/guides/hooks
 
 ### useCurrentOverlay
 
-Returns the ID of the currently top-most overlay.
+When an overlay is opened, it returns that overlay's ID.
+
+When a closed overlay is reopened with the same ID, it becomes the current overlay without changing its original registration order.
+
+When an overlay is closed or unmounted, it returns the last open overlay's ID in registration order, excluding the closed or unmounted overlay.
+
+If no overlays remain open, it returns `null`.
 
 The overlay ID can be specified by passing `overlayId` as the second argument to `overlay.open()` or `overlay.openAsync()`:
 
@@ -393,8 +399,8 @@ The published guide demonstrates the following recipes with Jest/Vitest + React
 - **Closing overlays via `overlay.unmount`** — render a component that opens an overlay imperatively, click a button calling `overlay.unmount(overlayId)`, and assert the overlay leaves the DOM with `waitFor`.
 - **Opening multiple overlays via `overlay.open`** — open N overlays in a single `useEffect` and assert all of their contents are in the DOM.
 - **Async result via `overlay.openAsync`** — assert that the value passed to `close(value)` resolves as the awaited result; mock with `vi.fn()` and verify with `toHaveBeenCalledWith`.
-- **Sequential unmount across overlays** — open multiple overlays, unmount them in a non-LIFO order, and assert `useCurrentOverlay` / DOM state stays consistent.
-- **Active overlay tracking via `useCurrentOverlay`** — assert that the hook returns the id of the top overlay across `open` / `close` / `unmount` transitions.
+- **Sequential unmount across overlays** — open multiple overlays, unmount them in a non-LIFO order, and assert removed overlays leave the DOM while the remaining overlays stay visible.
+- **Active overlay tracking via `useCurrentOverlay`** — assert that the hook returns the current overlay id across `open` / `close` / `unmount` transitions.
 - **Closing/removing all overlays** — `overlay.closeAll()` removes them from the screen while `useOverlayData()` still reports them; `overlay.unmountAll()` removes them from memory and the DOM entirely.
 
 Rule of thumb: assert via `waitFor` (overlays mount/unmount asynchronously) and use `userEvent` for clicks so portaled overlays receive events correctly.

docs/public/llms.txt

@@ -6,7 +6,7 @@ overlay-kit is published as the [`overlay-kit`](https://www.npmjs.com/package/ov
 
 - `<OverlayProvider>`: a context provider mounted once at the React root that determines where overlays render.
 - `overlay.open`, `overlay.openAsync`, `overlay.close`, `overlay.closeAll`, `overlay.unmount`, `overlay.unmountAll`: imperative API for opening and disposing overlays from inside or outside React (e.g., HTTP client hooks).
-- `useCurrentOverlay`, `useOverlayData`: hooks that expose the current top overlay id and the full registry of mounted overlays.
+- `useCurrentOverlay`, `useOverlayData`: hooks that expose the current overlay id and the full registry of mounted overlays.
 
 The library is UI-library agnostic. There is no built-in dialog UI — you supply the component, overlay-kit manages mounting, async results, and lifecycle. Documentation is bilingual (English at `/en`, Korean at `/ko`); English is the default locale and the canonical content surfaced here. The project is MIT-licensed and developed openly in the [toss/overlay-kit](https://github.com/toss/overlay-kit) GitHub repository.
 
@@ -15,7 +15,7 @@ The library is UI-library agnostic. There is no built-in dialog UI — you suppl
 - [Getting Started](https://overlay-kit.slash.page/en/docs/guides/introduction): install, OverlayProvider setup, and a complete `overlay.open` / `overlay.openAsync` walkthrough.
 - [Think in overlay-kit](https://overlay-kit.slash.page/en/docs/guides/think-in-overlay-kit): rationale for the Declarative Overlay Pattern, imperative vs declarative comparison, and core design principles (Co-location, Minimum API).
 - [Code Comparison](https://overlay-kit.slash.page/en/docs/guides/code-comparison): before/after of overlay code with and without overlay-kit.
-- [Hooks](https://overlay-kit.slash.page/en/docs/guides/hooks): `useCurrentOverlay` returns the top overlay's id; `useOverlayData` returns the full `{ id, componentKey, isOpen, controller }` registry.
+- [Hooks](https://overlay-kit.slash.page/en/docs/guides/hooks): `useCurrentOverlay` returns the current overlay id and, after close or unmount, falls back through remaining open overlays in registration order; `useOverlayData` returns the full `{ id, componentKey, isOpen, controller }` registry.
 - [Testing](https://overlay-kit.slash.page/en/docs/guides/testing): Jest/Vitest + React Testing Library recipes for closing overlays, multiple overlays, async results, `closeAll`/`unmountAll`, and hook-based state assertions.
 - [FAQ](https://overlay-kit.slash.page/en/docs/guides/faq): common questions about `open` vs `openAsync`, `close` vs `unmount`, supported UI libraries, TypeScript support, and animation handling.
 - [Opening Overlays](https://overlay-kit.slash.page/en/docs/more/basic): expanded examples of `overlay.open`, `overlay.openAsync`, and memory-release patterns (`onExit`, `setTimeout`).

docs/src/pages/en/docs/guides/hooks.mdx

@@ -10,7 +10,13 @@ Using `useCurrentOverlay` and `useOverlayData`, you can implement state-based UX
 
 ## useCurrentOverlay
 
-Returns the ID of the currently top-most overlay.
+When an overlay is opened, it returns that overlay's ID.
+
+When a closed overlay is reopened with the same ID, it becomes the current overlay without changing its original registration order.
+
+When an overlay is closed or unmounted, it returns the last open overlay's ID in registration order, excluding the closed or unmounted overlay.
+
+If no overlays remain open, it returns `null`.
 
 The overlay ID can be directly specified by passing `overlayId` as the second argument to `overlay.open()` or `overlay.openAsync()` when opening an overlay:
 

docs/src/pages/ko/docs/guides/hooks.mdx

@@ -12,7 +12,15 @@ import { Sandpack } from '@/components';
 
 ## useCurrentOverlay
 
-현재 가장 위에 떠 있는 오버레이의 ID를 반환해요.
+오버레이를 열면 해당 오버레이의 ID를 반환해요.
+
+닫은 오버레이를 같은 ID로 다시 열면 현재 오버레이가 되지만, 기존 등록 순서는 유지돼요.
+
+닫거나 제거한 오버레이는 반환하지 않아요.
+
+이때 등록 순서상 마지막 ID를 반환해요.
+
+열린 오버레이가 없으면 `null`을 반환해요.
 
 오버레이의 ID는 오버레이를 열 때 `overlay.open()` 또는 `overlay.openAsync()`의
 두 번째 인자로 다음처럼 `overlayId`를 넘겨 직접 지정할 수 있어요: