daangn · junghyeonsu · Jun 16, 2026 · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026
diff --git a/.changeset/tame-pillows-rule.md b/.changeset/tame-pillows-rule.md
@@ -0,0 +1,12 @@
+---
+"@seed-design/react-prevent-scroll": minor
+"@seed-design/react-drawer": minor
+"@seed-design/react-dialog": minor
+"@seed-design/react-dismissible-layer": minor
+---
+
+(BREAKING CHANGE: Drawer/BottomSheet의 `noBodyStyles`, `preventScrollRestoration` prop을 제거하세요.) Dialog와 Drawer(BottomSheet)의 모달 body 스크롤 잠금을 새로운 `usePreventScroll`(`@seed-design/react-prevent-scroll`) 기반으로 교체합니다.
+
+- 모달이 열려 있는 동안 배경 스크롤이 안정적으로 잠기며, 기존 vaul 기반 body position-fixed 방식을 대체합니다.
+- `dismissible-layer`는 backdrop-only 모델로 전환되어 더 이상 body의 pointer-events를 차단하지 않습니다.
+- 제거되는 `noBodyStyles`, `preventScrollRestoration`은 새 스크롤 잠금이 기존 기본 동작(`noBodyStyles=true`, `preventScrollRestoration=false`)을 그대로 대체합니다.
diff --git a/TECH.md b/TECH.md
@@ -95,6 +95,8 @@ react (스타일드 컴포넌트) ← react-headless (로직)
 | `bun react:test` | react 패키지 테스트 |
 | `bun test:all` | 전체 테스트 |
 
+**테스트 환경**: `bunfig.toml`의 `[test].preload`가 `scripts/happydom.ts`(DOM 환경)와 `scripts/testing-library.ts`를 로드한다. 후자가 `@testing-library/jest-dom` 매처를 등록하고 `afterEach(cleanup)`을 전역으로 걸어주므로, 테스트에서 `cleanup()`을 직접 호출하지 않는다.
+
 ### 개발
 
 | 명령어 | 설명 |

diff --git a/bun.lock b/bun.lock
diff --git a/docs/components/stackflow-example.tsx b/docs/components/stackflow-example.tsx
@@ -1,32 +1,32 @@
 import { Tab, Tabs } from "fumadocs-ui/components/tabs";
-import * as React from "react";
+import type * as React from "react";
 
 import ErrorBoundary from "./error-boundary";
 
-import { StackflowPreview } from "./stackflow-preview";
 import { StackflowIframePreview } from "./stackflow-iframe-preview";
 import { Box } from "@seed-design/react";
 
