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

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-import { JogakPluginOptions } from './types.js';
+import { JogakPluginOptions, UserViteOptions } from './types.js';
 /**
  * `jogak.config.{ts,mts,mjs,js,json}`의 default export 타입.
  *
@@ -27,6 +27,19 @@ export interface JogakConfig extends JogakPluginOptions {
     readonly minify?: boolean | 'esbuild' | 'terser';
     /** 빌드 소스맵. 기본 false. CLI `--sourcemap`로 override. */
     readonly sourcemap?: boolean;
+    /**
+     * 사용자 vite 인스턴스 spawn 옵션 (알파.8). 미지정 시 cwd의 `vite.config.{ts,mts,js,mjs,cjs}`를
+     * 자동 탐지해 별도 vite dev server를 띄워 iframe src로 사용한다.
+     *
+     * `previewIsolation: 'iframe'` (default)에서만 사용된다.
+     *
+     * @example 사용자 vite 명시 비활성화 (알파.7.1 동등 fallback)
+     * defineJogakConfig({ userVite: { disabled: true } })
+     *
+     * @example 사용자 vite 포트 명시
+     * defineJogakConfig({ userVite: { port: 5174 } })
+     */
+    readonly userVite?: UserViteOptions;
 }
 /**
  * `jogak.config.ts`에서 사용자가 호출하는 identity helper.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export type { ArgType, JogakMeta, Jogak, RegistryEntry, RegistryEntryMeta, CategoryTree, CategoryMetaTree, JogakAdapter, JogakPluginOptions, } from './types.js';
+export type { ArgType, JogakMeta, Jogak, RegistryEntry, RegistryEntryMeta, CategoryTree, CategoryMetaTree, JogakAdapter, JogakPluginOptions, UserViteOptions, } from './types.js';
 export { ComponentRegistry, defaultRegistry, UnknownEntryError } from './registry.js';
 export { ActionChannel, defaultActionChannel, action, injectActions, type ActionLog, type ActionListener, } from './actions.js';
 export { defineJogakConfig, type JogakConfig } from './config.js';

package/dist/types.d.ts

@@ -209,38 +209,83 @@ export interface JogakPluginOptions {
      */
     readonly globalCss?: boolean | string | readonly string[];
     /**
-     * Preview 영역의 격리 모드 (알파.7 도입, 알파.7.1에서 default 변경).
+     * Preview 영역의 격리 모드 (알파.7 도입, 알파.8에서 default `'iframe'`로 변경).
      *
-     * 사용자 globalCss와 jogak chrome의 양방향 격리를 제공한다. 알파.7까지는
-     * 사용자 globalCss를 outer document에 inject하면서 jogak chrome utility를
-     * 무력화하는 결함이 있었으나 알파.7.1에서 main.tsx + ShadowMount가 모드별
-     * scope을 분리하도록 정정됨.
+     * 알파.8의 default `'iframe'`은 사용자 vite 인스턴스를 spawn하여 그 vite의 정상 client에
+     * iframe document를 마운트한다. 사용자 plugins(@tailwindcss/vite 등)이 그대로 작동하므로
+     * **사용자 컴포넌트가 사용자 디자인 시스템 그대로 보인다**. 동시에 outer document의
+     * jogak chrome은 iframe 외부라 사용자 css 영향 zero (양방향 격리).
      *
      * 모드:
-     * - `'shadow'` (default, 알파.7.1): Preview의 `[data-jogak-content]` 영역만
-     *   ShadowRoot에 마운트하고 사용자 globalCss를 ShadowRoot scope에만 inject.
-     *   outer document의 jogak chrome은 사용자 reset/preflight 침범을 받지 않는다.
-     *   **한계**: Radix UI(shadcn dialog/popover/tooltip 등)는 default Portal target이
-     *   `document.body` (shadow 외부) — portal 내용은 사용자 css 미적용. 회피:
-     *   사용자가 명시적으로 `<Portal container={shadowRootEl}>` 전달.
-     * - `'iframe'`: Preview를 별도 `<iframe>`에 로드. 완벽 격리. **한계**: jogak의
-     *   "single Vite, no iframe" 차별점과 상충하므로 명시적 opt-in 한정. HMR은
-     *   iframe도 Vite dev server module이라 작동하지만, args/이벤트 전달이
-     *   `contentWindow` 직접 접근 한 단계 추가됨.
-     * - `'none'` (back-compat opt-in): Preview는 jogak SPA와 동일 document에 마운트하고
-     *   사용자 globalCss를 outer document에 inject. 사용자 reset/preflight가 jogak
-     *   chrome에 침범 가능. 사용자가 침범을 의도적으로 허용하는 경우만 사용.
-     *
-     * @default 'shadow'
-     *
-     * @example 양방향 격리 (default — 미지정 시 적용)
-     * jogak({ globalCss: true })  // previewIsolation 'shadow' 자동 적용
-     *
-     * @example 사용자 reset이 chrome에도 영향을 주길 원하는 경우
-     * jogak({ globalCss: true, previewIsolation: 'none' })
+     * - `'iframe'` (default, 알파.8): Preview를 사용자 vite의 정상 client(iframe)에 마운트.
+     *   사용자 utility 정상 컴파일 + 사용자 globalCss 적용 + Radix Portal 정상 (iframe document.body).
+     *   chrome 침범 zero. cross-origin postMessage로 entry/args 전달.
+     *   `userVite` 옵션으로 spawn 동작 제어.
+     * - `'shadow'` (deprecated, 알파.9 부활 검토): Preview를 ShadowRoot에 마운트. 알파.8 v1에서는
+     *   사용자 vite 산출물을 shadow에 inject하는 통로가 미구현 — 사용자 utility 미적용 한계.
+     *   chrome 침범은 zero지만 사용자 컴포넌트 시각이 raw에 가까움.
+     * - `'none'` (deprecated, 알파.10 제거 검토): 사용자 globalCss를 outer document에 inject.
+     *   jogak chrome이 사용자 reset/preflight 영향을 받음 (back-compat).
+     *
+     * @default 'iframe'
+     *
+     * @example 사용자 vite 자동 spawn + iframe 모드 (default — 미지정 시 적용)
+     * jogak({ globalCss: true })  // previewIsolation 'iframe', 사용자 vite 자동 탐지
      *
-     * @example Radix portal까지 완벽 격리
-     * jogak({ globalCss: true, previewIsolation: 'iframe' })
+     * @example 사용자 vite 스폰 비활성 + 사용자 reset이 chrome에도 영향 (back-compat)
+     * jogak({ globalCss: true, previewIsolation: 'none' })
      */
     readonly previewIsolation?: 'none' | 'shadow' | 'iframe';
