@jogak/ui 0.1.0-alpha.7.1 → 0.1.0-alpha.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jogak/ui",
-  "version": "0.1.0-alpha.7.1",
+  "version": "0.1.0-alpha.8",
   "description": "Showcase viewer UI for Jogak — Sidebar / Preview / Controls / Actions and the JogakApp shell.",
   "keywords": [
     "jogak",
@@ -65,8 +65,8 @@
     "prism-react-renderer": "^2.4.1",
     "tailwindcss": "^4.0.0",
     "@tailwindcss/vite": "^4.0.0",
-    "@jogak/core": "0.1.0-alpha.7.1",
-    "@jogak/react": "0.1.0-alpha.7.1"
+    "@jogak/core": "0.1.0-alpha.8",
+    "@jogak/react": "0.1.0-alpha.8"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",

package/src/app/App.tsx

@@ -21,15 +21,20 @@ export interface JogakAppProps {
   readonly metas?: readonly RegistryEntryMeta[]
   readonly codeTheme?: string
   /**
-   * 알파.7: Preview 영역 격리 모드. default `'none'`.
+   * 알파.8: Preview 영역 격리 모드. default `'iframe'`.
    *
-   * - `'none'` — Preview 콘텐츠를 chrome 같은 document에 렌더 (알파.6까지의 동작).
-   * - `'shadow'` — ShadowRoot 안에 마운트. 사용자 globalCss/reset이 chrome 침범 차단.
-   * - `'iframe'` — 별도 document(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'
+  /**
+   * 알파.8: 사용자 vite spawn URL. iframe `src` base로 사용.
+   * 빈 문자열 시 fallback (jogak SPA Vite scope의 preview-frame.tsx).
+   */
+  readonly userViteUrl?: string
 }
 
 function readUrlParams(): { entryId: string; jogakName: string | null } | null {
@@ -52,7 +57,8 @@ export function JogakApp({
   entries,
   metas,
   codeTheme = 'vsDark',
-  previewIsolation = 'shadow',
+  previewIsolation = 'iframe',
+  userViteUrl = '',
 }: JogakAppProps = {}): ReactElement {
   // ── 4가지 모드 결정 (계약 §5.2) ─────────────────────────────────────
   // 1) entries가 주어지면: 새 ComponentRegistry에 register (eager, 기존 동작)
@@ -156,6 +162,7 @@ export function JogakApp({
               codeTheme={codeTheme}
               onResolveJogak={handleResolveJogak}
               previewIsolation={previewIsolation}
+              userViteUrl={userViteUrl}
             />
           ) : (
             <div className="jogak:flex jogak:items-center jogak:justify-center jogak:h-full jogak:text-[var(--jogak-color-fg-subtle)]">

package/src/app/main.tsx

@@ -1,16 +1,19 @@
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
 import 'virtual:jogak'
-import { _jogakCodeTheme, _jogakPreviewIsolation } from 'virtual:jogak'
+import {
+  _jogakCodeTheme,
+  _jogakPreviewIsolation,
+  _jogakUserViteUrl,
+} from 'virtual:jogak'
 import '../styles/jogak.css'
 import { JogakApp } from './App.js'
 
-// 알파.7.1: 사용자 globalCss는 isolation === 'none'일 때만 outer document에 inject.
-// - 'shadow'/'iframe' 모드에서는 ShadowMount/preview-frame.tsx가 자기 scope에서
-//   사용자 css를 자체 import하므로 outer document inject가 불필요하고, 오히려
-//   chrome을 침범한다 (알파.7 결함).
-// - top-level await로 가드 — Vite는 string literal specifier의 dynamic import를
-//   정적 분석하여 별도 chunk + css HMR 표준 경로로 처리한다.
+// 알파.8: 사용자 globalCss는 사용자 vite scope(iframe entry)에서 처리되므로
+// jogak SPA outer document에는 import하지 않는다 — chrome 격리 보존.
+//
+// 'none' 모드(deprecated): 알파.7.1 동작 유지가 필요한 사용자만 명시 사용.
+// 이 경우만 outer document에 사용자 globalCss inject.
 if (_jogakPreviewIsolation === 'none') {
   await import('virtual:jogak/global-css')
 }
@@ -23,6 +26,7 @@ createRoot(rootEl).render(
     <JogakApp
       codeTheme={_jogakCodeTheme}
       previewIsolation={_jogakPreviewIsolation}
+      userViteUrl={_jogakUserViteUrl}
     />
   </StrictMode>,
 )

package/src/components/Preview/IframeMount.tsx

@@ -1,81 +1,92 @@
-import { useEffect, useRef } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import type { ReactElement } from 'react'
 import type { RegistryEntry } from '@jogak/core'
 
 export interface IframeMountProps {
   readonly entry: RegistryEntry
   readonly args: Readonly<Record<string, unknown>>
+  /**
+   * 알파.8: 사용자 vite spawn URL (예: `http://localhost:5174`).
+   * 빈 문자열 시 fallback (jogak SPA Vite scope의 `/preview-frame.html`).
+   */
+  readonly userViteUrl: string
   readonly className?: string
   readonly 'data-testid'?: string
 }
 
-interface SetPropsArgs {
-  readonly entry: RegistryEntry
-  readonly args: Readonly<Record<string, unknown>>
-}
-
-declare global {
-  interface Window {
-    __jogak_setProps__?: (args: SetPropsArgs) => void
-    __jogak_unmount__?: () => void
-  }
-}
-
 /**
- * 알파.7: previewIsolation='iframe' 모드의 mount 컴포넌트.
+ * 알파.8: previewIsolation='iframe' 모드의 mount 컴포넌트.
  *
- * - `<iframe src="/preview-frame.html">`을 마운트.
- * - iframe load 후 `iframe.contentWindow.__jogak_setProps__({ entry, args })`를
- *   호출해 entry/args를 주입한다 (postMessage 미사용 — 동일 origin이므로
- *   contentWindow 직접 접근 가능).
- * - entry/args 변경 시 setProps 재호출 (load 완료 이후).
+ * 통신:
+ * - 사용자 vite spawn URL이 주어지면(`userViteUrl !== ''`) iframe src를
+ *   `${userViteUrl}/__jogak_preview__/index.html` (cross-origin)로 설정.
+ * - 동일 origin fallback 시 `/preview-frame.html` (jogak SPA Vite scope).
  *
- * HMR:
- * - iframe document 자체도 Vite dev server module을 import하므로 사용자 컴포넌트
- *   파일 변경 시 fast refresh가 iframe 안에서 작동.
- * - previewIsolation 모드 자체 변경은 가상 모듈 invalidate → full reload.
+ * 양쪽 모두 postMessage로 통신:
+ * - 부모 → iframe: `{ type: 'jogak:setProps', entryId, args }` | `{ type: 'jogak:unmount' }`
+ * - iframe → 부모: `{ type: 'jogak:ready' }` | `{ type: 'jogak:rendered', entryId }`
  *
- * sandbox 미설정:
- * - 사용자 컴포넌트가 fetch/clipboard/storage 등 자유롭게 사용해야 하므로 sandbox X.
+ * `entry`는 객체가 아닌 **id만 전달** — iframe 안에서 `defaultRegistry.requestEntry(id)`로
+ * dynamic import. 사용자 vite scope의 entry 가상 모듈이 사용자 컴포넌트를 fetch하므로
+ * 사용자 plugins(@tailwindcss/vite, custom alias 등)이 정상 작동.
  */
 export function IframeMount({
   entry,
   args,
+  userViteUrl,
   className,
   'data-testid': dataTestId,
 }: IframeMountProps): ReactElement {
   const iframeRef = useRef<HTMLIFrameElement | null>(null)
-  const readyRef = useRef(false)
+  const [ready, setReady] = useState(false)
+
+  const src =
+    userViteUrl !== ''
+      ? `${userViteUrl}/__jogak_preview__/index.html`
+      : '/preview-frame.html'
 
-  // iframe load 후 첫 setProps
+  // postMessage 리스너 — iframe contentWindow 일치성 검증 후 처리.
   useEffect(() => {
+    const handler = (event: MessageEvent): void => {
+      const iframe = iframeRef.current
+      if (iframe === null) return
+      if (event.source !== iframe.contentWindow) return
+      const data = event.data
+      if (data == null || typeof data !== 'object') return
+      if (data.type === 'jogak:ready') setReady(true)
+    }
+    window.addEventListener('message', handler)
+    return () => {
+      window.removeEventListener('message', handler)
+    }
+  }, [])
+
+  // iframe ready 또는 entry/args 변경 시 setProps.
+  useEffect(() => {
+    if (!ready) return
     const iframe = iframeRef.current
     if (iframe === null) return
-    const handleLoad = (): void => {
-      readyRef.current = true
-      iframe.contentWindow?.__jogak_setProps__?.({ entry, args })
-    }
-    iframe.addEventListener('load', handleLoad)
+    iframe.contentWindow?.postMessage(
+      { type: 'jogak:setProps', entryId: entry.id, args },
+      '*',
+    )
+  }, [ready, entry, args])
+
+  // unmount 시 unmount 메시지 (race 회피 microtask defer).
+  useEffect(() => {
+    const iframe = iframeRef.current
     return () => {
-      iframe.removeEventListener('load', handleLoad)
-      // 알파.7.1: unmount race 회피 — iframe contentWindow 정리도 microtask defer.
+      if (iframe === null) return
       queueMicrotask(() => {
-        iframe.contentWindow?.__jogak_unmount__?.()
+        iframe.contentWindow?.postMessage({ type: 'jogak:unmount' }, '*')
       })
     }
-  // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
-  // entry/args 변경 시 setProps 재호출 (load 후에만)
-  useEffect(() => {
-    if (!readyRef.current) return
-    iframeRef.current?.contentWindow?.__jogak_setProps__?.({ entry, args })
-  }, [entry, args])
-
   return (
     <iframe
       ref={iframeRef}
-      src="/preview-frame.html"
+      src={src}
       title="Preview"
       className={className}
       data-testid={dataTestId}

package/src/components/Preview/index.tsx

@@ -24,13 +24,18 @@ export interface PreviewProps {
    */
   readonly onResolveJogak?: (entryId: string, jogakName: string) => void
   /**
-   * 알파.7: Preview 영역 격리 모드. default `'none'`.
+   * 알파.8: Preview 영역 격리 모드. default `'iframe'`.
    *
-   * - `'none'` — 기존 동작 (chrome과 같은 document, 알파.6 chrome 보호 rule 적용).
-   * - `'shadow'` — ShadowRoot에 마운트. 사용자 globalCss reset이 chrome 침범 차단.
-   * - `'iframe'` — `/preview-frame.html` iframe에 마운트. 강한 격리.
+   * - `'iframe'` (default) — 사용자 vite scope에 마운트. 사용자 utility 정상 컴파일.
+   * - `'shadow'` (deprecated) — ShadowRoot에 마운트. 사용자 utility 미적용.
+   * - `'none'` (deprecated) — chrome과 같은 document에 렌더.
    */
   readonly previewIsolation?: 'none' | 'shadow' | 'iframe'
+  /**
+   * 알파.8: 사용자 vite spawn URL. iframe `src` base.
+   * 빈 문자열 시 fallback (jogak SPA Vite scope의 `/preview-frame.html`).
+   */
+  readonly userViteUrl?: string
 }
 
 type ViewportKey = 'mobile' | 'tablet' | 'desktop'
@@ -120,7 +125,8 @@ export function Preview({
   onReset,
   codeTheme,
   onResolveJogak,
-  previewIsolation = 'shadow',
+  previewIsolation = 'iframe',
+  userViteUrl = '',
 }: PreviewProps): ReactElement {
   const state = useEntry(entryId)
   const [viewport, setViewport] = useState<ViewportKey>('desktop')
@@ -187,6 +193,7 @@ export function Preview({
       onBottomTabChange={setBottomTab}
       prismTheme={prismTheme}
       previewIsolation={previewIsolation}
+      userViteUrl={userViteUrl}
     />
   )
 }
@@ -275,6 +282,7 @@ interface ReadyFrameProps {
   readonly onBottomTabChange: (tab: 'controls' | 'actions') => void
   readonly prismTheme: PrismTheme
   readonly previewIsolation: 'none' | 'shadow' | 'iframe'
+  readonly userViteUrl: string
 }
 
 function ReadyFrame({
@@ -292,6 +300,7 @@ function ReadyFrame({
   onBottomTabChange,
   prismTheme,
   previewIsolation,
+  userViteUrl,
 }: ReadyFrameProps): ReactElement {
   // jogakName이 비어있으면 (deep link `?entry=...&jogak` 누락) 첫 jogak로 보정.
   const resolvedJogakName = jogakName ?? entry.jogaks[0]?.name ?? null
@@ -364,6 +373,7 @@ function ReadyFrame({
             source={entry.source}
             theme={prismTheme}
             previewIsolation={previewIsolation}
+            userViteUrl={userViteUrl}
           />
         </div>
       </div>
@@ -514,18 +524,19 @@ interface JogakRendererProps {
   readonly source: string | undefined
   readonly theme: PrismTheme
   readonly previewIsolation: 'none' | 'shadow' | 'iframe'
+  readonly userViteUrl: string
 }
 
 /**
- * 알파.7: previewIsolation 모드별로 사용자 콘텐츠 마운트 방식을 분기한다.
+ * 알파.8: previewIsolation 모드별로 사용자 콘텐츠 마운트 방식을 분기한다.
  *
- * - `'none'` — 같은 document에 직접 마운트 (알파.6까지의 동작 그대로).
- * - `'shadow'` — `<ShadowMount>` 안에 마운트해 ShadowRoot 격리.
- * - `'iframe'` — `<IframeMount>`로 별도 document에 마운트.
+ * - `'iframe'` (default) — 사용자 vite scope의 `<IframeMount>`로 별도 document.
+ * - `'shadow'` (deprecated) — `<ShadowMount>` 안에 마운트.
+ * - `'none'` (deprecated) — 같은 document에 직접 마운트.
  *
  * Show source 토글, 코드 패널 등 chrome 부분은 모드 무관하게 외부에 둔다.
  */
-function JogakRenderer({ entry, args, source, theme, previewIsolation }: JogakRendererProps): ReactElement {
+function JogakRenderer({ entry, args, source, theme, previewIsolation, userViteUrl }: JogakRendererProps): ReactElement {
   const [showCode, setShowCode] = useState(false)
 
   const previewBody = (
@@ -534,6 +545,7 @@ function JogakRenderer({ entry, args, source, theme, previewIsolation }: JogakRe
         entry={entry}
         args={args}
         previewIsolation={previewIsolation}
+        userViteUrl={userViteUrl}
       />
       <button
         type="button"
@@ -575,13 +587,14 @@ interface PreviewMountProps {
   readonly entry: RegistryEntry
   readonly args: Readonly<Record<string, unknown>>
   readonly previewIsolation: 'none' | 'shadow' | 'iframe'
+  readonly userViteUrl: string
 }
 
 const PREVIEW_HOST_CLASS =
   'jogak:border jogak:border-dashed jogak:border-[var(--jogak-color-border)] ' +
   'jogak:rounded-[var(--jogak-radius-xl)] jogak:p-4 jogak:pb-9'
 
-function PreviewMount({ entry, args, previewIsolation }: PreviewMountProps): ReactElement {
+function PreviewMount({ entry, args, previewIsolation, userViteUrl }: PreviewMountProps): ReactElement {
   if (previewIsolation === 'shadow') {
     return (
       <ShadowMount
@@ -598,13 +611,14 @@ function PreviewMount({ entry, args, previewIsolation }: PreviewMountProps): Rea
       <IframeMount
         entry={entry}
         args={args}
+        userViteUrl={userViteUrl}
         data-testid="preview-content"
         className={`${PREVIEW_HOST_CLASS} jogak:block jogak:w-full jogak:bg-transparent jogak:min-h-[256px]`}
       />
     )
   }
 
-  // 'none' — 기존 동작 그대로
+  // 'none' — deprecated 경로 (알파.7.1 동등 동작 보존, back-compat)
   return <NoneAdapterContent entry={entry} args={args} />
 }
 

package/src/vite-env.d.ts

@@ -4,10 +4,15 @@ declare module 'virtual:jogak' {
   /** 플러그인 설정에서 지정한 prism-react-renderer 테마 이름 */
   export const _jogakCodeTheme: string
   /**
-   * 알파.7: Preview 영역 격리 모드 ('none' | 'shadow' | 'iframe').
-   * `JogakPluginOptions.previewIsolation` (default 'none')의 literal emit.
+   * 알파.8: Preview 영역 격리 모드 ('none' | 'shadow' | 'iframe').
+   * `JogakPluginOptions.previewIsolation` (default 'iframe')의 literal emit.
    */
   export const _jogakPreviewIsolation: 'none' | 'shadow' | 'iframe'
+  /**
+   * 알파.8: 사용자 vite spawn URL. iframe `src` base로 사용 (예: `http://localhost:5174`).
+   * 빈 문자열 시 fallback (jogak SPA Vite scope의 preview-frame.tsx).
+   */
+  export const _jogakUserViteUrl: string
 }
 
 declare module 'virtual:jogak/global-css' {