@jogak/core 0.1.0-alpha.1 → 0.1.0-alpha.10.2

package/dist/renderers/react/index.mjs

@@ -0,0 +1,101 @@
+import { createElement as l, useContext as S, createContext as b, useState as y, useEffect as E, useMemo as f, useSyncExternalStore as R, useCallback as h } from "react";
+import { createRoot as j } from "react-dom/client";
+import { i as v } from "../../actions-BvvUNlgo.js";
+import { jsx as w } from "react/jsx-runtime";
+import { d as g } from "../../registry-CnBX6XxF.js";
+const P = {
+  framework: "react",
+  render(t, e, n) {
+    const r = t.meta.component, o = v(e, t.meta.argTypes ?? {}), s = n._jogakRoot;
+    if (s !== void 0)
+      s.render(l(r, o));
+    else {
+      const a = j(n);
+      a.render(l(r, o)), n._jogakRoot = a;
+    }
+  },
+  unmount(t) {
+    const e = t._jogakRoot;
+    e == null || e.unmount(), delete t._jogakRoot;
+  }
+}, d = b(g);
+function $({ registry: t = g, children: e }) {
+  return /* @__PURE__ */ w(d.Provider, { value: t, children: e });
+}
+function p() {
+  return S(d);
+}
+function m(t, e) {
+  const n = t.getEntryState(e);
+  if (n === "unknown")
+    return { status: "unknown" };
+  if (n === "hydrated") {
+    const o = t.get(e);
+    return o === void 0 ? {
+      status: "error",
+      error: new Error(`[jogak] inconsistent registry state for id "${e}"`)
+    } : { status: "ready", entry: o };
+  }
+  const r = x(t, e);
+  return r === void 0 ? {
+    status: "error",
+    error: new Error(`[jogak] meta missing for id "${e}"`)
+  } : { status: "loading", meta: r };
+}
+function x(t, e) {
+  for (const n of t.getAllMeta())
+    if (n.id === e) return n;
+}
+function G(t) {
+  const e = p(), [n, r] = y(
+    () => m(e, t)
+  );
+  return E(() => {
+    let o = !1, s = null;
+    const a = () => {
+      if (o) return;
+      const c = m(e, t);
+      r(c), c.status === "loading" && s !== "loading" ? (s = "loading", e.requestEntry(t).catch((i) => {
+        if (o) return;
+        const k = i instanceof Error ? i : new Error(String(i));
+        r({ status: "error", error: k });
+      })) : s = c.status;
+    };
+    a();
+    const u = e.subscribe(a);
+    return () => {
+      o = !0, u();
+    };
+  }, [e, t]), n;
+}
+function M(t) {
+  return (e) => t.subscribe(e);
+}
+function C(t) {
+  let e = null, n = null, r = null;
+  return () => {
+    const o = t.getAllMeta(), s = t.getMetaTree();
+    return r !== null && o === e && s === n || (e = o, n = s, r = { metas: o, metaTree: s }), r;
+  };
+}
+function J() {
+  const t = p(), e = f(() => M(t), [t]), n = f(() => C(t), [t]), r = R(e, n, n), o = h(
+    (s) => {
+      const a = s.trim().toLowerCase();
+      return a.length === 0 ? r.metas : r.metas.filter((u) => u.title.toLowerCase().includes(a));
+    },
+    [r.metas]
+  );
+  return {
+    metas: r.metas,
+    metaTree: r.metaTree,
+    searchMeta: o
+  };
+}
+export {
+  $ as JogakProvider,
+  P as reactAdapter,
+  G as useEntry,
+  p as useRegistry,
+  J as useRegistryMeta
+};

package/dist/renderers/react/useEntry.d.ts

