@jogak/ui 0.1.0-alpha.1 → 0.1.0-alpha.10.2

package/CHANGELOG.md

@@ -5,6 +5,118 @@ All notable changes to Jogak packages are documented here. The repository follow
 
 Version numbers apply to all packages in the workspace (synchronized release).
 
+## [0.1.0-alpha.10.2] — 2026-05-09
+
+### Fixed
+
+- **vitest.workspace.ts**: 알파.10에서 7개 패키지 디렉토리를 삭제했지만 `vitest.workspace.ts`가 여전히 `packages/react`, `packages/next`, `packages/web-components`를 참조해 `pnpm test` 시 startup error. core/ui/cli 3개로 정리.
+
+기타 패키지: source 변경 없음, synchronized release 유지를 위해 버전만 bump.
+
+## [0.1.0-alpha.10.1] — 2026-05-09
+
+### Fixed
+
+- **CI typecheck**: 알파.10에서 root `tsconfig.json` references에 `packages/cli`를 추가했으나, `tsc -b`가 cli typecheck 시점에 ui의 `dist/host/index.d.ts` (실제 파일은 없음 — ui는 `noEmit: true`)를 찾으려 해 `Cannot find module '@jogak/ui/host'` 에러 발생. 알파.9 이전처럼 cli는 root references에서 제외 — cli는 자기 `pnpm build` 단계의 `tsc -p tsconfig.json`에서 typecheck됨 (그 시점엔 ui dist가 이미 빌드돼 있음).
+
+기타 패키지: source 변경 없음, synchronized release 유지를 위해 버전만 bump.
+
+## [0.1.0-alpha.10] — 2026-05-09
+
+### Architectural unification — 10 packages → 3 packages
+
+알파.9.x에서 분리됐던 4개 빌더 어댑터(`@jogak/vite-adapter`, `@jogak/next-adapter`, `@jogak/webpack-adapter`, `@jogak/standalone-adapter`)와 3개 프레임워크 렌더러(`@jogak/react`, `@jogak/next`, `@jogak/web-components`)를 모두 `@jogak/core`로 통합. 이들의 본질은 build-tool / runtime 통합 코드이며 별도 패키지로 격리할 만한 런타임 substance가 없다는 판단.
+
+이제 publish되는 패키지는 `@jogak/core`, `@jogak/ui`, `@jogak/cli` 3개로 축소. 기능은 모두 유지되며 사용자 install도 단순화 (vite/next/webpack peer deps는 모두 `peerDependenciesMeta.optional` 처리 — 사용자가 실제로 쓰는 빌더만 install).
+
+### Added
+
+- **`@jogak/core/adapters/{vite,next,webpack,standalone}`**: 4개 builder adapter subpath. `@jogak/${name}-adapter` 패키지를 흡수.
+- **`@jogak/core/renderers/{react,next,web-components}`**: 3개 framework renderer subpath. 동명 별도 패키지를 흡수.
+- **`@jogak/core/vite-plugin`**: 알파.9.x의 `@jogak/core/vite`를 정식 명명. 기존 `@jogak/core/vite`는 backward-compat alias로 유지.
+- **CLI `loadAdapter`**: 사용자 cwd의 `@jogak/core` exports를 직접 lookup해서 adapter dynamic import. 별도 어댑터 패키지 install 불필요.
+
+### Changed
+
+- **import 경로 마이그레이션** (사용자 영향):
+  - `import ... from '@jogak/react'` → `import ... from '@jogak/core/renderers/react'`
+  - `import ... from '@jogak/next'` → `import ... from '@jogak/core/renderers/next'`
+  - `import ... from '@jogak/web-components'` → `import ... from '@jogak/core/renderers/web-components'`
+  - `import { jogak } from '@jogak/core/vite'` → `import { jogak } from '@jogak/core/vite-plugin'` (구 경로도 동작하지만 deprecated)
+- **`@jogak/core` peer deps 확장**: react/react-dom/next/webpack/webpack-dev-server/webpack-merge/html-webpack-plugin 추가 (모두 optional). 사용자가 쓰는 빌더만 설치.
+- **iframe scaffold 코드** (next-adapter, webpack-adapter): 생성되는 page.tsx/preview-entry.tsx가 `@jogak/core/renderers/react`를 import (이전 `@jogak/react`).
+
+### Removed
+
+- 7개 패키지 디렉토리 + npm registry deprecate notice:
+  - `@jogak/react`, `@jogak/next`, `@jogak/web-components`
+  - `@jogak/vite-adapter`, `@jogak/next-adapter`, `@jogak/webpack-adapter`, `@jogak/standalone-adapter`
+- 알파.9.x 사용자는 `npm view @jogak/<pkg> deprecated` 메시지로 마이그레이션 안내 받음.
+
+### CI
+
+- `release.yml`: pack/publish 목록을 `core/ui/cli` 3개로 축소. Trusted Publisher 신규 등록 zero (3개 모두 알파.9 시점 등록 완료).
+
+## [0.1.0-alpha.9.2] — 2026-05-09
+
+### Fixed
+
+- **CI**: `release.yml`의 publish 단계가 `jogak-next-*.tgz` 글로브 패턴을 사용해 `next` 패키지 publish 시 `next-adapter` tarball까지 매치되어 npm publish가 EUSAGE(다중 tarball)으로 실패. 이로 인해 알파.9.1에서 `core/react/ui/web-components`만 publish되고 `next/cli` 및 4개 어댑터는 publish 안 됨. 정확한 파일명(`jogak-${pkg}-${VERSION}.tgz`)으로 변경.
+
+기타 패키지: source 변경 없음, synchronized release 유지를 위해 버전만 bump.
+
+## [0.1.0-alpha.9.1] — 2026-05-09
+
+### Fixed
+
+- **CI**: `release.yml`의 pack 단계가 `core/react/ui/web-components/next/cli`만 포함했고 알파.9에서 신규 추가된 4개 어댑터(`vite-adapter` / `next-adapter` / `webpack-adapter` / `standalone-adapter`)를 누락. v0.1.0-alpha.9 태그로 부분 publish됐으나 어댑터들이 npm에 올라가지 않아 사용자가 import 불가. 4개 어댑터를 pack 목록에 추가 후 alpha.9.1로 재발행.
+
+기타 패키지: source 변경 없음, synchronized release 유지를 위해 버전만 bump.
+
+## [0.1.0-alpha.9] — 2026-05-09
+
+### Added
+
+- **`@jogak/vite-adapter`**, **`@jogak/next-adapter`**, **`@jogak/webpack-adapter`**, **`@jogak/standalone-adapter`**: 새 builder-agnostic adapter 패키지군. CLI가 사용자 cwd의 빌더(`next.config`, `vite.config`, `webpack.config`)를 감지하여 해당 adapter를 dynamic import한다. 사용자 컴포넌트는 사용자의 정상 빌더 client에서 평가되므로 utility class compiler(Tailwind v4 등)이 자연스럽게 동작한다.
+- **`@jogak/core`**: `BuilderAdapter` ABI(`adapter.ts`), 빌더 자동 감지(`detectBuilder`, `@jogak/core/server`), preview entry 공통 source(`renderPreviewEntrySource`), postMessage 프로토콜(`@jogak/core/preview-entry/protocol`).
+- **`JogakPluginOptions.userPreviewUrl` / `previewEntryPath`**: adapter dispatch 결과를 host UI iframe src로 주입하는 통로. (`userViteUrl`은 alpha.8 호환을 위해 alias로 유지)
+- **`@jogak/next-adapter`**: Next 14+ App Router에 `<userRoot>/app/jogak-preview/page.tsx` scaffold(`.gitignore` 자동, shutdown cleanup). `next dev` child process spawn + HTTP poll ready 감지. CLI가 사전 생성한 `.jogak/registry.ts`의 entries를 import하여 모듈 평가 시점에 등록.
+- **`@jogak/webpack-adapter`**: `<userRoot>/.jogak/webpack-preview/preview-entry.tsx` scaffold + `webpack-dev-server` programmatic API + `webpack-merge`로 사용자 webpack.config 통합.
+
+### Changed
+
+- **`@jogak/core`**: `fs`/`path`를 사용하는 server-only utility(`detectBuilder`, `resolveGlobalCssPaths`, `detectUserGlobalCss`)를 `@jogak/core/server` subpath로 분리. client bundle에 Node 모듈이 leak되는 문제를 차단.
+- **`@jogak/core`**, **`@jogak/ui`**, all adapters: CJS 산출물 확장자를 `.js` → `.cjs`로 변경. `"type": "module"` 환경에서 `.js`가 ESM으로 해석되어 발생하던 `exports is not defined in ES module scope` 오류를 해소.
+- **`previewIsolation`** default: `'shadow'` → `'iframe'`. shadow DOM 모드는 일부 portal 라이브러리(Radix 등)와 호환성 이슈가 있어 iframe 격리를 표준으로.
+- **`@jogak/ui`** preview-frame: 기존 `__jogak_setProps__` 직접 호출 프로토콜 → postMessage(`jogak:setProps` / `jogak:rendered` / `jogak:error`)로 통일. 모든 어댑터의 iframe entry가 동일 프로토콜을 따른다.
+- **`@jogak/cli`**: `jogak dev`가 registry 생성 완료를 대기한 뒤 어댑터를 spawn (이전: fire-and-forget). non-vite 어댑터의 scaffold가 비어있는 registry를 import하던 race condition 해소.
+
+### Fixed
+
+- **`@jogak/cli`**: 어댑터 dynamic import 시 `import.meta.resolve`/`createRequire`가 cli/dist 기준으로 해석돼 사용자 cwd의 어댑터 패키지를 찾지 못하던 문제. `<cwd>/node_modules/@jogak/${name}-adapter/package.json`을 직접 읽어 `exports['.'].import` 경로로 해석하도록 변경.
+- **`@jogak/next-adapter`**: 이전 시도의 `__jogak_preview__` 경로는 Next App Router의 private folder convention(`_`로 시작하는 폴더는 라우팅 제외)과 충돌해 404. `jogak-preview`로 변경.
+
+## [0.1.0-alpha.3] — 2026-05-07
+
+### Added
+
+- **`@jogak/core`**: Vite plugin now auto-detects user `tsconfig.json` (and `tsconfig.app.json` for the Vite scaffold-default split-references layout) and converts `compilerOptions.paths` into `vite resolve.alias`. This makes `runHost`-driven dev/build work zero-config for projects that use path aliases (shadcn/ui's `@/lib/utils` etc.). Without this, `runHost` ignored the user's `vite.config.ts` (`configFile: false`) and any `@/...` import inside a user component failed to resolve.
+- **`JogakPluginOptions.resolveAlias`**: explicit user-provided alias map for cases the auto-extraction can't handle (extends chains, complex glob patterns). Explicit entries override auto-extracted ones. Relative paths are resolved against the user root.
+
+### Fixed
+
+- Path aliases declared in user `tsconfig` are now respected during `jogak dev` and `jogak build`. Previously, every `*.jogak.tsx` that imported a component using `@/`-style imports would fail with `Failed to resolve import "@/..."` in the browser dev overlay.
+
+Other packages: no source changes; version bumped to keep the workspace synchronized.
+
+## [0.1.0-alpha.2] — 2026-05-07
+
+### Fixed
+
+- **`@jogak/ui`**: Published package was missing `src/app/main.tsx` (referenced by `index.html` as the SPA entry), causing `jogak dev` to 404 on the entry script and `jogak build` to fail with `Failed to resolve /src/app/main.tsx`. The `files` field in `package.json` only included `dist/`, but `runHost` uses the package's `index.html` as the Vite root and resolves `/src/app/main.tsx` from source. Added `src/app`, `src/components`, `src/hooks`, `src/index.ts`, `src/vite-env.d.ts` to `files`. Internal `src/host` and `src/examples` remain excluded (host is consumed via the published `dist/host` build; examples are repository-only demos).
+
+Other packages: no source changes; version bumped to keep the workspace synchronized.
+
 ## [0.1.0-alpha.1] — 2026-05-07
 
 ### Changed

package/README.md

@@ -12,27 +12,32 @@ pnpm add @jogak/ui @jogak/core @jogak/react react react-dom
 
 ## Usage
 
-### Embed into a Vite SPA
+### `jogak.config.ts` 사용 (권장)
 
-```ts
-// vite.config.ts
-import { jogak } from '@jogak/core/vite'
+알파.7부터 `jogak` CLI는 사용자 프로젝트 root의 `jogak.config.{ts,mts,mjs,js,json}`을
+자동 발견해 옵션을 읽습니다. shadcn/ui 사용자가 자주 만지는 옵션은 한 곳에 선언하세요:
 
-export default defineConfig({
-  plugins: [react(), jogak({ codeTheme: 'vsDark' })],
+```ts
+// jogak.config.ts (사용자 프로젝트 root)
+import { defineJogakConfig } from '@jogak/core'
+
+export default defineJogakConfig({
+  globalCss: true,              // 사용자 globalCss 자동 감지 + import
+  // previewIsolation: 'iframe',  // 'iframe' (default, 알파.8) | 'shadow' (deprecated) | 'none' (deprecated)
+  // userVite: { port: 5174 },    // 사용자 vite spawn 옵션 (자동 탐지 시 미명시)
+  codeTheme: 'vsDark',
+  port: 5173,                  // dev server (CLI --port로 override)
 })
 ```
 
-```tsx
-// main.tsx
-import 'virtual:jogak'
-import { _jogakCodeTheme } from 'virtual:jogak'
-import { JogakApp } from '@jogak/ui'
-import { createRoot } from 'react-dom/client'
+CLI는 본 config의 옵션을 읽어 jogak SPA 빌드/dev에 전달합니다. CLI 플래그가
+명시되면 config 값을 override합니다 (Vite 패턴).
+
+### `jogak.config.ts` 미사용 (CLI flag만)
 
-createRoot(document.getElementById('root')!).render(
-  <JogakApp codeTheme={_jogakCodeTheme} />,
-)
+```bash
+jogak dev --global-css --preview-isolation=none
+jogak build --global-css --preview-isolation=shadow
 ```
 
 ### Static catalog (Next.js / any host bundler)
@@ -48,6 +53,17 @@ export default function Page() {
 
 `@jogak/ui` ships pre-built ESM/CJS — no `transpilePackages` required for Next.js.
 
+### legacy: `vite.config.ts`에 `jogak()` plugin 직접 사용
+
+> 알파.6까지의 README는 사용자 `vite.config.ts`에 `jogak({ globalCss: true })`를
+> 작성하라 안내했지만, 이는 사용자 일반 vite 빌드용에만 적용되고 jogak SPA에는
+> 무효였습니다 (`runHost`가 `configFile: false`로 사용자 vite config 무시).
+> 알파.7부터는 위 `jogak.config.ts` 패턴을 사용하세요.
+
+`@jogak/core/vite`의 `jogak()` plugin은 사용자가 vite로 직접 jogak 카탈로그를
+embed하는 고급 시나리오(예: Next.js page 안에서 `<JogakApp entries={...} />`로
+정적 entries를 전달할 때 빌드 타임 generate)에서만 사용합니다.
+
 ### Sub-paths
 
 ```ts
@@ -62,6 +78,176 @@ import { runHost } from '@jogak/ui/host' // Node-only, used by @jogak/cli
 
 See the [main README](https://github.com/devclib/jogak#readme) for the full host embedding guide.
 
+## Styling roadmap
+
+| 단계 | 상태 | 내용 |
+|------|------|------|
+| alpha.4 | ✅ 완료 | jogak UI 빌드에 Tailwind v4 + `jogak:` prefix 도입 |
+| alpha.5 | ✅ 완료 | jogak UI 컴포넌트를 Tailwind class로 마이그레이션 (4 PR) |
+| alpha.6 | ✅ 완료 | `JogakPluginOptions.globalCss` 옵션 + chrome 보호 rule (단, 통로 부재로 사용자 환경에서 무효 — 알파.7에서 정정) |
+| alpha.7 | ✅ 완료 | `jogak.config.ts` 통로 + `previewIsolation` 옵션 + `JogakHostOptionsBase` 확장 (단, isolation 통로 결함으로 격리 무효 — 알파.7.1에서 정정) |
+| alpha.7.1 | ✅ 완료 | isolation 통로 hotfix + default `previewIsolation: 'shadow'` (단, 사용자 utility 미컴파일 한계 — 알파.8에서 사용자 vite 통합으로 해결) |
+| **alpha.8** | ✅ **본 릴리즈** | **사용자 vite 자동 spawn + 사용자 Tailwind utility 정상 컴파일 + default `previewIsolation: 'iframe'`** |
+| alpha.9+ | 예정 | shadow 모드 사용자 utility inject 부활, iframe sandbox 옵션, multi-baseline VR |
+
+### 사용자 globalCss 적용
+
+`runHost`는 vite root를 `@jogak/ui` 패키지로 두고 사용자 `vite.config.ts` / `main.tsx`를 무시하므로(`configFile: false`), 사용자 `index.css`(Tailwind/shadcn 디자인 토큰)가 jogak SPA에 자동 적용되지 않습니다. `globalCss` 옵션은 이를 opt-in으로 해결합니다.
+
+#### 사용법
+
+```ts
+// jogak.config.ts (사용자 프로젝트 root)
+import { defineJogakConfig } from '@jogak/core'
+
+export default defineJogakConfig({
+  globalCss: true,
+})
+```
+
+`globalCss: true`는 다음 후보를 우선순위 순으로 자동 감지해 **첫 발견 1개**만 import합니다:
+
+1. `src/index.css` (shadcn/ui Vite)
+2. `src/main.css`
+3. `src/styles.css`
+4. `src/styles/globals.css` (Next.js shadcn)
+5. `src/styles/index.css`
+6. `src/app/globals.css` (Next.js App Router shadcn)
+7. `src/global.css`
+8. `src/app.css`
+
+명시 경로(상대/절대) 또는 배열도 사용 가능합니다:
+
+```ts
+// 명시 경로 1개
+defineJogakConfig({ globalCss: './src/index.css' })
+
+// 다중 import (디자인 토큰 + reset 분리)
+defineJogakConfig({ globalCss: ['./src/tokens.css', './src/reset.css'] })
+```
+
+#### 격리 보장 (default `previewIsolation: 'iframe'`, 알파.8)
+
+- **Tailwind utility class**: jogak UI는 `prefix=jogak`로 빌드되어 사용자 utility와 충돌 zero (예: 사용자 `bg-primary` ≠ jogak `jogak:bg-...`).
+- **CSS variable**: jogak은 `--jogak-*` prefix로 namespace 격리 → 사용자 `:root { --primary }` 같은 디자인 토큰은 영향 없음.
+- **Form element 보호**: `[data-jogak-shell]` 안의 button/input/select/textarea는 사용자 reset의 `border` / `background` / `color` 침범을 받지 않도록 `:where()` 보호 rule 적용. specificity 0이라 사용자가 명시적으로 `[data-jogak-shell] button { ... }`를 작성하면 정상 override됩니다.
+
+### previewIsolation 사용 가이드 (알파.8)
+
+jogak chrome ↔ 사용자 영역의 **양방향 격리** + 사용자 컴포넌트는 사용자 디자인 시스템 그대로 표시. 알파.8부터 default가 `'iframe'`로 변경되어 사용자 vite 인스턴스가 자동 spawn되고, iframe document가 사용자 vite의 정상 client로 작동합니다.
+
+#### 모드 비교
+
+| 모드 | mount | 사용자 utility 컴파일 | chrome 침범 | Radix portal | cold start |
+|------|-------|---------------------|-----------|--------------|-----------|
+| `'iframe'` (default) | iframe document (사용자 vite scope) | **정상** ✅ | zero | iframe document (정상) | ★★ |
+| `'shadow'` (deprecated) | ShadowRoot | **미컴파일** | zero | document.body (shadow 외부) | ★★★ |
+| `'none'` (deprecated) | 같은 document | 미컴파일 | **있음** | document.body | ★★★ |
+
+#### `'iframe'` 모드 (default, 알파.8)
+
+jogak CLI가 사용자 cwd의 `vite.config.{ts,mts,js,mjs,cjs}`를 자동 탐지해 별도 vite dev server를 spawn합니다. iframe `src`가 그 사용자 vite를 가리키므로 사용자 plugins(@tailwindcss/vite, custom alias 등)이 정상 작동 → **사용자 컴포넌트가 사용자 디자인 그대로 표시**.
+
+```ts
+// jogak.config.ts (사용자 프로젝트 root)
+import { defineJogakConfig } from '@jogak/core'
+
+export default defineJogakConfig({
+  globalCss: true,
+  // previewIsolation: 'iframe',  // default
+  // userVite: { port: 5174 },    // 명시 시
+})
+```
+
+**자동 동작:**
+- 사용자 `vite.config.ts` 자동 탐지 → `loadConfigFromFile` + `mergeConfig`로 jogak plugins 자동 inject (사용자 액션 zero)
+- 사용자 vite default port 5174 (jogak SPA가 default 5173 차지). 사용자 명시 가능
+- cross-origin postMessage로 entry/args 전달 (`entry.id`만, iframe 안에서 `defaultRegistry.requestEntry(id)` dynamic import)
+- HMR: 사용자 vite의 React Fast Refresh + Tailwind utility 재생성 정상 작동
+
+**Fallback:**
+- `vite.config.ts` 미발견 또는 평가 실패 → spawn skip + warning. jogak SPA만 시작 (`'none'` 모드 동등 동작).
+
+**주의:**
+- jogak ↔ 사용자 vite 두 인스턴스 (vs 알파.7.1까지의 single vite). dev cold start +100ms, RSS +50~80MB.
+- iframe sandbox 미적용 (사용자 컴포넌트의 fetch/clipboard/storage 자유 사용).
+
+#### `'shadow'` 모드 (deprecated)
+
+ShadowRoot 격리는 정상 작동하나 사용자 utility가 shadow scope에 inject되지 않아 사용자 컴포넌트가 raw 형태로 표시됩니다. 알파.9에서 사용자 vite의 `transformRequest` API로 shadow inject 부활 검토.
+
+#### `'none'` 모드 (deprecated)
+
+사용자 globalCss를 outer document에 inject. 사용자 reset이 jogak chrome 침범. back-compat 시나리오만 사용:
+
+```ts
+defineJogakConfig({ globalCss: true, previewIsolation: 'none' })
+```
+
+### scope 가이드 — 알려진 영향 영역 (`'none'` 모드 기준)
+
+사용자 css의 다음 패턴은 jogak chrome에도 영향을 줄 수 있습니다 (전역 import이므로):
+
+- `body { ... }` — jogak SPA의 body에도 적용
+- `* { ... }` 또는 `*, *::before { ... }` — 모든 요소
+- 글로벌 reset (`button { all: unset }`, `* { border: 1px solid var(--border) }` 등)
+
+이를 사용자 콘텐츠 영역(preview)으로만 한정하려면 셀렉터를 `[data-jogak-content] *` scope로 작성하거나, `previewIsolation: 'shadow' | 'iframe'`을 사용하세요.
+
+```css
+/* 권장: preview 영역으로만 한정 */
+[data-jogak-content] *,
+[data-jogak-content] *::before,
+[data-jogak-content] *::after {
+  box-sizing: border-box;
+}
+
+[data-jogak-content] button {
+  /* 사용자 디자인 시스템 button reset */
+  all: unset;
+}
+```
+
+#### selector hint
+
+- `[data-jogak-shell]` — `JogakApp` 최상위 wrapper (chrome + preview 모두 포함)
+- `[data-jogak-content]` — Preview의 사용자 콘텐츠 영역 (사용자 컴포넌트가 렌더되는 div)
+
+### 알파.6 → 알파.7 마이그레이션
+
+알파.6 README는 다음 가이드를 안내했습니다:
+
+```ts
+// alpha.6 README (무효)
+// vite.config.ts
+import { jogak } from '@jogak/core/vite'
+export default defineConfig({
+  plugins: [react(), jogak({ globalCss: true })],
+})
+```
+
+이 설정은 사용자 일반 vite 빌드용에만 적용되고 jogak SPA에는 전달되지 않았습니다.
+알파.7부터 `jogak.config.ts`로 옮기세요:
+
+```ts
+// alpha.7+ — jogak.config.ts (사용자 프로젝트 root)
+import { defineJogakConfig } from '@jogak/core'
+
+export default defineJogakConfig({
+  globalCss: true,
+})
+```
+
+`vite.config.ts`에 `jogak()` plugin이 그대로 있어도 jogak SPA에는 영향 없으므로
+당장 제거할 필요는 없습니다 (alpha.6 동작 유지). 하지만 jogak.config.ts로 옮긴 후
+중복 제거를 권장합니다.
+
+### 알려진 한계
+
+- `globalCss` 옵션은 **opt-in**입니다 (default `false`). 알파.5까지의 동작은 동일합니다.
+- `globalCss: true` 자동 감지는 dev 시작 시점에 한 번만 수행됩니다. 후보 css 파일이 dev 시작 후에 새로 추가되면 dev 서버를 재시작해야 합니다. 명시 경로(`globalCss: './src/index.css'`)는 파일이 나중에 생성되어도 정상 hot reload됩니다.
+- CSS module(`.module.css`)을 자동 감지 후보에서 직접 import하지 않습니다 — 명시 경로로 넘기면 Vite가 module 처리합니다.
+
 - Repository: https://github.com/devclib/jogak
 - Issues: https://github.com/devclib/jogak/issues
 - License: [MIT](./LICENSE)

package/dist/app/App.d.ts

@@ -14,5 +14,28 @@ export interface JogakAppProps {
     readonly entries?: readonly RegistryEntry[];
     readonly metas?: readonly RegistryEntryMeta[];
     readonly codeTheme?: string;
+    /**
+     * 알파.8: Preview 영역 격리 모드. default `'iframe'`.
+     *
+     * - `'iframe'` (default) — 사용자 vite 정상 client(iframe)에 마운트. 사용자 utility 정상 컴파일.
+     * - `'shadow'` (deprecated) — ShadowRoot 안에 마운트. 사용자 utility 미적용.
+     * - `'none'` (deprecated) — chrome 같은 document에 렌더. 알파.6까지의 동작.
+     *
+     * 자세한 트레이드오프는 `@jogak/ui` README의 "previewIsolation 사용 가이드" 참조.
+     */
+    readonly previewIsolation?: 'none' | 'shadow' | 'iframe';
+    /**
+     * 알파.9: 어댑터 dev URL. iframe `src` base.
+     * 빈 문자열 시 fallback (jogak SPA Vite scope의 preview-frame.tsx).
+     */
+    readonly userPreviewUrl?: string;
+    /**
+     * 알파.9: iframe entry path (예: `/__jogak_preview__/index.html`).
+     */
+    readonly previewEntryPath?: string;
+    /**
+     * @deprecated 알파.10 제거 예정. `userPreviewUrl` 사용.
+     */
+    readonly userViteUrl?: string;
 }
-export declare function JogakApp({ entries, metas, codeTheme, }?: JogakAppProps): ReactElement;
+export declare function JogakApp({ entries, metas, codeTheme, previewIsolation, userPreviewUrl, previewEntryPath, userViteUrl, }?: JogakAppProps): ReactElement;

package/dist/components/Preview/IframeMount.d.ts

@@ -0,0 +1,35 @@
+import { ReactElement } from 'react';
+import { RegistryEntry } from '@jogak/core';
+export interface IframeMountProps {
+    readonly entry: RegistryEntry;
+    readonly args: Readonly<Record<string, unknown>>;
+    /**
+     * 알파.9: 어댑터 dev URL (예: `http://localhost:5174`).
+     * 빈 문자열 시 fallback (jogak SPA Vite scope의 `/preview-frame.html`).
+     */
+    readonly userPreviewUrl: string;
+    /**
+     * 알파.9: iframe entry path (예: `/__jogak_preview__/index.html`).
+     * 어댑터의 `previewEntryMeta.devEntryPath`.
+     */
+    readonly previewEntryPath: string;
+    readonly className?: string;
+    readonly 'data-testid'?: string;
+}
+/**
+ * 알파.8: previewIsolation='iframe' 모드의 mount 컴포넌트.
+ *
+ * 통신:
+ * - 사용자 vite spawn URL이 주어지면(`userViteUrl !== ''`) iframe src를
+ *   `${userViteUrl}/__jogak_preview__/index.html` (cross-origin)로 설정.
+ * - 동일 origin fallback 시 `/preview-frame.html` (jogak SPA Vite scope).
+ *
+ * 양쪽 모두 postMessage로 통신:
+ * - 부모 → iframe: `{ type: 'jogak:setProps', entryId, args }` | `{ type: 'jogak:unmount' }`
+ * - iframe → 부모: `{ type: 'jogak:ready' }` | `{ type: 'jogak:rendered', entryId }`
+ *
+ * `entry`는 객체가 아닌 **id만 전달** — iframe 안에서 `defaultRegistry.requestEntry(id)`로
+ * dynamic import. 사용자 vite scope의 entry 가상 모듈이 사용자 컴포넌트를 fetch하므로
+ * 사용자 plugins(@tailwindcss/vite, custom alias 등)이 정상 작동.
+ */
+export declare function IframeMount({ entry, args, userPreviewUrl, previewEntryPath, className, 'data-testid': dataTestId, }: IframeMountProps): ReactElement;

package/dist/components/Preview/ShadowMount.d.ts

@@ -0,0 +1,25 @@
+import { ReactElement, ReactNode, CSSProperties } from 'react';
+export interface ShadowMountProps {
+    readonly children: ReactNode;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+    readonly 'data-testid'?: string;
+}
+/**
+ * 알파.7.1: previewIsolation='shadow' 모드의 mount 컴포넌트.
+ *
+ * 책임: 양방향 격리만 제공 (Preview ↔ outer document 양방향 cascade 차단).
+ * - 사용자 globalCss는 main.tsx 가드로 outer document에 inject되지 않음.
+ * - shadow root 안에는 jogak chrome css도 사용자 css도 없음 (둘 다 외부에서 격리).
+ * - 사용자 컴포넌트의 utility class 컴파일은 결함 B (알파.8 사이클).
+ *
+ * 알파.7 결함 정정:
+ * - `syncStyleSheets`/`MutationObserver`/`adoptedStyleSheets` 흡수 로직 제거.
+ *   알파.7은 outer document에 사용자 css가 있는 한 chrome을 침범했고, shadow
+ *   안의 흡수 로직은 의미가 없었음. 알파.7.1: outer에 사용자 css 자체가 없음.
+ *
+ * Radix portal 한계 (사용자 인지 필요, README 명시):
+ * - default Portal target = document.body (shadow 외부). 사용자가 명시적으로
+ *   `<Portal container={shadowRootEl}>`을 전달해야 portal 내용도 격리됨.
+ */
+export declare function ShadowMount({ children, className, style, 'data-testid': dataTestId, }: ShadowMountProps): ReactElement;

package/dist/components/Preview/index.d.ts

@@ -1,5 +1,5 @@
 import { ReactElement } from 'react';
-import { UseEntryState } from '@jogak/react';
+import { UseEntryState } from '@jogak/core/renderers/react';
 export interface PreviewProps {
     readonly entryId: string;
     readonly jogakName: string | null;
@@ -12,6 +12,23 @@ export interface PreviewProps {
      * 첫 jogak로 자동 보정하기 위한 콜백. 부모가 selectedJogakName / URL을 갱신.
      */
     readonly onResolveJogak?: (entryId: string, jogakName: string) => void;
+    /**
+     * 알파.8: Preview 영역 격리 모드. default `'iframe'`.
+     *
+     * - `'iframe'` (default) — 사용자 vite scope에 마운트. 사용자 utility 정상 컴파일.
+     * - `'shadow'` (deprecated) — ShadowRoot에 마운트. 사용자 utility 미적용.
+     * - `'none'` (deprecated) — chrome과 같은 document에 렌더.
+     */
+    readonly previewIsolation?: 'none' | 'shadow' | 'iframe';
+    /**
+     * 알파.9: 어댑터 dev URL. iframe `src` base.
+     * 빈 문자열 시 fallback (jogak SPA Vite scope의 `/preview-frame.html`).
+     */
+    readonly userPreviewUrl?: string;
+    /**
+     * 알파.9: iframe entry path.
+     */
+    readonly previewEntryPath?: string;
 }
 /**
  * Preview — `useEntry(entryId)`의 status에 따라 분기 (계약 §5.4).
@@ -23,5 +40,5 @@ export interface PreviewProps {
  *
  * Layout shift 방지를 위해 캔버스 영역 minHeight 유지.
  */
-export declare function Preview({ entryId, jogakName, overrideArgs, onArgChange, onReset, codeTheme, onResolveJogak, }: PreviewProps): ReactElement;
+export declare function Preview({ entryId, jogakName, overrideArgs, onArgChange, onReset, codeTheme, onResolveJogak, previewIsolation, userPreviewUrl, previewEntryPath, }: PreviewProps): ReactElement;
 export type { UseEntryState };

package/dist/host/index.cjs

@@ -0,0 +1 @@
+"use strict";var S=Object.create;var g=Object.defineProperty;var k=Object.getOwnPropertyDescriptor;var A=Object.getOwnPropertyNames;var B=Object.getPrototypeOf,E=Object.prototype.hasOwnProperty;var H=(e,t,r,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of A(t))!E.call(e,o)&&o!==r&&g(e,o,{get:()=>t[o],enumerable:!(n=k(t,o))||n.enumerable});return e};var a=(e,t,r)=>(r=e!=null?S(B(e)):{},H(t||!e||!e.__esModule?g(r,"default",{value:e,enumerable:!0}):r,e));Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const N=require("node:url"),u=require("node:path");var f=typeof document<"u"?document.currentScript:null;const x=N.fileURLToPath(typeof document>"u"?require("url").pathToFileURL(__filename).href:f&&f.tagName.toUpperCase()==="SCRIPT"&&f.src||new URL("host/index.cjs",document.baseURI).href),s=u.resolve(u.dirname(x),"..",".."),F=u.resolve(s,"index.html"),V=u.resolve(s,"src/app/main.tsx");async function Y(e){const t=await import("vite"),r=await import("@vitejs/plugin-react"),n=await import("@jogak/core/vite-plugin"),o=await import("@tailwindcss/vite"),{createServer:y,build:h}=t,w=r.default,b=o.default,{jogak:P}=n,U=e.codeTheme??"vsDark",i={patterns:e.patterns,codeTheme:U,cwd:e.userRoot};e.tsConfigFilePath!==void 0&&(i.tsConfigFilePath=e.tsConfigFilePath),e.globalCss!==void 0&&(i.globalCss=e.globalCss),e.previewIsolation!==void 0&&(i.previewIsolation=e.previewIsolation),e.userPreviewUrl!==void 0&&(i.userPreviewUrl=e.userPreviewUrl),e.previewEntryPath!==void 0&&(i.previewEntryPath=e.previewEntryPath),e.userViteUrl!==void 0&&e.userPreviewUrl===void 0&&(i.userViteUrl=e.userViteUrl);const _=e.extraPlugins??[],d={root:s,configFile:!1,plugins:[w(),b(),P(i),..._],optimizeDeps:{include:["react","react-dom/client","@jogak/core","@jogak/core/renderers/react"]}};if(e.mode==="dev"){const D={port:e.port??5173,host:e.host??"localhost",open:e.open??!1,fs:{allow:[s,e.userRoot]}},L={...d,server:D},l=await y(L);await l.listen();const v=l.config.server.port??e.port??5173,c=e.host??"localhost",M=`http://${typeof c=="boolean"?c?"0.0.0.0":"localhost":c}:${v.toString()}/`;let p=!1;return{url:M,port:v,close:async()=>{p||(p=!0,await l.close())},printUrls:()=>{l.printUrls()}}}const C={...d,base:e.base??"./",build:{outDir:e.outDir,emptyOutDir:!0,sourcemap:e.sourcemap??!1,minify:e.minify??"esbuild",rollupOptions:{input:{main:u.resolve(s,"index.html"),preview:u.resolve(s,"preview-frame.html")}}}},R=Date.now(),I=await h(C),T=Date.now()-R,{assetCount:O,totalBytes:j}=q(I);return{outDir:e.outDir,elapsedMs:T,assetCount:O,totalBytes:j}}function q(e){const t=z(e);if(t===void 0)return{assetCount:0,totalBytes:0};let r=0,n=0;for(const o of t)r+=1,n+=$(o);return{assetCount:r,totalBytes:n}}function m(e){return typeof e=="object"&&e!==null&&Array.isArray(e.output)}function z(e){if(Array.isArray(e)){const t=[];for(const r of e)m(r)&&t.push(...r.output);return t}if(m(e))return e.output}function $(e){if(typeof e!="object"||e===null)return 0;const t=e;if(t.type==="chunk"&&typeof t.code=="string")return Buffer.byteLength(t.code,"utf8");if(t.type==="asset"){const r=t.source;if(typeof r=="string")return Buffer.byteLength(r,"utf8");if(r instanceof Uint8Array)return r.byteLength}return 0}exports.UI_HTML_ENTRY=F;exports.UI_MAIN_ENTRY=V;exports.runHost=Y;

package/dist/host/index.d.ts

@@ -6,7 +6,7 @@
  *
  * 주의:
  * - 이 파일은 Node.js 환경에서만 import되어야 한다.
- * - `vite`, `@vitejs/plugin-react`, `@jogak/core/vite`는 모두 dynamic import로
+ * - `vite`, `@vitejs/plugin-react`, `@jogak/core/vite-plugin`은 모두 dynamic import로
  *   로드한다 — `@jogak/ui` 메인 entry(브라우저 SPA)에서 우연히 host를 import
  *   하더라도 vite가 브라우저 번들에 포함되지 않게 하기 위함.
  */
@@ -38,6 +38,43 @@ export interface JogakHostOptionsBase {
     readonly extraPlugins?: readonly unknown[];
     /** stdout/stderr 출력 stream (테스트 시 주입). */
     readonly logger?: HostLogger;
+    /**
+     * 알파.7: 사용자 globalCss를 jogak SPA에 import한다 (algfa.6 옵션의 host 통로).
+     *
+     * `false`/`undefined` (default): 미주입.
+     * `true`: `<userRoot>/src/{...}.css` 자동 감지 후 첫 발견 1개 import.
+     * `string` / `readonly string[]`: 명시 경로.
+     *
+     * 본 옵션은 jogak() Vite plugin의 `globalCss` 옵션으로 그대로 전달된다.
+     */
+    readonly globalCss?: boolean | string | readonly string[];
+    /**
+     * 알파.8: Preview 영역 격리 모드.
+     *
+     * `'iframe'` (default, 알파.8), `'shadow'` (deprecated), `'none'` (deprecated) 중 하나.
+     * jogak() Vite plugin의 `previewIsolation` 옵션으로 그대로 전달된다.
+     *
+     * 자세한 모드 설명은 `JogakPluginOptions.previewIsolation` JSDoc 참조.
+     */
+    readonly previewIsolation?: 'none' | 'shadow' | 'iframe';
+    /**
+     * 알파.9: 어댑터 dev URL (예: `http://localhost:5174`).
+     * jogak SPA가 iframe `src` base로 사용한다.
+     *
+     * 미지정/빈 문자열 시 fallback (jogak SPA Vite scope의 preview-frame.tsx).
+     *
+     * jogak CLI의 어댑터 dispatch 결과 자동 전달 — 사용자가 직접 설정하지 않는다.
+     */
+    readonly userPreviewUrl?: string;
+    /**
+     * 알파.9: iframe entry path (예: `/__jogak_preview__/index.html`).
+     * `BuilderAdapter.previewEntryMeta.devEntryPath` 값. CLI 자동 전달.
+     */
+    readonly previewEntryPath?: string;
+    /**
+     * @deprecated 알파.10 제거 예정. `userPreviewUrl` 사용.
+     */
+    readonly userViteUrl?: string;
 }
 export interface JogakDevOptions extends JogakHostOptionsBase {
     readonly mode: 'dev';