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

package/CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to Jogak packages are documented here. The repository follow
 
 Version numbers apply to all packages in the workspace (synchronized release).
 
+## [0.1.0-alpha.3] — 2026-05-07
+
+### Added
+
+- **`@jogak/core`**: Vite plugin now auto-detects user `tsconfig.json` (and `tsconfig.app.json` for the Vite scaffold-default split-references layout) and converts `compilerOptions.paths` into `vite resolve.alias`. This makes `runHost`-driven dev/build work zero-config for projects that use path aliases (shadcn/ui's `@/lib/utils` etc.). Without this, `runHost` ignored the user's `vite.config.ts` (`configFile: false`) and any `@/...` import inside a user component failed to resolve.
+- **`JogakPluginOptions.resolveAlias`**: explicit user-provided alias map for cases the auto-extraction can't handle (extends chains, complex glob patterns). Explicit entries override auto-extracted ones. Relative paths are resolved against the user root.
+
+### Fixed
+
+- Path aliases declared in user `tsconfig` are now respected during `jogak dev` and `jogak build`. Previously, every `*.jogak.tsx` that imported a component using `@/`-style imports would fail with `Failed to resolve import "@/..."` in the browser dev overlay.
+
+Other packages: no source changes; version bumped to keep the workspace synchronized.
+
+## [0.1.0-alpha.2] — 2026-05-07
+
+### Fixed
+
+- **`@jogak/ui`**: Published package was missing `src/app/main.tsx` (referenced by `index.html` as the SPA entry), causing `jogak dev` to 404 on the entry script and `jogak build` to fail with `Failed to resolve /src/app/main.tsx`. The `files` field in `package.json` only included `dist/`, but `runHost` uses the package's `index.html` as the Vite root and resolves `/src/app/main.tsx` from source. Added `src/app`, `src/components`, `src/hooks`, `src/index.ts`, `src/vite-env.d.ts` to `files`. Internal `src/host` and `src/examples` remain excluded (host is consumed via the published `dist/host` build; examples are repository-only demos).
+
+Other packages: no source changes; version bumped to keep the workspace synchronized.
+
 ## [0.1.0-alpha.1] — 2026-05-07
 
 ### Changed

package/dist/types.d.ts

@@ -139,4 +139,19 @@ 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>>;
 }

package/dist/vite/index.js