@@ -0,0 +1,40 @@
+import { RegistryEntry, RegistryEntryMeta } from '../../index.js';
+/**
+ * Lazy entry hydration hook 상태값.
+ *
+ *  - `loading` : 메타는 있으나 entry 모듈은 아직 hydrate 전. `meta`로 헤더/skeleton 표시 가능.
+ *  - `ready`   : `requestEntry` 가 resolve 되어 완전한 `RegistryEntry` 가용.
+ *  - `error`   : hydration 도중 에러 — `UnknownEntryError` 포함.
+ *  - `unknown` : 등록되지 않은 id (`registerMeta` / `register` 둘 다 호출되지 않음).
+ *
+ * 본 타입은 어댑터 표면에 export 되어 ui 패키지가 `Preview` 분기에 사용한다.
+ */
+export type UseEntryState = {
+    readonly status: 'loading';
+    readonly meta: RegistryEntryMeta;
+} | {
+    readonly status: 'ready';
+    readonly entry: RegistryEntry;
+} | {
+    readonly status: 'error';
+    readonly error: Error;
+} | {
+    readonly status: 'unknown';
+};
+/**
+ * Lazy entry hydration 훅 (Phase 1 — 명시적 status 분기, Suspense 미사용).
+ *
+ * 동작:
+ *  1. 마운트 시점에 `getEntryState(id)`로 초기 상태 결정 (useState lazy init).
+ *  2. effect에서 `registry.subscribe`로 mutation을 감시 — registerMeta /
+ *     hydrateEntry / invalidateEntry 등 모든 변경에 자동 재산출.
+ *  3. recompute 결과가 `loading`이고 직전 상태가 `loading`이 아니었으면
+ *     `requestEntry(id)`를 트리거. 결과 entry는 hydrate가 notify를 통해
+ *     자동 반영하므로 then 안에서 setState 불필요(에러만 처리).
+ *  4. id 변경 시 effect 재실행, cleanup의 `cancelled` 플래그로 stale 차단.
+ *
+ * F4 통합: HMR 'jogak:meta-update' 이벤트가 invalidateEntry → requestEntry
+ * 흐름을 트리거하면 hydrated 상태였던 entry가 새 args/component로 다시
+ * hydrate되어 화면에 in-place 반영된다 (full-reload 회피).
+ */
+export declare function useEntry(id: string): UseEntryState;

package/dist/renderers/react/useRegistryMeta.d.ts

@@ -0,0 +1,27 @@
+import { CategoryMetaTree, RegistryEntryMeta } from '../../index.js';
+/**
+ * `useRegistryMeta` 반환 타입.
+ * `useRegistry`가 hydrated entry만 반영하는 것과 달리, 본 훅은 meta-only / pending 항목까지 포함.
+ *
+ *  - `metas`     : `registry.getAllMeta()` 결과 — registry 내부 캐시로 referential identity 보장
+ *  - `metaTree`  : `registry.getMetaTree()` 결과 — 사이드바 트리 구성용
+ *  - `searchMeta`: title 부분 일치(대소문자 무시) — Phase 1은 단순 string 매칭
+ */
+export interface UseRegistryMetaReturn {
+    readonly metas: readonly RegistryEntryMeta[];
+    readonly metaTree: CategoryMetaTree;
+    readonly searchMeta: (query: string) => readonly RegistryEntryMeta[];
+}
+/**
+ * 사이드바/검색용 메타 훅.
+ *
+ * `useSyncExternalStore` 기반으로 registry 변경(`register`/`unregister`/`registerMeta`/
+ * `hydrateEntry`/`clear`)에 자동 반응한다. registry 내부 snapshot 캐시(F2)와
+ * 외부 closure cache(makeGetSnapshot)의 이중 안전망으로 referential identity를 보장하여
+ * 무한 re-render를 방지한다.
+ *
+ * SSR: `getServerSnapshot`은 `getSnapshot`과 동일 함수. `defaultRegistry`는 module singleton이라
+ * 서버/클라이언트 동일 객체를 반환하며, registry가 비어있다면 빈 배열을 반환 후 클라이언트에서
+ * subscribe 통지로 자연 보정된다(`useSyncExternalStore`가 hydration 직후 client snapshot으로 전환).
+ */
+export declare function useRegistryMeta(): UseRegistryMetaReturn;

package/dist/renderers/web-components/define.d.ts

