@iyulab/modern-app 0.44.3 → 0.46.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [0.46.0] - 2026-10-08
+
+### Added
+
+- **`u-empty-state variant="no-access"`** — a screen this user may not see (a route `enter` guard returned
+  `false`). It is the fourth fact next to `no-data`, `no-results` and `error`, with its own next step (asking for
+  access) and its own default wording (English and Korean built in, `noAccessTitle`/`noAccessDescription` in
+  `modernAppLocale`). Unlike `error` it is not announced as an alert — a 403 is not an outage.
+- **The router's error classes and route types are exported from this package** — `RouteError`,
+  `AccessDeniedError`, `NotFoundError`, `ContentLoadError`, `ContentRenderError`, `OutletMissingError` and the
+  `RouteConfig`/`RouteContext`/`FallbackRouteConfig` types. A `fallback.render(ctx)` can tell a blocked screen from a
+  missing one (`ctx.error instanceof AccessDeniedError`) without declaring `@iyulab/router` itself.
+- `EmptyStateVariant` type.
+
+### Fixed
+
+- The React `IntrinsicElements` entry for `<u-empty-state>` (from `@iyulab/modern-app/react`) accepted only
+  `no-data` and `no-results`, so `variant="error"` did not type-check in JSX. It now uses the element's own type.
+
+## [0.45.0] - 2026-10-08
+
+### Changed (breaking)
+
+- **The boot auth gate reads `me()`'s answer by `status`.** `me()` returns an `AuthSession` —
+  `{ status: 'authenticated', user }`, `{ status: 'anonymous' }` or `{ status: 'unknown', error }` — the same shape
+  `@iyulab/enterprise`'s `createAuthClient().fetchMe()` returns, so the two connect as `me: () => auth.fetchMe()`.
+  Before, any value meant "signed in": a session client that answers "signed out" with an object (`fetchMe()` gives
+  `{ status: 'anonymous' }` on a 401) opened the shell to a user who had not signed in, with that object as
+  `app.user` — and `me`'s `unknown` return type let it type-check.
+  `anonymous` renders `renderLogin`; `unknown` (or `me()` throwing) renders `renderUnavailable` with the answer's
+  `error`. An answer whose `status` is not one of the three makes `app.load()` reject with a `TypeError` instead of
+  being guessed to mean signed in.
+  **Migrating:** return `{ status: 'authenticated', user }` where you returned the user and `{ status: 'anonymous' }`
+  where you returned `null`; with `@iyulab/enterprise`, drop the adapter and pass `auth.fetchMe` through.
+
 ## [0.44.3] - 2026-10-08
 
 ### Fixed

package/README.md

