@jogak/ui 0.1.0-alpha.9.1 → 1.0.0-beta.0

package/dist/lib/adapter-for.d.ts

@@ -0,0 +1,17 @@
+import { JogakAdapter } from '@jogak/core';
+/** RegistryEntryMeta.framework가 받을 수 있는 모든 값 (JogakAdapter.framework와 동일). */
+export type FrameworkKey = 'react' | 'next' | 'web-components' | 'vue' | 'svelte';
+/**
+ * framework 이름으로 어댑터를 가져온다. 첫 호출은 dynamic import, 이후는 캐시 반환.
+ *
+ * 동시에 같은 framework로 호출되는 경우(예: 여러 effect가 동시에 await)에도 단 한 번만
+ * import가 일어나도록 inflight Promise를 공유한다.
+ */
+export declare function adapterFor(framework: string): Promise<JogakAdapter>;
+/**
+ * @internal test-only. 어댑터 캐시를 초기화한다.
+ *
+ * cache hit/miss 테스트, framework lookup 격리 테스트에 사용. 프로덕션 코드에서는
+ * 호출하지 말 것 — dynamic import의 비용이 발생한다.
+ */
+export declare function __resetAdapterCacheForTesting(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jogak/ui",
-  "version": "0.1.0-alpha.9.1",
+  "version": "1.0.0-beta.0",
   "description": "Showcase viewer UI for Jogak — Sidebar / Preview / Controls / Actions and the JogakApp shell.",
   "keywords": [
     "jogak",
@@ -46,6 +46,7 @@
     "src/app",
     "src/components",
     "src/hooks",
+    "src/lib/adapter-for.ts",
     "src/styles",
     "src/index.ts",
     "src/vite-env.d.ts",
@@ -61,23 +62,24 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
+    "@tailwindcss/vite": "^4.0.0",
     "clsx": "^2.1.1",
     "prism-react-renderer": "^2.4.1",
     "tailwindcss": "^4.0.0",
-    "@tailwindcss/vite": "^4.0.0",
-    "@jogak/core": "0.1.0-alpha.9.1",
-    "@jogak/react": "0.1.0-alpha.9.1"
+    "@jogak/core": "1.0.0-beta.0"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^4.3.0",
+    "happy-dom": "^20.9.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "typescript": "^5.5.0",
-    "vite": "^6.0.0",
-    "vite-plugin-dts": "^4.5.4"
+    "vite": "^6.4.3",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^2.0.0"
   },
   "peerDependencies": {
     "@vitejs/plugin-react": "^4.3.0",
@@ -97,6 +99,7 @@
     "dev": "vite",
     "build": "vite build",
     "preview": "vite preview",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
 }

package/src/app/App.tsx

@@ -1,7 +1,7 @@
 import { useState, useCallback, useEffect, useMemo } from 'react'
 import { ComponentRegistry, defaultRegistry } from '@jogak/core'
 import type { RegistryEntry, RegistryEntryMeta } from '@jogak/core'
-import { JogakProvider } from '@jogak/react'
+import { JogakProvider } from '@jogak/core/renderers/react'
 import { Sidebar } from '../components/Sidebar/index.js'
 import { Preview } from '../components/Preview/index.js'
 import type { ReactElement } from 'react'

package/src/app/preview-frame.tsx

@@ -1,5 +1,6 @@
 /**
  * 알파.9: standalone-adapter 또는 fallback 시 사용되는 same-origin iframe entry.
+ * 알파.14.1: entry.meta.framework 기반 adapter dispatch (react/vue/svelte/wc 지원).
  *
  * `IframeMount`는 알파.9에서 postMessage 프로토콜로 통일됐다 (cross-origin 어댑터와 동일).
  * preview-frame.tsx도 같은 프로토콜을 따라야 한다 — 부모는 `jogak:setProps` 메시지를,
@@ -8,8 +9,9 @@
  * jogak host vite scope에서 동작하므로 `virtual:jogak` (registry metas + entry loader)와
  * `virtual:jogak/global-css` (사용자 globalCss) 가상 모듈을 그대로 사용한다.
  */
-import { reactAdapter } from '@jogak/react'
+import type { JogakAdapter } from '@jogak/core'
 import { defaultRegistry } from '@jogak/core'
+import { adapterFor } from '../lib/adapter-for.js'
 import 'virtual:jogak'
 import 'virtual:jogak/global-css'
 
@@ -17,23 +19,38 @@ const rootEl = document.getElementById('jogak-preview-root')
 if (rootEl === null) throw new Error('#jogak-preview-root not found')
 
 let currentContainer: HTMLDivElement | null = null
+let currentAdapter: JogakAdapter | null = null
 
 async function renderEntry(
   entryId: string,
   args: Readonly<Record<string, unknown>>,
 ): Promise<void> {
   const entry = await defaultRegistry.requestEntry(entryId)
+  const framework = entry.meta.framework ?? 'react'
+  const nextAdapter = await adapterFor(framework)
+
   if (currentContainer === null) {
     currentContainer = document.createElement('div')
     rootEl?.replaceChildren(currentContainer)
   }
-  reactAdapter.render(entry, args, currentContainer)
+  // entry framework가 바뀐 경우 이전 어댑터로 unmount 후 새 어댑터로 mount.
+  if (currentAdapter !== null && currentAdapter !== nextAdapter) {
+    currentAdapter.unmount(currentContainer)
+    // container 자체는 재사용 가능하지만 이전 어댑터가 남긴 root/component 상태가
+    // 섞이지 않도록 새 div로 교체.
+    const fresh = document.createElement('div')
+    rootEl?.replaceChildren(fresh)
+    currentContainer = fresh
+  }
+  currentAdapter = nextAdapter
+  await nextAdapter.render(entry, args, currentContainer)
 }
 
 function unmount(): void {
-  if (currentContainer !== null) {
-    reactAdapter.unmount(currentContainer)
+  if (currentContainer !== null && currentAdapter !== null) {
+    currentAdapter.unmount(currentContainer)
     currentContainer = null
+    currentAdapter = null
   }
 }
 

package/src/components/Controls/index.tsx

@@ -137,6 +137,12 @@ export function Controls({ args, argTypes, onArgChange }: ControlsProps): ReactE
   const keys = Array.from(new Set([...Object.keys(args), ...Object.keys(argTypes)]))
   const entries = keys.map((k) => [k, args[k]] as const)
 
+  // 알파.12: defaultValue를 가진 prop이 하나라도 있으면 Default 컬럼 노출.
+  // 모두 비어 있으면 컬럼 자체를 숨겨 테이블 가독성을 유지.
+  const hasAnyDefault = entries.some(
+    ([key]) => argTypes[key]?.defaultValue !== undefined,
+  )
+
   return (
     <div className="jogak:border-t-2 jogak:border-[var(--jogak-color-border)]">
       <div className="jogak:px-5 jogak:py-1.5 jogak:text-[11px] jogak:font-bold jogak:text-[var(--jogak-color-fg-subtle)] jogak:uppercase jogak:tracking-[0.08em] jogak:border-b jogak:border-[var(--jogak-color-border)] jogak:bg-[var(--jogak-color-bg-subtle)]">
@@ -152,6 +158,7 @@ export function Controls({ args, argTypes, onArgChange }: ControlsProps): ReactE
             <tr>
               <th className={thClass}>Name</th>
               <th className={thClass}>Control</th>
+              {hasAnyDefault && <th className={thClass}>Default</th>}
               <th className={thClass}>Description</th>
             </tr>
           </thead>
@@ -176,6 +183,18 @@ export function Controls({ args, argTypes, onArgChange }: ControlsProps): ReactE
                       onArgChange={onArgChange}
                     />
                   </td>
+                  {hasAnyDefault && (
+                    <td
+                      className={clsx(
+                        tdClass,
+                        'jogak:font-[family-name:var(--jogak-font-mono)] jogak:text-[12px] jogak:text-[var(--jogak-color-fg-muted)] jogak:whitespace-nowrap',
+                      )}
+                    >
+                      {argType?.defaultValue !== undefined
+                        ? formatDefaultValue(argType.defaultValue)
+                        : ''}
+                    </td>
+                  )}
                   <td className={clsx(tdClass, 'jogak:text-[var(--jogak-color-fg-subtle)]')}>
                     {argType?.description ?? ''}
                   </td>
@@ -188,3 +207,20 @@ export function Controls({ args, argTypes, onArgChange }: ControlsProps): ReactE
     </div>
   )
 }
+
+/**
+ * 알파.12: defaultValue를 Controls 패널에 표시할 때 사용. JSON-safe 값은 작은
+ * 인용부호로 string, 그 외 literal은 그대로 직렬화. 의도: 사용자가 코드에 쓸 수
+ * 있는 형태로 보여주기.
+ */
+function formatDefaultValue(v: unknown): string {
+  if (typeof v === 'string') return `'${v}'`
+  if (typeof v === 'number' || typeof v === 'boolean' || v === null) {
+    return String(v)
+  }
+  try {
+    return JSON.stringify(v)
+  } catch {
+    return String(v)
+  }
+}

package/src/components/Preview/format-usage.test.ts

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest'
+import type { RegistryEntry } from '@jogak/core'
+import { formatUsageCode } from './format-usage.js'
+
+function makeEntry(componentName: string, title = 'UI/Demo'): RegistryEntry {
+  function Demo(): null {
+    return null
+  }
+  Object.defineProperty(Demo, 'name', { value: componentName })
+  return {
+    id: title,
+    title,
+    jogaks: [],
+    meta: { title, component: Demo, argTypes: {} },
+    source: '',
+    filePath: '',
+  }
+}
+
+describe('formatUsageCode', () => {
+  it('children 문자열 → 단일 라인', () => {
+    const entry = makeEntry('Badge')
+    expect(formatUsageCode(entry, { children: 'New', variant: 'default' })).toBe(
+      '<Badge variant="default">New</Badge>',
+    )
+  })
+
+  it('children 없음 → self-closing', () => {
+    const entry = makeEntry('Card')
+    expect(formatUsageCode(entry, { title: 'Hello' })).toBe(
+      '<Card title="Hello" />',
+    )
+  })
+
+  it('boolean true → key only, false → key={false}', () => {
+    const entry = makeEntry('Toggle')
+    expect(formatUsageCode(entry, { disabled: true, checked: false })).toBe(
+      '<Toggle disabled checked={false} />',
+    )
+  })
+
+  it('number → 중괄호 표현', () => {
+    const entry = makeEntry('Counter')
+    expect(formatUsageCode(entry, { count: 42 })).toBe('<Counter count={42} />')
+  })
+
+  it('function → key={fn}', () => {
+    const entry = makeEntry('Button')
+    expect(
+      formatUsageCode(entry, { onClick: () => undefined, label: 'Go' }),
+    ).toBe('<Button onClick={fn} label="Go" />')
+  })
+
+  it('객체/배열 → JSON 표현', () => {
+    const entry = makeEntry('List')
+    expect(formatUsageCode(entry, { items: [1, 2, 3] })).toBe(
+      '<List items={[1,2,3]} />',
+    )
+  })
+
+  it('children에 number → JSX 표현', () => {
+    const entry = makeEntry('Counter')
+    expect(formatUsageCode(entry, { children: 7 })).toBe(
+      '<Counter>{7}</Counter>',
+    )
+  })
+
+  it('component name 없으면 title의 마지막 segment 사용', () => {
+    const entry: RegistryEntry = {
+      id: 'UI/Anonymous',
+      title: 'UI/Anonymous',
+      jogaks: [],
+      meta: {
+        title: 'UI/Anonymous',
+        component: undefined,
+        argTypes: {},
+      },
+      source: '',
+      filePath: '',
+    }
+    expect(formatUsageCode(entry, { children: 'X' })).toBe(
+      '<Anonymous>X</Anonymous>',
+    )
+  })
+
+  it('많은 props → multi-line 포맷', () => {
+    const entry = makeEntry('Form')
+    const out = formatUsageCode(entry, {
+      title: 'Long descriptive title',
+      description: 'Another lengthy text value',
+      disabled: false,
+      autoFocus: true,
+    })
+    expect(out).toContain('\n')
+    expect(out.startsWith('<Form\n  ')).toBe(true)
+    expect(out.endsWith('/>')).toBe(true)
+  })
+
+  it('따옴표 escape', () => {
+    const entry = makeEntry('Label')
+    expect(formatUsageCode(entry, { text: 'He said "hi"' })).toBe(
+      '<Label text="He said &quot;hi&quot;" />',
+    )
+  })
+
+  it('children + props 모두 multi-line으로 ', () => {
+    const entry = makeEntry('Card')
+    const out = formatUsageCode(entry, {
+      title: 'A long title',
+      description: 'A long description',
+      children: 'Body content',
+    })
+    expect(out).toMatch(/^<Card\n {2}title="A long title"\n {2}description="A long description"\n>\n {2}Body content\n<\/Card>$/u)
+  })
+})

package/src/components/Preview/format-usage.ts

@@ -0,0 +1,132 @@
+/**
+ * 알파.10.3: 컴포넌트 사용 코드 포매터.
+ *
+ * 코드 패널에는 `.jogak.tsx` 파일 전체가 아니라, 현재 args 기반의 사용 스니펫을 노출한다.
+ * 사용자가 Controls 패널에서 args를 바꾸면 즉시 갱신된다.
+ *
+ * 출력 예:
+ *   <Badge variant="default">New</Badge>
+ *
+ *   <Card
+ *     title="Hello"
+ *     disabled
+ *     onClick={fn}
+ *   />
+ */
+
+import type { RegistryEntry } from '@jogak/core'
+
+const SINGLE_LINE_THRESHOLD = 60
+
+/**
+ * `entry` + 현재 `args`로부터 JSX 사용 코드를 생성한다.
+ * children은 태그 본문에, 나머지 props는 attribute로.
+ */
+export function formatUsageCode(
+  entry: RegistryEntry,
+  args: Readonly<Record<string, unknown>>,
+): string {
+  const componentName = resolveComponentName(entry)
+  const { children, restProps } = splitChildren(args)
+
+  const propTokens = Object.entries(restProps)
+    .filter(([, v]) => v !== undefined)
+    .map(([k, v]) => formatProp(k, v))
+
+  const childrenStr = formatChildren(children)
+  const hasChildren = childrenStr !== null
+
+  // single-line 시도
+  const inlineProps = propTokens.length === 0 ? '' : ' ' + propTokens.join(' ')
+  const singleLine = hasChildren
+    ? `<${componentName}${inlineProps}>${childrenStr ?? ''}</${componentName}>`
+    : `<${componentName}${inlineProps} />`
+
+  if (singleLine.length <= SINGLE_LINE_THRESHOLD && !singleLine.includes('\n')) {
+    return singleLine
+  }
+
+  // multi-line — 각 prop을 별도 줄에
+  const indentedProps =
+    propTokens.length === 0 ? '' : '\n  ' + propTokens.join('\n  ') + '\n'
+  if (hasChildren) {
+    const indentedChildren = (childrenStr ?? '')
+      .split('\n')
+      .map((line) => `  ${line}`)
+      .join('\n')
+    return `<${componentName}${indentedProps}>\n${indentedChildren}\n</${componentName}>`
+  }
+  return `<${componentName}${indentedProps}/>`
+}
+
+function resolveComponentName(entry: RegistryEntry): string {
+  // 알파.14.1: iframe isolation 모드는 chrome scope에 component를 import하지 않으므로
+  // entry.meta.component가 `null`. fallback (title 마지막 segment)으로 직행한다.
+  const component = entry.meta.component as
+    | { displayName?: unknown; name?: unknown }
+    | null
+    | undefined
+  if (component !== null && component !== undefined) {
+    if (typeof component.displayName === 'string' && component.displayName.length > 0) {
+      return component.displayName
+    }
+    if (typeof component.name === 'string' && component.name.length > 0) {
+      return component.name
+    }
+  }
+  // fallback: title의 마지막 segment ("UI/Badge" → "Badge")
+  const lastSeg = entry.title.split('/').pop()
+  return lastSeg !== undefined && lastSeg.length > 0 ? lastSeg : 'Component'
+}
+
+interface SplitChildrenResult {
+  readonly children: unknown
+  readonly restProps: Readonly<Record<string, unknown>>
+}
+
+function splitChildren(args: Readonly<Record<string, unknown>>): SplitChildrenResult {
+  const { children, ...rest } = args as { children?: unknown } & Record<string, unknown>
+  return { children, restProps: rest }
+}
+
+function formatChildren(children: unknown): string | null {
+  if (children === undefined || children === null) return null
+  if (typeof children === 'string') {
+    if (children.length === 0) return null
+    return children
+  }
+  if (typeof children === 'number' || typeof children === 'bigint') {
+    return `{${children.toString()}}`
+  }
+  if (typeof children === 'boolean') {
+    return null
+  }
+  // 복합 타입(object/array/function): JSON 표현
+  return `{${stringifyValue(children)}}`
+}
+
+function formatProp(key: string, value: unknown): string {
+  if (value === true) return key
+  if (value === false) return `${key}={false}`
+  if (value === null) return `${key}={null}`
+  if (typeof value === 'string') {
+    // 따옴표 escape
+    const escaped = value.replace(/"/gu, '&quot;')
+    return `${key}="${escaped}"`
+  }
+  if (typeof value === 'number' || typeof value === 'bigint') {
+    return `${key}={${value.toString()}}`
+  }
+  if (typeof value === 'function') {
+    return `${key}={fn}`
+  }
+  return `${key}={${stringifyValue(value)}}`
+}
+
+function stringifyValue(value: unknown): string {
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return String(value)
+  }
+}

package/src/components/Preview/index.tsx

@@ -3,13 +3,15 @@ import type { ReactElement, CSSProperties } from 'react'
 import clsx from 'clsx'
 import { Highlight, themes } from 'prism-react-renderer'
 import type { PrismTheme } from 'prism-react-renderer'
-import { reactAdapter, useEntry } from '@jogak/react'
-import type { UseEntryState } from '@jogak/react'
-import type { RegistryEntry, RegistryEntryMeta, ArgType } from '@jogak/core'
+import { useEntry } from '@jogak/core/renderers/react'
+import type { UseEntryState } from '@jogak/core/renderers/react'
+import type { JogakAdapter, RegistryEntry, RegistryEntryMeta, ArgType } from '@jogak/core'
+import { adapterFor } from '../../lib/adapter-for.js'
 import { Controls } from '../Controls/index.js'
 import { Actions } from '../Actions/index.js'
 import { ShadowMount } from './ShadowMount.js'
 import { IframeMount } from './IframeMount.js'
+import { formatUsageCode } from './format-usage.js'
 
 export interface PreviewProps {
   readonly entryId: string
@@ -133,7 +135,11 @@ export function Preview({
   userPreviewUrl = '',
   previewEntryPath = '/__jogak_preview__/index.html',
 }: PreviewProps): ReactElement {
-  const state = useEntry(entryId)
+  // 알파.14.1: iframe isolation 모드에서는 chrome 측에 component 모듈을 import하지 않는다
+  // (chrome vite scope에 .vue/.svelte가 들어오면 plugin-vue/svelte 부재로 transform 실패).
+  // skipHydrate=true → useEntry가 synthetic entry(component=null)로 ready를 노출하고,
+  // 실제 마운트는 IframeMount가 사용자 vite scope의 iframe entry에 위임한다.
+  const state = useEntry(entryId, { skipHydrate: previewIsolation === 'iframe' })
   const [viewport, setViewport] = useState<ViewportKey>('desktop')
   const [bgMode, setBgMode] = useState<BgMode>('white')
   const [bottomTab, setBottomTab] = useState<'controls' | 'actions'>('controls')
@@ -378,7 +384,6 @@ function ReadyFrame({
             key={`${entry.id}/${jogak.name}`}
             entry={entry}
             args={mergedArgs}
-            source={entry.source}
             theme={prismTheme}
             previewIsolation={previewIsolation}
             userPreviewUrl={userPreviewUrl}
@@ -530,7 +535,6 @@ function Toolbar({
 interface JogakRendererProps {
   readonly entry: RegistryEntry
   readonly args: Readonly<Record<string, unknown>>
-  readonly source: string | undefined
   readonly theme: PrismTheme
   readonly previewIsolation: 'none' | 'shadow' | 'iframe'
   readonly userPreviewUrl: string
@@ -544,8 +548,10 @@ interface JogakRendererProps {
  * - `'shadow'` (deprecated) — `<ShadowMount>` 안에 마운트.
  * - `'none'` (deprecated) — 같은 document에 직접 마운트.
  */
-function JogakRenderer({ entry, args, source, theme, previewIsolation, userPreviewUrl, previewEntryPath }: JogakRendererProps): ReactElement {
+function JogakRenderer({ entry, args, theme, previewIsolation, userPreviewUrl, previewEntryPath }: JogakRendererProps): ReactElement {
   const [showCode, setShowCode] = useState(false)
+  // 알파.10.3: 코드 패널은 jogak 메타 파일이 아니라 현재 args 기반 사용 코드를 노출.
+  const usageCode = formatUsageCode(entry, args)
 
   const previewBody = (
     <div className="jogak:relative">
@@ -580,7 +586,7 @@ function JogakRenderer({ entry, args, source, theme, previewIsolation, userPrevi
       {/* 코드 패널 — 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} />
+          <SourceViewer source={usageCode} theme={theme} />
         </div>
       )}
     </div>
@@ -635,23 +641,50 @@ function PreviewMount({ entry, args, previewIsolation, userPreviewUrl, previewEn
 
 function NoneAdapterContent({ entry, args }: { entry: RegistryEntry; args: Readonly<Record<string, unknown>> }): ReactElement {
   const containerRef = useRef<HTMLDivElement>(null)
+  const adapterRef = useRef<JogakAdapter | null>(null)
 
+  // 알파.14.1: entry.meta.framework로 dispatch. async 적응을 위해 effect 내에서
+  // await adapterFor → 캡처된 adapter로 render. unmount는 같은 adapter ref 사용.
   useEffect(() => {
     const container = containerRef.current
     if (container === null) return
-    reactAdapter.render(entry, args, container)
+    let cancelled = false
+
+    const framework = entry.meta.framework ?? 'react'
+    void adapterFor(framework).then((adapter) => {
+      if (cancelled) return
+      adapterRef.current = adapter
+      void adapter.render(entry, args, container)
+    })
+
     return () => {
+      cancelled = true
+      const adapter = adapterRef.current
+      if (adapter === null) return
       // 알파.7.1: React 18 concurrent unmount race(`Attempted to synchronously unmount...`)
       // 회피 — fiber commit 끝난 직후로 defer.
-      queueMicrotask(() => { reactAdapter.unmount(container) })
+      queueMicrotask(() => { adapter.unmount(container) })
     }
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [entry])
 
+  // args 갱신용 effect — adapter가 이미 캐시돼 있으면 동기 분기를 탄다.
   useEffect(() => {
     const container = containerRef.current
     if (container === null) return
-    reactAdapter.render(entry, args, container)
+    let cancelled = false
+    const adapter = adapterRef.current
+    if (adapter !== null) {
+      void adapter.render(entry, args, container)
+      return
+    }
+    const framework = entry.meta.framework ?? 'react'
+    void adapterFor(framework).then((resolved) => {
+      if (cancelled) return
+      adapterRef.current = resolved
+      void resolved.render(entry, args, container)
+    })
+    return () => { cancelled = true }
   }, [entry, args])
 
   return (
@@ -664,19 +697,31 @@ function NoneAdapterContent({ entry, args }: { entry: RegistryEntry; args: Reado
 }
 
 /**
- * Shadow 모드 — ShadowMount의 ShadowRoot 안에서 react-adapter.render를 호출하는
+ * Shadow 모드 — ShadowMount의 ShadowRoot 안에서 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)
+  const adapterRef = useRef<JogakAdapter | null>(null)
 
   useEffect(() => {
     const c = ref.current
     if (c === null) return
-    reactAdapter.render(entry, args, c)
+    let cancelled = false
+
+    const framework = entry.meta.framework ?? 'react'
+    void adapterFor(framework).then((adapter) => {
+      if (cancelled) return
+      adapterRef.current = adapter
+      void adapter.render(entry, args, c)
+    })
+
     return () => {
+      cancelled = true
+      const adapter = adapterRef.current
+      if (adapter === null) return
       // 알파.7.1: unmount race 회피
-      queueMicrotask(() => { reactAdapter.unmount(c) })
+      queueMicrotask(() => { adapter.unmount(c) })
     }
   // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [entry])
@@ -684,7 +729,19 @@ function ShadowAdapterContent({ entry, args }: { entry: RegistryEntry; args: Rea
   useEffect(() => {
     const c = ref.current
     if (c === null) return
-    reactAdapter.render(entry, args, c)
+    let cancelled = false
+    const adapter = adapterRef.current
+    if (adapter !== null) {
+      void adapter.render(entry, args, c)
+      return
+    }
+    const framework = entry.meta.framework ?? 'react'
+    void adapterFor(framework).then((resolved) => {
+      if (cancelled) return
+      adapterRef.current = resolved
+      void resolved.render(entry, args, c)
+    })
+    return () => { cancelled = true }
   }, [entry, args])
 
   return <div ref={ref} data-testid="preview-content-shadow" />

package/src/components/Sidebar/index.tsx

@@ -2,7 +2,7 @@ import { useState, useEffect } from 'react'
 import type { CSSProperties, ReactElement } from 'react'
 import clsx from 'clsx'
 import type { CategoryMetaTree, RegistryEntryMeta } from '@jogak/core'
-import { useRegistryMeta } from '@jogak/react'
+import { useRegistryMeta } from '@jogak/core/renderers/react'
 
 // CSS custom property를 React style prop에 주입하기 위한 헬퍼 타입.
 // React 18+는 string-keyed `--` prefix를 인식하나 TS는 명시적 cast 필요.

package/src/hooks/useRegistry.ts

@@ -1,4 +1,4 @@
-import { useRegistry as useRegistryFromAdapter } from '@jogak/react'
+import { useRegistry as useRegistryFromAdapter } from '@jogak/core/renderers/react'
 import { useMemo } from 'react'
 import type { CategoryTree, RegistryEntry } from '@jogak/core'