@@ -0,0 +1,11 @@
+import { RegistryEntry } from '../../index.js';
+/**
+ * RegistryEntry를 Custom Element로 등록한다.
+ *
+ * Shadow DOM으로 스타일을 격리하므로 호스트 페이지 스타일이 프리뷰를 오염하지 않는다.
+ * Preact를 사용하여 React 런타임(~150KB) 없이 ~3KB로 렌더링한다.
+ *
+ * Attribute로 받은 값은 string이므로 ArgType.type을 보고 boolean/number로 캐스팅한다.
+ * 함수 prop은 attribute로 받을 수 없으므로 어댑터가 자동으로 Action spy를 주입한다.
+ */
+export declare function defineJogakElement(tagName: string, entry: RegistryEntry): void;

package/dist/renderers/web-components/index.cjs

@@ -0,0 +1 @@
+"use strict";var k=e=>{throw TypeError(e)};var u=(e,t,n)=>t.has(e)||k("Cannot "+n);var c=(e,t,n)=>(u(e,t,"read from private field"),n?n.call(e):t.get(e)),l=(e,t,n)=>t.has(e)?k("Cannot add the same private member more than once"):t instanceof WeakSet?t.add(e):t.set(e,n),a=(e,t,n,s)=>(u(e,t,"write to private field"),s?s.call(e,n):t.set(e,n),n),d=(e,t,n)=>(u(e,t,"access private method"),n);Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const m=require("preact"),C=require("../../actions-D9bnuJ1b.cjs");function g(e,t){var s,o,i,h;if(customElements.get(e)!==void 0)return;class n extends HTMLElement{constructor(){super();l(this,i);l(this,s,{});l(this,o);a(this,o,this.attachShadow({mode:"open"}))}static get observedAttributes(){return Object.keys(t.meta.argTypes??{})}connectedCallback(){d(this,i,h).call(this)}attributeChangedCallback(r,b,E){var f;const v=(f=t.meta.argTypes)==null?void 0:f[r];a(this,s,{...c(this,s),[r]:p(E,v)}),d(this,i,h).call(this)}disconnectedCallback(){m.render(null,c(this,o))}}s=new WeakMap,o=new WeakMap,i=new WeakSet,h=function(){const r=t.meta.component,b=C.injectActions(c(this,s),t.meta.argTypes??{});m.render(m.h(r,b),c(this,o))},customElements.define(e,n)}function p(e,t){if(e!==null)return(t==null?void 0:t.type)==="boolean"?e!=="false"&&e!=="0":(t==null?void 0:t.type)==="number"?Number(e):e}exports.defineJogakElement=g;

package/dist/renderers/web-components/index.d.ts

@@ -0,0 +1 @@
+export { defineJogakElement } from './define.js';

package/dist/renderers/web-components/index.mjs

@@ -0,0 +1,48 @@
+var b = (t) => {
+  throw TypeError(t);
+};
+var u = (t, e, n) => e.has(t) || b("Cannot " + n);
+var c = (t, e, n) => (u(t, e, "read from private field"), n ? n.call(t) : e.get(t)), r = (t, e, n) => e.has(t) ? b("Cannot add the same private member more than once") : e instanceof WeakSet ? e.add(t) : e.set(t, n), m = (t, e, n, s) => (u(t, e, "write to private field"), s ? s.call(t, n) : e.set(t, n), n), a = (t, e, n) => (u(t, e, "access private method"), n);
+import { render as k, h as E } from "preact";
+import { i as v } from "../../actions-BvvUNlgo.js";
+function H(t, e) {
+  var s, o, i, d;
+  if (customElements.get(t) !== void 0) return;
+  class n extends HTMLElement {
+    constructor() {
+      super();
+      r(this, i);
+      r(this, s, {});
+      r(this, o);
+      m(this, o, this.attachShadow({ mode: "open" }));
+    }
+    static get observedAttributes() {
+      return Object.keys(e.meta.argTypes ?? {});
+    }
+    connectedCallback() {
+      a(this, i, d).call(this);
+    }
+    attributeChangedCallback(l, h, p) {
+      var f;
+      const C = (f = e.meta.argTypes) == null ? void 0 : f[l];
+      m(this, s, {
+        ...c(this, s),
+        [l]: A(p, C)
+      }), a(this, i, d).call(this);
+    }
+    disconnectedCallback() {
+      k(null, c(this, o));
+    }
+  }
+  s = new WeakMap(), o = new WeakMap(), i = new WeakSet(), d = function() {
+    const l = e.meta.component, h = v(c(this, s), e.meta.argTypes ?? {});
+    k(E(l, h), c(this, o));
+  }, customElements.define(t, n);
+}
+function A(t, e) {
+  if (t !== null)
+    return (e == null ? void 0 : e.type) === "boolean" ? t !== "false" && t !== "0" : (e == null ? void 0 : e.type) === "number" ? Number(t) : t;
+}
+export {
+  H as defineJogakElement
+};

