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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jogak/ui",
-  "version": "0.1.0-alpha.7",
+  "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",
-    "@jogak/react": "0.1.0-alpha.7"
+    "@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 = 'none',
+  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,23 @@
 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'
-// 알파.6: 사용자 globalCss opt-in.
-// JogakPluginOptions.globalCss=false (default) → 빈 모듈 (no-op, SPA 번들 영향 zero).
-// true / string / string[] → plugin이 사용자 css를 import한다.
-// jogak.css 뒤에 둬서 사용자가 jogak chrome 기본값을 명시적으로 override 가능 —
-// 단, jogak utility는 prefix=jogak로 격리되어 사용자 utility와 충돌하지 않는다.
-import 'virtual:jogak/global-css'
 import { JogakApp } from './App.js'
 
+// 알파.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')
+}
+
 const rootEl = document.getElementById('root')
 if (rootEl === null) throw new Error('#root element not found')
 
@@ -19,6 +26,7 @@ createRoot(rootEl).render(
     <JogakApp
       codeTheme={_jogakCodeTheme}
       previewIsolation={_jogakPreviewIsolation}
+      userViteUrl={_jogakUserViteUrl}
     />
   </StrictMode>,
 )

package/src/components/Preview/IframeMount.tsx

@@ -1,79 +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 iframe = iframeRef.current
-    if (iframe === null) return
-    const handleLoad = (): void => {
-      readyRef.current = true
-      iframe.contentWindow?.__jogak_setProps__?.({ entry, args })
+    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)
     }
-    iframe.addEventListener('load', handleLoad)
+    window.addEventListener('message', handler)
     return () => {
-      iframe.removeEventListener('load', handleLoad)
-      // unmount 시 iframe 안 react root도 정리 (best-effort)
-      iframe.contentWindow?.__jogak_unmount__?.()
+      window.removeEventListener('message', handler)
     }
