@iyulab/modern-app 0.4.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # Changelog
 
+## [0.8.0] - 2026-08-01
+
+### Added
+
+- ★**셸을 브랜드 색으로 다시 칠할 수 있다** — 사이드바의 활성 메뉴 색이 파랑 프리미티브
+  (`--u-blue-600`)에 하드와이어돼 있었다. 소비자가 브랜드를 다른 색으로 잡아도 **화면에서
+  가장 눈에 띄는 좌측 메뉴만 파랑으로 남았고**, 이를 고치는 길이 둘 다 나빴다 — 팔레트를
+  덮으면 *진짜 파랑*이 필요한 배지·차트까지 오염되고(팔레트는 이름이 곧 값의 약속이다),
+  섀도 DOM 내부 CSS 를 뚫으면 구조 변경에 조용히 깨진다.
+
+  이제 셸은 역할 토큰을 경유한다. **재브랜딩이 한 줄이다**:
+
+  ```css
+  :root { --u-primary-color: #7B1FA2; }
+  ```
+
+- **셸 표면 토큰을 소비자 계약으로 공개했다** — `--app-sidebar-{bg,fg,active-bg,active-fg,width,width-slim}`
+  · `--app-header-{bg,fg}`. **전부 선택**이며 미지정 시 역할 토큰에서 파생되므로, 아무것도
+  하지 않으면 브랜드를 따라오고 원하면 셸만 따로 조절한다. 문서: [docs/theme.md](docs/theme.md).
+
+  활성 메뉴의 hover 는 **별도 토큰이 아니라 파생**(`color-mix(… 85%, black)`)이다 — 한쪽만
+  덮은 소비자가 어긋난 색 쌍을 얻는 것이 이 계약이 막으려는 결함이기 때문이다.
+
+- **브라우저 테스트 프로젝트** — 실제 렌더에서만 드러나는 것을 검증한다
+  (`npm run test:browser`). `color-mix` 계산과 커스텀 프로퍼티 캐스케이드는 jsdom 이
+  재현하지 못한다.
+
+### Fixed
+
+- **라우팅 실패 표시가 컴포넌트의 위험색 규약을 따르지 않던 문제 수정** — `u-progress-bar` 의
+  API 에 없는 `error` 속성을 세우고 색을 자체 CSS 로 덮고 있었다. 컴포넌트가 제공하는
+  `status="error"` 를 쓰도록 고쳤다 — 막대 색이 규약값으로 정정되고, 종전에는 정정되지 않던
+  버퍼 색도 함께 따라온다.
+- **진행 표시 트랙 색 지정이 오타로 동작하지 않던 문제 수정** — `--progres-bar-track-color`
+  (`s` 누락)라 트랙이 투명해지지 않고 기본 회색으로 남아 있었다.
+- **키보드 포커스 링이 테마를 따르지 않던 문제 수정** — 사이드바 그룹·버튼의 포커스 윤곽선이
+  하드코딩된 색(`#6666ff`)이었다. 브랜드와 무관했고 다크 테마에서도 그대로였다.
+
+### Changed
+
+- ⚠**활성 메뉴 hover 배경이 미세하게 어두워진다** — 고정된 `--u-blue-700`(#1976D2) 대신
+  활성 색에서 파생하므로 기본 팔레트에서 #1A74C3 이 된다. 소비자가 브랜드를 바꿔도 hover 가
+  함께 따라오게 하려면 파생이어야 한다(고정 단은 따라오지 않는다).
+- ⚠**사이드바 그룹의 강조 텍스트 색이 바뀐다** — 같은 파생식을 쓴다. 대비는 오히려
+  올라간다(4.60:1 → 4.85:1, WCAG AA 통과 유지).
+- **사이드바 본문 텍스트가 `--u-neutral-800` 에서 시맨틱 토큰 `--u-txt-color` 로 바뀌었다.**
+  소비자의 텍스트 색 지정을 따르게 된다.
+
+## [0.7.0] - 2026-08-01
+
+### Fixed
+
+- ★**토큰 시트를 로드하지 않으면 앱 셸이 깨지던 문제 수정** — 사이드바·레이아웃의 색 선언
+  **34곳**이 `@iyulab/components` 의 시트 토큰을 폴백 없이 참조하고 있었다. 시트가 없으면
+  `var(--u-*)` 가 무효가 되어 **그 선언이 통째로 버려지므로**, 메뉴 텍스트가 보이지 않고
+  사이드바 배경이 투명해졌다. 앱 셸이라 화면 전체가 영향을 받는다.
+
+  이제 각 참조가 기본 테마 값을 폴백으로 갖는다(`var(--u-txt-color, #212121)`).
+  **시트를 로드하는 경우 시각 변화는 없다** — 폴백은 시트가 없을 때만 평가된다.
+  리터럴이 업스트림 시트와 어긋나지 않도록 대조 테스트가 강제하며, 폴백은 손으로 쓰지 않고
+  생성한다.
+
+  ⚠**폰트(`--u-font-base`)는 예외**다 — 폴백을 배선하지 않았다. 시트가 없으면 브라우저 기본
+  폰트로 대체되어 화면이 깨지지 않는다(색은 깨진다).
+
+## [0.6.0] - 2026-07-03
+
+### Added
+- **`AppConfig.auth`** — 부팅 인증 게이트. 지정하면 앱 셸(레이아웃·라우터)을 만들기 전에 `me()` 로 세션을 판정하여, 인증 시 셸을 로드하고 미인증 시 `renderLogin` 으로 로그인 UI 를 띄운다. 로그인 성공 시 `onSuccess()` 를 호출하면 앱이 (재)로드되어 셸이 나타난다. `onAuthenticated(user)` 로 셸 구성 직전 훅(권한 set 등)을 제공한다.
+  - 프레임워크는 인증 **오케스트레이션**(판정→분기→재로드)만 소유. 세션 조회/로그인 HTTP·사용자/권한 형태·세션-중 401 은 앱/`@iyulab/enterprise`(`createAuthClient`/`createODataService`)가 소유한다. 소비앱이 `app.load()` 앞단에 손으로 짜던 부팅 게이트를 표준화.
+- **`app.user`** getter — 인증 게이트 사용 시 인증된 현재 사용자(미인증/미사용이면 `undefined`).
+- **사이드바 네이티브 권한 메뉴 필터** — 모든 메뉴 항목(link/section/group/button/html)에 `requirePermission?`/`requireAnyPermission?` 지원(공통 `SidebarPermissionGuard`). `SidebarLayoutConfig.hasPermission` 판정 함수를 주면 만족하지 않는 항목을 숨기고, 항목이 모두 걸러진 section/group 은 통째로 숨긴다. 소비앱이 손으로 짜던 `filterMenu` 를 표준화. 순수 헬퍼 `filterSidebarItems(items, hasPermission)` 도 export.
+
+### Notes
+- `auth`/`hasPermission` 미지정 시 동작은 완전히 하위호환(게이트·필터 없이 기존대로 셸 로드).
+
+## [0.5.0] - 2026-07-02
+
+### Added
+- `AppConfig.enter` — global route guard, forwarded to the underlying `@iyulab/router` `Router`. Previously `@iyulab/router` already supported this via `RouterConfig.enter`, but `App.load()` never passed it through, so the global guard path was unreachable from modern-app. Return a `string` to redirect, `false` to cancel (403), `true`/nothing to proceed. See [docs/routing.md#authentication--guards](./docs/routing.md#authentication--guards).
+- `AppConfig.initialLoad` / `AppConfig.useIntercept` — forwarded to `Router` alongside `enter` (previously also unreachable; `initialLoad: false` is needed for guard unit tests that drive navigation explicitly).
+- Vitest + happy-dom test infrastructure (`npm test`) — first automated test suite for this package, covering `AppConfig.enter` redirect/cancel behavior.
+
+### Changed
+- `package.json` `scripts`: `"test"` now runs `vitest run` (was `vite`, which only started the dev server). The old behavior is available as `"start"`.
+
 ## [0.4.0] - 2026-07-02
 
 ### Added

package/README.md

@@ -77,6 +77,15 @@ app.theme.set('dark');
 app.theme.isInitialized; // boolean
 ```
 
+Rebranding the shell is one declaration — the sidebar's active menu follows it:
+
+```css
+:root { --u-primary-color: #7B1FA2; }
+```
+
+Shell surfaces can also be tuned on their own (`--app-sidebar-bg`, `--app-sidebar-width`, …).
+See [theme.md](./docs/theme.md).
+
 ### Notifications
 
 ```typescript
@@ -109,14 +118,69 @@ import { translate } from 'lit-i18n';
 html`<p>${translate('common::greeting')}</p>`;
 ```
 
+### 부팅 인증 게이트 (`auth`)
+
+셸을 만들기 전에 세션을 판정한다. 소비앱이 `app.load()` 앞단에 손으로 짜던 "me 조회 → 미인증이면 로그인, 인증이면 앱 로드" 게이트를 표준화한다. 세션 조회/로그인 HTTP 는 `@iyulab/enterprise` 의 `createAuthClient` 가, 세션-중 401 은 `createODataService` 의 `onUnauthorized` 가 담당한다(프레임워크는 오케스트레이션만 소유).
+
+```typescript
+import { createAuthClient, setPermissions } from '@iyulab/enterprise';
+
+const auth = createAuthClient<User, Cred>({ meUrl: '/api/auth/me', loginUrl: '/api/auth/login', logoutUrl: '/api/auth/logout' });
+
+await app.load({
+  layout: { type: 'sidebar', /* ... */ },
+  auth: {
+    me: () => auth.fetchMe(),                         // null → 미인증 → renderLogin
+    renderLogin: ({ root, onSuccess }) => renderLoginPage(root, auth, onSuccess),
+    onAuthenticated: (user) => setPermissions((user as User).Permissions),
+  },
+  routes: [ /* ... */ ],
+});
+
+app.user; // 인증된 현재 사용자(미인증/미사용 시 undefined)
+```
+
+- `me()` 가 값을 반환하면 셸 로드, `null`/`undefined` 면 `renderLogin({ root, onSuccess })`.
+- 로그인 성공 시 `onSuccess()` 를 호출하면 앱이 재로드되어 셸이 나타나고 로그인 UI 는 정리된다.
+- `auth` 미지정 시 완전히 하위호환(게이트 없이 기존대로 로드).
+
+### 권한 기반 메뉴 필터
+
+모든 사이드바 메뉴 항목에 `requirePermission`/`requireAnyPermission` 를 달고, 레이아웃에 `hasPermission` 판정 함수를 주면 권한 없는 항목이 숨겨진다. 항목이 모두 걸러진 section/group 은 통째로 숨는다. 소비앱이 손으로 짜던 `filterMenu` 를 대체한다.
+
+```typescript
+import { hasPermission } from '@iyulab/enterprise';
+
+await app.load({
+  layout: {
+    type: 'sidebar',
+    hasPermission,                                  // enterprise 권한 store 판정
+    main: [
+      { type: 'link', icon: 'house', label: '홈', href: '/' },
+      { type: 'link', icon: 'gear', label: '설정', href: '/settings', requirePermission: 'admin.maintenance' },
+      {
+        type: 'section', title: '주문',
+        items: [
+          { type: 'link', label: '주문 목록', href: '/orders', requireAnyPermission: ['orders.read', 'orders.write'] },
+        ],
+      },
+    ],
+  },
+  auth: { /* ... */ },
+});
+```
+
+- `hasPermission` 미지정 시 필터링하지 않는다(모든 항목 표시 — 하위호환).
+- 순수 헬퍼 `filterSidebarItems(items, hasPermission)` 를 직접 재사용할 수도 있다.
+
 ## Documentation
 
 | Guide | Description |
 |-------|-------------|
 | [getting-started.md](./docs/getting-started.md) | Bootstrap, architecture, entry point setup |
-| [routing.md](./docs/routing.md) | Route config, URL params, async routes, progress |
+| [routing.md](./docs/routing.md) | Route config, URL params, async routes, progress, auth guards |
 | [layout.md](./docs/layout.md) | Sidebar layout, all menu item types, responsive behaviour |
-| [theme.md](./docs/theme.md) | Theme init, runtime switching, CSS tokens |
+| [theme.md](./docs/theme.md) | Theme init, runtime switching, token layers, shell surface tokens |
 | [notifications.md](./docs/notifications.md) | Toast methods and options |
 | [i18n.md](./docs/i18n.md) | i18next setup, plugins, lit-i18n usage |
 | [configuration.md](./docs/configuration.md) | Full TypeScript interface reference |

package/dist/App.d.ts

@@ -12,6 +12,8 @@ declare class App {
     private _layout?;
     private _router?;
     private _screen?;
+    private _user?;
+    private _loginTeardown?;
     private constructor();
     /** 싱글톤 인스턴스 반환 */
     static get instance(): App;
@@ -21,6 +23,8 @@ declare class App {
     get router(): Router | undefined;
     /** 화면 크기 반환 */
     get screen(): ScreenSize | undefined;
+    /** 인증 게이트(`auth`) 사용 시 인증된 현재 사용자. 미인증/미사용이면 undefined. */
+    get user(): unknown;
     /** 스타일 테마 관리 유틸리티 객체 반환 */
     get theme(): typeof Theme;
     /** 다국어 로컬라이저(i18next) 반환 */

package/dist/App.js

@@ -18,6 +18,9 @@ var o = class o {
 	get screen() {
 		return this._screen?.get();
 	}
+	get user() {
+		return this._user;
+	}
 	get theme() {
 		return i;
 	}
@@ -25,7 +28,21 @@ var o = class o {
 		return t;
 	}
 	async load(a) {
-		if (this.unload(), this._config = a, await i.init(a.theme), a.iconBasepath && r(a.iconBasepath), a.i18n) {
+		if (this.unload(), this._config = a, a.auth) {
+			let e = await a.auth.me();
+			if (e == null) {
+				let e = a.root || document.body, t = a.auth.renderLogin({
+					root: e,
+					onSuccess: () => {
+						this.load(a);
+					}
+				});
+				t && (this._loginTeardown = t);
+				return;
+			}
+			this._user = e, await a.auth.onAuthenticated?.(e);
+		}
+		if (await i.init(a.theme), a.iconBasepath && r(a.iconBasepath), a.i18n) {
 			for (let e of a.i18n.plugins || []) t.use(e);
 			await t.init(a.i18n);
 		}
@@ -39,11 +56,14 @@ var o = class o {
 			root: this._layout,
 			basepath: a.basepath,
 			routes: a.routes,
-			fallback: a.fallback
+			fallback: a.fallback,
+			enter: a.enter,
+			initialLoad: a.initialLoad,
+			useIntercept: a.useIntercept
 		});
 	}
 	unload() {
-		this._screen &&= (this._screen.destroy(), void 0), this._layout &&= (this._layout.remove(), void 0), this._router &&= (this._router.destroy(), void 0), this._config &&= void 0;
+		this._loginTeardown &&= (this._loginTeardown(), void 0), this._user = void 0, this._screen &&= (this._screen.destroy(), void 0), this._layout &&= (this._layout.remove(), void 0), this._router &&= (this._router.destroy(), void 0), this._config &&= void 0;
 	}
 	navigate(e) {
 		this._router?.go(e);

package/dist/_virtual/{_@oxc-project_runtime@0.138.0 → _@oxc-project_runtime@0.142.0}/helpers/esm/decorate.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.138.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.142.0/helpers/esm/decorate.js
 function e(e, t, n, r) {
 	var i = arguments.length, a = i < 3 ? t : r === null ? r = Object.getOwnPropertyDescriptor(t, n) : r, o;
 	if (typeof Reflect == "object" && typeof Reflect.decorate == "function") a = Reflect.decorate(e, t, n, r);

package/dist/_virtual/{_@oxc-project_runtime@0.138.0 → _@oxc-project_runtime@0.142.0}/helpers/esm/decorateMetadata.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.138.0/helpers/esm/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.142.0/helpers/esm/decorateMetadata.js
 function e(e, t) {
 	if (typeof Reflect == "object" && typeof Reflect.metadata == "function") return Reflect.metadata(e, t);
 }

package/dist/components/SidebarButton.d.ts

@@ -1,9 +1,10 @@
 import { DirectiveResult } from 'lit/directive.js';
 import { StyledElement, StyleMap } from '../internals/StyledElement.js';
+import { SidebarPermissionGuard } from '../layouts/SidebarPermission.js';
 /** 버튼 항목 부분 */
 type ElementParts = 'host' | 'base' | 'icon' | 'label';
 /** 버튼 항목 구성 */
-export interface SidebarButtonConfig {
+export interface SidebarButtonConfig extends SidebarPermissionGuard {
     type: 'button';
     icon?: string;
     label?: string | DirectiveResult;

package/dist/components/SidebarButton.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.138.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.138.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { styles as r } from "./SidebarButton.styles.js";
 import { html as i } from "lit";

package/dist/components/SidebarButton.styles.js

@@ -4,7 +4,7 @@ var t = e`
   :host {
     display: block;
     width: 100%;
-    color: var(--u-txt-color);
+    color: var(--app-sidebar-fg, var(--u-txt-color, #212121));
     background-color: transparent;
     border: none;
     border-radius: 8px;
@@ -12,11 +12,11 @@ var t = e`
     cursor: pointer;
   }
   :host(:hover) {
-    color: var(--u-txt-color-hover);
-    background-color: var(--u-bg-color-hover);
+    color: var(--u-txt-color-hover, #1E88E5);
+    background-color: var(--u-bg-color-hover, #F5F5F5);
   }
   :host(:active) {
-    background-color: var(--u-bg-color-active);
+    background-color: var(--u-bg-color-active, #EEEEEE);
   }
 
   button {
@@ -35,7 +35,7 @@ var t = e`
     padding: 8px;
   }
   button:focus-visible {
-    outline: 2px solid #6666ff;
+    outline: 2px solid var(--u-primary-color-weak, #2196F3);
     outline-offset: 2px;
   }
   

package/dist/components/SidebarGroup.d.ts

@@ -1,9 +1,10 @@
 import { DirectiveResult } from 'lit/directive.js';
 import { StyledElement, StyleMap } from '../internals/StyledElement.js';
 import { SidebarLinkConfig } from './SidebarLink.js';
+import { SidebarPermissionGuard } from '../layouts/SidebarPermission.js';
 type ElementParts = 'host' | 'header' | 'icon' | 'label' | 'caret' | 'items';
 /** 그룹: 하위 링크들 묶음 */
-export interface SidebarGroupConfig {
+export interface SidebarGroupConfig extends SidebarPermissionGuard {
     type: 'group';
     /** 기본 접힘 상태 */
     collapsed?: boolean;

package/dist/components/SidebarGroup.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.138.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.138.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { SidebarLink as r } from "./SidebarLink.js";
 import { styles as i } from "./SidebarGroup.styles.js";

package/dist/components/SidebarGroup.styles.js

@@ -2,9 +2,12 @@ import { css as e } from "lit";
 //#region src/components/SidebarGroup.styles.ts
 var t = e`
   :host {
+    /* SidebarLink 과 같은 원천 — 그룹 강조는 활성 링크와 같은 색 계열이어야 한다 */
+    --group-accent: var(--app-sidebar-active-bg, var(--u-primary-color, #1E88E5));
+
     display: flex;
     flex-direction: column;
-    color: var(--u-neutral-800);
+    color: var(--app-sidebar-fg, var(--u-txt-color, #212121));
   }
 
   button {
@@ -28,17 +31,19 @@ var t = e`
     padding: 8px;
   }
   button[selected] {
-    color: var(--u-blue-700);
+    /* 패널 위 텍스트라 강조색을 그대로 쓰면 대비가 부족하다(blue-600 = 3.68:1).
+       활성 배경과 같은 파생식으로 한 단 어둡게 해 AA 를 넘긴다(4.85:1). */
+    color: color-mix(in srgb, var(--group-accent) 85%, black);
   }
   button:hover {
-    color: var(--u-txt-color-hover);
-    background-color: var(--u-bg-color-hover);
+    color: var(--u-txt-color-hover, #1E88E5);
+    background-color: var(--u-bg-color-hover, #F5F5F5);
   }
   button:active {
-    background-color: var(--u-bg-color-active);
+    background-color: var(--u-bg-color-active, #EEEEEE);
   }
   button:focus-visible {
-    outline: 2px solid #6666ff;
+    outline: 2px solid var(--u-primary-color-weak, #2196F3);
     outline-offset: 2px;
   }
 
@@ -73,7 +78,7 @@ var t = e`
     gap: 4px;
     margin-top: 4px;
     margin-left: 32px;
-    border-left: 2px solid var(--u-border-color-weak);
+    border-left: 2px solid var(--u-border-color-weak, #EEEEEE);
     padding-left: 8px;
     overflow: hidden;
     transition: all 0.3s ease;

package/dist/components/SidebarLink.d.ts

@@ -1,8 +1,9 @@
 import { DirectiveResult } from 'lit/directive.js';
 import { StyledElement, StyleMap } from '../internals/StyledElement.js';
+import { SidebarPermissionGuard } from '../layouts/SidebarPermission.js';
 type ElementParts = 'host' | 'base' | 'icon' | 'label';
 /** 링크 항목 디폴트 타입 */
-export interface SidebarLinkConfig {
+export interface SidebarLinkConfig extends SidebarPermissionGuard {
     type: 'link';
     icon?: string;
     label: string | DirectiveResult;

package/dist/components/SidebarLink.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.138.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.138.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { styles as r } from "./SidebarLink.styles.js";
 import { html as i } from "lit";

package/dist/components/SidebarLink.styles.js

@@ -2,26 +2,32 @@ import { css as e } from "lit";
 //#region src/components/SidebarLink.styles.ts
 var t = e`
   :host {
+    /* 활성 배경의 단일 원천. 소비자는 셸 계약 토큰(--app-sidebar-active-bg) 또는
+       역할 토큰(--u-primary-color) 어느 쪽을 덮어도 hover 파생까지 함께 따라온다.
+       팔레트(--u-blue-600)를 직접 읽으면 브랜드를 바꾸려는 소비자가 "진짜 파랑"이
+       필요한 배지·차트까지 함께 오염시키는 길밖에 없다. */
+    --link-active-bg: var(--app-sidebar-active-bg, var(--u-primary-color, #1E88E5));
+
     display: block;
-    color: var(--u-neutral-800);
+    color: var(--app-sidebar-fg, var(--u-txt-color, #212121));
     background-color: transparent;
     border-radius: 8px;
     transition: all 0.2s ease;
     cursor: pointer;
   }
   :host(:hover) {
-    color: var(--u-txt-color-hover);
-    background-color: var(--u-bg-color-hover);
+    color: var(--u-txt-color-hover, #1E88E5);
+    background-color: var(--u-bg-color-hover, #F5F5F5);
   }
   :host([selected]) {
-    color: var(--u-txt-color-inverse);
-    background-color: var(--u-blue-600);
-    box-shadow: 0 1px 3px var(--u-shadow-color-weak);
+    color: var(--app-sidebar-active-fg, var(--u-txt-color-inverse, #FFFFFF));
+    background-color: var(--link-active-bg);
+    box-shadow: 0 1px 3px var(--u-shadow-color-weak, rgba(0, 0, 0, 0.08));
   }
   :host([selected]:hover) {
-    color: var(--u-txt-color-inverse);
-    background-color: var(--u-blue-700);
-    box-shadow: 0 2px 6px var(--u-shadow-color-normal);
+    color: var(--app-sidebar-active-fg, var(--u-txt-color-inverse, #FFFFFF));
+    background-color: color-mix(in srgb, var(--link-active-bg) 85%, black);
+    box-shadow: 0 2px 6px var(--u-shadow-color-normal, rgba(0, 0, 0, 0.12));
   }
   
   .container {

package/dist/components/SidebarSection.d.ts

@@ -2,9 +2,10 @@ import { DirectiveResult } from 'lit/directive.js';
 import { StyledElement, StyleMap } from '../internals/StyledElement.js';
 import { SidebarLinkConfig } from './SidebarLink.js';
 import { SidebarGroupConfig } from './SidebarGroup.js';
+import { SidebarPermissionGuard } from '../layouts/SidebarPermission.js';
 type ElementParts = 'host' | 'header' | 'title' | 'subtitle' | 'items';
 /** 섹션 내에는 그룹 또는 링크들만 허용 */
-export interface SidebarSectionConfig {
+export interface SidebarSectionConfig extends SidebarPermissionGuard {
     type: 'section';
     title: string | DirectiveResult;
     subTitle?: string | DirectiveResult;

package/dist/components/SidebarSection.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.138.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.138.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { styles as r } from "./SidebarSection.styles.js";
 import { html as i } from "lit";

package/dist/components/SidebarSection.styles.js

@@ -14,8 +14,13 @@ var t = e`
     padding: 8px 12px 4px;
   }
 
+  /* ⚠아래 두 색만 팔레트를 직접 읽는다 — 시맨틱 토큰으로 옮기면 대비가 무너지기 때문이다.
+     섹션 제목·부제는 본문(neutral-800)보다 약한 3단 위계를 이루는데, 역할 층의 보조
+     텍스트 단은 --u-txt-color-weak 하나뿐이고 그 값은 흰 배경에서 2.68:1 이라
+     WCAG AA(4.5:1)에 미달한다. 현행 두 값은 6.19:1 · 4.61:1 로 통과한다.
+     ⇒ 역할 층에 AA 를 넘는 보조 텍스트 단이 생기면 그때 옮긴다. */
   .title {
-    color: var(--u-neutral-700);
+    color: var(--u-neutral-700, #616161);
     font-size: 12px;
     font-weight: 700;
     letter-spacing: 0.5px;
@@ -25,7 +30,7 @@ var t = e`
   }
   
   .subtitle {
-    color: var(--u-neutral-600);
+    color: var(--u-neutral-600, #757575);
     font-size: 11px;
     font-weight: 300;
   }

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 import { app } from './App.js';
 export type * from './types/AppConfigs';
 export type * from './types/AppOptions';
+export type * from './types/AuthConfig';
+export type { SidebarPermissionGuard } from './layouts/SidebarPermission';
+export { filterSidebarItems } from './layouts/filterSidebarItems.js';
 export { app };
 export default app;

package/dist/index.js

@@ -1,5 +1,6 @@
 import { app as e } from "./App.js";
+import { filterSidebarItems as t } from "./layouts/filterSidebarItems.js";
 //#region src/index.ts
-var t = e;
+var n = e;
 //#endregion
-export { e as app, t as default };
+export { e as app, n as default, t as filterSidebarItems };

package/dist/internals/StyledElement.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.138.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.138.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorate.js";
 import { property as n } from "lit/decorators.js";
 import { UElement as r } from "@iyulab/components/dist/components/UElement.js";
 //#region src/internals/StyledElement.ts

package/dist/layouts/SidebarLayout.js

@@ -1,27 +1,28 @@
 import { app as e } from "../App.js";
-import t from "../_virtual/_@oxc-project_runtime@0.138.0/helpers/esm/decorateMetadata.js";
-import n from "../_virtual/_@oxc-project_runtime@0.138.0/helpers/esm/decorate.js";
-import { StyledElement as r } from "../internals/StyledElement.js";
+import { filterSidebarItems as t } from "./filterSidebarItems.js";
+import n from "../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorateMetadata.js";
+import r from "../_virtual/_@oxc-project_runtime@0.142.0/helpers/esm/decorate.js";
+import { StyledElement as i } from "../internals/StyledElement.js";
 import "../components/SidebarSection.js";
 import "../components/SidebarLink.js";
 import "../components/SidebarGroup.js";
 import "../components/SidebarButton.js";
-import { styles as i } from "./SidebarLayout.styles.js";
-import { html as a, nothing as o } from "lit";
-import { customElement as s, property as c, query as l, state as u } from "lit/decorators.js";
-import { unsafeHTML as d } from "lit/directives/unsafe-html.js";
-import { repeat as f } from "lit/directives/repeat.js";
+import { styles as a } from "./SidebarLayout.styles.js";
+import { html as o, nothing as s } from "lit";
+import { customElement as c, property as l, query as u, state as d } from "lit/decorators.js";
+import { unsafeHTML as f } from "lit/directives/unsafe-html.js";
+import { repeat as p } from "lit/directives/repeat.js";
 import "@iyulab/components/dist/components/icon/UIcon.js";
 import "@iyulab/components/dist/components/button/UButton.js";
-import { UProgressBar as p } from "@iyulab/components/dist/components/progress-bar/UProgressBar.js";
+import { UProgressBar as m } from "@iyulab/components/dist/components/progress-bar/UProgressBar.js";
 //#region src/layouts/SidebarLayout.ts
-function m(e) {
+function h(e) {
 	let t = e.tagName;
 	if (t === "INPUT" || t === "TEXTAREA" || t === "SELECT" || e.isContentEditable) return !0;
 	let n = e.getAttribute("role");
 	return n === "textbox" || n === "searchbox" || n === "combobox" || n === "spinbutton";
 }
-var h = class extends r {
+var g = class extends i {
 	constructor(...t) {
 		super(...t), this.state = "default", this.context = null, this.isMatchedLink = (e) => !this.context || !e ? !1 : (e = typeof e == "string" ? new URLPattern(e, window.location.origin) : e, e.test(this.context.path, window.location.origin)), this.handleBrandLogoClick = (t) => () => {
 			e.navigate(t ?? "");
@@ -39,12 +40,12 @@ var h = class extends r {
 				this.progressBarEl.removeAttribute("visible");
 			}, 300), (this.shadowRoot?.querySelector(".main"))?.focus({ preventScroll: !0 });
 		}, this.handleRouteError = (e) => {
-			this.progressBarEl.setAttribute("error", ""), this.progressBarEl.value = 100, setTimeout(() => {
-				this.progressBarEl.removeAttribute("visible"), this.progressBarEl.removeAttribute("error");
+			this.progressBarEl.status = "error", this.progressBarEl.value = 100, setTimeout(() => {
+				this.progressBarEl.removeAttribute("visible"), this.progressBarEl.status = "default";
 			}, 300);
 		}, this._handleMainKeydown = (e) => {
 			let t = e.composedPath()[0];
-			if (t instanceof HTMLElement && m(t)) return;
+			if (t instanceof HTMLElement && h(t)) return;
 			let n = this.shadowRoot?.querySelector(".main");
 			if (!n) return;
 			let r = n.clientHeight;
@@ -77,7 +78,7 @@ var h = class extends r {
 		};
 	}
 	static {
-		this.styles = [super.styles, i];
+		this.styles = [super.styles, a];
 	}
 	connectedCallback() {
 		super.connectedCallback(), window.addEventListener("route-begin", this.handleRouteBegin), window.addEventListener("route-done", this.handleRouteDone), window.addEventListener("route-progress", this.handleRouteProgress), window.addEventListener("route-error", this.handleRouteError), window.addEventListener("screen-resize", this.handleScreenResize);
@@ -89,7 +90,7 @@ var h = class extends r {
 		super.willUpdate(e), e.has("config") && (this.styles = this.config?.styles);
 	}
 	render() {
-		return this.config ? a`
+		return this.config ? o`
       <!-- Mobile Header -->
       <div class="mobile-header" part="mobile-header" ?hidden="${!this.state.startsWith("mobile")}">
         ${this.renderLogo()}
@@ -124,12 +125,12 @@ var h = class extends r {
 
         <!-- Sidebar Navigation Menu -->
         <nav class="sidebar-main" part="sidebar-main" scrollable>
-          ${f(this.config.main ?? [], (e, t) => t, (e) => this.renderItem(e))}
+          ${p(t(this.config.main ?? [], this.config.hasPermission), (e, t) => t, (e) => this.renderItem(e))}
         </nav>
 
         <!-- Sidebar Footer -->
         <div class="sidebar-footer" part="sidebar-footer">
-          ${f(this.config.footer ?? [], (e, t) => t, (e) => this.renderItem(e))}
+          ${p(t(this.config.footer ?? [], this.config.hasPermission), (e, t) => t, (e) => this.renderItem(e))}
         </div>
       </aside>
 
@@ -144,14 +145,15 @@ var h = class extends r {
       <div class="backdrop" ?hidden="${this.state !== "modal"}"
         @click="${this.handleBackdropClick}"
       ></div>
-    ` : o;
+    ` : s;
 	}
 	renderItem(e) {
-		if (!e) return o;
+		if (!e) return s;
 		if (e.type === "html") {
 			let t = e.render(this.state);
-			return typeof t == "string" ? d(t) : a`${t}`;
-		} else if (e.type === "button") return a`
+			return typeof t == "string" ? f(t) : o`${t}`;
+		}
+		if (e.type === "button") return o`
         <u-sidebar-button
           ?compact=${this.state === "slim"}
           .icon="${e.icon}"
@@ -160,9 +162,9 @@ var h = class extends r {
           @click="${e.onClick}"
         ></u-sidebar-button>
       `;
-		else if (e.type === "link") {
+		if (e.type === "link") {
 			let t = this.isMatchedLink(e.pattern || e.href);
-			return a`
+			return o`
         <u-sidebar-link
           ?compact=${this.state === "slim"}
           ?selected=${t}
@@ -173,18 +175,19 @@ var h = class extends r {
           .styles="${e.styles}"
         ></u-sidebar-link>
       `;
-		} else if (e.type === "section") return a`
+		}
+		if (e.type === "section") return o`
         <u-sidebar-section
           ?compact=${this.state === "slim"}
           .mainTitle="${e.title}"
           .subTitle="${e.subTitle}"
           .styles="${e.styles}">
-          ${f(e.items, (e, t) => t, (e) => this.renderItem(e))}
+          ${p(e.items, (e, t) => t, (e) => this.renderItem(e))}
         </u-sidebar-section>
       `;
-		else if (e.type === "group") {
+		if (e.type === "group") {
 			let t = e.items.some((e) => this.isMatchedLink(e.pattern || e.href));
-			return a`
+			return o`
         <u-sidebar-group
           ?compact=${this.state === "slim"}
           ?selected=${t}
@@ -192,14 +195,15 @@ var h = class extends r {
           .icon="${e.icon}"
           .label="${e.label}"
           .styles="${e.styles}">
-          ${f(e.items, (e, t) => t, (e) => this.renderItem(e))}
+          ${p(e.items, (e, t) => t, (e) => this.renderItem(e))}
         </u-sidebar-group>
       `;
-		} else return o;
+		}
+		return s;
 	}
 	renderLogo() {
 		let e = this.config?.logo;
-		if (!e || typeof e == "string") return a`
+		if (!e || typeof e == "string") return o`
         <u-icon class="logo"
           .name="${e}"
           @click=${this.handleBrandLogoClick()}
@@ -207,13 +211,13 @@ var h = class extends r {
       `;
 		if (typeof e == "function") {
 			let t = e(this.state);
-			return a`
+			return o`
         <span class="logo" @click=${this.handleBrandLogoClick()}>
-          ${typeof t == "string" ? d(t) : t}
+          ${typeof t == "string" ? f(t) : t}
         </span>
       `;
 		}
-		return a`
+		return o`
       <img class="logo"
         src="${e.src}"
         alt="${e.alt ?? ""}"
@@ -222,9 +226,9 @@ var h = class extends r {
     `;
 	}
 };
-n([c({
+r([l({
 	type: String,
 	reflect: !0
-}), t("design:type", Object)], h.prototype, "state", void 0), n([c({ type: Object }), t("design:type", Object)], h.prototype, "config", void 0), n([l("u-progress-bar"), t("design:type", p === void 0 ? Object : p)], h.prototype, "progressBarEl", void 0), n([u(), t("design:type", Object)], h.prototype, "context", void 0), h = n([s("u-sidebar-layout")], h);
+}), n("design:type", Object)], g.prototype, "state", void 0), r([l({ type: Object }), n("design:type", Object)], g.prototype, "config", void 0), r([u("u-progress-bar"), n("design:type", m === void 0 ? Object : m)], g.prototype, "progressBarEl", void 0), r([d(), n("design:type", Object)], g.prototype, "context", void 0), g = r([c("u-sidebar-layout")], g);
 //#endregion
-export { h as SidebarLayout };
+export { g as SidebarLayout };

package/dist/layouts/SidebarLayout.styles.js

@@ -16,12 +16,12 @@ var t = e`
   }
 
   .logo {
-    color: var(--u-txt-color);
+    color: var(--u-txt-color, #212121);
     font-size: 24px;
     cursor: pointer;
   }
   .logo:hover {
-    color: var(--u-txt-color-hover);
+    color: var(--u-txt-color-hover, #1E88E5);
   }
   img.logo {
     height: 24px;
@@ -31,7 +31,7 @@ var t = e`
 
   .title {
     flex: 1;
-    color: var(--u-txt-color);
+    color: var(--u-txt-color, #212121);
     font-size: 18px;
     line-height: 24px;
     font-weight: 700;
@@ -48,7 +48,7 @@ var t = e`
     background: transparent;
   }
   .toggler:hover {
-    color: var(--u-txt-color-hover);
+    color: var(--u-txt-color-hover, #1E88E5);
   }
 
   /* Sidebar Container */
@@ -60,16 +60,17 @@ var t = e`
     justify-content: space-between;
     gap: 8px;
     height: 100%;
-    background: var(--u-panel-bg-color);
-    border-right: 1px solid var(--u-border-color);
+    background: var(--app-sidebar-bg, var(--u-panel-bg-color, #FFFFFF));
+    color: var(--app-sidebar-fg, var(--u-txt-color, #212121));
+    border-right: 1px solid var(--u-border-color, #E0E0E0);
     transition: all 0.3s ease;
   }
   /* Sidebar states */
   .sidebar[state="default"] {
-    width: 260px;
+    width: var(--app-sidebar-width, 260px);
   }
   .sidebar[state="slim"] {
-    width: 64px;
+    width: var(--app-sidebar-width-slim, 64px);
   }
   .sidebar[state="slim"] .sidebar-header {
     flex-direction: column;
@@ -77,7 +78,7 @@ var t = e`
     padding: 16px;
   }
   .sidebar[state="modal"] {
-    width: 260px;
+    width: var(--app-sidebar-width, 260px);
     position: absolute;
     top: 0;
     left: 0;
@@ -107,8 +108,9 @@ var t = e`
     justify-content: space-between;
     gap: 12px;
     padding: 16px;
-    background: var(--u-panel-bg-color);
-    border-bottom: 1px solid var(--u-border-color-weak);
+    background: var(--app-header-bg, var(--u-panel-bg-color, #FFFFFF));
+    color: var(--app-header-fg, var(--u-txt-color, #212121));
+    border-bottom: 1px solid var(--u-border-color-weak, #EEEEEE);
     user-select: none;
   }
 
@@ -120,7 +122,7 @@ var t = e`
     justify-content: space-between;
     gap: 12px;
     padding: 16px;
-    border-bottom: 1px solid var(--u-border-color-weak);
+    border-bottom: 1px solid var(--u-border-color-weak, #EEEEEE);
     user-select: none;
   }
 
@@ -141,7 +143,7 @@ var t = e`
     flex-direction: column;
     gap: 4px;
     padding: 8px;
-    border-top: 1px solid var(--u-border-color-weak);
+    border-top: 1px solid var(--u-border-color-weak, #EEEEEE);
   }
   .sidebar-footer:empty {
     display: none;
@@ -151,14 +153,14 @@ var t = e`
   .main {
     position: relative;
     flex: 1;
-    background: var(--u-bg-color);
+    background: var(--u-bg-color, #FFFFFF);
     overflow: auto;
     outline: none;
   }
 
   .main u-progress-bar {
     --progress-bar-height: 4px;
-    --progres-bar-track-color: transparent;
+    --progress-bar-track-color: transparent;
     
     position: absolute;
     z-index: 100;
@@ -174,9 +176,6 @@ var t = e`
     opacity: 1;
     transform: translateY(0);
   }
-  .main u-progress-bar[error] {
-    --progress-bar-color: var(--u-red-500);
-  }
 
   /* Backdrop for modal mode */
   .backdrop {
@@ -186,7 +185,7 @@ var t = e`
     left: 0;
     right: 0;
     bottom: 0;
-    background: var(--u-overlay-bg-color);
+    background: var(--u-overlay-bg-color, rgba(0, 0, 0, 0.5));
   }
 `;
 //#endregion

package/dist/layouts/SidebarLayout.types.d.ts

@@ -4,12 +4,14 @@ import { SidebarLinkConfig } from '../components/SidebarLink';
 import { SidebarSectionConfig } from '../components/SidebarSection';
 import { SidebarGroupConfig } from '../components/SidebarGroup';
 import { SidebarButtonConfig } from '../components/SidebarButton';
+import { SidebarPermissionGuard } from './SidebarPermission';
+export type { SidebarPermissionGuard } from './SidebarPermission';
 /** 사이드바 레이아웃 컴포넌트의 요소(part) 타입 */
 export type SidebarParts = 'host' | 'mobile-header' | 'sidebar' | 'sidebar-header' | 'sidebar-main' | 'sidebar-footer' | 'main' | 'progress';
 /** 사이드바 상태 타입 */
 export type SidebarState = 'default' | 'slim' | 'modal' | 'mobile' | 'mobile-open';
 /** 사이드바 안에 HTML 또는 엘리먼트를 직접 렌더링하는 설정 */
-export interface SidebarHtmlConfig {
+export interface SidebarHtmlConfig extends SidebarPermissionGuard {
     type: 'html';
     render: (state: SidebarState) => TemplateResult<1> | HTMLElement | string;
 }
@@ -36,6 +38,12 @@ export interface SidebarLayoutConfig {
     main?: SidebarItem[];
     /** 하단(footer)에 고정해서 렌더할 항목들 */
     footer?: SidebarItem[];
+    /**
+     * 메뉴 항목 권한 필터 판정. 지정하면 `requirePermission`/`requireAnyPermission` 를 만족하지
+     * 않는 항목을 숨기고, 항목이 모두 걸러진 section/group 은 통째로 숨긴다.
+     * 미지정 시 필터링하지 않는다(모든 항목 표시). 보통 `@iyulab/enterprise` 의 `hasPermission` 을 넘긴다.
+     */
+    hasPermission?: (code: string) => boolean;
     /** 사이드바 스타일 맵 */
     styles?: StyleMap<SidebarParts>;
 }

package/dist/layouts/SidebarPermission.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 사이드바 메뉴 항목의 권한 가드. 모든 메뉴 config(link/section/group/button/html)가 확장한다.
+ *
+ * 판정 자체는 `SidebarLayoutConfig.hasPermission` 으로 **주입**한다 — 라이브러리는 권한 코드를
+ * 불투명 문자열로만 다루고 의미(도메인)는 앱이 소유한다. `@iyulab/enterprise` 의 `hasPermission`
+ * 을 그대로 넘겨 쓰는 것이 일반적이다.
+ *
+ * 의존성 없는 leaf 모듈 — 각 메뉴 config 파일이 순환 없이 import 한다.
+ */
+export interface SidebarPermissionGuard {
+    /** 이 권한 코드를 보유해야 항목이 표시된다. */
+    requirePermission?: string;
+    /** 이 코드 중 하나라도 보유하면 표시된다(빈 배열은 제약 없음). */
+    requireAnyPermission?: string[];
+}

package/dist/layouts/filterSidebarItems.d.ts

@@ -0,0 +1,11 @@
+import { SidebarItem } from './SidebarLayout.types';
+/**
+ * 권한에 따라 사이드바 메뉴 트리를 필터링한다. 소비앱이 손으로 짜던 `filterMenu` 를 표준화.
+ *
+ * - 각 항목의 `requirePermission`/`requireAnyPermission` 를 `hasPermission` 으로 검사해 탈락 항목 제거.
+ * - `section`/`group` 은 자식(`items`)을 재귀 필터하고, **자식이 모두 걸러지면 컨테이너째 제거**한다.
+ * - `hasPermission` 이 없으면(undefined) 원본을 그대로 반환한다(필터링 없음).
+ *
+ * 원본 배열/항목을 변형하지 않고 새 배열/얕은 복제본을 반환한다(순수).
+ */
+export declare function filterSidebarItems(items: readonly SidebarItem[], hasPermission?: (code: string) => boolean): SidebarItem[];

package/dist/layouts/filterSidebarItems.js

@@ -0,0 +1,19 @@
+//#region src/layouts/filterSidebarItems.ts
+function e(e, t) {
+	return !(e.requirePermission && !t(e.requirePermission) || e.requireAnyPermission && e.requireAnyPermission.length > 0 && !e.requireAnyPermission.some((e) => t(e)));
+}
+function t(n, r) {
+	if (!r) return n;
+	let i = r, a = [];
+	for (let r of n) if (r && e(r, i)) if (r.type === "section" || r.type === "group") {
+		let e = t(r.items, i);
+		if (e.length === 0) continue;
+		a.push({
+			...r,
+			items: e
+		});
+	} else a.push(r);
+	return a;
+}
+//#endregion
+export { t as filterSidebarItems };

package/dist/types/AppConfigs.d.ts

@@ -1,7 +1,8 @@
 import { InitOptions, Module, Newable, NewableModule } from 'i18next';
-import { RouteConfig, FallbackRouteConfig } from '@iyulab/router';
+import { RouteConfig, FallbackRouteConfig, RouteContext } from '@iyulab/router';
 import { ThemeInitOptions } from '@iyulab/components/dist/utilities/Theme.js';
 import { SidebarLayoutConfig } from '../layouts/SidebarLayout.types';
+import { AuthGateConfig } from './AuthConfig';
 /**
  * i18next의 초기화 옵션과 플러그인 배열을 포함한 다국어 설정
  */
@@ -45,6 +46,33 @@ export interface AppConfig {
      * 라우팅 실패 시 대체 컨텐츠 설정
      */
     fallback?: FallbackRouteConfig;
+    /**
+     * 모든 라우트 전환 전에 호출되는 전역 인증/권한 가드입니다.
+     * - `string` 반환: 해당 경로로 redirect
+     * - `false` 반환: 네비게이션 취소(403)
+     * - `true`/무반환: 통과
+     * @example
+     * ```typescript
+     * app.load({
+     *   enter: (ctx) => isAuthenticated() || `/login?returnTo=${encodeURIComponent(ctx.pathname)}`,
+     *   routes: [
+     *     { path: '/login', render: () => html`<login-page></login-page>` },
+     *     // ...
+     *   ],
+     * });
+     * ```
+     */
+    enter?: (ctx: RouteContext) => Promise<string | boolean> | string | boolean;
+    /**
+     * 초기 로드 시 현재 URL로 라우팅을 자동으로 수행할지 여부를 설정합니다.
+     * @default true
+     */
+    initialLoad?: boolean;
+    /**
+     * `a` 태그 클릭 시 클라이언트 라우팅을 수행할지 여부를 설정합니다.
+     * @default true
+     */
+    useIntercept?: boolean;
     /**
      * 애플리케이션이 렌더링될 루트 HTML 요소
      * @default document.body
@@ -65,4 +93,22 @@ export interface AppConfig {
      * @see 설정에 대한 자세한 내용은 {@link https://www.i18next.com/overview/configuration-options} 참조하십시오.
      */
     i18n?: I18nInitOptions;
+    /**
+     * 부팅 인증 게이트(선택). 지정하면 앱 셸을 만들기 전에 `me()` 로 세션을 판정하여
+     * 인증 시 셸 로드, 미인증 시 `renderLogin` 으로 로그인 UI 를 띄운다.
+     * @see AuthGateConfig
+     * @example
+     * ```typescript
+     * app.load({
+     *   layout: { type: 'sidebar', ... },
+     *   auth: {
+     *     me: () => authClient.fetchMe(),                 // null → 미인증
+     *     renderLogin: ({ root, onSuccess }) => renderLoginPage(root, onSuccess),
+     *     onAuthenticated: (user) => setPermissions((user as User).Permissions),
+     *   },
+     *   routes: [ ... ],
+     * });
+     * ```
+     */
+    auth?: AuthGateConfig;
 }

package/dist/types/AuthConfig.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 부팅 인증 게이트 설정.
+ *
+ * `app.load({ auth })` 에 넘기면, 앱 셸(레이아웃·라우터)을 만들기 전에 세션을 판정한다:
+ * `me()` 가 값을 반환하면 인증된 것으로 보고 셸을 로드하고, `null`/`undefined` 면
+ * 미인증으로 보고 `renderLogin` 으로 로그인 UI 를 띄운다. 로그인 성공 시 `onSuccess()` 를
+ * 호출하면 앱이 (재)로드되어 셸이 나타난다.
+ *
+ * 프레임워크는 인증의 **오케스트레이션**(판정 → 분기 → 재로드)만 소유한다. 세션 조회/로그인
+ * 자체(HTTP)와 사용자·권한 형태, 세션-중 401 처리는 앱/`@iyulab/enterprise` 가 소유한다.
+ */
+export interface AuthGateContext {
+    /** 로그인 UI 를 그릴 루트 요소(= `app.load` 의 `root`, 기본 `document.body`). */
+    root: Element;
+    /** 로그인 성공 시 호출한다. 앱이 (재)로드되어 셸을 띄운다(이때 `me()` 는 사용자를 반환해야 한다). */
+    onSuccess: () => void;
+}
+export interface AuthGateConfig {
+    /**
+     * 현재 세션 조회. 값을 반환하면 인증, `null`/`undefined` 면 미인증으로 본다.
+     * 동기/비동기 모두 허용한다.
+     */
+    me: () => Promise<unknown | null | undefined> | unknown | null | undefined;
+    /**
+     * 미인증 시 `context.root` 에 로그인 UI 를 그린다. 성공하면 `context.onSuccess()` 를 호출해야 한다.
+     * 정리 함수를 반환하면 앱 로드/`unload` 시 호출되어 로그인 UI 를 제거한다.
+     */
+    renderLogin: (context: AuthGateContext) => (() => void) | void;
+    /**
+     * 인증 성공 후, 앱 셸을 만들기 직전에 호출된다(선택).
+     * 사용자별 라우트/메뉴 필터 등 셸 구성 전 처리를 여기서 한다.
+     */
+    onAuthenticated?: (user: unknown) => void | Promise<void>;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/modern-app",
   "description": "web-framework by iyulab based on lit-element",
-  "version": "0.4.0",
+  "version": "0.8.0",
   "keywords": [
     "iyulab",
     "web-framework",
@@ -34,19 +34,25 @@
     }
   },
   "scripts": {
-    "test": "vite",
-    "build": "vite build"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "start": "vite",
+    "build": "vite build",
+    "test:browser": "vitest run --project=browser"
   },
   "dependencies": {
-    "@iyulab/components": "^1.1.1",
-    "@iyulab/router": "^0.10.0",
-    "i18next": "^26.2.0",
+    "@iyulab/components": "^1.8.0",
+    "@iyulab/router": "^0.10.2",
+    "i18next": "^26.3.6",
     "lit": "^3.3.3"
   },
   "devDependencies": {
-    "@types/node": "^25.8.0",
+    "@types/node": "^26.1.1",
+    "@vitest/browser-playwright": "^4.1.10",
+    "happy-dom": "^20.10.6",
     "typescript": "^5.9.3",
-    "vite": "^8.0.13",
-    "vite-plugin-dts": "^5.0.0"
+    "vite": "^8.1.4",
+    "vite-plugin-dts": "^5.0.3",
+    "vitest": "^4.1.10"
   }
 }