package/dist/server.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("node:fs"),l=require("node:path"),u=require("./detect-global-css-CDcuUAYE.cjs"),d=["ts","js","mjs","cjs"],b=["ts","js","mjs","cjs"],j=["ts","mts","js","mjs","cjs"];function h(s){const e=C(s),n={...(e==null?void 0:e.dependencies)??{},...(e==null?void 0:e.devDependencies)??{}},t=a(s,d,"next.config"),f="next"in n,p="react-scripts"in n,i=a(s,b,"webpack.config"),g="webpack"in n,r=a(s,j,"vite.config");if(t||f){const c=[];return r&&c.push("vite.config.* (마이그레이션 중?)"),{name:"next",signal:t?"next.config.*":"package.json: next dep",...c.length>0?{ambiguous:c}:{}}}return p?{name:"webpack",signal:"package.json: react-scripts dep (CRA)"}:i||g?{name:"webpack",signal:i?"webpack.config.*":"package.json: webpack dep"}:r?{name:"vite",signal:"vite.config.*"}:{name:"standalone",signal:"(no builder signals)"}}function a(s,e,n){for(const t of e)if(o.existsSync(l.resolve(s,`${n}.${t}`)))return!0;return!1}function C(s){const e=l.resolve(s,"package.json");if(o.existsSync(e))try{const n=o.readFileSync(e,"utf-8");return JSON.parse(n)}catch{return}}exports.detectUserGlobalCss=u.detectUserGlobalCss;exports.resolveGlobalCssPaths=u.resolveGlobalCssPaths;exports.detectBuilder=h;

package/dist/server.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 알파.9: server-only 유틸리티 (Node.js only).
+ *
+ * 본 subpath의 함수들은 `node:fs`/`node:path`를 사용하므로 브라우저 client 번들에
+ * 포함되어서는 안 된다. CLI / 어댑터 / Vite plugin 등 Node 환경에서만 import.
+ *
+ * 사용처:
+ * - `@jogak/cli`: detectBuilder
+ * - `@jogak/vite-adapter` / `@jogak/next-adapter` / `@jogak/webpack-adapter`: resolveGlobalCssPaths
+ */
+export { detectBuilder, type DetectBuilderResult, } from './builder-detect.js';
+export { detectUserGlobalCss, resolveGlobalCssPaths, } from './vite-plugin/detect-global-css.js';

package/dist/server.mjs

@@ -0,0 +1,45 @@
+import { existsSync as r, readFileSync as u } from "node:fs";
+import { resolve as f } from "node:path";
+import { d as N, r as S } from "./detect-global-css-CIVMmgzy.js";
+const m = ["ts", "js", "mjs", "cjs"], d = ["ts", "js", "mjs", "cjs"], j = ["ts", "mts", "js", "mjs", "cjs"];
+function k(n) {
+  const e = b(n), s = {
+    ...(e == null ? void 0 : e.dependencies) ?? {},
+    ...(e == null ? void 0 : e.devDependencies) ?? {}
+  }, t = c(n, m, "next.config"), p = "next" in s, g = "react-scripts" in s, o = c(n, d, "webpack.config"), l = "webpack" in s, i = c(n, j, "vite.config");
+  if (t || p) {
+    const a = [];
+    return i && a.push("vite.config.* (마이그레이션 중?)"), {
+      name: "next",
+      signal: t ? "next.config.*" : "package.json: next dep",
+      ...a.length > 0 ? { ambiguous: a } : {}
+    };
+  }
+  return g ? {
+    name: "webpack",
+    signal: "package.json: react-scripts dep (CRA)"
+  } : o || l ? {
+    name: "webpack",
+    signal: o ? "webpack.config.*" : "package.json: webpack dep"
+  } : i ? { name: "vite", signal: "vite.config.*" } : { name: "standalone", signal: "(no builder signals)" };
+}
+function c(n, e, s) {
+  for (const t of e)
+    if (r(f(n, `${s}.${t}`))) return !0;
+  return !1;
+}
+function b(n) {
+  const e = f(n, "package.json");
+  if (r(e))
+    try {
+      const s = u(e, "utf-8");
+      return JSON.parse(s);
+    } catch {
+      return;
+    }
+}
+export {
+  k as detectBuilder,
+  N as detectUserGlobalCss,
+  S as resolveGlobalCssPaths
+};