@@ -184,11 +184,7 @@ const auth = createAuthClient<User, Cred>({ meUrl: '/api/auth/me', loginUrl: '/a
 await app.load({
   layout: { type: 'sidebar', /* ... */ },
   auth: {
-    me: async () => {
-      const s = await auth.fetchMe();
-      if (s.status === 'unknown') throw s.error;      // 모름(서버 다운·오프라인) → renderUnavailable
-      return s.status === 'authenticated' ? s.user : null; // null → 미인증 → renderLogin
-    },
+    me: () => auth.fetchMe(),   // SessionState: authenticated · anonymous → renderLogin · unknown → renderUnavailable
     renderLogin: ({ root, onSuccess }) => renderLoginPage(root, auth, onSuccess),
     renderUnavailable: ({ root, retry }) => renderOfflinePage(root, retry),
     onAuthenticated: (user) => setPermissions((user as User).Permissions),
@@ -199,8 +195,9 @@ await app.load({
 app.user; // 인증된 현재 사용자(미인증/미사용 시 undefined)
 ```
 
-- `me()` 가 값을 반환하면 셸 로드, `null`/`undefined` 면 `renderLogin({ root, onSuccess })`.
-- `me()` 가 **던지면** 세션을 «모름» 으로 보고 로그인 UI 를 그리지 않는다 — `renderUnavailable({ root, error, retry })` 를 그리고, 없으면 `app.load()` 가 그 오류로 실패한다. 서버가 잠깐 503 을 낸 것을 «미인증» 으로 돌려주면 로그인된 사용자가 로그인 화면으로 간다.
+- `me()` 는 `AuthSession` — `{ status: 'authenticated', user }` · `{ status: 'anonymous' }` · `{ status: 'unknown', error }` — 을 돌려준다. `authenticated` 면 셸을 로드하고 `app.user` 는 `user` 다. `anonymous` 면 `renderLogin({ root, onSuccess })`.
+- `unknown`(또는 `me()` 가 **던짐**)이면 세션을 «모름» 으로 보고 로그인 UI 를 그리지 않는다 — `renderUnavailable({ root, error, retry })` 를 그리고, 없으면 `app.load()` 가 그 오류로 실패한다. 서버가 잠깐 503 을 낸 것을 «미인증» 으로 다루면 로그인된 사용자가 로그인 화면으로 간다.
+- `status` 가 셋 중 하나가 아닌 답(사용자 객체 · `null`)은 `app.load()` 가 `TypeError` 로 거절한다 — 인증으로 추측하지 않는다.
 - 로그인 성공 시 `onSuccess()` 를 호출하면 앱이 재로드되어 셸이 나타나고 로그인 UI 는 정리된다.
 - `auth` 미지정 시 완전히 하위호환(게이트 없이 기존대로 로드).
 

package/dist/App.js

@@ -52,17 +52,23 @@ var u = class s {
 			}, n;
 			try {
 				n = await a.auth.me();
-			} catch (n) {
-				if (!a.auth.renderUnavailable) throw n;
+			} catch (e) {
+				n = {
+					status: "unknown",
+					error: e
+				};
+			}
+			if (n?.status === "unknown") {
+				if (!a.auth.renderUnavailable) throw n.error;
 				let r = a.auth.renderUnavailable({
 					root: e,
-					error: n,
+					error: n.error,
 					retry: t
 				});
 				r && (this._gateTeardown = r);
 				return;
 			}
-			if (n == null) {
+			if (n?.status === "anonymous") {
 				let n = a.auth.renderLogin({
 					root: e,
 					onSuccess: t
@@ -70,7 +76,8 @@ var u = class s {
 				n && (this._gateTeardown = n);
 				return;
 			}
-			this._user = n, await a.auth.onAuthenticated?.(n);
+			if (n?.status !== "authenticated") throw TypeError("auth.me() must return { status: 'authenticated', user } | { status: 'anonymous' } | { status: 'unknown', error }");
+			this._user = n.user, await a.auth.onAuthenticated?.(n.user);
 		}
 		let o = a.root || document.body;
 		this._layout = await this.createLayout(o, a.layout), this._screen = new e({

package/dist/components/EmptyState.d.ts

@@ -1,5 +1,7 @@
 import { StyledElement } from '../internals/StyledElement.js';
 type ElementParts = 'host' | 'icon' | 'message' | 'title' | 'description' | 'actions';
+/** 빈 상태가 전하는 사실 — 다음 행동이 갈린다(`EmptyState.variant` 참조). */
+export type EmptyStateVariant = 'no-data' | 'no-results' | 'error' | 'no-access';
 /**
  * 빈 상태 — 목록·검색 결과가 비었을 때.
  *
@@ -19,6 +21,9 @@ type ElementParts = 'host' | 'icon' | 'message' | 'title' | 'description' | 'act
  * <u-empty-state variant="error" .description=${error.message}>
  *   <u-button slot="actions" @click=${retry}>Try again</u-button>
  * </u-empty-state>
+ *
+ * <!-- 라우트 가드가 막았다(403) — 장애가 아니라 권한의 사실이다. -->
+ * <u-empty-state variant="no-access"></u-empty-state>
  * ```
  *
  * ⚠**기본 문구는 영어다** — 이 패키지는 범용 층이라 특정 언어를 기본값으로 가질 수 없다.
@@ -32,10 +37,12 @@ type ElementParts = 'host' | 'icon' | 'message' | 'title' | 'description' | 'act
 export declare class EmptyState extends StyledElement<ElementParts> {
     static styles: import('lit').CSSResultGroup[];
     /**
-     * `no-data` = 아직 없음 / `no-results` = 조건에 맞는 것이 없음 / `error` = 불러오지 못함.
-     * 셋은 다음 행동이 다르다(만들기 · 조건 바꾸기 · 다시 시도) — `error` 의 제목은 보조기기에 알린다(`role="alert"`).
+     * `no-data` = 아직 없음 / `no-results` = 조건에 맞는 것이 없음 / `error` = 불러오지 못함 /
+     * `no-access` = 있지만 이 사용자에게 보여 줄 수 없음(라우트 가드의 거부 · 403).
+     * 넷은 다음 행동이 다르다(만들기 · 조건 바꾸기 · 다시 시도 · 권한 요청) — `error` 의 제목은 보조기기에 알린다(`role="alert"`).
+     * `no-access` 는 알리지 않는다 — 장애가 아니라 화면의 내용이고, 라우트 완료 때 본문으로 가는 포커스가 그것을 읽게 한다.
      */
-    variant: 'no-data' | 'no-results' | 'error';
+    variant: EmptyStateVariant;
     /** 제목. 비우면 variant 기본 문구. */
     title: string;
     /** 보조 설명. 비우면 variant 기본 문구. */

package/dist/components/EmptyState.js

@@ -16,19 +16,28 @@ var d = class extends n {
 	}
 	get defaults() {
 		let e = r(this.locale || void 0);
-		return this.variant === "error" ? {
-			icon: "⚠️",
-			title: e.errorTitle,
-			description: e.errorDescription
-		} : this.variant === "no-results" ? {
-			icon: "🔍",
-			title: e.noResultsTitle,
-			description: e.noResultsDescription
-		} : {
-			icon: "📄",
-			title: e.noDataTitle,
-			description: e.noDataDescription
-		};
+		switch (this.variant) {
+			case "error": return {
+				icon: "⚠️",
+				title: e.errorTitle,
+				description: e.errorDescription
+			};
+			case "no-access": return {
+				icon: "🔒",
+				title: e.noAccessTitle,
+				description: e.noAccessDescription
+			};
+			case "no-results": return {
+				icon: "🔍",
+				title: e.noResultsTitle,
+				description: e.noResultsDescription
+			};
+			default: return {
+				icon: "📄",
+				title: e.noDataTitle,
+				description: e.noDataDescription
+			};
+		}
 	}
 	render() {
 		let e = this.defaults, t = this.description || e.description;
@@ -53,6 +62,6 @@ var d = class extends n {
 t([l({
 	type: String,
 	reflect: !0
-}), e("design:type", String)], d.prototype, "variant", void 0), t([l({ type: String }), e("design:type", Object)], d.prototype, "title", void 0), t([l({ type: String }), e("design:type", Object)], d.prototype, "description", void 0), t([l({ type: String }), e("design:type", Object)], d.prototype, "locale", void 0), t([u(), e("design:type", Object)], d.prototype, "hasActions", void 0), d = t([c("u-empty-state")], d);
+}), e("design:type", Object)], d.prototype, "variant", void 0), t([l({ type: String }), e("design:type", Object)], d.prototype, "title", void 0), t([l({ type: String }), e("design:type", Object)], d.prototype, "description", void 0), t([l({ type: String }), e("design:type", Object)], d.prototype, "locale", void 0), t([u(), e("design:type", Object)], d.prototype, "hasActions", void 0), d = t([c("u-empty-state")], d);
 //#endregion
 export { d as EmptyState };

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export type * from './types/AppConfigs';
 export type * from './types/AppOptions';
 export type * from './types/AuthConfig';
 export type { SidebarPermissionGuard } from './layouts/SidebarPermission';
+export type { RouteConfig, RouteContext, FallbackRouteConfig } from '@iyulab/router';
+export { RouteError, NotFoundError, AccessDeniedError, ContentLoadError, ContentRenderError, OutletMissingError, } from '@iyulab/router';
 export type { SidebarIconsConfig, SidebarLayoutConfig, SidebarItem, SidebarLogoConfig, SidebarLinkConfig, SidebarSectionConfig, SidebarGroupConfig, SidebarButtonConfig, SidebarMenuConfig, SidebarMenuItemConfig, SidebarHtmlConfig, SidebarState, } from './layouts/SidebarLayout.types';
 export type { SidebarLayoutEventMap } from './layouts/SidebarLayout.js';
 export { filterSidebarItems } from './layouts/filterSidebarItems.js';

package/dist/index.js

@@ -13,7 +13,8 @@ import { ActionBar as g } from "./components/ActionBar.js";
 import { MasterDetailLayout as _ } from "./components/MasterDetailLayout.js";
 import { Wizard as v } from "./components/Wizard.js";
 import { translate as y } from "./translate.js";
+import { AccessDeniedError as b, ContentLoadError as x, ContentRenderError as S, NotFoundError as C, OutletMissingError as w, RouteError as T } from "@iyulab/router";
 //#region src/index.ts
-var b = t;
+var E = t;
 //#endregion
-export { g as ActionBar, p as EmptyState, l as GroupBox, d as InfoField, u as InfoSection, _ as MasterDetailLayout, c as PageHeader, e as ScreenObserver, h as Timeline, m as TimelineItem, v as Wizard, t as app, b as default, n as filterSidebarItems, r as getDefaultLocale, i as getLocaleStrings, f as isBlank, a as modernAppLocale, o as registerLocale, s as setDefaultLocale, y as translate };
+export { b as AccessDeniedError, g as ActionBar, x as ContentLoadError, S as ContentRenderError, p as EmptyState, l as GroupBox, d as InfoField, u as InfoSection, _ as MasterDetailLayout, C as NotFoundError, w as OutletMissingError, c as PageHeader, T as RouteError, e as ScreenObserver, h as Timeline, m as TimelineItem, v as Wizard, t as app, E as default, n as filterSidebarItems, r as getDefaultLocale, i as getLocaleStrings, f as isBlank, a as modernAppLocale, o as registerLocale, s as setDefaultLocale, y as translate };

package/dist/internals/locale.d.ts

@@ -10,6 +10,9 @@ export interface ModernAppLocaleStrings {
     /** Empty state — the list could not be loaded (`variant="error"`). */
     errorTitle: string;
     errorDescription: string;
+    /** Empty state — the screen exists but this user may not see it (`variant="no-access"` — a route guard said no). */
+    noAccessTitle: string;
+    noAccessDescription: string;
     /** Accessible label for an overlay-mode close button (master-detail layout, sidebar layout overlay). */
     detailClose: string;
     /** Sidebar layout — accessible label for the mobile-header menu toggle button. */

package/dist/internals/locale.js

@@ -8,6 +8,8 @@ var t = {
 	noResultsDescription: "Try changing your search terms or filters.",
 	errorTitle: "Couldn’t load this list",
 	errorDescription: "Something went wrong while loading. Try again.",
+	noAccessTitle: "You don’t have access",
+	noAccessDescription: "Ask an administrator for access if you need it.",
 	detailClose: "Close",
 	toggleMobileMenu: "Toggle menu",
 	toggleSidebar: "Toggle sidebar",
@@ -26,6 +28,8 @@ n.register("en", t), n.register("ko", {
 	noResultsDescription: "검색어나 필터를 바꿔 보세요.",
 	errorTitle: "목록을 불러오지 못했습니다",
 	errorDescription: "불러오는 중 문제가 생겼습니다. 다시 시도해 주세요.",
+	noAccessTitle: "접근 권한이 없습니다",
+	noAccessDescription: "필요하면 관리자에게 권한을 요청하세요.",
 	detailClose: "닫기",
 	toggleMobileMenu: "메뉴 열고 닫기",
 	toggleSidebar: "사이드바 열고 닫기",
@@ -62,6 +66,8 @@ function l(e) {
 		noResultsDescription: t("noResultsDescription"),
 		errorTitle: t("errorTitle"),
 		errorDescription: t("errorDescription"),
+		noAccessTitle: t("noAccessTitle"),
+		noAccessDescription: t("noAccessDescription"),
 		detailClose: t("detailClose"),
 		toggleMobileMenu: t("toggleMobileMenu"),
 		toggleSidebar: t("toggleSidebar"),

package/dist/react.d.ts

@@ -3,6 +3,7 @@ import { EventName } from '@lit/react';
 import { SidebarLayout as SidebarLayoutElement, SidebarLayoutEventMap } from './layouts/SidebarLayout.js';
 import { Wizard as WizardElement, WizardEventMap } from './components/Wizard.js';
 import { GroupBoxLevel } from './components/GroupBox.js';
+import { EmptyStateVariant } from './components/EmptyState.js';
 import { TimelineItemColor } from './components/TimelineItem.js';
 import { InfoFieldFormat, InfoFieldSize, InfoFieldTrend, InfoFieldTone } from './components/InfoField.js';
 export { ScreenObserver } from './internals/ScreenObserver.js';
@@ -37,7 +38,8 @@ declare module 'react' {
                 sticky?: boolean;
             };
             'u-empty-state': React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
-                variant?: 'no-data' | 'no-results';
+                /** 요소의 유니온을 그대로 쓴다 — 손으로 옮긴 유니온이 `'error'` 를 빠뜨린 채 남아 있었다. */
+                variant?: EmptyStateVariant;
                 title?: string;
                 description?: string;
                 locale?: string;

package/dist/types/AppConfigs.d.ts

@@ -101,8 +101,8 @@ export interface AppConfig {
      */
     i18n?: I18nInitOptions;
     /**
-     * 부팅 인증 게이트(선택). 지정하면 앱 셸을 만들기 전에 `me()` 로 세션을 판정하여
-     * 인증 시 셸 로드, 미인증 시 `renderLogin` 으로 로그인 UI 를 띄운다. `me()` 가 던지면(세션 모름)
+     * 부팅 인증 게이트(선택). 지정하면 앱 셸을 만들기 전에 `me()` 의 답(`AuthSession`)으로 세션을 판정하여
+     * `authenticated` 면 셸 로드, `anonymous` 면 `renderLogin` 으로 로그인 UI, `unknown`(또는 `me()` 가 던짐)이면
      * `renderUnavailable` 을 그린다.
      * @see AuthGateConfig
      * @example
@@ -110,11 +110,7 @@ export interface AppConfig {
      * app.load({
      *   layout: { type: 'sidebar', ... },
      *   auth: {
-     *     me: async () => {                               // @iyulab/enterprise createAuthClient
-     *       const s = await authClient.fetchMe();
-     *       if (s.status === 'unknown') throw s.error;    // 모름 — 로그인이 아니라 renderUnavailable
-     *       return s.status === 'authenticated' ? s.user : null; // null → 미인증
-     *     },
+     *     me: () => authClient.fetchMe(),                 // @iyulab/enterprise createAuthClient — SessionState 그대로
      *     renderLogin: ({ root, onSuccess }) => renderLoginPage(root, onSuccess),
      *     renderUnavailable: ({ root, retry }) => renderOfflinePage(root, retry),
      *     onAuthenticated: (user) => setPermissions((user as User).Permissions),

package/dist/types/AuthConfig.d.ts

@@ -1,12 +1,17 @@
 /**
  * 부팅 인증 게이트 설정.
  *
- * `app.load({ auth })` 에 넘기면, 앱 셸(레이아웃·라우터)을 만들기 전에 세션을 판정한다:
- * `me()` 가 값을 반환하면 인증된 것으로 보고 셸을 로드하고, `null`/`undefined` 면
- * 미인증으로 보고 `renderLogin` 으로 로그인 UI 를 띄운다. 로그인 성공 시 `onSuccess()` 를
- * 호출하면 앱이 (재)로드되어 셸이 나타난다. `me()` 가 **던지면** 세션을 «모름»(서버 다운·오프라인)
- * 으로 보고 로그인 UI 를 그리지 않는다 — `renderUnavailable` 이 있으면 그것을, 없으면 `load` 가 그
- * 오류로 실패한다.
+ * `app.load({ auth })` 에 넘기면, 앱 셸(레이아웃·라우터)을 만들기 전에 세션을 판정한다. `me()` 는
+ * 세 답 중 하나(`AuthSession`)를 돌려준다:
+ * - `authenticated` — 셸을 로드한다(`user` 가 `app.user` 가 된다).
+ * - `anonymous` — 셸 대신 `renderLogin` 으로 로그인 UI 를 띄운다. 로그인 성공 시 `onSuccess()` 를
+ *   호출하면 앱이 (재)로드되어 셸이 나타난다.
+ * - `unknown` — 세션을 확인하지 못했다(서버 다운·오프라인). 미인증이 아니므로 로그인 UI 를 그리지
+ *   않는다 — `renderUnavailable` 이 있으면 그것을, 없으면 `load` 가 그 오류로 실패한다. `me()` 가
+ *   **던지는** 것도 같은 답이다.
+ *
+ * `@iyulab/enterprise` 의 `createAuthClient().fetchMe()` 가 돌려주는 `SessionState` 가 이 형태 그대로라
+ * `me: () => auth.fetchMe()` 로 잇는다.
  *
  * 프레임워크는 인증의 **오케스트레이션**(판정 → 분기 → 재로드)만 소유한다. 세션 조회/로그인
  * 자체(HTTP)와 사용자·권한 형태, 세션-중 401 처리는 앱/`@iyulab/enterprise` 가 소유한다.
@@ -14,33 +19,46 @@
 export interface AuthGateContext {
     /** 로그인 UI 를 그릴 루트 요소(= `app.load` 의 `root`, 기본 `document.body`). */
     root: Element;
-    /** 로그인 성공 시 호출한다. 앱이 (재)로드되어 셸을 띄운다(이때 `me()` 는 사용자를 반환해야 한다). */
+    /** 로그인 성공 시 호출한다. 앱이 (재)로드되어 셸을 띄운다(이때 `me()` 는 `authenticated` 를 돌려줘야 한다). */
     onSuccess: () => void;
 }
 /** `renderUnavailable` 이 받는 맥락 — 세션을 확인하지 못했을 때. */
 export interface AuthGateUnavailableContext {
     /** 안내 UI 를 그릴 루트 요소(= `app.load` 의 `root`, 기본 `document.body`). */
     root: Element;
-    /** `me()` 가 던진 값. */
+    /** `unknown` 답의 `error`, 또는 `me()` 가 던진 값. */
     error: unknown;
     /** 다시 확인한다 — 앱이 (재)로드되어 `me()` 를 다시 부른다(재시도 버튼·`online` 이벤트에서). */
     retry: () => void;
 }
+/**
+ * 세션 조회의 답 — `status` 로 가른다. «미인증»과 «모름»은 다른 답이다: 서버가 잠깐 503 을 낸 것을
+ * 미인증으로 다루면 로그인된 사용자가 로그인 화면으로 간다.
+ */
+export type AuthSession<TUser = unknown> = {
+    status: 'authenticated';
+    user: TUser;
+} | {
+    status: 'anonymous';
+} | {
+    status: 'unknown';
+    error: unknown;
+};
 export interface AuthGateConfig {
     /**
-     * 현재 세션 조회. 값을 반환하면 인증, `null`/`undefined` 면 미인증으로 본다. **세션을 확인하지
-     * 못했으면 던진다**(서버 다운·오프라인) — 그것을 `null` 로 돌려주면 로그인된 사용자가 로그인 화면으로 간다.
-     * 동기/비동기 모두 허용한다.
+     * 현재 세션 조회 — `AuthSession` 을 돌려준다(동기/비동기 모두 허용). 던지면 `unknown` 으로 본다.
+     * `status` 가 셋 중 하나가 아닌 값을 돌려주면 `load` 가 `TypeError` 로 실패한다 — 사용자 객체를 그대로
+     * 돌려주는 옛 형태를 «인증됨»으로 추측하지 않는다.
      */
-    me: () => Promise<unknown | null | undefined> | unknown | null | undefined;
+    me: () => AuthSession | Promise<AuthSession>;
     /**
      * 미인증 시 `context.root` 에 로그인 UI 를 그린다. 성공하면 `context.onSuccess()` 를 호출해야 한다.
      * 정리 함수를 반환하면 앱 로드/`unload` 시 호출되어 로그인 UI 를 제거한다.
      */
     renderLogin: (context: AuthGateContext) => (() => void) | void;
     /**
-     * `me()` 가 던졌을 때(세션 모름) `context.root` 에 안내 UI 를 그린다(선택). `context.retry()` 로 다시
-     * 확인한다. 정리 함수를 반환하면 앱 로드/`unload` 시 호출된다. 없으면 `load` 가 `me()` 의 오류로 실패한다.
+     * 세션을 모를 때(`unknown` · `me()` 가 던짐) `context.root` 에 안내 UI 를 그린다(선택). `context.retry()` 로
+     * 다시 확인한다. 정리 함수를 반환하면 앱 로드/`unload` 시 호출된다. 없으면 `load` 가 그 오류로 실패한다.
      */
     renderUnavailable?: (context: AuthGateUnavailableContext) => (() => void) | void;
     /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/modern-app",
   "description": "web-framework by iyulab based on lit-element",
-  "version": "0.44.3",
+  "version": "0.46.0",
   "keywords": [
     "iyulab",
     "web-framework",
@@ -81,8 +81,8 @@
     "@iyulab/components": ">=2.8.0",
     "@lit/react": "^1.0.8",
     "@types/node": "^26.1.1",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@vitest/browser-playwright": "^5.0.0",
     "glob": "^13.0.6",
     "happy-dom": "^20.10.6",

package/skills/modern-app/references/api.md

@@ -190,8 +190,11 @@ interface FallbackRouteConfig {
 }
 ```
 
-`RouteError` is importable from `@iyulab/router` (`code`/`original`/`timestamp` alongside the
-inherited `message`) — always populated when the fallback fires.
+`RouteError` (`code`/`original`/`timestamp` alongside the inherited `message`) is always populated
+when the fallback fires. It and its subclasses (`AccessDeniedError` — an `enter` guard returned `false`,
+code 403 · `NotFoundError` · `ContentLoadError` · `ContentRenderError` · `OutletMissingError`) are
+exported from `@iyulab/modern-app` — tell a blocked screen from a missing one with
+`ctx.error instanceof AccessDeniedError` and render it as `<u-empty-state variant="no-access">`.
 
 ---
 
@@ -227,13 +230,23 @@ The framework owns only the orchestration (check → branch → reload) — sess
 `@iyulab/enterprise`'s `createAuthClient`/`createODataService`).
 
 ```typescript
+/**
+ * A session lookup's answer. "Signed out" and "could not tell" are different answers — treating a
+ * brief 503 as signed out sends a signed-in user to the login screen. `@iyulab/enterprise`'s
+ * `createAuthClient().fetchMe()` returns exactly this shape: `me: () => auth.fetchMe()`.
+ */
+type AuthSession<TUser = unknown> =
+  | { status: 'authenticated'; user: TUser }   // shell loads; app.user = user
+  | { status: 'anonymous' }                    // renderLogin
+  | { status: 'unknown'; error: unknown };     // renderUnavailable
+
 interface AuthGateConfig {
   /**
-   * Resolve the current session. Return a value for authenticated, `null`/`undefined` for not.
-   * **Throw when the session could not be checked** (server down, offline) — returning `null`
-   * there would send a signed-in user to the login screen.
+   * Resolve the current session — sync or async. Throwing counts as `unknown`. An answer whose
+   * `status` is not one of the three makes `app.load()` reject with a `TypeError`: a user object
+   * or `null` is never guessed to mean "signed in".
    */
-  me: () => Promise<unknown | null | undefined> | unknown | null | undefined;
+  me: () => AuthSession | Promise<AuthSession>;
 
   /**
    * Renders login UI into `context.root` when unauthenticated. Call `context.onSuccess()` on
@@ -242,10 +255,11 @@ interface AuthGateConfig {
   renderLogin: (context: AuthGateContext) => (() => void) | void;
 
   /**
-   * Renders a "can't reach the server" view into `context.root` when `me()` throws. Call
+   * Renders a "can't reach the server" view into `context.root` when the session is `unknown`
+   * (or `me()` throws). Call
    * `context.retry()` to check again (a retry button, the `online` event). Return a cleanup
    * function to have it called on app load/`unload`. Without it, `app.load()` rejects with
-   * `me()`'s error.
+   * that error.
    */
   renderUnavailable?: (context: AuthGateUnavailableContext) => (() => void) | void;
 
@@ -263,7 +277,7 @@ interface AuthGateContext {
 interface AuthGateUnavailableContext {
   /** Root element to render into (same as `AppConfig.root`, default `document.body`). */
   root: Element;
-  /** What `me()` threw. */
+  /** The `unknown` answer's `error`, or what `me()` threw. */
   error: unknown;
   /** Check again — the app (re)loads and calls `me()` again. */
   retry: () => void;

package/skills/modern-app/references/components/empty-state.md

@@ -8,6 +8,8 @@ Shown when a list or a search comes back with nothing.
 *nothing has been created yet* and the next action is **create**. The second means *nothing
 matches these conditions* and the next action is **change the filter**. Show the same wording
 for both and a user with a filter still applied reads it as *"my data disappeared"*.
+The same holds for a screen this user may not see: it is neither empty nor broken, and its next
+action is **asking for access**.
 
 ```html
 <u-empty-state variant="no-data" title="No orders yet">
@@ -20,6 +22,9 @@ for both and a user with a filter still applied reads it as *"my data disappeare
 <u-empty-state variant="error" description="Request failed (503)">
   <u-button slot="actions">Try again</u-button>
 </u-empty-state>
+
+<!-- A route guard said no (403) — not an outage, so it is not announced as an alert. -->
+<u-empty-state variant="no-access"></u-empty-state>
 ```
 
 ## Slots
@@ -33,7 +38,7 @@ for both and a user with a filter still applied reads it as *"my data disappeare
 
 | Property | Type | Default | Reflect | Description |
 |----------|------|---------|---------|-------------|
-| `variant` | `'no-data'\|'no-results'\|'error'` | `'no-data'` | ✓ | Which fact is being shown; changes the default wording. `error` (could not load) announces its title |
+| `variant` | `'no-data'\|'no-results'\|'error'\|'no-access'` | `'no-data'` | ✓ | Which fact is being shown; changes the default wording. `error` (could not load) announces its title; `no-access` (this user may not see it) does not |
 | `title` | `string` | `''` | | Override the default title |
 | `description` | `string` | `''` | | Override the default description |
 | `locale` | `string` | `''` | | Locale tag override for built-in strings |
@@ -63,3 +68,23 @@ for both and a user with a filter still applied reads it as *"my data disappeare
 ⚠ Default wording is **English**, with Korean built in — choose the language with `Locale.set()` of
 `@iyulab/components`, register others with `modernAppLocale.register(lang, …)`, or pass
 `title`/`description` per screen.
+
+## Blocked routes
+
+A route `enter` guard that returns `false` raises `AccessDeniedError` (code 403) into the app
+`fallback`. The error classes are exported from `@iyulab/modern-app`, so the fallback can tell a
+blocked screen from a missing one without depending on the router directly:
+
+```typescript
+import { app, AccessDeniedError } from '@iyulab/modern-app';
+import { html } from 'lit';
+
+await app.load({
+  // …
+  fallback: {
+    render: (ctx) => ctx.error instanceof AccessDeniedError
+      ? html`<u-empty-state variant="no-access"></u-empty-state>`
+      : html`<u-empty-state variant="error" .description=${ctx.error.message}></u-empty-state>`,
+  },
+});
+```