npm - @jogak/ui - Versions diffs - 0.1.0-alpha.5 → 0.1.0-alpha.7 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/CHANGELOG.md +43 -0
package/README.md +171 -23
package/dist/app/App.d.ts +11 -1
package/dist/components/Preview/IframeMount.d.ts +37 -0
package/dist/components/Preview/ShadowMount.d.ts +26 -0
package/dist/components/Preview/index.d.ts +9 -1
package/dist/host/index.d.ts +20 -0
package/dist/host/index.js +1 -1
package/dist/host/index.mjs +51 -45
package/dist/index.js +2 -1
package/dist/index.mjs +456 -330
package/package.json +4 -3
package/preview-frame.html +17 -0
package/src/app/App.tsx +12 -0
package/src/app/main.tsx +11 -2
package/src/app/preview-frame.tsx +46 -0
package/src/components/Preview/IframeMount.tsx +82 -0
package/src/components/Preview/ShadowMount.tsx +101 -0
package/src/components/Preview/index.tsx +138 -34
package/src/styles/jogak.css +20 -0
package/src/vite-env.d.ts +9 -0

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@jogak/ui",
-  "version": "0.1.0-alpha.5",
+  "version": "0.1.0-alpha.7",
   "description": "Showcase viewer UI for Jogak — Sidebar / Preview / Controls / Actions and the JogakApp shell.",
   "keywords": [
     "jogak",
@@ -42,6 +42,7 @@
   "files": [
     "dist",
     "index.html",
+    "preview-frame.html",
     "src/app",
     "src/components",
     "src/hooks",
@@ -64,8 +65,8 @@
     "prism-react-renderer": "^2.4.1",
     "tailwindcss": "^4.0.0",
     "@tailwindcss/vite": "^4.0.0",
-    "@jogak/core": "0.1.0-alpha.5",
-    "@jogak/react": "0.1.0-alpha.5"
+    "@jogak/core": "0.1.0-alpha.7",
+    "@jogak/react": "0.1.0-alpha.7"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",

package/preview-frame.html ADDED Viewed

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>jogak preview</title>
+    <style>
+      *, *::before, *::after { box-sizing: border-box; }
+      html, body { margin: 0; }
+      body { font-family: system-ui, sans-serif; }
+    </style>
+  </head>
+  <body>
+    <div id="jogak-preview-root"></div>
+    <script type="module" src="/src/app/preview-frame.tsx"></script>
+  </body>
+</html>

package/src/app/App.tsx CHANGED Viewed

@@ -20,6 +20,16 @@ export interface JogakAppProps {
   readonly entries?: readonly RegistryEntry[]
   readonly metas?: readonly RegistryEntryMeta[]
   readonly codeTheme?: string
+  /**
+   * 알파.7: Preview 영역 격리 모드. default `'none'`.
+   *
+   * - `'none'` — Preview 콘텐츠를 chrome 같은 document에 렌더 (알파.6까지의 동작).
+   * - `'shadow'` — ShadowRoot 안에 마운트. 사용자 globalCss/reset이 chrome 침범 차단.
+   * - `'iframe'` — 별도 document(iframe)에 마운트. 가장 강한 격리.
+   *
+   * 자세한 트레이드오프는 `@jogak/ui` README의 "previewIsolation 사용 가이드" 참조.
+   */
+  readonly previewIsolation?: 'none' | 'shadow' | 'iframe'
 }
 function readUrlParams(): { entryId: string; jogakName: string | null } | null {
@@ -42,6 +52,7 @@ export function JogakApp({
   entries,
   metas,
   codeTheme = 'vsDark',
+  previewIsolation = 'none',
 }: JogakAppProps = {}): ReactElement {
   // ── 4가지 모드 결정 (계약 §5.2) ─────────────────────────────────────
   // 1) entries가 주어지면: 새 ComponentRegistry에 register (eager, 기존 동작)
@@ -144,6 +155,7 @@ export function JogakApp({
               onReset={handleReset}
               codeTheme={codeTheme}
               onResolveJogak={handleResolveJogak}
+              previewIsolation={previewIsolation}
             />
           ) : (
             <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 CHANGED Viewed

@@ -1,8 +1,14 @@
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
 import 'virtual:jogak'
-import { _jogakCodeTheme } from 'virtual:jogak'
+import { _jogakCodeTheme, _jogakPreviewIsolation } 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'
 const rootEl = document.getElementById('root')
@@ -10,6 +16,9 @@ if (rootEl === null) throw new Error('#root element not found')
 createRoot(rootEl).render(
   <StrictMode>
-    <JogakApp codeTheme={_jogakCodeTheme} />
+    <JogakApp
+      codeTheme={_jogakCodeTheme}
+      previewIsolation={_jogakPreviewIsolation}
+    />
   </StrictMode>,
 )

package/src/app/preview-frame.tsx ADDED Viewed

@@ -0,0 +1,46 @@
+/**
+ * 알파.7: previewIsolation='iframe' 모드 — iframe document entry.
+ *
+ * - 부모 Preview 컴포넌트의 `<IframeMount>`가 `iframe.contentWindow.__jogak_setProps__`
+ *   를 호출해 entry/args를 주입한다.
+ * - iframe과 부모는 동일 origin (Vite dev server) → contentWindow 직접 접근 가능.
+ *   postMessage는 cross-origin/iframe sandbox 시나리오에서만 필요.
+ * - 사용자 globalCss(`virtual:jogak/global-css`)만 import — jogak.css는 chrome 전용
+ *   이라 iframe에서는 미필요. 사용자 reset이 iframe document에 free하게 적용됨.
+ */
+import { reactAdapter } from '@jogak/react'
+import type { RegistryEntry } from '@jogak/core'
+import 'virtual:jogak'
+import 'virtual:jogak/global-css'
+interface SetPropsArgs {
+  readonly entry: RegistryEntry
+  readonly args: Readonly<Record<string, unknown>>
+}
+declare global {
+  interface Window {
+    __jogak_setProps__?: (args: SetPropsArgs) => void
+    __jogak_unmount__?: () => void
+  }
+}
+const rootEl = document.getElementById('jogak-preview-root')
+if (rootEl === null) throw new Error('#jogak-preview-root not found')
+let currentEl: HTMLDivElement | null = null
+window.__jogak_setProps__ = ({ entry, args }) => {
+  if (currentEl === null) {
+    currentEl = document.createElement('div')
+    rootEl.replaceChildren(currentEl)
+  }
+  reactAdapter.render(entry, args, currentEl)
+}
+window.__jogak_unmount__ = () => {
+  if (currentEl !== null) {
+    reactAdapter.unmount(currentEl)
+    currentEl = null
+  }
+}

package/src/components/Preview/IframeMount.tsx ADDED Viewed

@@ -0,0 +1,82 @@
+import { useEffect, useRef } 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>>
+  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 컴포넌트.
+ *
+ * - `<iframe src="/preview-frame.html">`을 마운트.
+ * - iframe load 후 `iframe.contentWindow.__jogak_setProps__({ entry, args })`를
+ *   호출해 entry/args를 주입한다 (postMessage 미사용 — 동일 origin이므로
+ *   contentWindow 직접 접근 가능).
+ * - entry/args 변경 시 setProps 재호출 (load 완료 이후).
+ *
+ * HMR:
+ * - iframe document 자체도 Vite dev server module을 import하므로 사용자 컴포넌트
+ *   파일 변경 시 fast refresh가 iframe 안에서 작동.
+ * - previewIsolation 모드 자체 변경은 가상 모듈 invalidate → full reload.
+ *
+ * sandbox 미설정:
+ * - 사용자 컴포넌트가 fetch/clipboard/storage 등 자유롭게 사용해야 하므로 sandbox X.
+ */
+export function IframeMount({
+  entry,
+  args,
+  className,
+  'data-testid': dataTestId,
+}: IframeMountProps): ReactElement {
+  const iframeRef = useRef<HTMLIFrameElement | null>(null)
+  const readyRef = useRef(false)
+  // iframe load 후 첫 setProps
+  useEffect(() => {
+    const iframe = iframeRef.current
+    if (iframe === null) return
+    const handleLoad = (): void => {
+      readyRef.current = true
+      iframe.contentWindow?.__jogak_setProps__?.({ entry, args })
+    }
+    iframe.addEventListener('load', handleLoad)
+    return () => {
+      iframe.removeEventListener('load', handleLoad)
+      // unmount 시 iframe 안 react root도 정리 (best-effort)
+      iframe.contentWindow?.__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"
+      title="Preview"
+      className={className}
+      data-testid={dataTestId}
+    />
+  )
+}

package/src/components/Preview/ShadowMount.tsx ADDED Viewed

@@ -0,0 +1,101 @@
+import { useEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
+import type { ReactElement, ReactNode, CSSProperties } from 'react'
+export interface ShadowMountProps {
+  readonly children: ReactNode
+  readonly className?: string
+  readonly style?: CSSProperties
+  /** 외부 테스트 hook (호스트 div에 부여). */
+  readonly 'data-testid'?: string
+}
+/**
+ * 알파.7: 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도 갱신.
+ *
+ * Radix portal 한계 (사용자 인지 필요):
+ * - 사용자 컴포넌트가 `Dialog.Portal` / `Popover.Portal` 등을 default로 쓰면
+ *   portal target은 `document.body` — ShadowRoot 외부. utility class는 외부
+ *   document에 정의되어 적용됨, 단 z-index/focus/event boundary가 분리될 수 있음.
+ * - 회피: 사용자가 명시적으로 `<Portal container={shadowRootEl}>`을 전달.
+ */
+export function ShadowMount({
+  children,
+  className,
+  style,
+  'data-testid': dataTestId,
+}: ShadowMountProps): ReactElement {
+  const hostRef = useRef<HTMLDivElement | null>(null)
+  const [shadowRoot, setShadowRoot] = useState<ShadowRoot | null>(null)
+  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' })
+    }
+    setShadowRoot(sr)
+    syncStyleSheets(sr)
+    const observer = observeDocumentStyles(sr)
+    return () => { observer.disconnect() }
+  }, [])
+  return (
+    <div
+      ref={hostRef}
+      className={className}
+      data-testid={dataTestId}
+      // eslint-disable-next-line no-restricted-syntax -- jogak: ShadowMount caller-supplied style passthrough (host wrapper, content goes through ShadowRoot portal)
+      style={style}
+    >
+      {shadowRoot !== null ? createPortal(children, shadowRoot) : null}
+    </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 CHANGED Viewed

@@ -8,6 +8,8 @@ import type { UseEntryState } from '@jogak/react'
 import type { RegistryEntry, RegistryEntryMeta, ArgType } from '@jogak/core'
 import { Controls } from '../Controls/index.js'
 import { Actions } from '../Actions/index.js'
+import { ShadowMount } from './ShadowMount.js'
+import { IframeMount } from './IframeMount.js'
 export interface PreviewProps {
   readonly entryId: string
@@ -21,6 +23,14 @@ export interface PreviewProps {
    * 첫 jogak로 자동 보정하기 위한 콜백. 부모가 selectedJogakName / URL을 갱신.
    */
   readonly onResolveJogak?: (entryId: string, jogakName: string) => void
+  /**
+   * 알파.7: Preview 영역 격리 모드. default `'none'`.
+   *
+   * - `'none'` — 기존 동작 (chrome과 같은 document, 알파.6 chrome 보호 rule 적용).
+   * - `'shadow'` — ShadowRoot에 마운트. 사용자 globalCss reset이 chrome 침범 차단.
+   * - `'iframe'` — `/preview-frame.html` iframe에 마운트. 강한 격리.
+   */
+  readonly previewIsolation?: 'none' | 'shadow' | 'iframe'
 }
 type ViewportKey = 'mobile' | 'tablet' | 'desktop'
@@ -110,6 +120,7 @@ export function Preview({
   onReset,
   codeTheme,
   onResolveJogak,
+  previewIsolation = 'none',
 }: PreviewProps): ReactElement {
   const state = useEntry(entryId)
   const [viewport, setViewport] = useState<ViewportKey>('desktop')
@@ -175,6 +186,7 @@ export function Preview({
       onBgModeChange={setBgMode}
       onBottomTabChange={setBottomTab}
       prismTheme={prismTheme}
+      previewIsolation={previewIsolation}
     />
   )
 }
@@ -262,6 +274,7 @@ interface ReadyFrameProps {
   readonly onBgModeChange: (bg: BgMode) => void
   readonly onBottomTabChange: (tab: 'controls' | 'actions') => void
   readonly prismTheme: PrismTheme
+  readonly previewIsolation: 'none' | 'shadow' | 'iframe'
 }
 function ReadyFrame({
@@ -278,6 +291,7 @@ function ReadyFrame({
   onBgModeChange,
   onBottomTabChange,
   prismTheme,
+  previewIsolation,
 }: ReadyFrameProps): ReactElement {
   // jogakName이 비어있으면 (deep link `?entry=...&jogak` 누락) 첫 jogak로 보정.
   const resolvedJogakName = jogakName ?? entry.jogaks[0]?.name ?? null
@@ -349,6 +363,7 @@ function ReadyFrame({
             args={mergedArgs}
             source={entry.source}
             theme={prismTheme}
+            previewIsolation={previewIsolation}
           />
         </div>
       </div>
@@ -498,12 +513,104 @@ interface JogakRendererProps {
   readonly args: Readonly<Record<string, unknown>>
   readonly source: string | undefined
   readonly theme: PrismTheme
+  readonly previewIsolation: 'none' | 'shadow' | 'iframe'
 }
-function JogakRenderer({ entry, args, source, theme }: JogakRendererProps): ReactElement {
-  const containerRef = useRef<HTMLDivElement>(null)
+/**
+ * 알파.7: previewIsolation 모드별로 사용자 콘텐츠 마운트 방식을 분기한다.
+ *
+ * - `'none'` — 같은 document에 직접 마운트 (알파.6까지의 동작 그대로).
+ * - `'shadow'` — `<ShadowMount>` 안에 마운트해 ShadowRoot 격리.
+ * - `'iframe'` — `<IframeMount>`로 별도 document에 마운트.
+ *
+ * Show source 토글, 코드 패널 등 chrome 부분은 모드 무관하게 외부에 둔다.
+ */
+function JogakRenderer({ entry, args, source, theme, previewIsolation }: JogakRendererProps): ReactElement {
   const [showCode, setShowCode] = useState(false)
+  const previewBody = (
+    <div className="jogak:relative">
+      <PreviewMount
+        entry={entry}
+        args={args}
+        previewIsolation={previewIsolation}
+      />
+      <button
+        type="button"
+        onClick={() => { setShowCode((v) => !v) }}
+        aria-pressed={showCode}
+        aria-label={showCode ? 'Hide source code' : 'Show source code'}
+        className={clsx(
+          'jogak:absolute jogak:bottom-2 jogak:right-2 jogak:px-[9px] jogak:py-1',
+          'jogak:text-[11px] jogak:font-[family-name:var(--jogak-font-mono)] jogak:font-semibold jogak:tracking-[0.02em]',
+          'jogak:text-[var(--jogak-color-bg)] jogak:border-none jogak:rounded-[5px] jogak:cursor-pointer',
+          'jogak:shadow-[0_1px_4px_rgba(0,0,0,0.2)] jogak:transition-[background-color] jogak:duration-150 jogak:leading-none',
+          showCode ? 'jogak:bg-[var(--jogak-color-accent)]' : 'jogak:bg-[#1e293b]',
+        )}
+      >
+        {'</>'}
+      </button>
+    </div>
+  )
+  return (
+    <div>
+      {previewBody}
+      {/* 코드 패널 — preview-content 하단으로 펼쳐짐 */}
+      {showCode && (
+        <div className="jogak:mt-2 jogak:rounded-[var(--jogak-radius-xl)] jogak:overflow-hidden jogak:h-[320px] jogak:shadow-[0_0_0_1px_rgba(0,0,0,0.08),_0_4px_16px_rgba(0,0,0,0.12)]">
+          <SourceViewer source={source} theme={theme} />
+        </div>
+      )}
+    </div>
+  )
+}
+// ── PreviewMount ──────────────────────────────────────────
+//
+// previewIsolation 모드별 콘텐츠 마운트. chrome 외곽 (border/radius/padding)은 모드
+// 별 호스트 element에 동일하게 적용해 VR baseline 변경을 zero로 유지한다.
+interface PreviewMountProps {
+  readonly entry: RegistryEntry
+  readonly args: Readonly<Record<string, unknown>>
+  readonly previewIsolation: 'none' | 'shadow' | 'iframe'
+}
+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 {
+  if (previewIsolation === 'shadow') {
+    return (
+      <ShadowMount
+        data-testid="preview-content"
+        className={PREVIEW_HOST_CLASS}
+      >
+        <ShadowAdapterContent entry={entry} args={args} />
+      </ShadowMount>
+    )
+  }
+  if (previewIsolation === 'iframe') {
+    return (
+      <IframeMount
+        entry={entry}
+        args={args}
+        data-testid="preview-content"
+        className={`${PREVIEW_HOST_CLASS} jogak:block jogak:w-full jogak:bg-transparent jogak:min-h-[256px]`}
+      />
+    )
+  }
+  // 'none' — 기존 동작 그대로
+  return <NoneAdapterContent entry={entry} args={args} />
+}
+function NoneAdapterContent({ entry, args }: { entry: RegistryEntry; args: Readonly<Record<string, unknown>> }): ReactElement {
+  const containerRef = useRef<HTMLDivElement>(null)
   useEffect(() => {
     const container = containerRef.current
     if (container === null) return
@@ -519,41 +626,38 @@ function JogakRenderer({ entry, args, source, theme }: JogakRendererProps): Reac
   }, [entry, args])
   return (
-    <div>
-      {/* preview-content 영역 + 토글 버튼 */}
-      <div className="jogak:relative">
-        <div
-          ref={containerRef}
-          data-testid="preview-content"
-          className="jogak:border jogak:border-dashed jogak:border-[var(--jogak-color-border)] jogak:rounded-[var(--jogak-radius-xl)] jogak:p-4 jogak:pb-9"
-        />
-        <button
-          type="button"
-          onClick={() => { setShowCode((v) => !v) }}
-          aria-pressed={showCode}
-          aria-label={showCode ? 'Hide source code' : 'Show source code'}
-          className={clsx(
-            'jogak:absolute jogak:bottom-2 jogak:right-2 jogak:px-[9px] jogak:py-1',
-            'jogak:text-[11px] jogak:font-[family-name:var(--jogak-font-mono)] jogak:font-semibold jogak:tracking-[0.02em]',
-            'jogak:text-[var(--jogak-color-bg)] jogak:border-none jogak:rounded-[5px] jogak:cursor-pointer',
-            'jogak:shadow-[0_1px_4px_rgba(0,0,0,0.2)] jogak:transition-[background-color] jogak:duration-150 jogak:leading-none',
-            showCode ? 'jogak:bg-[var(--jogak-color-accent)]' : 'jogak:bg-[#1e293b]',
-          )}
-        >
-          {'</>'}
-        </button>
-      </div>
-      {/* 코드 패널 — preview-content 하단으로 펼쳐짐 */}
-      {showCode && (
-        <div className="jogak:mt-2 jogak:rounded-[var(--jogak-radius-xl)] jogak:overflow-hidden jogak:h-[320px] jogak:shadow-[0_0_0_1px_rgba(0,0,0,0.08),_0_4px_16px_rgba(0,0,0,0.12)]">
-          <SourceViewer source={source} theme={theme} />
-        </div>
-      )}
-    </div>
+    <div
+      ref={containerRef}
+      data-testid="preview-content"
+      className={PREVIEW_HOST_CLASS}
+    />
   )
 }
+/**
+ * Shadow 모드 — ShadowMount의 ShadowRoot 안에서 react-adapter.render를 호출하는
+ * 작은 wrapper. ShadowMount 안 portal 내부에 위치하므로 useRef는 ShadowRoot scope.
+ */
+function ShadowAdapterContent({ entry, args }: { entry: RegistryEntry; args: Readonly<Record<string, unknown>> }): ReactElement {
+  const ref = useRef<HTMLDivElement>(null)
+  useEffect(() => {
+    const c = ref.current
+    if (c === null) return
+    reactAdapter.render(entry, args, c)
+    return () => { reactAdapter.unmount(c) }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [entry])
+  useEffect(() => {
+    const c = ref.current
+    if (c === null) return
+    reactAdapter.render(entry, args, c)
+  }, [entry, args])
+  return <div ref={ref} data-testid="preview-content-shadow" />
+}
 // ── SourceViewer ──────────────────────────────────────────
 interface SourceViewerProps {

package/src/styles/jogak.css CHANGED Viewed

@@ -82,6 +82,26 @@
      * 회귀 자체 차단 + 알파.6 사용자 globalCss 충돌 가능성 zero.
      */
   }
+  /*
+   * 알파.6 wrapper 보호 rule (api-contracts §8 옵션 C).
+   *
+   * 사용자 globalCss(예: shadcn `@layer base { * { @apply border-border ... } }`)가
+   * jogak chrome의 form element를 침범하는 것을 차단한다. `:where(...)` specificity 0
+   * 으로 사용자가 명시적으로 `[data-jogak-shell] button { ... }`를 작성하면 자연스럽게
+   * 이긴다.
+   *
+   * 적용 범위: chrome의 모든 form element. preview(`[data-jogak-content]`) 안의
+   * 사용자 컴포넌트는 영향 받지 않음 — `:not([data-jogak-content] *)`로 제외.
+   *
+   * 알파.5 baseline 영향: zero. chrome 컴포넌트는 본 rule이 차단하는 사용자 reset이
+   * 없을 때 동일 시각 (revert-layer는 해당 layer가 없으면 no-op).
+   */
+  [data-jogak-shell] :where(button, input, select, textarea):not([data-jogak-content] *) {
+    border-color: revert-layer;
+    background-color: revert-layer;
+    color: revert-layer;
+  }
 }
 @layer components {

package/src/vite-env.d.ts CHANGED Viewed

@@ -3,4 +3,13 @@
 declare module 'virtual:jogak' {
   /** 플러그인 설정에서 지정한 prism-react-renderer 테마 이름 */
   export const _jogakCodeTheme: string
+  /**
+   * 알파.7: Preview 영역 격리 모드 ('none' | 'shadow' | 'iframe').
+   * `JogakPluginOptions.previewIsolation` (default 'none')의 literal emit.
+   */
+  export const _jogakPreviewIsolation: 'none' | 'shadow' | 'iframe'
+}
+declare module 'virtual:jogak/global-css' {
+  // empty — side-effect only
 }