package/dist/source-9OiU8x_y.cjs

@@ -0,0 +1,43 @@
+"use strict";const n=`
+import { reactAdapter } from '@jogak/core/renderers/react'
+import { defaultRegistry } from '@jogak/core'
+__EXTRA_IMPORTS__
+
+const rootEl = document.getElementById('jogak-preview-root')
+if (rootEl === null) throw new Error('[jogak] #jogak-preview-root not found')
+
+let currentContainer = null
+
+async function renderEntry(entryId, 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
+  }
+}
+
+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 o(e={}){const r=(e.extraImports??[]).map(t=>`import ${JSON.stringify(t)}`).join(`
+`);return n.replace("__EXTRA_IMPORTS__",r)}exports.renderPreviewEntrySource=o;

package/dist/source-D44KTQPu.js

@@ -0,0 +1,50 @@
+const n = `
+import { reactAdapter } from '@jogak/core/renderers/react'
+import { defaultRegistry } from '@jogak/core'
+__EXTRA_IMPORTS__
+
+const rootEl = document.getElementById('jogak-preview-root')
+if (rootEl === null) throw new Error('[jogak] #jogak-preview-root not found')
+
+let currentContainer = null
+
+async function renderEntry(entryId, 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
+  }
+}
+
+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 a(e = {}) {
+  const r = (e.extraImports ?? []).map((t) => `import ${JSON.stringify(t)}`).join(`
+`);
+  return n.replace("__EXTRA_IMPORTS__", r);
+}
+export {
+  a as r
+};

package/dist/types.d.ts