-  // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
-  // entry/args 변경 시 setProps 재호출 (load 후에만)
+  // iframe ready 또는 entry/args 변경 시 setProps.
   useEffect(() => {
-    if (!readyRef.current) return
-    iframeRef.current?.contentWindow?.__jogak_setProps__?.({ entry, args })
-  }, [entry, args])
+    if (!ready) return
+    const iframe = iframeRef.current
+    if (iframe === null) return
+    iframe.contentWindow?.postMessage(
+      { type: 'jogak:setProps', entryId: entry.id, args },
+      '*',
+    )
+  }, [ready, entry, args])
+
+  // unmount 시 unmount 메시지 (race 회피 microtask defer).
+  useEffect(() => {
+    const iframe = iframeRef.current
+    return () => {
+      if (iframe === null) return
+      queueMicrotask(() => {
+        iframe.contentWindow?.postMessage({ type: 'jogak:unmount' }, '*')
+      })
+    }
+  }, [])
 
   return (
     <iframe
       ref={iframeRef}
-      src="/preview-frame.html"
+      src={src}
       title="Preview"
       className={className}
       data-testid={dataTestId}

package/src/components/Preview/ShadowMount.tsx

@@ -6,26 +6,25 @@ export interface ShadowMountProps {
   readonly children: ReactNode
   readonly className?: string
   readonly style?: CSSProperties
-  /** 외부 테스트 hook (호스트 div에 부여). */
   readonly 'data-testid'?: string
 }
 
 /**
- * 알파.7: previewIsolation='shadow' 모드의 mount 컴포넌트.
+ * 알파.7.1: previewIsolation='shadow' 모드의 mount 컴포넌트.
  *
- * 역할:
- * - 호스트 `<div>`에 `attachShadow({ mode: 'open' })`로 ShadowRoot를 부착.
- * - `createPortal`로 children을 ShadowRoot에 렌더 (React tree 유지).
- * - 외부 document의 모든 `<style>` / cross-origin 가능 stylesheet를
- *   `adoptedStyleSheets`로 ShadowRoot에 share (jogak.css + virtual:jogak/global-css
- *   둘 다 자동 포함).
- * - Vite dev에서 `<style>` HMR 시 MutationObserver로 ShadowRoot도 갱신.
+ * 책임: 양방향 격리만 제공 (Preview ↔ outer document 양방향 cascade 차단).
+ * - 사용자 globalCss는 main.tsx 가드로 outer document에 inject되지 않음.
+ * - shadow root 안에는 jogak chrome css도 사용자 css도 없음 (둘 다 외부에서 격리).
+ * - 사용자 컴포넌트의 utility class 컴파일은 결함 B (알파.8 사이클).
  *
- * Radix portal 한계 (사용자 인지 필요):
- * - 사용자 컴포넌트가 `Dialog.Portal` / `Popover.Portal` 등을 default로 쓰면
- *   portal target은 `document.body` — ShadowRoot 외부. utility class는 외부
- *   document에 정의되어 적용됨, 단 z-index/focus/event boundary가 분리될 수 있음.
- * - 회피: 사용자가 명시적으로 `<Portal container={shadowRootEl}>`을 전달.
+ * 알파.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 function ShadowMount({
   children,
@@ -39,16 +38,9 @@ export function ShadowMount({
   useEffect(() => {
     const host = hostRef.current
     if (host === null) return
-    let sr: ShadowRoot
-    if (host.shadowRoot !== null) {
-      sr = host.shadowRoot
-    } else {
-      sr = host.attachShadow({ mode: 'open' })
-    }
+    const sr = host.shadowRoot ?? host.attachShadow({ mode: 'open' })
     setShadowRoot(sr)
-    syncStyleSheets(sr)
-    const observer = observeDocumentStyles(sr)
-    return () => { observer.disconnect() }
+    // shadow root는 host element와 함께 GC — 명시 detach 불필요.
   }, [])
 
   return (
@@ -63,39 +55,3 @@ export function ShadowMount({
     </div>
   )
 }
-
-/**
- * 외부 document의 모든 stylesheet를 ShadowRoot에 share한다.
- *
- * - `adoptedStyleSheets` API를 사용 (Chromium/Safari/Firefox 모던 브라우저 지원).
- * - cross-origin sheet는 `cssRules` 접근 시 SecurityError → catch 후 skip.
- * - Vite dev의 `<style>` HMR이 자주 발생할 수 있어 `replaceSync`를 통한 새
- *   `CSSStyleSheet` 인스턴스 생성으로 처리.
- */
-function syncStyleSheets(shadowRoot: ShadowRoot): void {
-  const sheets: CSSStyleSheet[] = []
-  for (const sheet of Array.from(document.styleSheets)) {
-    try {
-      const rules = sheet.cssRules
-      const cs = new CSSStyleSheet()
-      const cssText = Array.from(rules).map((r) => r.cssText).join('\n')
-      cs.replaceSync(cssText)
-      sheets.push(cs)
-    } catch {
-      // cross-origin sheet — skip
-    }
-  }
-  shadowRoot.adoptedStyleSheets = sheets
-}
-
-/**
- * document.head의 변화(`<style>` HMR add/remove)를 관찰해 ShadowRoot의
- * adoptedStyleSheets를 다시 sync.
- */
-function observeDocumentStyles(shadowRoot: ShadowRoot): MutationObserver {
-  const observer = new MutationObserver(() => {
-    syncStyleSheets(shadowRoot)
-  })
-  observer.observe(document.head, { childList: true, subtree: true })
-  return observer
-}

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 = 'none',
+  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} />
 }
 
@@ -615,7 +629,11 @@ function NoneAdapterContent({ entry, args }: { entry: RegistryEntry; args: Reado
     const container = containerRef.current
     if (container === null) return
     reactAdapter.render(entry, args, container)
-    return () => { reactAdapter.unmount(container) }
+    return () => {
+      // 알파.7.1: React 18 concurrent unmount race(`Attempted to synchronously unmount...`)
+      // 회피 — fiber commit 끝난 직후로 defer.
+      queueMicrotask(() => { reactAdapter.unmount(container) })
+    }
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [entry])
 
@@ -645,7 +663,10 @@ function ShadowAdapterContent({ entry, args }: { entry: RegistryEntry; args: Rea
     const c = ref.current
     if (c === null) return
     reactAdapter.render(entry, args, c)
-    return () => { reactAdapter.unmount(c) }
+    return () => {
+      // 알파.7.1: unmount race 회피
+      queueMicrotask(() => { reactAdapter.unmount(c) })
+    }
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [entry])
 

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' {