@iyulab/modern-app 0.18.18 → 0.19.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [0.19.0] - 2026-09-10
+
+### Changed
+
+- **Fallback literals for `--u-txt-color-weak` follow `@iyulab/components` 1.40.0.** They are
+  only used when that stylesheet is not loaded; with it, nothing changes here.
+
+### Fixed
+
+- **`u-master-detail-layout` ignored a change to `overlayBreakpoint` until the element
+  happened to resize.** The overlay decision has two inputs — the component's own width
+  and the breakpoint — but it was only ever evaluated inside the `ResizeObserver`
+  callback, so setting the prop at runtime left the `overlay` attribute on its previous
+  verdict. Setting it once before first render always worked, which is why the gap went
+  unnoticed. It is now re-evaluated whenever either input changes.
+
+### Changed
+
+- **`@iyulab/components` moved from `dependencies` to `peerDependencies`.** It owns
+  process-global state — the custom element registry and module-level singletons — so a
+  duplicate copy in the install tree splits that state with no error: the notification layer
+  stops seeing overlays that a different copy registered, which is exactly the failure the
+  1.39.0 toast fix addresses. Consumers already installing `@iyulab/components` are unaffected;
+  the declaration now says that this package uses the copy they installed.
+
+## [0.18.19] - 2026-09-04
+
+### Added
+
+- **`SidebarLayout` had no way for a consumer to control scroll position on route
+  change, and no official way to reach its scroll container at all** — only an
+  undocumented shadow-DOM `part="main"` selector, a style-only CSS hook rather than a
+  JS access contract. Added `layout.scrollBehavior(context, main)`, called on every
+  `route-done` before focus moves to the container, and a public `mainElement`
+  accessor on the element for reading/writing scroll position outside the hook (e.g.
+  saving a position from a `route-begin` listener). Unset `scrollBehavior` does
+  nothing, matching Vue Router's own default for an unset `scrollBehavior`.
+
 ## [0.18.18] - 2026-09-04
 
 ### Fixed

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

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.148.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.149.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.148.0 → _@oxc-project_runtime@0.149.0}/helpers/esm/decorateMetadata.js

@@ -1,4 +1,4 @@
-//#region \0@oxc-project+runtime@0.148.0/helpers/esm/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.149.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.148.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.149.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.148.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.149.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/EmptyState.styles.js

@@ -7,7 +7,7 @@ var t = e`
     align-items: center;
     text-align: center;
     padding: var(--u-space-4xl, 40px) var(--u-space-xl, 20px);
-    color: var(--u-txt-color-weak, #757575);
+    color: var(--u-txt-color-weak, #616161);
   }
 
   .icon {

package/dist/components/GroupBox.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.149.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.148.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.149.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";

package/dist/components/InfoField.styles.js

@@ -10,7 +10,7 @@ var t = e`
     font-size: var(--u-text-caption-size, 12px);
     font-weight: var(--u-text-caption-weight, 400);
     line-height: var(--u-text-caption-leading, 1.5);