@@ -139,4 +139,165 @@ export interface JogakPluginOptions {
      * 또는 `--force`를 관리해야 한다.
      */
     readonly disableCacheValidation?: boolean;
+    /**
+     * 사용자 명시 path alias. 미지정 시 사용자 tsconfig의 `compilerOptions.paths`를
+     * 자동으로 읽어 vite `resolve.alias`로 등록한다 (shadcn/ui 같이 `@/`를 쓰는
+     * 일반적 환경 대응).
+     *
+     * 자동 추출은 단순 prefix 매핑(`"@/*": ["./src/*"]`)만 처리하므로,
+     * `extends` 체인이나 복합 glob 패턴을 쓰는 경우 본 옵션으로 명시 전달한다.
+     * 본 옵션이 자동 추출 결과를 덮어쓴다.
+     *
+     * 값은 alias prefix → 절대 경로(또는 cwd 기준 상대 경로) 맵이다.
+     *
+     * @example
+     * jogak({ resolveAlias: { '@': './src', '@components': './src/components' } })
+     */
+    readonly resolveAlias?: Readonly<Record<string, string>>;
+    /**
+     * 사용자 globalCss를 jogak SPA에 import한다 (알파.6 opt-in).
+     *
+     * 동기:
+     * - `runHost`는 vite root를 `@jogak/ui` 패키지로 두고 사용자 `vite.config.ts`/
+     *   `main.tsx`를 무시하므로(`configFile: false`), 사용자 `index.css`(Tailwind/
+     *   shadcn 디자인 토큰)가 jogak SPA에 자동 적용되지 않는다.
+     * - 본 옵션이 `true`이거나 명시 경로면 plugin이 사용자 css를 가상 모듈로
+     *   주입해 jogak SPA가 import한다.
+     *
+     * 의미:
+     * - `false` (default): 미주입. jogak chrome 기본 스타일만 사용 (알파.4~5 동작 그대로).
+     * - `true`: `<userRoot>/src/{index,main,styles,global,app,globals}.css` 후보를
+     *   순차 검사해 **첫 발견 1개**만 import. 미발견 시 빈 모듈 (no-op).
+     * - `string`: 사용자 root 기준 상대 경로 또는 절대 경로 1개. 자동 감지 비활성화.
+     * - `string[]`: 명시 경로 N개를 배열 순서대로 모두 import. 자동 감지 비활성화.
+     *
+     * 자동 감지 후보 (우선순위 순):
+     * 1. `src/index.css` (shadcn/ui Vite)
+     * 2. `src/main.css`
+     * 3. `src/styles.css`
+     * 4. `src/styles/globals.css` (Next.js shadcn)
+     * 5. `src/styles/index.css`
+     * 6. `src/app/globals.css` (Next.js App Router shadcn)
+     * 7. `src/global.css`
+     * 8. `src/app.css`
+     *
+     * 격리:
+     * - jogak UI는 알파.4~5에서 Tailwind v4 + `prefix=jogak`로 마이그레이션되어
+     *   사용자 utility class와 충돌 zero (예: 사용자 `.bg-primary` ≠ jogak `.jogak\:bg-...`).
+     * - jogak CSS variable은 `--jogak-*` prefix → 사용자 `:root { --primary }` 같은
+     *   토큰과 namespace 충돌 zero.
+     * - 단, 사용자 css의 `*` selector / `body` selector / reset 류는 jogak chrome에
+     *   영향 가능. README의 "scope 가이드" 패턴 참조.
+     *
+     * 한계 (알파.7+ 로드맵):
+     * - 사용자 css를 preview 영역으로만 한정하는 Shadow DOM/iframe 격리는 미지원.
+     * - `previewIsolation` 옵션은 알파.7+에서 별도 도입.
+     * - `globalCss: true` 자동 감지는 dev 시작 시점에 한 번만 수행 — 후보 css 파일이
+     *   dev 시작 후에 새로 추가되면 dev 서버 재시작이 필요하다. 명시 경로
+     *   (`globalCss: './src/index.css'`)는 파일이 나중에 생성되어도 정상 hot reload된다.
+     *
+     * @default false
+     *
+     * @example 자동 감지
+     * jogak({ globalCss: true })
+     *
+     * @example 명시 경로
+     * jogak({ globalCss: './src/index.css' })
+     *
+     * @example 다중 import (디자인 토큰 + reset 분리)
+     * jogak({ globalCss: ['./src/tokens.css', './src/index.css'] })
+     */
+    readonly globalCss?: boolean | string | readonly string[];
+    /**
+     * Preview 영역의 격리 모드 (알파.7 도입, 알파.8에서 default `'iframe'`로 변경).
+     *
+     * 알파.8의 default `'iframe'`은 사용자 vite 인스턴스를 spawn하여 그 vite의 정상 client에
+     * iframe document를 마운트한다. 사용자 plugins(@tailwindcss/vite 등)이 그대로 작동하므로
+     * **사용자 컴포넌트가 사용자 디자인 시스템 그대로 보인다**. 동시에 outer document의
+     * jogak chrome은 iframe 외부라 사용자 css 영향 zero (양방향 격리).
+     *
+     * 모드:
+     * - `'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 사용자 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;
+    /**
+     * @deprecated 알파.10 제거 예정. `userPreviewUrl` 사용.
+     *
+     * 알파.8 internal: jogak SPA가 iframe src로 사용할 사용자 vite의 base URL.
+     */
+    readonly userViteUrl?: string;
+    /**
+     * 알파.9 internal: jogak SPA가 iframe src로 사용할 어댑터 dev URL
+     * (예: `http://localhost:5174`). CLI의 어댑터 dispatch 결과가 host 통해 plugin에 전달.
+     *
+     * 빈 문자열 시 fallback (jogak SPA Vite scope의 preview-frame).
+     *
+     * 사용자가 직접 설정하는 옵션이 아니다.
+     */
+    readonly userPreviewUrl?: string;
+    /**
+     * 알파.9 internal: iframe src의 path (예: `/__jogak_preview__/index.html`).
+     * `BuilderAdapter.previewEntryMeta.devEntryPath` 값. 어댑터별 routing.
+     *
+     * 사용자가 직접 설정하는 옵션이 아니다.
+     */
+    readonly previewEntryPath?: 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.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("../plugin-Wtlz0hae.cjs");exports.jogak=e.jogak;