+    /**
+     * 알파.8 internal: 본 jogak() plugin이 사용자 vite scope의 preview-frame entry용으로
+     * 동작하는지. CLI의 spawnUserVite가 사용자 vite에 jogak()을 mergeConfig로 inject할 때
+     * `previewFrame: true`를 함께 설정한다.
+     *
+     * `previewFrame: true`일 때:
+     * - jogak SPA chrome 가상 모듈(`_jogakCodeTheme`/`_jogakPreviewIsolation`/`_jogakUserViteUrl`/
+     *   `_jogakMetas`) emit 비활성화
+     * - entry 가상 모듈(`virtual:jogak/entry/<slug>`)은 그대로 emit (preview-entry가 사용)
+     * - 사용자 측 vite plugins(@tailwindcss/vite 등)와 공존
+     *
+     * 사용자가 직접 설정하는 옵션이 아니다.
+     */
+    readonly previewFrame?: boolean;
+    /**
+     * 알파.8 internal: jogak SPA가 iframe src로 사용할 사용자 vite의 base URL
+     * (예: `http://localhost:5174`). CLI가 spawnUserVite 결과를 `runHost` 통해
+     * jogak() plugin에 전달한다.
+     *
+     * 빈 문자열 또는 미지정 시 기존 fallback (jogak SPA Vite scope의 preview-frame.tsx).
+     *
+     * 사용자가 직접 설정하는 옵션이 아니다.
+     */
+    readonly userViteUrl?: string;
+}
+/**
+ * 알파.8: 사용자 vite 인스턴스 spawn 옵션.
+ *
+ * jogak CLI는 사용자 cwd의 `vite.config.{ts,mts,js,mjs,cjs}`를 자동 탐지해 별도
+ * vite dev server를 spawn한다. iframe 모드의 src로 사용되어 사용자 컴포넌트가
+ * 사용자 vite plugins(@tailwindcss/vite, custom alias 등)의 정상 client에서
+ * 평가된다.
+ */
+export interface UserViteOptions {
+    /**
+     * 사용자 vite.config.ts 절대/상대 경로. 미지정 시 cwd에서 자동 탐지
+     * (`vite.config.ts` > `vite.config.mts` > `vite.config.js` > `vite.config.mjs` > `vite.config.cjs`).
+     */
+    readonly configFile?: string;
+    /**
+     * 사용자 vite dev server 포트. 미지정 시 0(free port).
+     */
+    readonly port?: number;
+    /**
+     * 사용자 vite dev server host. 미지정 시 'localhost'.
+     */
+    readonly host?: string | boolean;
+    /**
+     * 사용자 vite spawn을 비활성화. 알파.7.1 동등 fallback 동작
+     * (사용자 utility 미컴파일).
+     */
+    readonly disabled?: boolean;
 }

package/dist/vite/index.js