-type StackflowExampleProps = (
-  | { names: string[]; path?: never }
-  | { names?: never; path: string }
-) & {
+interface StackflowExampleProps {
+  /**
+   * Path into the stackflow-spa app to load inside the isolated iframe preview.
+   *
+   * Inline previews are intentionally not supported: rendering a stackflow
+   * activity inline (e.g. an `defaultOpen` modal) mutates the shared
+   * `document.body` — scroll lock, focus trap — and freezes the surrounding
+   * docs page. The iframe scopes those global effects to its own document.
+   */
+  path: string;
   children?: React.ReactNode;
-};
-
-export function StackflowExample(props: StackflowExampleProps) {
-  const { names, path, children } = props;
+}
 
+export function StackflowExample({ path, children }: StackflowExampleProps) {
   return (
     <ErrorBoundary>
       <Tabs items={["미리보기", "코드"]}>
         <Tab value="미리보기">
-          {names && <StackflowPreview names={names} />}
-          {path && (
-            <Box p="x2">
-              <StackflowIframePreview path={path} />
-            </Box>
-          )}
+          <Box p="x2">
+            <StackflowIframePreview path={path} />
+          </Box>
         </Tab>
         <Tab value="코드">{children}</Tab>
       </Tabs>

diff --git a/docs/components/stackflow-preview.tsx b/docs/components/stackflow-preview.tsx
diff --git a/docs/components/stackflow/Stack.ts b/docs/components/stackflow/Stack.ts
diff --git a/docs/components/stackflow/Stackflow.tsx b/docs/components/stackflow/Stackflow.tsx
diff --git a/docs/content/react/components/(deprecated)/inline-banner.mdx b/docs/content/react/components/(deprecated)/inline-banner.mdx
@@ -209,12 +209,3 @@ variant가 `criticalWeak`이나 `criticalSolid`인 경우 `position: sticky` 등
   }
   ```
 </ComponentExample>
-
-<StackflowExample names={["react/inline-banner/activity"]}>
-  ```json doc-gen:file
-  {
-    "file": "examples/react/inline-banner/activity.tsx",
-    "codeblock": true
-  }
-  ```
-</StackflowExample>
diff --git a/docs/content/react/components/(tabs)/chip-tabs.mdx b/docs/content/react/components/(tabs)/chip-tabs.mdx
@@ -113,14 +113,3 @@ npx @seed-design/cli@latest add ui:chip-tabs
   }
   ```
 </ComponentExample>
-
-### Stackflow
-
-<StackflowExample names={["react/chip-tabs/basic-activity"]}>
-  ```json doc-gen:file
-  {
-    "file": "examples/react/chip-tabs/basic-activity.tsx",
-    "codeblock": true
-  }
-  ```
-</StackflowExample>
diff --git a/docs/content/react/components/alert-dialog.mdx b/docs/content/react/components/alert-dialog.mdx
@@ -229,10 +229,10 @@ Portal은 기본적으로 `document.body`에 렌더링됩니다.
 
 ### Stackflow
 
-<StackflowExample names={["react/alert-dialog/stackflow"]}>
+<StackflowExample path="/alert-dialog-stackflow">
   ```json doc-gen:file
   {
-    "file": "examples/react/alert-dialog/stackflow.tsx",
+    "file": "../examples/stackflow-spa/src/activities/ActivityAlertDialogStackflow.tsx",
     "codeblock": true
   }
   ```

diff --git a/docs/content/react/components/article.mdx b/docs/content/react/components/article.mdx
@@ -97,19 +97,19 @@ TabsCarousel 컴포넌트에서 제스처를 방지할 영역을 지정하는
 
 </Cards>
 
-<StackflowExample names={["react/article/prevent-pull"]}>
+<StackflowExample path="/article-prevent-pull">
   ```json doc-gen:file
   {
-    "file": "examples/react/article/prevent-pull.tsx",
+    "file": "../examples/stackflow-spa/src/activities/ActivityArticlePreventPull.tsx",
     "codeblock": true
   }
   ```
 </StackflowExample>
 
-<StackflowExample names={["react/article/prevent-drag"]}>
+<StackflowExample path="/article-prevent-drag">
   ```json doc-gen:file
   {
-    "file": "examples/react/article/prevent-drag.tsx",
+    "file": "../examples/stackflow-spa/src/activities/ActivityArticlePreventDrag.tsx",
     "codeblock": true
   }
   ```

diff --git a/docs/content/react/components/pull-to-refresh.mdx b/docs/content/react/components/pull-to-refresh.mdx
@@ -3,10 +3,10 @@ title: Pull To Refresh
 description: 사용자가 화면을 아래로 당겨 콘텐츠를 새로고침할 수 있게 해주는 컴포넌트입니다. 모바일 환경에서 최신 콘텐츠를 불러올 때 사용됩니다.
 ---
 
-<StackflowExample names={["react/pull-to-refresh/preview"]}>
+<StackflowExample path="/pull-to-refresh-preview">
   ```json doc-gen:file
   {
-    "file": "examples/react/pull-to-refresh/preview.tsx",
+    "file": "../examples/stackflow-spa/src/activities/ActivityPullToRefreshPreview.tsx",
     "codeblock": true
   }
   ```
@@ -38,10 +38,10 @@ npx @seed-design/cli@latest add ui:pull-to-refresh
 
 ### PTR in Tabs
 
-<StackflowExample names={["react/pull-to-refresh/tabs"]}>
+<StackflowExample path="/pull-to-refresh-tabs">
   ```json doc-gen:file
   {
-    "file": "examples/react/pull-to-refresh/tabs.tsx",
+    "file": "../examples/stackflow-spa/src/activities/ActivityPullToRefreshTabs.tsx",
     "codeblock": true
   }
   ```
@@ -64,10 +64,10 @@ npx @seed-design/cli@latest add ui:pull-to-refresh
 
 `PullToRefresh.preventPull` 속성을 사용하여 특정 영역에서 PTR 동작을 방지할 수 있습니다. `user-select: auto;`등을 통해 텍스트 선택이 가능한 영역에서 주로 사용됩니다.
 
-<StackflowExample names={["react/pull-to-refresh/prevent-pull"]}>
+<StackflowExample path="/pull-to-refresh-prevent-pull">
   ```json doc-gen:file
   {
-    "file": "examples/react/pull-to-refresh/prevent-pull.tsx",
+    "file": "../examples/stackflow-spa/src/activities/ActivityPullToRefreshPreventPull.tsx",
     "codeblock": true
   }
   ```

diff --git a/docs/content/react/components/result-section.mdx b/docs/content/react/components/result-section.mdx
@@ -55,10 +55,10 @@ npx @seed-design/cli@latest add ui:result-section
 
 ### With CTA & Progress Circle
 
-<StackflowExample names={["react/result-section/cta-progress-circle"]}>
+<StackflowExample path="/result-section-cta-progress-circle">
   ```json doc-gen:file
   {
-    "file": "examples/react/result-section/cta-progress-circle.tsx",
+    "file": "../examples/stackflow-spa/src/activities/ActivityResultSectionCtaProgressCircle.tsx",
     "codeblock": true
   }
   ```