@iyulab/modern-app 0.44.2 → 0.45.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [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
+
+- `u-wizard` keeps its live announcement inside the element — the absolutely positioned announcement escaped an
+  unpositioned scroll container and could stretch the document.
+
 ## [0.44.2] - 2026-10-07
 
 ### 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/_virtual/{_@oxc-project_runtime@0.152.0 → _@oxc-project_runtime@0.153.0}/helpers/esm/decorate.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.153.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.152.0 → _@oxc-project_runtime@0.153.0}/helpers/esm/decorateMetadata.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.152.0/helpers/esm/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.153.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/ActionBar.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { slotHasContent as r } from "../internals/slotted.js";
 import { styles as i } from "./ActionBar.styles.js";

package/dist/components/EmptyState.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { getLocaleStrings as r } from "../internals/locale.js";
 import { slotHasContent as i } from "../internals/slotted.js";

package/dist/components/GroupBox.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { slotHasContent as r } from "../internals/slotted.js";
 import { styles as i } from "./GroupBox.styles.js";

package/dist/components/InfoField.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { styles as r } from "./InfoField.styles.js";
 import { html as i } from "lit";
@@ -26,11 +26,7 @@ var f = class extends n {
 			let e = t.getAttribute("role") ?? (t.localName === "progress" ? "progressbar" : t.localName === "meter" ? "meter" : null);
 			if (e !== "progressbar" && e !== "meter") continue;
 			let n = this.namedWidgets.get(t), r = t.getAttribute("aria-label");
-			if (t.hasAttribute("aria-labelledby") || r !== null && r !== n) {
-				this.namedWidgets.delete(t);
-				continue;
-			}
-			this.label ? (t.setAttribute("aria-label", this.label), this.namedWidgets.set(t, this.label)) : n !== void 0 && (t.removeAttribute("aria-label"), this.namedWidgets.delete(t));
+			t.hasAttribute("aria-labelledby") || r !== null && r !== n ? this.namedWidgets.delete(t) : this.label ? (t.setAttribute("aria-label", this.label), this.namedWidgets.set(t, this.label)) : n !== void 0 && (t.removeAttribute("aria-label"), this.namedWidgets.delete(t));
 		}
 	}
 	updated(e) {

package/dist/components/InfoSection.js

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

package/dist/components/MasterDetailLayout.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { getLocaleStrings as r } from "../internals/locale.js";
 import { slotHasContent as i } from "../internals/slotted.js";

package/dist/components/PageHeader.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { getLocaleStrings as r } from "../internals/locale.js";
 import { slotHasContent as i } from "../internals/slotted.js";

package/dist/components/SidebarButton.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { DEFAULT_NAV_ICON as r } from "../internals/nav-icon.js";
 import { styles as i } from "./SidebarButton.styles.js";

package/dist/components/SidebarGroup.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { DEFAULT_NAV_ICON as r } from "../internals/nav-icon.js";
 import { SidebarLink as i } from "./SidebarLink.js";

package/dist/components/SidebarLink.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { getLocaleStrings as r } from "../internals/locale.js";
 import { DEFAULT_NAV_ICON as i } from "../internals/nav-icon.js";

package/dist/components/SidebarSection.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.153.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/Timeline.js

@@ -1,4 +1,4 @@
-import e from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
 import { StyledElement as t } from "../internals/StyledElement.js";
 import "./TimelineItem.js";
 import { styles as n } from "./Timeline.styles.js";

package/dist/components/TimelineItem.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { slotHasContent as r } from "../internals/slotted.js";
 import { styles as i } from "./TimelineItem.styles.js";

package/dist/components/Wizard.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { getLocaleStrings as r } from "../internals/locale.js";
 import { styles as i } from "./Wizard.styles.js";

package/dist/components/Wizard.styles.js

@@ -3,6 +3,9 @@ import { css as e } from "lit";
 var t = e`
   :host {
     display: flex;
+    /* 위치 지정 — 안의 숨김 문구(절대 위치 · 1px)의 포함 블록이 이 요소가 된다. 없으면 포함 블록이 문서 전체라 호스트의
+       overflow 감싸개를 건너뛰고 그 정적 위치에서 문서를 늘렸다(위치 지정되지 않은 스크롤 상자 안에서). */
+    position: relative;
     flex-direction: row;
     gap: var(--u-space-xl, 20px);
     min-width: 0;

package/dist/internals/StyledElement.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.153.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
@@ -25,11 +25,8 @@ var i = class extends r {
 		for (let [n, r] of Object.entries(t)) {
 			if (r == null) continue;
 			let t = String(r);
-			if (n.startsWith("--") || n.includes("-")) {
-				e.style.setProperty(n, t);
-				continue;
-			}
-			try {
+			if (n.startsWith("--") || n.includes("-")) e.style.setProperty(n, t);
+			else try {
 				e.style[n] = t;
 			} catch {
 				let r = n.replace(/[A-Z]/g, (e) => "-" + e.toLowerCase());

package/dist/layouts/SidebarLayout.js

@@ -1,7 +1,7 @@
 import { app as e } from "../App.js";
 import { filterSidebarItems as t } from "./filterSidebarItems.js";
-import n from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorateMetadata.js";
-import r from "../_virtual/_@oxc-project_runtime@0.152.0/helpers/esm/decorate.js";
+import n from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorateMetadata.js";
+import r from "../_virtual/_@oxc-project_runtime@0.153.0/helpers/esm/decorate.js";
 import { StyledElement as i } from "../internals/StyledElement.js";
 import { getLocaleStrings as a } from "../internals/locale.js";
 import { slotHasContent as o } from "../internals/slotted.js";

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.2",
+  "version": "0.45.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

@@ -227,13 +227,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 +252,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 +274,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;