@@ -1,25 +1,94 @@
-"use strict";var K=Object.create;var L=Object.defineProperty;var q=Object.getOwnPropertyDescriptor;var W=Object.getOwnPropertyNames;var X=Object.getPrototypeOf,Y=Object.prototype.hasOwnProperty;var H=(e,t,s,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of W(t))!Y.call(e,a)&&a!==s&&L(e,a,{get:()=>t[a],enumerable:!(o=q(t,a))||o.enumerable});return e};var z=(e,t,s)=>(s=e!=null?K(X(e)):{},H(t||!e||!e.__esModule?L(s,"default",{value:e,enumerable:!0}):s,e));Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const f=require("node:path"),_=require("node:fs"),k=require("node:fs/promises"),R=require("../extractor-client-CiWszHel.cjs"),Q=["@jogak/core","@jogak/react","@jogak/web-components","@jogak/next"];async function P(e){try{const o=await k.stat(e);if(!o.isDirectory())return o.mtimeMs}catch{return 0}let t=0,s;try{s=await k.readdir(e)}catch{return 0}for(const o of s){const a=f.join(e,o);try{const l=await k.stat(a);if(l.isDirectory()){const y=await P(a);y>t&&(t=y)}else l.mtimeMs>t&&(t=l.mtimeMs)}catch{continue}}return t}async function Z(e){const t=f.resolve(e.root,"node_modules/.vite/deps");if(!_.existsSync(t))return{purged:!1};const s=f.join(t,"_metadata.json");if(!_.existsSync(s))return{purged:!1};let o;try{o=(await k.stat(s)).mtimeMs}catch(l){return e.logger.warn(`[jogak] cache validation: failed to stat _metadata.json (${l.message})`),{purged:!1}}const a=e.packages??Q;for(const l of a){const y=f.resolve(e.root,"node_modules",l,"dist");if(!_.existsSync(y))continue;let h;try{h=await P(y)}catch(w){e.logger.warn(`[jogak] cache validation: failed to walk ${l}/dist (${w.message})`);continue}if(h>o+1e3)try{return await k.rm(t,{recursive:!0,force:!0}),e.logger.info(`[jogak] vite deps cache invalidated (stale): ${l} dist newer than cache`),{purged:!0,reason:l}}catch(w){return e.logger.warn(`[jogak] cache validation: failed to purge ${t} (${w.message})`),{purged:!1}}}return{purged:!1}}const ee=["src/index.css","src/main.css","src/styles.css","src/styles/globals.css","src/styles/index.css","src/app/globals.css","src/global.css","src/app.css"];function te(e){for(const t of ee){const s=f.resolve(e,t);if(_.existsSync(s))return[s]}return[]}function re(e,t){if(e===void 0||e===!1)return[];if(e===!0)return te(t);if(typeof e=="string")return e.length>0?[f.resolve(t,e)]:[];const s=[];for(const o of e)typeof o=="string"&&o.length>0&&s.push(f.resolve(t,o));return s}function se(e){return e.replace(/\/\*[\s\S]*?\*\//g,"").replace(/^\s*\/\/.*$/gm,"")}function oe(e){if(_.existsSync(e))try{const t=_.readFileSync(e,"utf8");return JSON.parse(se(t))}catch{return}}function ne(e,t,s){if(!e.endsWith("/*")||!t.endsWith("/*"))return;const o=e.slice(0,-2),a=f.resolve(s,t.slice(0,-2));return[o,a]}function ae(e,t){var a,l;const s={},o=new Set([e,f.resolve(t,"tsconfig.app.json")]);for(const y of o){const h=oe(y);if(h===void 0)continue;const w=(a=h.compilerOptions)==null?void 0:a.paths;if(w===void 0)continue;const d=((l=h.compilerOptions)==null?void 0:l.baseUrl)??".",p=f.resolve(f.dirname(y),d);for(const[S,b]of Object.entries(w)){const x=b[0];if(x===void 0)continue;const C=ne(S,x,p);if(C===void 0)continue;const[A,r]=C;s[A]===void 0&&(s[A]=r)}}return s}const F="virtual:jogak",M="\0"+F,G="virtual:jogak/entry/",O="\0"+G,U="virtual:jogak/global-css",$="\0"+U;function ie(e){return Buffer.from(e,"utf8").toString("base64url")}function ce(e){return Buffer.from(e,"base64url").toString("utf8")}function D(e){return{title:e.title,jogakNamesKey:[...e.jogakNames].sort().join("|")}}function le(e,t){return e!==void 0&&e.title===t.title&&e.jogakNamesKey===t.jogakNamesKey}function ue(e={}){const{patterns:t=["src/**/*.jogak.ts","src/**/*.jogak.tsx"],codeTheme:s="vsDark"}=e,o=e.cwd,a=e.tsConfigFilePath,l=e.disableCacheValidation===!0,y=e.resolveAlias,h=e.globalCss,w=e.previewIsolation??"shadow";let d,p,S;const b=new Map,x=new Map,C=new Map;async function A(){const{glob:r}=await import("glob"),g=S??process.cwd(),n=(await r(t,{cwd:g,absolute:!0})).sort(),u=[];b.clear(),x.clear();for(const i of n){let v="";try{v=await k.readFile(i,"utf8")}catch{continue}let j={},c=null;if(p!==void 0){try{j=await p.extract(i)}catch{j={}}try{c=await p.extractMeta(i)}catch{c=null}}if(c===null)continue;const m=c.title;b.set(m,i),x.set(i,m);const T={id:m,title:c.title,jogakNames:c.jogakNames,autoArgTypes:j,userArgTypes:c.userArgTypes,source:v,filePath:i,metaExtras:c.metaExtras};C.set(i,D(T)),u.push({id:m,filePath:i,meta:T})}return u}return{name:"vite-plugin-jogak",config(){const r=o??process.cwd(),g=a??f.resolve(r,"tsconfig.json"),n=ae(g,r),u={};if(y!==void 0)for(const[v,j]of Object.entries(y))u[v]=f.resolve(r,j);const i={...n,...u};if(Object.keys(i).length!==0)return{resolve:{alias:i}}},async configResolved(r){S=o??r.root,r.command==="serve"&&!l&&await Z({root:r.root,logger:{info:n=>r.logger.info(n),warn:n=>r.logger.warn(n)}});const g=a??f.resolve(S,"tsconfig.json");p=_.existsSync(g)?R.createPropsExtractor({tsConfigFilePath:g}):R.createPropsExtractor()},configureServer(r){d=r},buildEnd(){p==null||p.releaseCache()},resolveId(r){if(r===F)return M;if(r===U)return $;if(r.startsWith(G))return"\0"+r},async load(r){if(r===$){const g=S??process.cwd(),n=re(h,g);return n.length===0?`// [jogak] globalCss not configured or no candidates found.
+"use strict";var Q=Object.create;var N=Object.defineProperty;var Z=Object.getOwnPropertyDescriptor;var ee=Object.getOwnPropertyNames;var te=Object.getPrototypeOf,re=Object.prototype.hasOwnProperty;var ne=(e,t,r,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let a of ee(t))!re.call(e,a)&&a!==r&&N(e,a,{get:()=>t[a],enumerable:!(o=Z(t,a))||o.enumerable});return e};var oe=(e,t,r)=>(r=e!=null?Q(te(e)):{},ne(t||!e||!e.__esModule?N(r,"default",{value:e,enumerable:!0}):r,e));Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const g=require("node:path"),E=require("node:fs"),I=require("node:fs/promises"),D=require("../extractor-client-CiWszHel.cjs"),ae=["@jogak/core","@jogak/react","@jogak/web-components","@jogak/next"];async function B(e){try{const o=await I.stat(e);if(!o.isDirectory())return o.mtimeMs}catch{return 0}let t=0,r;try{r=await I.readdir(e)}catch{return 0}for(const o of r){const a=g.join(e,o);try{const l=await I.stat(a);if(l.isDirectory()){const f=await B(a);f>t&&(t=f)}else l.mtimeMs>t&&(t=l.mtimeMs)}catch{continue}}return t}async function se(e){const t=g.resolve(e.root,"node_modules/.vite/deps");if(!E.existsSync(t))return{purged:!1};const r=g.join(t,"_metadata.json");if(!E.existsSync(r))return{purged:!1};let o;try{o=(await I.stat(r)).mtimeMs}catch(l){return e.logger.warn(`[jogak] cache validation: failed to stat _metadata.json (${l.message})`),{purged:!1}}const a=e.packages??ae;for(const l of a){const f=g.resolve(e.root,"node_modules",l,"dist");if(!E.existsSync(f))continue;let v;try{v=await B(f)}catch(w){e.logger.warn(`[jogak] cache validation: failed to walk ${l}/dist (${w.message})`);continue}if(v>o+1e3)try{return await I.rm(t,{recursive:!0,force:!0}),e.logger.info(`[jogak] vite deps cache invalidated (stale): ${l} dist newer than cache`),{purged:!0,reason:l}}catch(w){return e.logger.warn(`[jogak] cache validation: failed to purge ${t} (${w.message})`),{purged:!1}}}return{purged:!1}}const ie=["src/index.css","src/main.css","src/styles.css","src/styles/globals.css","src/styles/index.css","src/app/globals.css","src/global.css","src/app.css"];function ce(e){for(const t of ie){const r=g.resolve(e,t);if(E.existsSync(r))return[r]}return[]}function J(e,t){if(e===void 0||e===!1)return[];if(e===!0)return ce(t);if(typeof e=="string")return e.length>0?[g.resolve(t,e)]:[];const r=[];for(const o of e)typeof o=="string"&&o.length>0&&r.push(g.resolve(t,o));return r}function le(e){return e.replace(/\/\*[\s\S]*?\*\//g,"").replace(/^\s*\/\/.*$/gm,"")}function ue(e){if(E.existsSync(e))try{const t=E.readFileSync(e,"utf8");return JSON.parse(le(t))}catch{return}}function de(e,t,r){if(!e.endsWith("/*")||!t.endsWith("/*"))return;const o=e.slice(0,-2),a=g.resolve(r,t.slice(0,-2));return[o,a]}function ge(e,t){var a,l;const r={},o=new Set([e,g.resolve(t,"tsconfig.app.json")]);for(const f of o){const v=ue(f);if(v===void 0)continue;const w=(a=v.compilerOptions)==null?void 0:a.paths;if(w===void 0)continue;const T=((l=v.compilerOptions)==null?void 0:l.baseUrl)??".",R=g.resolve(g.dirname(f),T);for(const[d,y]of Object.entries(w)){const _=y[0];if(_===void 0)continue;const k=de(d,_,R);if(k===void 0)continue;const[S,b]=k;r[S]===void 0&&(r[S]=b)}}return r}const W="virtual:jogak",O="\0"+W,K="virtual:jogak/entry/",L="\0"+K,H="virtual:jogak/global-css",U="\0"+H,M="virtual:jogak/preview-entry",$="\0"+M,Y="virtual:jogak/preview-global-css",F="\0"+Y;function fe(e){return Buffer.from(e,"utf8").toString("base64url")}function me(e){return Buffer.from(e,"base64url").toString("utf8")}const pe="/__jogak_preview__/index.html";function ye(e){return{name:"vite-plugin-jogak-preview-frame",enforce:"pre",configureServer(t){t.middlewares.use((r,o,a)=>{if(r.url===void 0||r.url.split("?")[0]!==pe||r.method!=="GET")return a();const f=ve();t.transformIndexHtml(r.url,f).then(v=>{o.statusCode=200,o.setHeader("Content-Type","text/html; charset=utf-8"),o.end(v)}).catch(a)})},resolveId(t){if(t===M)return $;if(t===Y)return F},load(t){if(t===F){const r=J(e.globalCss,e.userRoot);return r.length===0?`// [jogak] preview-global-css: no candidates
 export {}
-`:`${n.map(i=>`import ${JSON.stringify(i)}`).join(`
+`:r.map(o=>`import ${JSON.stringify(o)}`).join(`
+`)+`
+export {}
+`}if(t===$)return he}}}function ve(){return`<!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>
+      html, body { margin: 0; padding: 0; }
+      #jogak-preview-root { display: block; }
+    </style>
+  </head>
+  <body>
+    <div id="jogak-preview-root"></div>
+    <script type="module" src="/@id/${M}"><\/script>
+  </body>
+</html>
+`}const he=`
+import { reactAdapter } from '@jogak/react'
+import { defaultRegistry } from '@jogak/core'
+import 'virtual:jogak'
+import 'virtual:jogak/preview-global-css'
+
+const rootEl = document.getElementById('jogak-preview-root')
+if (rootEl === null) throw new Error('[jogak] #jogak-preview-root not found')
+
+let currentContainer = null
+let currentArgs = {}
+let currentEntryId = null
+
+async function renderEntry(entryId, args) {
+  currentEntryId = entryId
+  currentArgs = args
+  const entry = await defaultRegistry.requestEntry(entryId)
+  if (currentContainer === null) {
+    currentContainer = document.createElement('div')
+    rootEl.replaceChildren(currentContainer)
+  }
+  reactAdapter.render(entry, args, currentContainer)
+}
+
+function unmount() {
+  if (currentContainer !== null) {
+    reactAdapter.unmount(currentContainer)
+    currentContainer = null
+    currentEntryId = null
+  }
+}
+
+window.addEventListener('message', (event) => {
+  const data = event.data
+  if (data == null || typeof data !== 'object') return
+  if (data.type === 'jogak:setProps') {
+    void renderEntry(data.entryId, data.args ?? {}).then(() => {
+      window.parent.postMessage({ type: 'jogak:rendered', entryId: data.entryId }, '*')
+    }).catch((err) => {
+      window.parent.postMessage({ type: 'jogak:error', message: String(err?.message ?? err) }, '*')
+    })
+  } else if (data.type === 'jogak:unmount') {
+    unmount()
+  }
+})
+
+window.parent.postMessage({ type: 'jogak:ready' }, '*')
+`;function G(e){return{title:e.title,jogakNamesKey:[...e.jogakNames].sort().join("|")}}function we(e,t){return e!==void 0&&e.title===t.title&&e.jogakNamesKey===t.jogakNamesKey}function je(e={}){const{patterns:t=["src/**/*.jogak.ts","src/**/*.jogak.tsx"],codeTheme:r="vsDark"}=e,o=e.cwd,a=e.tsConfigFilePath,l=e.disableCacheValidation===!0,f=e.resolveAlias,v=e.globalCss,w=e.previewIsolation??"iframe",T=e.previewFrame===!0,R=e.userViteUrl??"";let d,y,_;const k=new Map,S=new Map,b=new Map;async function P(){const{glob:n}=await import("glob"),m=_??process.cwd(),s=(await n(t,{cwd:m,absolute:!0})).sort(),u=[];k.clear(),S.clear();for(const i of s){let h="";try{h=await I.readFile(i,"utf8")}catch{continue}let j={},c=null;if(y!==void 0){try{j=await y.extract(i)}catch{j={}}try{c=await y.extractMeta(i)}catch{c=null}}if(c===null)continue;const p=c.title;k.set(p,i),S.set(i,p);const C={id:p,title:c.title,jogakNames:c.jogakNames,autoArgTypes:j,userArgTypes:c.userArgTypes,source:h,filePath:i,metaExtras:c.metaExtras};b.set(i,G(C)),u.push({id:p,filePath:i,meta:C})}return u}return{name:"vite-plugin-jogak",config(){const n=o??process.cwd(),m=a??g.resolve(n,"tsconfig.json"),s=ge(m,n),u={};if(f!==void 0)for(const[h,j]of Object.entries(f))u[h]=g.resolve(n,j);const i={...s,...u};if(Object.keys(i).length!==0)return{resolve:{alias:i}}},async configResolved(n){_=o??n.root,n.command==="serve"&&!l&&await se({root:n.root,logger:{info:s=>n.logger.info(s),warn:s=>n.logger.warn(s)}});const m=a??g.resolve(_,"tsconfig.json");y=E.existsSync(m)?D.createPropsExtractor({tsConfigFilePath:m}):D.createPropsExtractor()},configureServer(n){d=n},buildEnd(){y==null||y.releaseCache()},resolveId(n){if(n===W)return O;if(n===H)return U;if(n.startsWith(K))return"\0"+n},async load(n){if(n===U){const m=_??process.cwd(),s=J(v,m);return s.length===0?`// [jogak] globalCss not configured or no candidates found.
+export {}
+`:`${s.map(i=>`import ${JSON.stringify(i)}`).join(`
 `)}
 export {}
-`}if(r===M){const n=(await A()).map(u=>u.meta);return`import { defaultRegistry } from '@jogak/core'
+`}if(n===O){const s=(await P()).map(i=>i.meta),u=T?"":`
+export const _jogakCodeTheme = ${JSON.stringify(r)}
+export const _jogakPreviewIsolation = ${JSON.stringify(w)}
+export const _jogakUserViteUrl = ${JSON.stringify(R)}
+export const _jogakMetas = _metas
+`;return`import { defaultRegistry } from '@jogak/core'
 
 const _entryLoader = (slug) =>
   import(/* @vite-ignore */ '/@id/__x00__virtual:jogak/entry/' + slug)
 defaultRegistry.setEntryLoader((id) => {
-  const slug = ${de()}
+  const slug = ${_e()}
   return _entryLoader(slug(id))
 })
 
-const _metas = ${JSON.stringify(n)}
+const _metas = ${JSON.stringify(s)}
 
 for (const m of _metas) defaultRegistry.registerMeta(m)
-
-export const _jogakCodeTheme = ${JSON.stringify(s)}
-export const _jogakPreviewIsolation = ${JSON.stringify(w)}
-export const _jogakMetas = _metas
-`}if(r.startsWith(O)){const g=r.slice(O.length),n=ce(g);let u=b.get(n);return u===void 0&&(await A(),u=b.get(n)),u===void 0?`// [jogak] unknown entry id: ${JSON.stringify(n)}
+${u}`}if(n.startsWith(L)){const m=n.slice(L.length),s=me(m);let u=k.get(s);return u===void 0&&(await P(),u=k.get(s)),u===void 0?`// [jogak] unknown entry id: ${JSON.stringify(s)}
 export {}
 `:`import * as _user from ${JSON.stringify(u)}
 import { defaultRegistry } from '@jogak/core'
@@ -30,18 +99,18 @@ delete _named.default
 const _jogaks = Object.values(_named).filter(
   (v) => v !== null && typeof v === 'object' && typeof v.name === 'string'
 )
-defaultRegistry.hydrateEntry(${JSON.stringify(n)}, _jogaks, _meta?.component)
+defaultRegistry.hydrateEntry(${JSON.stringify(s)}, _jogaks, _meta?.component)
 
 if (import.meta.hot) {
   import.meta.hot.accept()
 }
 
 export {}
-`}},async handleHotUpdate({file:r,modules:g}){const n=/\.jogak\.(tsx?|jsx?)$/.test(r),u=/\.(tsx?|jsx?)$/.test(r)&&!n;if(!n&&!u||d===void 0||!n)return;const i=d.moduleGraph.getModuleById(M),v=x.get(r),j=v!==void 0?O+ie(v):void 0,c=j!==void 0?d.moduleGraph.getModuleById(j):void 0;let m=null,T={},E="";if(p!==void 0){try{m=await p.extractMeta(r)}catch{m=null}try{T=await p.extract(r)}catch{T={}}try{E=await k.readFile(r,"utf8")}catch{E=""}}if(m===null){i!==void 0&&d.moduleGraph.invalidateModule(i),c!==void 0&&d.moduleGraph.invalidateModule(c),d.ws.send({type:"full-reload"});return}const N=D(m),V=C.get(r),J=le(V,N);if(C.set(r,N),!J||v===void 0){i!==void 0&&d.moduleGraph.invalidateModule(i),c!==void 0&&d.moduleGraph.invalidateModule(c),d.ws.send({type:"full-reload"});return}const B={id:v,title:m.title,jogakNames:m.jogakNames,autoArgTypes:T,userArgTypes:m.userArgTypes,source:E,filePath:r,metaExtras:m.metaExtras};c!==void 0&&d.moduleGraph.invalidateModule(c),d.ws.send({type:"custom",event:"jogak:meta-update",data:{id:v,meta:B}});const I=[...g];return c!==void 0&&!I.includes(c)&&I.push(c),I}}}function de(){return`(rawId) => {
+`}},async handleHotUpdate({file:n,modules:m}){const s=/\.jogak\.(tsx?|jsx?)$/.test(n),u=/\.(tsx?|jsx?)$/.test(n)&&!s;if(!s&&!u||d===void 0||!s)return;const i=d.moduleGraph.getModuleById(O),h=S.get(n),j=h!==void 0?L+fe(h):void 0,c=j!==void 0?d.moduleGraph.getModuleById(j):void 0;let p=null,C={},A="";if(y!==void 0){try{p=await y.extractMeta(n)}catch{p=null}try{C=await y.extract(n)}catch{C={}}try{A=await I.readFile(n,"utf8")}catch{A=""}}if(p===null){i!==void 0&&d.moduleGraph.invalidateModule(i),c!==void 0&&d.moduleGraph.invalidateModule(c),d.ws.send({type:"full-reload"});return}const V=G(p),X=b.get(n),q=we(X,V);if(b.set(n,V),!q||h===void 0){i!==void 0&&d.moduleGraph.invalidateModule(i),c!==void 0&&d.moduleGraph.invalidateModule(c),d.ws.send({type:"full-reload"});return}const z={id:h,title:p.title,jogakNames:p.jogakNames,autoArgTypes:C,userArgTypes:p.userArgTypes,source:A,filePath:n,metaExtras:p.metaExtras};c!==void 0&&d.moduleGraph.invalidateModule(c),d.ws.send({type:"custom",event:"jogak:meta-update",data:{id:h,meta:z}});const x=[...m];return c!==void 0&&!x.includes(c)&&x.push(c),x}}}function _e(){return`(rawId) => {
     if (typeof Buffer !== 'undefined') return Buffer.from(rawId, 'utf8').toString('base64url')
     // 브라우저 폴백: btoa는 binary string 기준이라 UTF-8을 한번 인코딩해야 한다.
     const enc = new TextEncoder().encode(rawId)
     let bin = ''
     for (let i = 0; i < enc.length; i++) bin += String.fromCharCode(enc[i])
     return btoa(bin).replace(/\\+/g, '-').replace(/\\//g, '_').replace(/=+$/, '')
-  }`}exports.jogak=ue;
+  }`}exports.jogak=je;exports.jogakPreviewFramePlugin=ye;

package/dist/vite/index.mjs

@@ -1,83 +1,83 @@
-import { resolve as y, join as P, dirname as W } from "node:path";
-import { existsSync as T, readFileSync as X } from "node:fs";
-import { stat as O, rm as Y, readdir as q, readFile as L } from "node:fs/promises";
-import { c as R } from "../extractor-client-CReBed7x.js";
-const H = [
+import { resolve as y, join as B, dirname as q } from "node:path";
+import { existsSync as S, readFileSync as tt } from "node:fs";
+import { stat as x, rm as et, readdir as rt, readFile as P } from "node:fs/promises";
+import { c as D } from "../extractor-client-CReBed7x.js";
+const nt = [
   "@jogak/core",
   "@jogak/react",
   "@jogak/web-components",
   "@jogak/next"
 ];
-async function F(t) {
+async function J(t) {
   try {
-    const a = await O(t);
-    if (!a.isDirectory())
-      return a.mtimeMs;
+    const o = await x(t);
+    if (!o.isDirectory())
+      return o.mtimeMs;
   } catch {
     return 0;
   }
-  let o = 0, s;
+  let e = 0, n;
   try {
-    s = await q(t);
+    n = await rt(t);
   } catch {
     return 0;
   }
-  for (const a of s) {
-    const g = P(t, a);
+  for (const o of n) {
+    const c = B(t, o);
     try {
-      const c = await O(g);
-      if (c.isDirectory()) {
-        const p = await F(g);
-        p > o && (o = p);
-      } else c.mtimeMs > o && (o = c.mtimeMs);
+      const l = await x(c);
+      if (l.isDirectory()) {
+        const g = await J(c);
+        g > e && (e = g);
+      } else l.mtimeMs > e && (e = l.mtimeMs);
     } catch {
       continue;
     }
   }
-  return o;
+  return e;
 }
-async function z(t) {
-  const o = y(t.root, "node_modules/.vite/deps");
-  if (!T(o))
+async function ot(t) {
+  const e = y(t.root, "node_modules/.vite/deps");
+  if (!S(e))
     return { purged: !1 };
-  const s = P(o, "_metadata.json");
-  if (!T(s))
+  const n = B(e, "_metadata.json");
+  if (!S(n))
     return { purged: !1 };
-  let a;
+  let o;
   try {
-    a = (await O(s)).mtimeMs;
-  } catch (c) {
+    o = (await x(n)).mtimeMs;
+  } catch (l) {
     return t.logger.warn(
-      `[jogak] cache validation: failed to stat _metadata.json (${c.message})`
+      `[jogak] cache validation: failed to stat _metadata.json (${l.message})`
     ), { purged: !1 };
   }
-  const g = t.packages ?? H;
-  for (const c of g) {
-    const p = y(t.root, "node_modules", c, "dist");
-    if (!T(p)) continue;
-    let h;
+  const c = t.packages ?? nt;
+  for (const l of c) {
+    const g = y(t.root, "node_modules", l, "dist");
+    if (!S(g)) continue;
+    let v;
     try {
-      h = await F(p);
+      v = await J(g);
     } catch (w) {
       t.logger.warn(
-        `[jogak] cache validation: failed to walk ${c}/dist (${w.message})`
+        `[jogak] cache validation: failed to walk ${l}/dist (${w.message})`
       );
       continue;
     }
-    if (h > a + 1e3)
+    if (v > o + 1e3)
       try {
-        return await Y(o, { recursive: !0, force: !0 }), t.logger.info(
-          `[jogak] vite deps cache invalidated (stale): ${c} dist newer than cache`
-        ), { purged: !0, reason: c };
+        return await et(e, { recursive: !0, force: !0 }), t.logger.info(
+          `[jogak] vite deps cache invalidated (stale): ${l} dist newer than cache`
+        ), { purged: !0, reason: l };
       } catch (w) {
         return t.logger.warn(
-          `[jogak] cache validation: failed to purge ${o} (${w.message})`
+          `[jogak] cache validation: failed to purge ${e} (${w.message})`
         ), { purged: !1 };
       }
   }
   return { purged: !1 };
 }
-const Q = [
+const at = [
   "src/index.css",
   "src/main.css",
   "src/styles.css",
@@ -87,125 +87,225 @@ const Q = [
   "src/global.css",
   "src/app.css"
 ];
-function Z(t) {
-  for (const o of Q) {
-    const s = y(t, o);
-    if (T(s)) return [s];
+function st(t) {
+  for (const e of at) {
+    const n = y(t, e);
+    if (S(n)) return [n];
   }
   return [];
 }
-function tt(t, o) {
+function W(t, e) {
   if (t === void 0 || t === !1) return [];
-  if (t === !0) return Z(o);
+  if (t === !0) return st(e);
   if (typeof t == "string")
-    return t.length > 0 ? [y(o, t)] : [];
-  const s = [];
-  for (const a of t)
-    typeof a == "string" && a.length > 0 && s.push(y(o, a));
-  return s;
+    return t.length > 0 ? [y(e, t)] : [];
+  const n = [];
+  for (const o of t)
+    typeof o == "string" && o.length > 0 && n.push(y(e, o));
+  return n;
 }
-function et(t) {
+function it(t) {
   return t.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
 }
-function ot(t) {
-  if (T(t))
+function ct(t) {
+  if (S(t))
     try {
-      const o = X(t, "utf8");
-      return JSON.parse(et(o));
+      const e = tt(t, "utf8");
+      return JSON.parse(it(e));
     } catch {
       return;
     }
 }
-function rt(t, o, s) {
-  if (!t.endsWith("/*") || !o.endsWith("/*")) return;
-  const a = t.slice(0, -2), g = y(s, o.slice(0, -2));
-  return [a, g];
+function lt(t, e, n) {
+  if (!t.endsWith("/*") || !e.endsWith("/*")) return;
+  const o = t.slice(0, -2), c = y(n, e.slice(0, -2));
+  return [o, c];
 }
-function st(t, o) {
-  var g, c;
-  const s = {}, a = /* @__PURE__ */ new Set([
+function ut(t, e) {
+  var c, l;
+  const n = {}, o = /* @__PURE__ */ new Set([
     t,
-    y(o, "tsconfig.app.json")
+    y(e, "tsconfig.app.json")
   ]);
-  for (const p of a) {
-    const h = ot(p);
-    if (h === void 0) continue;
-    const w = (g = h.compilerOptions) == null ? void 0 : g.paths;
+  for (const g of o) {
+    const v = ct(g);
+    if (v === void 0) continue;
+    const w = (c = v.compilerOptions) == null ? void 0 : c.paths;
     if (w === void 0) continue;
-    const u = ((c = h.compilerOptions) == null ? void 0 : c.baseUrl) ?? ".", m = y(W(p), u);
-    for (const [_, k] of Object.entries(w)) {
-      const S = k[0];
-      if (S === void 0) continue;
-      const b = rt(_, S, m);
-      if (b === void 0) continue;
-      const [A, e] = b;
-      s[A] === void 0 && (s[A] = e);
+    const b = ((l = v.compilerOptions) == null ? void 0 : l.baseUrl) ?? ".", T = y(q(g), b);
+    for (const [d, p] of Object.entries(w)) {
+      const _ = p[0];
+      if (_ === void 0) continue;
+      const k = lt(d, _, T);
+      if (k === void 0) continue;
+      const [E, C] = k;
+      n[E] === void 0 && (n[E] = C);
     }
   }
-  return s;
+  return n;
 }
-const G = "virtual:jogak", E = "\0" + G, U = "virtual:jogak/entry/", M = "\0" + U, V = "virtual:jogak/global-css", $ = "\0" + V;
-function at(t) {
+const K = "virtual:jogak", L = "\0" + K, H = "virtual:jogak/entry/", O = "\0" + H, Y = "virtual:jogak/global-css", U = "\0" + Y, M = "virtual:jogak/preview-entry", $ = "\0" + M, X = "virtual:jogak/preview-global-css", F = "\0" + X;
+function dt(t) {
   return Buffer.from(t, "utf8").toString("base64url");
 }
-function nt(t) {
+function gt(t) {
   return Buffer.from(t, "base64url").toString("utf8");
 }
-function D(t) {
+const ft = "/__jogak_preview__/index.html";
+function kt(t) {
+  return {
+    name: "vite-plugin-jogak-preview-frame",
+    enforce: "pre",
+    configureServer(e) {
+      e.middlewares.use((n, o, c) => {
+        if (n.url === void 0 || n.url.split("?")[0] !== ft || n.method !== "GET") return c();
+        const g = mt();
+        e.transformIndexHtml(n.url, g).then((v) => {
+          o.statusCode = 200, o.setHeader("Content-Type", "text/html; charset=utf-8"), o.end(v);
+        }).catch(c);
+      });
+    },
+    resolveId(e) {
+      if (e === M) return $;
+      if (e === X) return F;
+    },
+    load(e) {
+      if (e === F) {
+        const n = W(t.globalCss, t.userRoot);
+        return n.length === 0 ? `// [jogak] preview-global-css: no candidates
+export {}
+` : n.map((o) => `import ${JSON.stringify(o)}`).join(`
+`) + `
+export {}
+`;
+      }
+      if (e === $)
+        return pt;
+    }
+  };
+}
+function mt() {
+  return `<!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>
+      html, body { margin: 0; padding: 0; }
+      #jogak-preview-root { display: block; }
+    </style>
+  </head>
+  <body>
+    <div id="jogak-preview-root"></div>
+    <script type="module" src="/@id/${M}"><\/script>
+  </body>
+</html>
+`;
+}
+const pt = `
+import { reactAdapter } from '@jogak/react'
+import { defaultRegistry } from '@jogak/core'
+import 'virtual:jogak'
+import 'virtual:jogak/preview-global-css'
+
+const rootEl = document.getElementById('jogak-preview-root')
+if (rootEl === null) throw new Error('[jogak] #jogak-preview-root not found')
+
+let currentContainer = null
+let currentArgs = {}
+let currentEntryId = null
+
+async function renderEntry(entryId, args) {
+  currentEntryId = entryId
+  currentArgs = args
+  const entry = await defaultRegistry.requestEntry(entryId)
+  if (currentContainer === null) {
+    currentContainer = document.createElement('div')
+    rootEl.replaceChildren(currentContainer)
+  }
+  reactAdapter.render(entry, args, currentContainer)
+}
+
+function unmount() {
+  if (currentContainer !== null) {
+    reactAdapter.unmount(currentContainer)
+    currentContainer = null
+    currentEntryId = null
+  }
+}
+
+window.addEventListener('message', (event) => {
+  const data = event.data
+  if (data == null || typeof data !== 'object') return
+  if (data.type === 'jogak:setProps') {
+    void renderEntry(data.entryId, data.args ?? {}).then(() => {
+      window.parent.postMessage({ type: 'jogak:rendered', entryId: data.entryId }, '*')
+    }).catch((err) => {
+      window.parent.postMessage({ type: 'jogak:error', message: String(err?.message ?? err) }, '*')
+    })
+  } else if (data.type === 'jogak:unmount') {
+    unmount()
+  }
+})
+
+window.parent.postMessage({ type: 'jogak:ready' }, '*')
+`;
+function G(t) {
   return {
     title: t.title,
     jogakNamesKey: [...t.jogakNames].sort().join("|")
   };
 }
-function it(t, o) {
-  return t !== void 0 && t.title === o.title && t.jogakNamesKey === o.jogakNamesKey;
+function yt(t, e) {
+  return t !== void 0 && t.title === e.title && t.jogakNamesKey === e.jogakNamesKey;
 }
-function gt(t = {}) {
+function Et(t = {}) {
   const {
-    patterns: o = ["src/**/*.jogak.ts", "src/**/*.jogak.tsx"],
-    codeTheme: s = "vsDark"
-  } = t, a = t.cwd, g = t.tsConfigFilePath, c = t.disableCacheValidation === !0, p = t.resolveAlias, h = t.globalCss, w = t.previewIsolation ?? "shadow";
-  let u, m, _;
-  const k = /* @__PURE__ */ new Map(), S = /* @__PURE__ */ new Map(), b = /* @__PURE__ */ new Map();
-  async function A() {
-    const { glob: e } = await import("glob"), d = _ ?? process.cwd(), r = (await e(o, { cwd: d, absolute: !0 })).sort(), l = [];
-    k.clear(), S.clear();
-    for (const n of r) {
-      let v = "";
+    patterns: e = ["src/**/*.jogak.ts", "src/**/*.jogak.tsx"],
+    codeTheme: n = "vsDark"
+  } = t, o = t.cwd, c = t.tsConfigFilePath, l = t.disableCacheValidation === !0, g = t.resolveAlias, v = t.globalCss, w = t.previewIsolation ?? "iframe", b = t.previewFrame === !0, T = t.userViteUrl ?? "";
+  let d, p, _;
+  const k = /* @__PURE__ */ new Map(), E = /* @__PURE__ */ new Map(), C = /* @__PURE__ */ new Map();
+  async function V() {
+    const { glob: r } = await import("glob"), f = _ ?? process.cwd(), a = (await r(e, { cwd: f, absolute: !0 })).sort(), u = [];
+    k.clear(), E.clear();
+    for (const s of a) {
+      let h = "";
       try {
-        v = await L(n, "utf8");
+        h = await P(s, "utf8");
       } catch {
         continue;
       }
       let j = {}, i = null;
-      if (m !== void 0) {
+      if (p !== void 0) {
         try {
-          j = await m.extract(n);
+          j = await p.extract(s);
         } catch {
           j = {};
         }
         try {
-          i = await m.extractMeta(n);
+          i = await p.extractMeta(s);
         } catch {
           i = null;
         }
       }
       if (i === null) continue;
-      const f = i.title;
-      k.set(f, n), S.set(n, f);
-      const C = {
-        id: f,
+      const m = i.title;
+      k.set(m, s), E.set(s, m);
+      const I = {
+        id: m,
         title: i.title,
         jogakNames: i.jogakNames,
         autoArgTypes: j,
         userArgTypes: i.userArgTypes,
-        source: v,
-        filePath: n,
+        source: h,
+        filePath: s,
         metaExtras: i.metaExtras
       };
-      b.set(n, D(C)), l.push({ id: f, filePath: n, meta: C });
+      C.set(s, G(I)), u.push({ id: m, filePath: s, meta: I });
     }
-    return l;
+    return u;
   }
   return {
     name: "vite-plugin-jogak",
@@ -220,77 +320,78 @@ function gt(t = {}) {
      * 우선순위: `options.resolveAlias` (명시) > tsconfig 자동 추출.
      */
     config() {
-      const e = a ?? process.cwd(), d = g ?? y(e, "tsconfig.json"), r = st(d, e), l = {};
-      if (p !== void 0)
-        for (const [v, j] of Object.entries(p))
-          l[v] = y(e, j);
-      const n = { ...r, ...l };
-      if (Object.keys(n).length !== 0)
+      const r = o ?? process.cwd(), f = c ?? y(r, "tsconfig.json"), a = ut(f, r), u = {};
+      if (g !== void 0)
+        for (const [h, j] of Object.entries(g))
+          u[h] = y(r, j);
+      const s = { ...a, ...u };
+      if (Object.keys(s).length !== 0)
         return {
-          resolve: { alias: n }
+          resolve: { alias: s }
         };
     },
-    async configResolved(e) {
-      _ = a ?? e.root, e.command === "serve" && !c && await z({
-        root: e.root,
+    async configResolved(r) {
+      _ = o ?? r.root, r.command === "serve" && !l && await ot({
+        root: r.root,
         logger: {
-          info: (r) => e.logger.info(r),
-          warn: (r) => e.logger.warn(r)
+          info: (a) => r.logger.info(a),
+          warn: (a) => r.logger.warn(a)
         }
       });
-      const d = g ?? y(_, "tsconfig.json");
-      m = T(d) ? R({ tsConfigFilePath: d }) : R();
+      const f = c ?? y(_, "tsconfig.json");
+      p = S(f) ? D({ tsConfigFilePath: f }) : D();
     },
-    configureServer(e) {
-      u = e;
+    configureServer(r) {
+      d = r;
     },
     buildEnd() {
-      m == null || m.releaseCache();
+      p == null || p.releaseCache();
     },
-    resolveId(e) {
-      if (e === G)
-        return E;
-      if (e === V)
-        return $;
-      if (e.startsWith(U))
-        return "\0" + e;
+    resolveId(r) {
+      if (r === K)
+        return L;
+      if (r === Y)
+        return U;
+      if (r.startsWith(H))
+        return "\0" + r;
     },
-    async load(e) {
-      if (e === $) {
-        const d = _ ?? process.cwd(), r = tt(h, d);
-        return r.length === 0 ? `// [jogak] globalCss not configured or no candidates found.
+    async load(r) {
+      if (r === U) {
+        const f = _ ?? process.cwd(), a = W(v, f);
+        return a.length === 0 ? `// [jogak] globalCss not configured or no candidates found.
 export {}
-` : `${r.map((n) => `import ${JSON.stringify(n)}`).join(`
+` : `${a.map((s) => `import ${JSON.stringify(s)}`).join(`
 `)}
 export {}
 `;
       }
-      if (e === E) {
-        const r = (await A()).map((l) => l.meta);
+      if (r === L) {
+        const a = (await V()).map((s) => s.meta), u = b ? "" : `
+export const _jogakCodeTheme = ${JSON.stringify(n)}
+export const _jogakPreviewIsolation = ${JSON.stringify(w)}
+export const _jogakUserViteUrl = ${JSON.stringify(T)}
+export const _jogakMetas = _metas
+`;
         return `import { defaultRegistry } from '@jogak/core'
 
 const _entryLoader = (slug) =>
   import(/* @vite-ignore */ '/@id/__x00__virtual:jogak/entry/' + slug)
 defaultRegistry.setEntryLoader((id) => {
-  const slug = ${ct()}
+  const slug = ${vt()}
   return _entryLoader(slug(id))
 })
 
-const _metas = ${JSON.stringify(r)}
+const _metas = ${JSON.stringify(a)}
 
 for (const m of _metas) defaultRegistry.registerMeta(m)
-
-export const _jogakCodeTheme = ${JSON.stringify(s)}
-export const _jogakPreviewIsolation = ${JSON.stringify(w)}
-export const _jogakMetas = _metas
-`;
+${u}`;
       }
-      if (e.startsWith(M)) {
-        const d = e.slice(M.length), r = nt(d);
-        let l = k.get(r);
-        return l === void 0 && (await A(), l = k.get(r)), l === void 0 ? `// [jogak] unknown entry id: ${JSON.stringify(r)}
+      if (r.startsWith(O)) {
+        const f = r.slice(O.length), a = gt(f);
+        let u = k.get(a);
+        return u === void 0 && (await V(), u = k.get(a)), u === void 0 ? `// [jogak] unknown entry id: ${JSON.stringify(a)}
 export {}
-` : `import * as _user from ${JSON.stringify(l)}
+` : `import * as _user from ${JSON.stringify(u)}
 import { defaultRegistry } from '@jogak/core'
 
 const _meta = _user.default
@@ -299,7 +400,7 @@ delete _named.default
 const _jogaks = Object.values(_named).filter(
   (v) => v !== null && typeof v === 'object' && typeof v.name === 'string'
 )
-defaultRegistry.hydrateEntry(${JSON.stringify(r)}, _jogaks, _meta?.component)
+defaultRegistry.hydrateEntry(${JSON.stringify(a)}, _jogaks, _meta?.component)
 
 if (import.meta.hot) {
   import.meta.hot.accept()
@@ -309,60 +410,60 @@ export {}
 `;
       }
     },
-    async handleHotUpdate({ file: e, modules: d }) {
-      const r = /\.jogak\.(tsx?|jsx?)$/.test(e), l = /\.(tsx?|jsx?)$/.test(e) && !r;
-      if (!r && !l || u === void 0 || !r) return;
-      const n = u.moduleGraph.getModuleById(
-        E
-      ), v = S.get(e), j = v !== void 0 ? M + at(v) : void 0, i = j !== void 0 ? u.moduleGraph.getModuleById(j) : void 0;
-      let f = null, C = {}, I = "";
-      if (m !== void 0) {
+    async handleHotUpdate({ file: r, modules: f }) {
+      const a = /\.jogak\.(tsx?|jsx?)$/.test(r), u = /\.(tsx?|jsx?)$/.test(r) && !a;
+      if (!a && !u || d === void 0 || !a) return;
+      const s = d.moduleGraph.getModuleById(
+        L
+      ), h = E.get(r), j = h !== void 0 ? O + dt(h) : void 0, i = j !== void 0 ? d.moduleGraph.getModuleById(j) : void 0;
+      let m = null, I = {}, R = "";
+      if (p !== void 0) {
         try {
-          f = await m.extractMeta(e);
+          m = await p.extractMeta(r);
         } catch {
-          f = null;
+          m = null;
         }
         try {
-          C = await m.extract(e);
+          I = await p.extract(r);
         } catch {
-          C = {};
+          I = {};
         }
         try {
-          I = await L(e, "utf8");
+          R = await P(r, "utf8");
         } catch {
-          I = "";
+          R = "";
         }
       }
-      if (f === null) {
-        n !== void 0 && u.moduleGraph.invalidateModule(n), i !== void 0 && u.moduleGraph.invalidateModule(i), u.ws.send({ type: "full-reload" });
+      if (m === null) {
+        s !== void 0 && d.moduleGraph.invalidateModule(s), i !== void 0 && d.moduleGraph.invalidateModule(i), d.ws.send({ type: "full-reload" });
         return;
       }
-      const N = D(f), J = b.get(e), B = it(J, N);
-      if (b.set(e, N), !B || v === void 0) {
-        n !== void 0 && u.moduleGraph.invalidateModule(n), i !== void 0 && u.moduleGraph.invalidateModule(i), u.ws.send({ type: "full-reload" });
+      const N = G(m), z = C.get(r), Q = yt(z, N);
+      if (C.set(r, N), !Q || h === void 0) {
+        s !== void 0 && d.moduleGraph.invalidateModule(s), i !== void 0 && d.moduleGraph.invalidateModule(i), d.ws.send({ type: "full-reload" });
         return;
       }
-      const K = {
-        id: v,
-        title: f.title,
-        jogakNames: f.jogakNames,
-        autoArgTypes: C,
-        userArgTypes: f.userArgTypes,
-        source: I,
-        filePath: e,
-        metaExtras: f.metaExtras
+      const Z = {
+        id: h,
+        title: m.title,
+        jogakNames: m.jogakNames,
+        autoArgTypes: I,
+        userArgTypes: m.userArgTypes,
+        source: R,
+        filePath: r,
+        metaExtras: m.metaExtras
       };
-      i !== void 0 && u.moduleGraph.invalidateModule(i), u.ws.send({
+      i !== void 0 && d.moduleGraph.invalidateModule(i), d.ws.send({
         type: "custom",
         event: "jogak:meta-update",
-        data: { id: v, meta: K }
+        data: { id: h, meta: Z }
       });
-      const x = [...d];
-      return i !== void 0 && !x.includes(i) && x.push(i), x;
+      const A = [...f];
+      return i !== void 0 && !A.includes(i) && A.push(i), A;
     }
   };
 }
-function ct() {
+function vt() {
   return `(rawId) => {
     if (typeof Buffer !== 'undefined') return Buffer.from(rawId, 'utf8').toString('base64url')
     // 브라우저 폴백: btoa는 binary string 기준이라 UTF-8을 한번 인코딩해야 한다.
@@ -373,5 +474,6 @@ function ct() {
   }`;
 }
 export {
-  gt as jogak
+  Et as jogak,
+  kt as jogakPreviewFramePlugin
 };

package/dist/vite/plugin.d.ts

@@ -1,3 +1,4 @@
 import { Plugin } from 'vite';
 import { JogakPluginOptions } from '../types.js';
 export declare function jogak(options?: JogakPluginOptions): Plugin;
+export { jogakPreviewFramePlugin, type JogakPreviewFramePluginOptions, } from './preview-frame-plugin.js';

package/dist/vite/preview-frame-plugin.d.ts

@@ -0,0 +1,21 @@
+import { Plugin } from 'vite';
+import { JogakPluginOptions } from '../types.js';
+/**
+ * 알파.8: 사용자 vite scope에서 preview-frame iframe entry를 emit하는 plugin.
+ *
+ * jogak CLI의 `spawnUserVite`가 사용자 vite.config.ts에 `mergeConfig`로 자동 inject
+ * — 사용자가 직접 등록할 필요 없음.
+ *
+ * 책임:
+ * 1. `/__jogak_preview__/index.html` middleware: jogak preview-entry를 로드하는 HTML 응답
+ * 2. `virtual:jogak/preview-entry` 가상 모듈: postMessage 리스너 + reactAdapter.render
+ * 3. `virtual:jogak/preview-global-css` 가상 모듈: 사용자 globalCss를 사용자 vite의
+ *    `@tailwindcss/vite` 등 정상 css 파이프라인을 통해 컴파일
+ */
+export interface JogakPreviewFramePluginOptions {
+    /** 사용자 프로젝트 root (cwd). globalCss 자동 탐지 base. */
+    readonly userRoot: string;
+    /** 사용자 globalCss (jogak.config.ts의 globalCss와 동일 의미). */
+    readonly globalCss?: JogakPluginOptions['globalCss'];
+}
+export declare function jogakPreviewFramePlugin(options: JogakPreviewFramePluginOptions): Plugin;

package/dist/vite/virtual-ids.d.ts

@@ -18,5 +18,19 @@ export declare const RESOLVED_VIRTUAL_ENTRY_PREFIX: string;
 /** Global css 모듈 — 사용자 globalCss를 import한다 (알파.6, opt-in). */
 export declare const VIRTUAL_GLOBAL_CSS_ID = "virtual:jogak/global-css";
 export declare const RESOLVED_VIRTUAL_GLOBAL_CSS_ID: string;
+/**
+ * Preview frame entry (알파.8) — 사용자 vite scope의 iframe entry.
+ * jogakPreviewFramePlugin이 emit. 사용자 vite의 module graph에 포함되어
+ * 사용자 plugins(@tailwindcss/vite 등)가 정상 처리.
+ */
+export declare const VIRTUAL_PREVIEW_ENTRY_ID = "virtual:jogak/preview-entry";
+export declare const RESOLVED_VIRTUAL_PREVIEW_ENTRY_ID: string;
+/**
+ * Preview-scope의 사용자 globalCss (알파.8) — 알파.6의 `virtual:jogak/global-css`는
+ * jogak SPA scope. 본 모듈은 사용자 vite scope의 preview-frame entry용.
+ * jogakPreviewFramePlugin이 emit.
+ */
+export declare const VIRTUAL_PREVIEW_GLOBAL_CSS_ID = "virtual:jogak/preview-global-css";
+export declare const RESOLVED_VIRTUAL_PREVIEW_GLOBAL_CSS_ID: string;
 export declare function idToSlug(id: string): string;
 export declare function slugToId(slug: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jogak/core",
-  "version": "0.1.0-alpha.7.1",
+  "version": "0.1.0-alpha.8",
   "description": "Core types, registry, and Vite plugin for Jogak — a lightweight Storybook alternative.",
   "keywords": [
     "jogak",