-    color: var(--u-txt-color-weak, #757575);
+    color: var(--u-txt-color-weak, #616161);
     margin-bottom: var(--u-space-3xs, 2px);
   }
 
@@ -37,7 +37,7 @@ var t = e`
      ⚠더 흐리게 만들고 싶은 유혹이 있는데, 이 자리가 안 읽히면 사용자는 빈 칸인지
      로딩 중인지 구별하지 못한다. */
   .value.blank {
-    color: var(--u-txt-color-weak, #757575);
+    color: var(--u-txt-color-weak, #616161);
     font-weight: var(--u-text-body-weight, 400);
   }
 
@@ -71,7 +71,7 @@ var t = e`
   }
 
   .trend.tone-neutral {
-    color: var(--u-txt-color-weak, #757575);
+    color: var(--u-txt-color-weak, #616161);
   }
 `;
 //#endregion

package/dist/components/InfoSection.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.149.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.d.ts

@@ -52,6 +52,20 @@ export declare class MasterDetailLayout extends StyledElement<ElementParts> {
     private hasDetail;
     private resizeObserver?;
     connectedCallback(): void;
+    /**
+     * 오버레이 판정 한 곳. **두 입력이 있고 둘 다 바뀔 수 있다** — 자기 폭과
+     * `overlayBreakpoint`.
+     *
+     * 🔴**종전에는 이 판정이 ResizeObserver 콜백 «안에만» 있었다.** 그래서 `overlayBreakpoint`
+     * 를 런타임에 바꿔도 **폭이 함께 바뀌지 않으면 아무 일도 일어나지 않았다** — prop 은
+     * 새 값을 갖고 있는데 `overlay` 속성은 옛 판정 그대로다. 값에 반응하는 prop 으로
+     * 선언·문서화해 놓고 실제로는 리사이즈에만 반응한 셈이라, 이 리포가 「선언 ≠ 동작」이라
+     * 부르는 부류다.
+     *
+     * @param width 0 이면 아직 레이아웃되지 않은 과도 상태일 수 있다(예: 조상이 `display:none`)
+     *   — 그 순간의 값으로 오버레이를 강제하지 않는다.
+     */
+    private applyOverlay;
     disconnectedCallback(): void;
     protected updated(changed: PropertyValues): void;
     /**

package/dist/components/MasterDetailLayout.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.149.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";
@@ -22,15 +22,17 @@ var u = class extends n {
 	}
 	connectedCallback() {
 		super.connectedCallback(), this.resizeObserver = new ResizeObserver((e) => {
-			let t = e[0]?.contentRect.width ?? 0;
-			t !== 0 && this.toggleAttribute("overlay", t < this.overlayBreakpoint);
+			this.applyOverlay(e[0]?.contentRect.width ?? 0);
 		}), this.resizeObserver.observe(this);
 	}
+	applyOverlay(e) {
+		e !== 0 && this.toggleAttribute("overlay", e < this.overlayBreakpoint);
+	}
 	disconnectedCallback() {
 		super.disconnectedCallback(), this.resizeObserver?.disconnect();
 	}
 	updated(e) {
-		super.updated(e), e.has("masterSize") && this.style.setProperty("--_master-size", this.masterSize);
+		super.updated(e), e.has("masterSize") && this.style.setProperty("--_master-size", this.masterSize), e.has("overlayBreakpoint") && this.applyOverlay(this.getBoundingClientRect().width);
 	}
 	render() {
 		return o`

package/dist/components/PageHeader.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.149.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.styles.js

@@ -37,7 +37,7 @@ var t = e`
     font-size: var(--u-text-caption-size, 12px);
     font-weight: var(--u-text-caption-weight, 400);
     line-height: var(--u-text-caption-leading, 1.5);
-    color: var(--u-txt-color-weak, #757575);
+    color: var(--u-txt-color-weak, #616161);
   }
 
   .back {

package/dist/components/SidebarButton.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.149.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.148.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.149.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.148.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.149.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 "./SidebarLink.styles.js";

package/dist/components/SidebarSection.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.149.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/Wizard.js

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

@@ -40,7 +40,7 @@ var t = e`
     border: none;
     padding: var(--u-space-2xs, 4px) 0;
     font: inherit;
-    color: var(--u-txt-color-weak, #757575);
+    color: var(--u-txt-color-weak, #616161);
     cursor: pointer;
     text-align: left;
   }

package/dist/internals/StyledElement.js

@@ -1,5 +1,5 @@
-import e from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorateMetadata.js";
-import t from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import e from "../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import t from "../_virtual/_@oxc-project_runtime@0.149.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.d.ts

@@ -14,6 +14,13 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
     progressBarEl: UProgressBar;
     /** 현재 라우터 컨텍스트 */
     context: RouteContext | null;
+    /**
+     * 라우트 컨텐츠의 실제 스크롤 컨테이너(섀도 DOM `[part="main"]`). `scrollTop`을 읽어
+     * 위치를 저장하거나, 써서 복원한다 — `part="main"`은 스타일링용 CSS 훅일 뿐 JS 접근
+     * 계약이 아니었으므로, 소비자가 이 컨테이너에 안정적으로 접근할 공식 수단으로 신설.
+     * 아직 렌더 전이면 `null`.
+     */
+    get mainElement(): HTMLElement | null;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected willUpdate(changedProperties: PropertyValues): void;

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.148.0/helpers/esm/decorateMetadata.js";
-import r from "../_virtual/_@oxc-project_runtime@0.148.0/helpers/esm/decorate.js";
+import n from "../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorateMetadata.js";
+import r from "../_virtual/_@oxc-project_runtime@0.149.0/helpers/esm/decorate.js";
 import { StyledElement as i } from "../internals/StyledElement.js";
 import { getLocaleStrings as a } from "../internals/locale.js";
 import "../components/SidebarSection.js";
@@ -40,7 +40,9 @@ var v = class extends i {
 		}, this.handleRouteDone = (e) => {
 			this.progressBarEl.value = 100, setTimeout(() => {
 				this.progressBarEl.removeAttribute("visible");
-			}, 300), (this.shadowRoot?.querySelector(".main"))?.focus({ preventScroll: !0 });
+			}, 300);
+			let t = this.shadowRoot?.querySelector(".main");
+			t && (this.config?.scrollBehavior?.(e.context, t), t.focus({ preventScroll: !0 }));
 		}, this.handleRouteError = (e) => {
 			this.progressBarEl.status = "error", this.progressBarEl.value = 100, setTimeout(() => {
 				this.progressBarEl.removeAttribute("visible"), this.progressBarEl.status = "default";
@@ -82,6 +84,9 @@ var v = class extends i {
 	static {
 		this.styles = [super.styles, o];
 	}
+	get mainElement() {
+		return this.shadowRoot?.querySelector(".main") ?? null;
+	}
 	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);
 	}

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

@@ -1,4 +1,5 @@
 import { TemplateResult } from 'lit';
+import { RouteContext } from '@iyulab/router';
 import { StyleMap } from '../internals/StyledElement';
 import { SidebarLinkConfig } from '../components/SidebarLink';
 import { SidebarSectionConfig } from '../components/SidebarSection';
@@ -55,6 +56,14 @@ export interface SidebarLayoutConfig {
      * 미지정 시 필터링하지 않는다(모든 항목 표시). 보통 `@iyulab/enterprise` 의 `hasPermission` 을 넘긴다.
      */
     hasPermission?: (code: string) => boolean;
+    /**
+     * 라우트 전환이 끝날 때(`route-done`, 포커스가 메인 스크롤 컨테이너로 옮겨지기 직전)
+     * 호출된다 — 새 라우트의 `RouteContext`와 그 스크롤 컨테이너(`SidebarLayout.mainElement`와
+     * 동일 엘리먼트)를 받는다. 스크롤 위치를 리셋·저장·복원하는 로직은 이 훅 안에서 직접
+     * 구현한다(예: 목록→상세로 갔다가 돌아올 때 스크롤 위치 복원). 미지정 시 기본값은
+     * "아무것도 안 함" — Vue Router의 `scrollBehavior` 미지정 기본값과 동일하다(breaking 아님).
+     */
+    scrollBehavior?: (context: RouteContext, main: HTMLElement) => void;
     /** 사이드바 스타일 맵 */
     styles?: StyleMap<SidebarParts>;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/modern-app",
   "description": "web-framework by iyulab based on lit-element",
-  "version": "0.18.18",
+  "version": "0.19.0",
   "keywords": [
     "iyulab",
     "web-framework",
@@ -60,12 +60,12 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@iyulab/components": "^1.27.0",
     "@iyulab/router": "^0.11.0",
     "i18next": "^26.3.6",
     "lit": "^3.3.3"
   },
   "peerDependencies": {
+    "@iyulab/components": ">=1.27.0",
     "@lit/react": ">=1.0.8",
     "react": ">=18.0.0"
   },
@@ -86,7 +86,7 @@
     "happy-dom": "^20.10.6",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.2",
     "vite": "^8.1.4",
     "vite-plugin-dts": "^5.0.3",
     "vitest": "^4.1.10"

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

@@ -269,5 +269,5 @@ interface AuthGateContext {
 | `router` | `Router \| undefined` | Underlying `@iyulab/router` instance |
 | `screen` | `ScreenSize \| undefined` | Current responsive screen size |
 | `user` | `unknown` | Authenticated user when the `auth` boot gate is used; `undefined` if unauthenticated or unused |
-| `theme` | `Theme` (static) | Theme utility (`get`, `set`, `isInitialized`) |
+| `theme` | `Theme` (static) | Theme utility — `get()`, `set()`, `resolved()`, `accent()`, `isInitialized`. Branch on `resolved()` (always `'light'` or `'dark'`), not `get()`, which can be `'system'` |
 | `i18n` | `i18next` | Raw i18next instance |

package/skills/modern-app/references/components/master-detail-layout.md

@@ -35,6 +35,22 @@ each pane. CSS container-query conditions cannot read a runtime custom property,
 configurable breakpoint means measuring the host's own width in JavaScript and reflecting an
 `overlay` attribute — same self-width philosophy, different mechanism, for a fixed reason.
 
+## Sizing
+
+This is a shell, not a sized box: `:host` is `height: 100%`, so **the parent decides its height**.
+Inside a page shell that is already constrained (an `app.load()` layout, a grid or flex row with a
+height) there is nothing to do.
+
+Put it in a container with no height of its own and `height: 100%` has nothing to resolve against,
+so the panes fall back to their content's height rather than the available space. That renders
+fine — it simply is not the full-height split pane you asked for, and the independent per-pane
+scrolling (`overflow: auto` on `master` and `detail`) only means something once the height is
+constrained.
+
+```css
+.page { height: 100%; }   /* or any constrained height on the parent */
+```
+
 ## Slots
 
 | Name | Description |

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

@@ -24,6 +24,9 @@ interface SidebarLayoutConfig {
   /** Permission filter — hides items (and emptied section/groups) whose requirement fails. Unset shows everything. See "권한 기반 메뉴 필터" below. */
   hasPermission?: (code: string) => boolean;
 
+  /** Called on `route-done` (before focus moves to the container) with the new route's `RouteContext` and the scroll container itself — implement reset/save/restore here. Unset does nothing (same default as Vue Router's unset `scrollBehavior`). Also reachable outside the hook via the element's `.mainElement` accessor. */
+  scrollBehavior?: (context: RouteContext, main: HTMLElement) => void;
+
   /** Per-part style overrides (CSS custom properties / inline styles). */
   styles?: StyleMap<SidebarParts>;
 }
@@ -225,13 +228,19 @@ for `for="#id"` anchoring to resolve (see the `id` note above).
 }
 ```
 
-⚠**Pick `placement` based on `state`, not a fixed value.** On `mobile`/`mobile-open`, the sidebar
-itself widens to occupy nearly the full screen — a sideways placement (`right-start`, the natural
-choice for a desktop flyout) then has no room on either side, and `flip()` correctly declines to
-flip when the opposite side has none either. The popover renders off-screen and is invisible. A
-vertical placement (`bottom-start`) has room regardless of sidebar width and works at every state.
-Confirmed empirically in `tests/browser/sidebar-popover-submenu.browser.test.ts` — this is not a
-`strategy="absolute"` vs `"fixed"` distinction, switching strategy does not change the outcome.
+**A fixed `placement` is safe as of `@iyulab/components@1.37.1`.** On `mobile`/`mobile-open`
+the sidebar widens to occupy nearly the full screen, so a sideways placement (`right-start`,
+the natural desktop flyout) has room on neither side. `flip()` now falls back **across the**
+**axis** in exactly that case, landing the popover vertically instead of off-screen.
+
+⚠ Against an older `components` it did render off-screen and invisible — `flip()` only ever
+considered the opposite side on the same axis, found no room there either, and gave up. If you
+pin below `1.37.1`, keep choosing `placement` from `state` as the snippet above does.
+
+Choosing from `state` is still reasonable when you want to *decide* the direction rather than
+let `flip()` pick it. Either way this is not a `strategy="absolute"` vs `"fixed"` distinction —
+switching strategy changes nothing. Both behaviours are pinned in
+`tests/browser/sidebar-popover-submenu.browser.test.ts`.
 
 ---
 
@@ -252,6 +261,21 @@ Parts available for `styles` overrides on the root layout:
 
 ---
 
+## Sizing
+
+`<u-sidebar-layout>` is a shell: `:host` is `height: 100%` with `overflow: hidden`, so **its
+height comes from the parent** — it never sizes itself. `app.load()` covers the default case: when
+`root` is `document.body` it sets `margin: 0; width: 100vw; height: 100vh` on the body for you.
+
+⚠ **A custom `root` receives no styling.** Hand it a container with no height of its own and
+`height: 100%` has nothing to resolve against: the shell renders at whatever its own chrome
+resolves to (measured: about 133px) instead of filling the screen — with no error and nothing in
+the console. Give that container a height:
+
+```css
+#app { height: 100vh; }   /* or 100%, inside an already-constrained ancestor */
+```
+
 ## Responsive behaviour
 
 | Screen width | Sidebar state |