@@ -1,21 +1,21 @@
-"use strict";var V=Object.create;var N=Object.defineProperty;var G=Object.getOwnPropertyDescriptor;var U=Object.getOwnPropertyNames;var B=Object.getPrototypeOf,J=Object.prototype.hasOwnProperty;var q=(e,a,i,u)=>{if(a&&typeof a=="object"||typeof a=="function")for(let d of U(a))!J.call(e,d)&&d!==i&&N(e,d,{get:()=>a[d],enumerable:!(u=G(a,d))||u.enumerable});return e};var K=(e,a,i)=>(i=e!=null?V(B(e)):{},q(a||!e||!e.__esModule?N(i,"default",{value:e,enumerable:!0}):i,e));Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const j=require("node:path"),_=require("node:fs"),v=require("node:fs/promises"),R=require("../extractor-client-CiWszHel.cjs"),X=["@jogak/core","@jogak/react","@jogak/web-components","@jogak/next"];async function P(e){try{const u=await v.stat(e);if(!u.isDirectory())return u.mtimeMs}catch{return 0}let a=0,i;try{i=await v.readdir(e)}catch{return 0}for(const u of i){const d=j.join(e,u);try{const g=await v.stat(d);if(g.isDirectory()){const r=await P(d);r>a&&(a=r)}else g.mtimeMs>a&&(a=g.mtimeMs)}catch{continue}}return a}async function W(e){const a=j.resolve(e.root,"node_modules/.vite/deps");if(!_.existsSync(a))return{purged:!1};const i=j.join(a,"_metadata.json");if(!_.existsSync(i))return{purged:!1};let u;try{u=(await v.stat(i)).mtimeMs}catch(g){return e.logger.warn(`[jogak] cache validation: failed to stat _metadata.json (${g.message})`),{purged:!1}}const d=e.packages??X;for(const g of d){const r=j.resolve(e.root,"node_modules",g,"dist");if(!_.existsSync(r))continue;let s;try{s=await P(r)}catch(p){e.logger.warn(`[jogak] cache validation: failed to walk ${g}/dist (${p.message})`);continue}if(s>u+1e3)try{return await v.rm(a,{recursive:!0,force:!0}),e.logger.info(`[jogak] vite deps cache invalidated (stale): ${g} dist newer than cache`),{purged:!0,reason:g}}catch(p){return e.logger.warn(`[jogak] cache validation: failed to purge ${a} (${p.message})`),{purged:!1}}}return{purged:!1}}const $="virtual:jogak",T="\0"+$,F="virtual:jogak/entry/",I="\0"+F;function Y(e){return Buffer.from(e,"utf8").toString("base64url")}function H(e){return Buffer.from(e,"base64url").toString("utf8")}function A(e){return{title:e.title,jogakNamesKey:[...e.jogakNames].sort().join("|")}}function z(e,a){return e!==void 0&&e.title===a.title&&e.jogakNamesKey===a.jogakNamesKey}function Q(e={}){const{patterns:a=["src/**/*.jogak.ts","src/**/*.jogak.tsx"],codeTheme:i="vsDark"}=e,u=e.cwd,d=e.tsConfigFilePath,g=e.disableCacheValidation===!0;let r,s,p;const k=new Map,x=new Map,M=new Map;async function b(){const{glob:t}=await import("glob"),m=p??process.cwd(),n=await t(a,{cwd:m,absolute:!0}),f=[];k.clear(),x.clear();for(const c of n){let y="";try{y=await v.readFile(c,"utf8")}catch{continue}let h={},o=null;if(s!==void 0){try{h=await s.extract(c)}catch{h={}}try{o=await s.extractMeta(c)}catch{o=null}}if(o===null)continue;const l=o.title;k.set(l,c),x.set(c,l);const w={id:l,title:o.title,jogakNames:o.jogakNames,autoArgTypes:h,userArgTypes:o.userArgTypes,source:y,filePath:c,metaExtras:o.metaExtras};M.set(c,A(w)),f.push({id:l,filePath:c,meta:w})}return f}return{name:"vite-plugin-jogak",async configResolved(t){p=u??t.root,t.command==="serve"&&!g&&await W({root:t.root,logger:{info:n=>t.logger.info(n),warn:n=>t.logger.warn(n)}});const m=d??j.resolve(p,"tsconfig.json");s=_.existsSync(m)?R.createPropsExtractor({tsConfigFilePath:m}):R.createPropsExtractor()},configureServer(t){r=t},buildEnd(){s==null||s.releaseCache()},resolveId(t){if(t===$)return T;if(t.startsWith(F))return"\0"+t},async load(t){if(t===T){const n=(await b()).map(f=>f.meta);return`import { defaultRegistry } from '@jogak/core'
+"use strict";var V=Object.create;var N=Object.defineProperty;var G=Object.getOwnPropertyDescriptor;var J=Object.getOwnPropertyNames;var B=Object.getPrototypeOf,K=Object.prototype.hasOwnProperty;var q=(e,o,a,c)=>{if(o&&typeof o=="object"||typeof o=="function")for(let s of J(o))!K.call(e,s)&&s!==a&&N(e,s,{get:()=>o[s],enumerable:!(c=G(o,s))||c.enumerable});return e};var W=(e,o,a)=>(a=e!=null?V(B(e)):{},q(o||!e||!e.__esModule?N(a,"default",{value:e,enumerable:!0}):a,e));Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const p=require("node:path"),_=require("node:fs"),w=require("node:fs/promises"),O=require("../extractor-client-CiWszHel.cjs"),X=["@jogak/core","@jogak/react","@jogak/web-components","@jogak/next"];async function P(e){try{const c=await w.stat(e);if(!c.isDirectory())return c.mtimeMs}catch{return 0}let o=0,a;try{a=await w.readdir(e)}catch{return 0}for(const c of a){const s=p.join(e,c);try{const u=await w.stat(s);if(u.isDirectory()){const y=await P(s);y>o&&(o=y)}else u.mtimeMs>o&&(o=u.mtimeMs)}catch{continue}}return o}async function Y(e){const o=p.resolve(e.root,"node_modules/.vite/deps");if(!_.existsSync(o))return{purged:!1};const a=p.join(o,"_metadata.json");if(!_.existsSync(a))return{purged:!1};let c;try{c=(await w.stat(a)).mtimeMs}catch(u){return e.logger.warn(`[jogak] cache validation: failed to stat _metadata.json (${u.message})`),{purged:!1}}const s=e.packages??X;for(const u of s){const y=p.resolve(e.root,"node_modules",u,"dist");if(!_.existsSync(y))continue;let n;try{n=await P(y)}catch(l){e.logger.warn(`[jogak] cache validation: failed to walk ${u}/dist (${l.message})`);continue}if(n>c+1e3)try{return await w.rm(o,{recursive:!0,force:!0}),e.logger.info(`[jogak] vite deps cache invalidated (stale): ${u} dist newer than cache`),{purged:!0,reason:u}}catch(l){return e.logger.warn(`[jogak] cache validation: failed to purge ${o} (${l.message})`),{purged:!1}}}return{purged:!1}}function H(e){return e.replace(/\/\*[\s\S]*?\*\//g,"").replace(/^\s*\/\/.*$/gm,"")}function z(e){if(_.existsSync(e))try{const o=_.readFileSync(e,"utf8");return JSON.parse(H(o))}catch{return}}function Q(e,o,a){if(!e.endsWith("/*")||!o.endsWith("/*"))return;const c=e.slice(0,-2),s=p.resolve(a,o.slice(0,-2));return[c,s]}function Z(e,o){var s,u;const a={},c=new Set([e,p.resolve(o,"tsconfig.app.json")]);for(const y of c){const n=z(y);if(n===void 0)continue;const l=(s=n.compilerOptions)==null?void 0:s.paths;if(l===void 0)continue;const S=((u=n.compilerOptions)==null?void 0:u.baseUrl)??".",j=p.resolve(p.dirname(y),S);for(const[x,T]of Object.entries(l)){const M=T[0];if(M===void 0)continue;const t=Q(x,M,j);if(t===void 0)continue;const[f,r]=t;a[f]===void 0&&(a[f]=r)}}return a}const $="virtual:jogak",C="\0"+$,F="virtual:jogak/entry/",A="\0"+F;function ee(e){return Buffer.from(e,"utf8").toString("base64url")}function te(e){return Buffer.from(e,"base64url").toString("utf8")}function R(e){return{title:e.title,jogakNamesKey:[...e.jogakNames].sort().join("|")}}function oe(e,o){return e!==void 0&&e.title===o.title&&e.jogakNamesKey===o.jogakNamesKey}function re(e={}){const{patterns:o=["src/**/*.jogak.ts","src/**/*.jogak.tsx"],codeTheme:a="vsDark"}=e,c=e.cwd,s=e.tsConfigFilePath,u=e.disableCacheValidation===!0,y=e.resolveAlias;let n,l,S;const j=new Map,x=new Map,T=new Map;async function M(){const{glob:t}=await import("glob"),f=S??process.cwd(),r=await t(o,{cwd:f,absolute:!0}),g=[];j.clear(),x.clear();for(const d of r){let v="";try{v=await w.readFile(d,"utf8")}catch{continue}let h={},i=null;if(l!==void 0){try{h=await l.extract(d)}catch{h={}}try{i=await l.extractMeta(d)}catch{i=null}}if(i===null)continue;const m=i.title;j.set(m,d),x.set(d,m);const k={id:m,title:i.title,jogakNames:i.jogakNames,autoArgTypes:h,userArgTypes:i.userArgTypes,source:v,filePath:d,metaExtras:i.metaExtras};T.set(d,R(k)),g.push({id:m,filePath:d,meta:k})}return g}return{name:"vite-plugin-jogak",config(){const t=c??process.cwd(),f=s??p.resolve(t,"tsconfig.json"),r=Z(f,t),g={};if(y!==void 0)for(const[v,h]of Object.entries(y))g[v]=p.resolve(t,h);const d={...r,...g};if(Object.keys(d).length!==0)return{resolve:{alias:d}}},async configResolved(t){S=c??t.root,t.command==="serve"&&!u&&await Y({root:t.root,logger:{info:r=>t.logger.info(r),warn:r=>t.logger.warn(r)}});const f=s??p.resolve(S,"tsconfig.json");l=_.existsSync(f)?O.createPropsExtractor({tsConfigFilePath:f}):O.createPropsExtractor()},configureServer(t){n=t},buildEnd(){l==null||l.releaseCache()},resolveId(t){if(t===$)return C;if(t.startsWith(F))return"\0"+t},async load(t){if(t===C){const r=(await M()).map(g=>g.meta);return`import { defaultRegistry } from '@jogak/core'
 
 const _entryLoader = (slug) =>
   import(/* @vite-ignore */ '/@id/__x00__virtual:jogak/entry/' + slug)
 defaultRegistry.setEntryLoader((id) => {
-  const slug = ${Z()}
+  const slug = ${ae()}
   return _entryLoader(slug(id))
 })
 
-const _metas = ${JSON.stringify(n)}
+const _metas = ${JSON.stringify(r)}
 
 for (const m of _metas) defaultRegistry.registerMeta(m)
 
-export const _jogakCodeTheme = ${JSON.stringify(i)}
+export const _jogakCodeTheme = ${JSON.stringify(a)}
 export const _jogakMetas = _metas
-`}if(t.startsWith(I)){const m=t.slice(I.length),n=H(m);let f=k.get(n);return f===void 0&&(await b(),f=k.get(n)),f===void 0?`// [jogak] unknown entry id: ${JSON.stringify(n)}
+`}if(t.startsWith(A)){const f=t.slice(A.length),r=te(f);let g=j.get(r);return g===void 0&&(await M(),g=j.get(r)),g===void 0?`// [jogak] unknown entry id: ${JSON.stringify(r)}
 export {}
-`:`import * as _user from ${JSON.stringify(f)}
+`:`import * as _user from ${JSON.stringify(g)}
 import { defaultRegistry } from '@jogak/core'
 
 const _meta = _user.default
@@ -24,18 +24,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(r)}, _jogaks, _meta?.component)
 
 if (import.meta.hot) {
   import.meta.hot.accept()
 }
 
 export {}
-`}},async handleHotUpdate({file:t,modules:m}){const n=/\.jogak\.(tsx?|jsx?)$/.test(t),f=/\.(tsx?|jsx?)$/.test(t)&&!n;if(!n&&!f||r===void 0||!n)return;const c=r.moduleGraph.getModuleById(T),y=x.get(t),h=y!==void 0?I+Y(y):void 0,o=h!==void 0?r.moduleGraph.getModuleById(h):void 0;let l=null,w={},S="";if(s!==void 0){try{l=await s.extractMeta(t)}catch{l=null}try{w=await s.extract(t)}catch{w={}}try{S=await v.readFile(t,"utf8")}catch{S=""}}if(l===null){c!==void 0&&r.moduleGraph.invalidateModule(c),o!==void 0&&r.moduleGraph.invalidateModule(o),r.ws.send({type:"full-reload"});return}const C=A(l),D=M.get(t),O=z(D,C);if(M.set(t,C),!O||y===void 0){c!==void 0&&r.moduleGraph.invalidateModule(c),o!==void 0&&r.moduleGraph.invalidateModule(o),r.ws.send({type:"full-reload"});return}const L={id:y,title:l.title,jogakNames:l.jogakNames,autoArgTypes:w,userArgTypes:l.userArgTypes,source:S,filePath:t,metaExtras:l.metaExtras};o!==void 0&&r.moduleGraph.invalidateModule(o),r.ws.send({type:"custom",event:"jogak:meta-update",data:{id:y,meta:L}});const E=[...m];return o!==void 0&&!E.includes(o)&&E.push(o),E}}}function Z(){return`(rawId) => {
+`}},async handleHotUpdate({file:t,modules:f}){const r=/\.jogak\.(tsx?|jsx?)$/.test(t),g=/\.(tsx?|jsx?)$/.test(t)&&!r;if(!r&&!g||n===void 0||!r)return;const d=n.moduleGraph.getModuleById(C),v=x.get(t),h=v!==void 0?A+ee(v):void 0,i=h!==void 0?n.moduleGraph.getModuleById(h):void 0;let m=null,k={},E="";if(l!==void 0){try{m=await l.extractMeta(t)}catch{m=null}try{k=await l.extract(t)}catch{k={}}try{E=await w.readFile(t,"utf8")}catch{E=""}}if(m===null){d!==void 0&&n.moduleGraph.invalidateModule(d),i!==void 0&&n.moduleGraph.invalidateModule(i),n.ws.send({type:"full-reload"});return}const I=R(m),D=T.get(t),L=oe(D,I);if(T.set(t,I),!L||v===void 0){d!==void 0&&n.moduleGraph.invalidateModule(d),i!==void 0&&n.moduleGraph.invalidateModule(i),n.ws.send({type:"full-reload"});return}const U={id:v,title:m.title,jogakNames:m.jogakNames,autoArgTypes:k,userArgTypes:m.userArgTypes,source:E,filePath:t,metaExtras:m.metaExtras};i!==void 0&&n.moduleGraph.invalidateModule(i),n.ws.send({type:"custom",event:"jogak:meta-update",data:{id:v,meta:U}});const b=[...f];return i!==void 0&&!b.includes(i)&&b.push(i),b}}}function ae(){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=Q;
+  }`}exports.jogak=re;

package/dist/vite/index.mjs

@@ -1,8 +1,8 @@
-import { resolve as S, join as $ } from "node:path";
-import { existsSync as j } from "node:fs";
-import { stat as I, rm as G, readdir as U, readFile as C } from "node:fs/promises";
+import { resolve as h, join as $, dirname as G } from "node:path";
+import { existsSync as S, readFileSync as J } from "node:fs";
+import { stat as C, rm as B, readdir as K, readFile as N } from "node:fs/promises";
 import { c as R } from "../extractor-client-CReBed7x.js";
-const B = [
+const W = [
   "@jogak/core",
   "@jogak/react",
   "@jogak/web-components",
@@ -10,107 +10,147 @@ const B = [
 ];
 async function P(t) {
   try {
-    const u = await I(t);
-    if (!u.isDirectory())
-      return u.mtimeMs;
+    const l = await C(t);
+    if (!l.isDirectory())
+      return l.mtimeMs;
   } catch {
     return 0;
   }
-  let n = 0, m;
+  let o = 0, f;
   try {
-    m = await U(t);
+    f = await K(t);
   } catch {
     return 0;
   }
-  for (const u of m) {
-    const p = $(t, u);
+  for (const l of f) {
+    const m = $(t, l);
     try {
-      const l = await I(p);
-      if (l.isDirectory()) {
-        const a = await P(p);
-        a > n && (n = a);
-      } else l.mtimeMs > n && (n = l.mtimeMs);
+      const c = await C(m);
+      if (c.isDirectory()) {
+        const p = await P(m);
+        p > o && (o = p);
+      } else c.mtimeMs > o && (o = c.mtimeMs);
     } catch {
       continue;
     }
   }
-  return n;
+  return o;
 }
-async function J(t) {
-  const n = S(t.root, "node_modules/.vite/deps");
-  if (!j(n))
+async function X(t) {
+  const o = h(t.root, "node_modules/.vite/deps");
+  if (!S(o))
     return { purged: !1 };
-  const m = $(n, "_metadata.json");
-  if (!j(m))
+  const f = $(o, "_metadata.json");
+  if (!S(f))
     return { purged: !1 };
-  let u;
+  let l;
   try {
-    u = (await I(m)).mtimeMs;
-  } catch (l) {
+    l = (await C(f)).mtimeMs;
+  } catch (c) {
     return t.logger.warn(
-      `[jogak] cache validation: failed to stat _metadata.json (${l.message})`
+      `[jogak] cache validation: failed to stat _metadata.json (${c.message})`
     ), { purged: !1 };
   }
-  const p = t.packages ?? B;
-  for (const l of p) {
-    const a = S(t.root, "node_modules", l, "dist");
-    if (!j(a)) continue;
-    let i;
+  const m = t.packages ?? W;
+  for (const c of m) {
+    const p = h(t.root, "node_modules", c, "dist");
+    if (!S(p)) continue;
+    let r;
     try {
-      i = await P(a);
-    } catch (y) {
+      r = await P(p);
+    } catch (i) {
       t.logger.warn(
-        `[jogak] cache validation: failed to walk ${l}/dist (${y.message})`
+        `[jogak] cache validation: failed to walk ${c}/dist (${i.message})`
       );
       continue;
     }
-    if (i > u + 1e3)
+    if (r > l + 1e3)
       try {
-        return await G(n, { recursive: !0, force: !0 }), t.logger.info(
-          `[jogak] vite deps cache invalidated (stale): ${l} dist newer than cache`
-        ), { purged: !0, reason: l };
-      } catch (y) {
+        return await B(o, { recursive: !0, force: !0 }), t.logger.info(
+          `[jogak] vite deps cache invalidated (stale): ${c} dist newer than cache`
+        ), { purged: !0, reason: c };
+      } catch (i) {
         return t.logger.warn(
-          `[jogak] cache validation: failed to purge ${n} (${y.message})`
+          `[jogak] cache validation: failed to purge ${o} (${i.message})`
         ), { purged: !1 };
       }
   }
   return { purged: !1 };
 }
-const D = "virtual:jogak", T = "\0" + D, F = "virtual:jogak/entry/", x = "\0" + F;
-function K(t) {
+function Y(t) {
+  return t.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+}
+function q(t) {
+  if (S(t))
+    try {
+      const o = J(t, "utf8");
+      return JSON.parse(Y(o));
+    } catch {
+      return;
+    }
+}
+function H(t, o, f) {
+  if (!t.endsWith("/*") || !o.endsWith("/*")) return;
+  const l = t.slice(0, -2), m = h(f, o.slice(0, -2));
+  return [l, m];
+}
+function z(t, o) {
+  var m, c;
+  const f = {}, l = /* @__PURE__ */ new Set([
+    t,
+    h(o, "tsconfig.app.json")
+  ]);
+  for (const p of l) {
+    const r = q(p);
+    if (r === void 0) continue;
+    const i = (m = r.compilerOptions) == null ? void 0 : m.paths;
+    if (i === void 0) continue;
+    const k = ((c = r.compilerOptions) == null ? void 0 : c.baseUrl) ?? ".", w = h(G(p), k);
+    for (const [_, T] of Object.entries(i)) {
+      const M = T[0];
+      if (M === void 0) continue;
+      const e = H(_, M, w);
+      if (e === void 0) continue;
+      const [d, a] = e;
+      f[d] === void 0 && (f[d] = a);
+    }
+  }
+  return f;
+}
+const D = "virtual:jogak", x = "\0" + D, F = "virtual:jogak/entry/", A = "\0" + F;
+function Q(t) {
   return Buffer.from(t, "utf8").toString("base64url");
 }
-function X(t) {
+function Z(t) {
   return Buffer.from(t, "base64url").toString("utf8");
 }
-function A(t) {
+function O(t) {
   return {
     title: t.title,
     jogakNamesKey: [...t.jogakNames].sort().join("|")
   };
 }
-function W(t, n) {
-  return t !== void 0 && t.title === n.title && t.jogakNamesKey === n.jogakNamesKey;
+function tt(t, o) {
+  return t !== void 0 && t.title === o.title && t.jogakNamesKey === o.jogakNamesKey;
 }
-function Z(t = {}) {
+function it(t = {}) {
   const {
-    patterns: n = ["src/**/*.jogak.ts", "src/**/*.jogak.tsx"],
-    codeTheme: m = "vsDark"
-  } = t, u = t.cwd, p = t.tsConfigFilePath, l = t.disableCacheValidation === !0;
-  let a, i, y;
-  const w = /* @__PURE__ */ new Map(), k = /* @__PURE__ */ new Map(), _ = /* @__PURE__ */ new Map();
-  async function N() {
-    const { glob: e } = await import("glob"), g = y ?? process.cwd(), o = await e(n, { cwd: g, absolute: !0 }), d = [];
-    w.clear(), k.clear();
-    for (const s of o) {
-      let f = "";
+    patterns: o = ["src/**/*.jogak.ts", "src/**/*.jogak.tsx"],
+    codeTheme: f = "vsDark"
+  } = t, l = t.cwd, m = t.tsConfigFilePath, c = t.disableCacheValidation === !0, p = t.resolveAlias;
+  let r, i, k;
+  const w = /* @__PURE__ */ new Map(), _ = /* @__PURE__ */ new Map(), T = /* @__PURE__ */ new Map();
+  async function M() {
+    const { glob: e } = await import("glob"), d = k ?? process.cwd(), a = await e(o, { cwd: d, absolute: !0 }), u = [];
+    w.clear(), _.clear();
+    for (const s of a) {
+      let y = "";
       try {
-        f = await C(s, "utf8");
+        y = await N(s, "utf8");
       } catch {
         continue;
       }
-      let v = {}, r = null;
+      let v = {}, n = null;
       if (i !== void 0) {
         try {
           v = await i.extract(s);
@@ -118,79 +158,100 @@ function Z(t = {}) {
           v = {};
         }
         try {
-          r = await i.extractMeta(s);
+          n = await i.extractMeta(s);
         } catch {
-          r = null;
+          n = null;
         }
       }
-      if (r === null) continue;
-      const c = r.title;
-      w.set(c, s), k.set(s, c);
-      const h = {
-        id: c,
-        title: r.title,
-        jogakNames: r.jogakNames,
+      if (n === null) continue;
+      const g = n.title;
+      w.set(g, s), _.set(s, g);
+      const j = {
+        id: g,
+        title: n.title,
+        jogakNames: n.jogakNames,
         autoArgTypes: v,
-        userArgTypes: r.userArgTypes,
-        source: f,
+        userArgTypes: n.userArgTypes,
+        source: y,
         filePath: s,
-        metaExtras: r.metaExtras
+        metaExtras: n.metaExtras
       };
-      _.set(s, A(h)), d.push({ id: c, filePath: s, meta: h });
+      T.set(s, O(j)), u.push({ id: g, filePath: s, meta: j });
     }
-    return d;
+    return u;
   }
   return {
     name: "vite-plugin-jogak",
+    /**
+     * 사용자 path alias 주입.
+     *
+     * `runHost`는 vite root를 `@jogak/ui` 패키지로 두고 사용자 `vite.config.ts`를
+     * 무시하므로(`configFile: false`), 사용자가 컴포넌트 안에서 쓰는 `@/lib/utils`
+     * 같은 alias가 그냥은 적용되지 않는다. 본 hook이 사용자 tsconfig의
+     * `compilerOptions.paths`를 vite `resolve.alias`로 자동 변환해 주입한다.
+     *
+     * 우선순위: `options.resolveAlias` (명시) > tsconfig 자동 추출.
+     */
+    config() {
+      const e = l ?? process.cwd(), d = m ?? h(e, "tsconfig.json"), a = z(d, e), u = {};
+      if (p !== void 0)
+        for (const [y, v] of Object.entries(p))
+          u[y] = h(e, v);
+      const s = { ...a, ...u };
+      if (Object.keys(s).length !== 0)
+        return {
+          resolve: { alias: s }
+        };
+    },
     async configResolved(e) {
-      y = u ?? e.root, e.command === "serve" && !l && await J({
+      k = l ?? e.root, e.command === "serve" && !c && await X({
         root: e.root,
         logger: {
-          info: (o) => e.logger.info(o),
-          warn: (o) => e.logger.warn(o)
+          info: (a) => e.logger.info(a),
+          warn: (a) => e.logger.warn(a)
         }
       });
-      const g = p ?? S(y, "tsconfig.json");
-      i = j(g) ? R({ tsConfigFilePath: g }) : R();
+      const d = m ?? h(k, "tsconfig.json");
+      i = S(d) ? R({ tsConfigFilePath: d }) : R();
     },
     configureServer(e) {
-      a = e;
+      r = e;
     },
     buildEnd() {
       i == null || i.releaseCache();
     },
     resolveId(e) {
       if (e === D)
-        return T;
+        return x;
       if (e.startsWith(F))
         return "\0" + e;
     },
     async load(e) {
-      if (e === T) {
-        const o = (await N()).map((d) => d.meta);
+      if (e === x) {
+        const a = (await M()).map((u) => u.meta);
         return `import { defaultRegistry } from '@jogak/core'
 
 const _entryLoader = (slug) =>
   import(/* @vite-ignore */ '/@id/__x00__virtual:jogak/entry/' + slug)
 defaultRegistry.setEntryLoader((id) => {
-  const slug = ${Y()}
+  const slug = ${et()}
   return _entryLoader(slug(id))
 })
 
-const _metas = ${JSON.stringify(o)}
+const _metas = ${JSON.stringify(a)}
 
 for (const m of _metas) defaultRegistry.registerMeta(m)
 
-export const _jogakCodeTheme = ${JSON.stringify(m)}
+export const _jogakCodeTheme = ${JSON.stringify(f)}
 export const _jogakMetas = _metas
 `;
       }
-      if (e.startsWith(x)) {
-        const g = e.slice(x.length), o = X(g);
-        let d = w.get(o);
-        return d === void 0 && (await N(), d = w.get(o)), d === void 0 ? `// [jogak] unknown entry id: ${JSON.stringify(o)}
+      if (e.startsWith(A)) {
+        const d = e.slice(A.length), a = Z(d);
+        let u = w.get(a);
+        return u === void 0 && (await M(), u = w.get(a)), u === void 0 ? `// [jogak] unknown entry id: ${JSON.stringify(a)}
 export {}
-` : `import * as _user from ${JSON.stringify(d)}
+` : `import * as _user from ${JSON.stringify(u)}
 import { defaultRegistry } from '@jogak/core'
 
 const _meta = _user.default
@@ -199,7 +260,7 @@ delete _named.default
 const _jogaks = Object.values(_named).filter(
   (v) => v !== null && typeof v === 'object' && typeof v.name === 'string'
 )
-defaultRegistry.hydrateEntry(${JSON.stringify(o)}, _jogaks, _meta?.component)
+defaultRegistry.hydrateEntry(${JSON.stringify(a)}, _jogaks, _meta?.component)
 
 if (import.meta.hot) {
   import.meta.hot.accept()
@@ -209,60 +270,60 @@ export {}
 `;
       }
     },
-    async handleHotUpdate({ file: e, modules: g }) {
-      const o = /\.jogak\.(tsx?|jsx?)$/.test(e), d = /\.(tsx?|jsx?)$/.test(e) && !o;
-      if (!o && !d || a === void 0 || !o) return;
-      const s = a.moduleGraph.getModuleById(
-        T
-      ), f = k.get(e), v = f !== void 0 ? x + K(f) : void 0, r = v !== void 0 ? a.moduleGraph.getModuleById(v) : void 0;
-      let c = null, h = {}, M = "";
+    async handleHotUpdate({ file: e, modules: d }) {
+      const a = /\.jogak\.(tsx?|jsx?)$/.test(e), u = /\.(tsx?|jsx?)$/.test(e) && !a;
+      if (!a && !u || r === void 0 || !a) return;
+      const s = r.moduleGraph.getModuleById(
+        x
+      ), y = _.get(e), v = y !== void 0 ? A + Q(y) : void 0, n = v !== void 0 ? r.moduleGraph.getModuleById(v) : void 0;
+      let g = null, j = {}, E = "";
       if (i !== void 0) {
         try {
-          c = await i.extractMeta(e);
+          g = await i.extractMeta(e);
         } catch {
-          c = null;
+          g = null;
         }
         try {
-          h = await i.extract(e);
+          j = await i.extract(e);
         } catch {
-          h = {};
+          j = {};
         }
         try {
-          M = await C(e, "utf8");
+          E = await N(e, "utf8");
         } catch {
-          M = "";
+          E = "";
         }
       }
-      if (c === null) {
-        s !== void 0 && a.moduleGraph.invalidateModule(s), r !== void 0 && a.moduleGraph.invalidateModule(r), a.ws.send({ type: "full-reload" });
+      if (g === null) {
+        s !== void 0 && r.moduleGraph.invalidateModule(s), n !== void 0 && r.moduleGraph.invalidateModule(n), r.ws.send({ type: "full-reload" });
         return;
       }
-      const b = A(c), O = _.get(e), L = W(O, b);
-      if (_.set(e, b), !L || f === void 0) {
-        s !== void 0 && a.moduleGraph.invalidateModule(s), r !== void 0 && a.moduleGraph.invalidateModule(r), a.ws.send({ type: "full-reload" });
+      const I = O(g), L = T.get(e), U = tt(L, I);
+      if (T.set(e, I), !U || y === void 0) {
+        s !== void 0 && r.moduleGraph.invalidateModule(s), n !== void 0 && r.moduleGraph.invalidateModule(n), r.ws.send({ type: "full-reload" });
         return;
       }
       const V = {
-        id: f,
-        title: c.title,
-        jogakNames: c.jogakNames,
-        autoArgTypes: h,
-        userArgTypes: c.userArgTypes,
-        source: M,
+        id: y,
+        title: g.title,
+        jogakNames: g.jogakNames,
+        autoArgTypes: j,
+        userArgTypes: g.userArgTypes,
+        source: E,
         filePath: e,
-        metaExtras: c.metaExtras
+        metaExtras: g.metaExtras
       };
-      r !== void 0 && a.moduleGraph.invalidateModule(r), a.ws.send({
+      n !== void 0 && r.moduleGraph.invalidateModule(n), r.ws.send({
         type: "custom",
         event: "jogak:meta-update",
-        data: { id: f, meta: V }
+        data: { id: y, meta: V }
       });
-      const E = [...g];
-      return r !== void 0 && !E.includes(r) && E.push(r), E;
+      const b = [...d];
+      return n !== void 0 && !b.includes(n) && b.push(n), b;
     }
   };
 }
-function Y() {
+function et() {
   return `(rawId) => {
     if (typeof Buffer !== 'undefined') return Buffer.from(rawId, 'utf8').toString('base64url')
     // 브라우저 폴백: btoa는 binary string 기준이라 UTF-8을 한번 인코딩해야 한다.
@@ -273,5 +334,5 @@ function Y() {
   }`;
 }
 export {
-  Z as jogak
+  it as jogak
 };

package/dist/vite/resolve-paths.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 사용자 tsconfig의 `compilerOptions.paths`를 vite `resolve.alias`로 변환한다.
+ *
+ * 동기:
+ * - `runHost`는 vite root를 `@jogak/ui` 패키지로 두고 사용자 `vite.config.ts`를
+ *   무시하므로(`configFile: false`), 사용자가 정의한 alias가 적용되지 않는다.
+ * - shadcn/ui 같은 라이브러리는 `@/lib/utils` 같은 alias를 컴포넌트 안에서
+ *   사용하고, 사용자가 작성한 `*.jogak.tsx`도 같은 alias로 컴포넌트를 import.
+ * - 따라서 jogak이 사용자의 path alias를 자동으로 인식하지 못하면 dev/build에서
+ *   "Failed to resolve import" 에러가 난다.
+ *
+ * 처리 범위:
+ * - 단순 prefix 매핑: `"@/*": ["./src/*"]` → `{ "@": "<baseDir>/src" }`
+ * - references로 분할된 tsconfig (Vite 기본 스캐폴드 = `tsconfig.json` +
+ *   `tsconfig.app.json`): 후보 경로 두 개 모두 시도하고 먼저 발견된 매핑을 채택.
+ *
+ * 미처리 (의도적):
+ * - `extends` 체인: TypeScript Compiler API를 부모 V8에 로드하기 부담이 커서
+ *   단순 정규식 + JSON 파싱으로 처리. 대부분의 사용자 케이스(scaffold default,
+ *   shadcn/ui)는 references 패턴이라 본 범위에서 충분.
+ * - 복합 glob 패턴: 두 개 이상의 와일드카드를 포함하는 매핑은 처리하지 않는다.
+ *
+ * 자동 추출이 실패하면 `JogakPluginOptions.resolveAlias`로 명시적 alias를
+ * 전달할 수 있다 (사용자 fallback).
+ */
+/**
+ * 사용자 tsconfig 후보 경로들에서 paths를 추출해 alias 맵으로 합친다.
+ *
+ * @param primaryTsConfig 사용자가 명시했거나 자동 감지된 1차 tsconfig 절대 경로
+ * @param userRoot        사용자 프로젝트 루트 — references 분할 시 fallback 후보 위치 계산용
+ */
+export declare function readTsConfigAlias(primaryTsConfig: string, userRoot: string): Readonly<Record<string, string>>;

package/package.json

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