@iyulab/modern-app 0.31.0 → 0.33.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.33.0] - 2026-09-30
+
+### Added
+
+- **«Skip to main content» link in the sidebar layout** — the shell's first Tab stop, shown only while
+  it has focus (`part="skip-link"`). Activating it moves focus the way a finished route does: to the
+  screen's `[autofocus]` element, else to the route area. A keyboard user no longer tabs through the
+  whole menu on every screen (WCAG 2.4.1 Bypass Blocks). The text is the new `skipToContent` key of
+  `modernAppLocale` (English and Korean built in).
+
+### Changed
+
+- **The route area (`part="main"`) is a `<main>` element**, so screen readers list it as the main
+  landmark. It was a `<div>`. Styling through `::part(main)` and `layout.styles` is unchanged. If your
+  route screens render their own `<main>`, change it to a `<div>` or `<section>` — a page should have
+  one main landmark.
+
+## [0.32.0] - 2026-09-28
+
+### Changed
+
+- **The shell's overlay panel is a layer in `@iyulab/components`' layer stack.** Escape inside the
+  panel still fires `overlay-close`, and a drawer, dialog or popover opened inside the panel still
+  closes first — the order now comes from `OverlayManager` (layers stack in the order they opened)
+  instead of the shell waiting a task to see who else handled the key. The Escape that closes the
+  panel is now marked consumed (`defaultPrevented`), like every layer's; an Escape pressed outside
+  the panel is still left alone. Requires `@iyulab/components` 1.49.0 or later.
+- The sidebar and the mobile header read `--u-layer-shell` (1000 and one above it, as before), the
+  shared stacking token from `@iyulab/components`.
+
 ## [0.31.0] - 2026-09-28
 
 ### Changed

package/README.md

@@ -276,6 +276,7 @@ conformance claim for the success criteria it does not list.
 |---|---|---|
 | SC 2.5.8 Target Size (Minimum) | Every pointer target this package renders itself — sidebar links, buttons and group headers (expanded and compact), the sidebar logo and toggle, wizard steps, the page header's back link — is at least 24×24 CSS px or meets the spacing exception (24px between centers), and is actually hit at that position | `tests/browser/target-size.browser.test.ts` (real Chromium) |
 | SC 2.1.1 Keyboard (pointer-cursor check) | Nothing this package renders shows a pointer cursor without being an interactive element — the sidebar logo is a link | `tests/browser/target-size.browser.test.ts` |
+| SC 2.4.1 Bypass Blocks | The sidebar layout's first Tab stop is a «Skip to main content» link, visible when focused and at least 24px tall; it moves focus to the screen's `[autofocus]` element or to the route area, which is the page's single `<main>` landmark | `tests/browser/sidebar-layout-skip-link.browser.test.ts` |
 
 Buttons placed through slots or rendered as `u-button` without size overrides (wizard back/next, the
 master-detail close button) follow `@iyulab/components`, which measures them in its own gate. Color

package/dist/internals/locale.d.ts

@@ -13,6 +13,8 @@ export interface ModernAppLocaleStrings {
     toggleMobileMenu: string;
     /** Sidebar layout — accessible label for the sidebar-header collapse/expand toggle button. */
     toggleSidebar: string;
+    /** Sidebar layout — the «skip to main content» link, the first Tab stop of the shell. */
+    skipToContent: string;
     /** Wizard — default Back/Next action labels ("Submit" wording is the consumer's call). */
     wizardBack: string;
     wizardNext: string;

package/dist/internals/locale.js

@@ -9,6 +9,7 @@ var t = {
 	detailClose: "Close",
 	toggleMobileMenu: "Toggle menu",
 	toggleSidebar: "Toggle sidebar",
+	skipToContent: "Skip to main content",
 	wizardBack: "Back",
 	wizardNext: "Next",
 	wizardStepAnnouncement: "Step {index} of {total}: {label}"
@@ -22,6 +23,7 @@ n.register("en", t), n.register("ko", {
 	detailClose: "닫기",
 	toggleMobileMenu: "메뉴 열고 닫기",
 	toggleSidebar: "사이드바 열고 닫기",
+	skipToContent: "본문으로 건너뛰기",
 	wizardBack: "이전",
 	wizardNext: "다음",
 	wizardStepAnnouncement: "{total}단계 중 {index}단계: {label}"
@@ -53,6 +55,7 @@ function l(e) {
 		detailClose: t("detailClose"),
 		toggleMobileMenu: t("toggleMobileMenu"),
 		toggleSidebar: t("toggleSidebar"),
+		skipToContent: t("skipToContent"),
 		wizardBack: t("wizardBack"),
 		wizardNext: t("wizardNext"),
 		wizardStepAnnouncement: (t, n, r) => {

package/dist/layouts/SidebarLayout.d.ts

@@ -111,6 +111,10 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
      * 그리기 전에 올 수 있고, 그때 찾으면 `[autofocus]` 가 아직 없다.
      */
     private focusRoute;
+    /** 본문의 시작으로 포커스 — 화면이 선언한 `[autofocus]`, 없으면 본문(`main`) 자체. */
+    private focusContentStart;
+    /** «본문 바로가기» — 라우트 완료와 같은 규칙으로 본문의 시작에 포커스를 둔다(`#517`). */
+    private handleSkipLinkClick;
     /** 라우트 에러 핸들러 */
     private handleRouteError;
     private handleOverlaySlotChange;
@@ -132,18 +136,13 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
      */
     private restoreOverlayFocus;
     /**
-     * 패널 안의 Escape 는 닫기 버튼과 같은 `overlay-close` 를 낸다 — 단, **안쪽 층이 모두 판정한 뒤에**.
+     * 패널 안의 Escape 는 닫기 버튼과 같은 `overlay-close` 를 낸다.
      *
-     * 셸의 오버레이는 가장 바깥 층이다. 그런데 window 의 같은 단계 리스너는 «등록 순서» 로 돌고,
-     * 셸은 오버레이가 열릴 때 등록하므로 패널 안에서 «나중에» 연 층(`u-drawer`·`u-dialog` — 역시
-     * window 에서 받는다)보다 먼저 돈다. 거기서 판정하면 바깥이 닫히고 안쪽이 남는다(거꾸로다).
-     * ⇒ 리스너에서는 판정하지 않고 **디스패치가 끝난 뒤**(다음 태스크) `defaultPrevented` 를 본다 —
-     *   그때는 어느 순서로 등록된 층이든 이미 자기 몫을 가져갔다. 한 번의 Escape 는 한 층만 닫는다.
-     * ⚠마이크로태스크로는 부족하다 — 네이티브 이벤트에서는 리스너 사이마다 마이크로태스크가 비워져,
-     *   뒤에 등록된 층보다 먼저 돈다.
-     * ⚠셸은 `preventDefault` 하지 않는다 — 가장 바깥 층이 키를 «먹었다» 고 표시하면 안쪽 층의 가드
-     *   (`defaultPrevented` 면 닫지 않는다)를 오염시킨다.
-     * 경로에 패널이 없으면(사이드바, 패널 위에 띄운 대화상자) 받지 않는다.
+     * 패널은 components 의 층 스택(`OverlayManager.openLayer`)에 선 한 층이다 — 층은 여는 순서로 쌓이고
+     * Escape 한 번은 가장 위 층 하나만 닫으므로, 패널 «안» 에서 나중에 연 서랍·대화상자·팝오버가 먼저
+     * 닫힌다. 종전에는 셸이 window 에서 직접 받아 «등록 순서» 가 층 순서를 거슬렀고, 그것을 다음
+     * 태스크로 미룬 판정으로 메웠다 — 이제 순서는 한 곳이 정한다.
+     * 비모달 패널이라 **포커스가 패널 안일 때만** 닫는다(사이드바에서 누른 Escape 는 거절 — 소비하지 않는다).
      */
     private handleOverlayEscape;
     private handleOverlayClose;

package/dist/layouts/SidebarLayout.js

@@ -20,32 +20,33 @@ import { repeat as g } from "lit/directives/repeat.js";
 import { ifDefined as _ } from "lit/directives/if-defined.js";
 import { createDevWarner as v } from "@iyulab/components/dist/utilities/devWarning.js";
 import { isFocusCandidate as y, querySelectorDeep as b } from "@iyulab/components/dist/utilities/elements.js";
-import { UProgressBar as x } from "@iyulab/components/dist/components/progress-bar/UProgressBar.js";
+import { OverlayManager as x } from "@iyulab/components/dist/utilities/OverlayManager.js";
+import { UProgressBar as S } from "@iyulab/components/dist/components/progress-bar/UProgressBar.js";
 //#region src/layouts/SidebarLayout.ts
-var S, C = v("@iyulab/modern-app"), w = 0;
-function T(e) {
+var C, w = v("@iyulab/modern-app"), T = 0;
+function E(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";
 }
-function E(e) {
+function D(e) {
 	let t = getComputedStyle(e);
 	return (t.overflowY === "auto" || t.overflowY === "scroll") && e.scrollHeight > e.clientHeight;
 }
-function D(e, t) {
+function O(e, t) {
 	for (let n of e) if (n instanceof HTMLElement) {
-		if (E(n)) return n === t;
+		if (D(n)) return n === t;
 		if (n === t) break;
 	}
 	return !0;
 }
-function O() {
+function k() {
 	let e = document.activeElement;
 	for (; e?.shadowRoot?.activeElement;) e = e.shadowRoot.activeElement;
 	return e;
 }
-function k(e, t) {
+function A(e, t) {
 	let n = t;
 	for (; n;) {
 		if (n === e) return !0;
@@ -53,12 +54,12 @@ function k(e, t) {
 	}
 	return !1;
 }
-var A = class extends i {
+var j = class extends i {
 	static {
-		S = this;
+		C = this;
 	}
 	constructor(...t) {
-		super(...t), this.state = "default", this.locale = "", this.hasOverlay = !1, this.hasNotice = !1, this.overlayTrigger = null, this.internals = typeof this.attachInternals == "function" ? this.attachInternals() : void 0, this.context = null, this.unsizedWarnKey = `unsized:${++w}`, 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.handleToggleButtonClick = () => {
+		super(...t), this.state = "default", this.locale = "", this.hasOverlay = !1, this.hasNotice = !1, this.overlayTrigger = null, this.internals = typeof this.attachInternals == "function" ? this.attachInternals() : void 0, this.context = null, this.unsizedWarnKey = `unsized:${++T}`, 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.handleToggleButtonClick = () => {
 			let t = this.screenSize ?? e.screen ?? "large";
 			t === "large" ? this.state = this.state === "default" ? "slim" : "default" : t === "medium" ? this.state = this.state === "slim" ? "modal" : "slim" : t === "small" ? this.state = this.state === "mobile" ? "mobile-open" : "mobile" : console.warn("Unknown screen size:", t);
 		}, this.handleBackdropClick = () => {
@@ -73,6 +74,10 @@ var A = class extends i {
 			}, 300);
 			let t = this.shadowRoot?.querySelector(".main");
 			t && (this.config?.scrollBehavior?.(e.context, t), this.focusRoute(t));
+		}, this.handleSkipLinkClick = (e) => {
+			e.preventDefault();
+			let t = this.shadowRoot?.querySelector(".main");
+			t && this.focusContentStart(this.hasOverlay ? [] : this.routeContent(), t);
 		}, this.handleRouteError = (e) => {
 			this.progressBarEl.status = "error", this.progressBarEl.value = 100, setTimeout(() => {
 				this.progressBarEl.removeAttribute("visible"), this.progressBarEl.status = "default";
@@ -80,25 +85,22 @@ var A = class extends i {
 		}, this.handleOverlaySlotChange = (e) => {
 			let t = o(e.target);
 			if (t && !this.hasOverlay) {
-				let e = O();
+				let e = k();
 				this.overlayTrigger = e && e !== document.body ? e : null;
 			}
 			this.hasOverlay = t;
 		}, this.handleNoticeSlotChange = (e) => {
 			this.hasNotice = o(e.target);
 		}, this.handleOverlayEscape = (e) => {
-			if (e.key !== "Escape" || e.isComposing || !this.hasOverlay) return;
 			let t = this.shadowRoot?.querySelector(".overlay");
-			t && e.composedPath().includes(t) && setTimeout(() => {
-				!e.defaultPrevented && this.hasOverlay && this.handleOverlayClose();
-			}, 0);
+			return !this.hasOverlay || !t || !e.composedPath().includes(t) ? !1 : (this.handleOverlayClose(), !0);
 		}, this.handleOverlayClose = () => {
 			this.fire("overlay-close", { cancelable: !1 });
 		}, this._handleMainKeydown = (e) => {
 			let t = e.composedPath()[0];
-			if (t instanceof HTMLElement && T(t)) return;
+			if (t instanceof HTMLElement && E(t)) return;
 			let n = this.shadowRoot?.querySelector(".main");
-			if (!n || !D(e.composedPath(), n)) return;
+			if (!n || !O(e.composedPath(), n)) return;
 			let r = n.clientHeight;
 			switch (e.key) {
 				case " ":
@@ -138,13 +140,13 @@ var A = class extends i {
 		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);
 	}
 	disconnectedCallback() {
-		window.removeEventListener("route-begin", this.handleRouteBegin), window.removeEventListener("route-done", this.handleRouteDone), window.removeEventListener("route-progress", this.handleRouteProgress), window.removeEventListener("route-error", this.handleRouteError), window.removeEventListener("screen-resize", this.handleScreenResize), window.removeEventListener("keydown", this.handleOverlayEscape), super.disconnectedCallback();
+		window.removeEventListener("route-begin", this.handleRouteBegin), window.removeEventListener("route-done", this.handleRouteDone), window.removeEventListener("route-progress", this.handleRouteProgress), window.removeEventListener("route-error", this.handleRouteError), window.removeEventListener("screen-resize", this.handleScreenResize), x.closeLayer(this), super.disconnectedCallback();
 	}
 	willUpdate(e) {
 		super.willUpdate(e), e.has("config") && (this.styles = this.config?.styles);
 	}
 	updated(e) {
-		super.updated(e), e.has("hasOverlay") && (this.internals?.states?.[this.hasOverlay ? "add" : "delete"]("overlay"), this.hasOverlay ? (window.addEventListener("keydown", this.handleOverlayEscape), this.focusOverlay()) : e.get("hasOverlay") === !0 && (window.removeEventListener("keydown", this.handleOverlayEscape), this.restoreOverlayFocus()));
+		super.updated(e), e.has("hasOverlay") && (this.internals?.states?.[this.hasOverlay ? "add" : "delete"]("overlay"), this.hasOverlay ? (x.openLayer(this, this.handleOverlayEscape), this.focusOverlay()) : e.get("hasOverlay") === !0 && (x.closeLayer(this), this.restoreOverlayFocus()));
 	}
 	firstUpdated(e) {
 		super.firstUpdated(e), this.warnIfUnsized();
@@ -153,11 +155,16 @@ var A = class extends i {
 		process.env.NODE_ENV !== "production" && requestAnimationFrame(() => {
 			if (!this.isConnected) return;
 			let e = this.getBoundingClientRect().height;
-			e >= 200 || C(this.unsizedWarnKey, `u-sidebar-layout is only ${Math.round(e)}px tall — its height: 100% found no sized ancestor, so the shell sits at its own chrome height and the route area has almost no room. Give the root element a height (e.g. #app { height: 100vh } — app.load() does this for document.body).`);
+			e >= 200 || w(this.unsizedWarnKey, `u-sidebar-layout is only ${Math.round(e)}px tall — its height: 100% found no sized ancestor, so the shell sits at its own chrome height and the route area has almost no room. Give the root element a height (e.g. #app { height: 100vh } — app.load() does this for document.body).`);
 		});
 	}
 	render() {
 		return this.config ? l`
+      <!-- 반복 영역 건너뛰기(WCAG 2.4.1) — 셸의 첫 Tab. 포커스될 때만 보인다. -->
+      <a class="skip-link" part="skip-link" href="#" @click=${this.handleSkipLinkClick}>
+        ${a(this.locale || void 0).skipToContent}
+      </a>
+
       <!-- Mobile Header -->
       <div class="mobile-header" part="mobile-header" ?hidden="${!this.state.startsWith("mobile")}">
         ${this.renderLogo()}
@@ -206,7 +213,7 @@ var A = class extends i {
 
       <!-- Main Content -->
       <div class="main-region">
-        <div class="main" part="main" scrollable tabindex="-1" @keydown=${this._handleMainKeydown}>
+        <main class="main" part="main" scrollable tabindex="-1" @keydown=${this._handleMainKeydown}>
           <u-progress-bar part="progress"></u-progress-bar>
 
           <div class="main-content" part="main-content" ?inert=${this.hasOverlay}>
@@ -217,7 +224,7 @@ var A = class extends i {
             </div>
             <slot></slot>
           </div>
-        </div>
+        </main>
 
         <div class="overlay ${this.hasOverlay ? "" : "empty"}" part="overlay">
           <u-button class="overlay-close" part="overlay-close" variant="ghost"
@@ -305,7 +312,7 @@ var A = class extends i {
 		};
 	}
 	icon(e) {
-		return this.config?.icons?.[e] ?? S.DEFAULT_ICONS[e];
+		return this.config?.icons?.[e] ?? C.DEFAULT_ICONS[e];
 	}
 	renderLogo() {
 		let e = this.config?.logo, t = this.config?.title ?? "Home";
@@ -342,12 +349,14 @@ var A = class extends i {
 	async focusRoute(e) {
 		let t = this.routeContent();
 		if (await Promise.all(t.map((e) => e.updateComplete)), this.hasOverlay || !e.isConnected) return;
-		let n = O();
-		if (n && t.some((e) => k(e, n))) return;
-		let r = b(t, "[autofocus]", y);
-		r?.focus();
-		let i = O();
-		r && i && k(r, i) || e.focus({ preventScroll: !0 });
+		let n = k();
+		n && t.some((e) => A(e, n)) || this.focusContentStart(t, e);
+	}
+	focusContentStart(e, t) {
+		let n = b(e, "[autofocus]", y);
+		n?.focus();
+		let r = k();
+		n && r && A(n, r) || t.focus({ preventScroll: !0 });
 	}
 	overlayPanels() {
 		return (this.shadowRoot?.querySelector("slot[name=\"overlay\"]"))?.assignedElements({ flatten: !0 }) ?? [];
@@ -355,19 +364,19 @@ var A = class extends i {
 	async focusOverlay() {
 		let e = this.overlayPanels();
 		if (await Promise.all(e.map((e) => e.updateComplete)), !this.hasOverlay) return;
-		let t = O();
-		t && e.some((e) => k(e, t)) || (b(e, "[autofocus]", y) ?? b(e, "input, select, textarea, u-input, u-textarea, u-select, u-checkbox, u-radio, u-switch, u-slider", y) ?? this.shadowRoot?.querySelector(".overlay-close"))?.focus();
+		let t = k();
+		t && e.some((e) => A(e, t)) || (b(e, "[autofocus]", y) ?? b(e, "input, select, textarea, u-input, u-textarea, u-select, u-checkbox, u-radio, u-switch, u-slider", y) ?? this.shadowRoot?.querySelector(".overlay-close"))?.focus();
 	}
 	restoreOverlayFocus() {
 		let e = this.overlayTrigger;
 		this.overlayTrigger = null;
-		let t = O();
+		let t = k();
 		t && t !== document.body || (e?.isConnected ? e.focus() : this.mainElement?.focus({ preventScroll: !0 }));
 	}
 };
 r([f({
 	type: String,
 	reflect: !0
-}), n("design:type", Object)], A.prototype, "state", void 0), r([f({ type: Object }), n("design:type", Object)], A.prototype, "config", void 0), r([f({ type: String }), n("design:type", Object)], A.prototype, "locale", void 0), r([p("u-progress-bar"), n("design:type", x === void 0 ? Object : x)], A.prototype, "progressBarEl", void 0), r([m(), n("design:type", Object)], A.prototype, "hasOverlay", void 0), r([m(), n("design:type", Object)], A.prototype, "hasNotice", void 0), r([m(), n("design:type", Object)], A.prototype, "context", void 0), A = S = r([d("u-sidebar-layout")], A);
+}), n("design:type", Object)], j.prototype, "state", void 0), r([f({ type: Object }), n("design:type", Object)], j.prototype, "config", void 0), r([f({ type: String }), n("design:type", Object)], j.prototype, "locale", void 0), r([p("u-progress-bar"), n("design:type", S === void 0 ? Object : S)], j.prototype, "progressBarEl", void 0), r([m(), n("design:type", Object)], j.prototype, "hasOverlay", void 0), r([m(), n("design:type", Object)], j.prototype, "hasNotice", void 0), r([m(), n("design:type", Object)], j.prototype, "context", void 0), j = C = r([d("u-sidebar-layout")], j);
 //#endregion
-export { A as SidebarLayout };
+export { j as SidebarLayout };

package/dist/layouts/SidebarLayout.styles.js

@@ -72,10 +72,39 @@ var t = e`
     color: var(--u-txt-color-hover, #1565C0);
   }
 
+  /* 본문 바로가기 — 포커스될 때만 보인다(보이지 않을 때는 자리도 차지하지 않는다). */
+  .skip-link {
+    position: absolute;
+    top: 8px;
+    left: 8px;
+    z-index: calc(var(--u-layer-shell, 1000) + 2);
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+  .skip-link:focus {
+    width: auto;
+    height: auto;
+    min-height: 24px;
+    overflow: visible;
+    clip-path: none;
+    display: inline-flex;
+    align-items: center;
+    padding: 6px 12px;
+    border-radius: var(--u-radius-md, 4px);
+    background: var(--u-bg-color, #FFFFFF);
+    color: var(--u-txt-color, #212121);
+    box-shadow: 0 0 0 2px var(--u-primary-color, #1976D2);
+    text-decoration: none;
+    outline: none;
+  }
+
   /* Sidebar Container */
   .sidebar {
     position: relative;
-    z-index: 1000;
+    z-index: var(--u-layer-shell, 1000);
     display: flex;
     flex-direction: column;
     justify-content: space-between;
@@ -126,7 +155,7 @@ var t = e`
   /* Mobile Header */
   .mobile-header {
     position: relative;
-    z-index: 1001;
+    z-index: calc(var(--u-layer-shell, 1000) + 1);
     display: flex;
     flex-direction: row;
     align-items: center;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/modern-app",
   "description": "web-framework by iyulab based on lit-element",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "keywords": [
     "iyulab",
     "web-framework",
@@ -64,7 +64,7 @@
     "lit": "^3.3.3"
   },
   "peerDependencies": {
-    "@iyulab/components": ">=1.47.1",
+    "@iyulab/components": ">=1.49.0",
     "@lit/react": ">=1.0.8",
     "react": ">=18.0.0"
   },
@@ -77,7 +77,7 @@
     }
   },
   "devDependencies": {
-    "@iyulab/components": ">=1.47.1",
+    "@iyulab/components": ">=1.49.0",
     "@lit/react": "^1.0.8",
     "@types/node": "^26.1.1",
     "@types/react": "^19.2.14",

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

@@ -257,6 +257,7 @@ Parts available for `styles` overrides on the root layout:
 | Part | Element |
 |------|---------|
 | `host` | Outer layout shell |
+| `skip-link` | «Skip to main content» link — the shell's first Tab stop, shown only while focused |
 | `mobile-header` | Top bar shown on mobile |
 | `sidebar` | Sidebar panel |
 | `sidebar-header` | Logo + title area |
@@ -333,6 +334,15 @@ told apart in CSS; notices are rare and short-lived.
 While the overlay is open, `part="main-content"` becomes a box at the area's height, because a
 stacking context needs one — route content is inert and under the overlay then.
 
+### Skip link and main landmark
+
+The route area is a `<main>` landmark (`part="main"`), so a screen reader can jump to it. The shell's
+first Tab stop is a **«Skip to main content»** link (`part="skip-link"`, localized — `skipToContent` in
+`modernAppLocale`), visible only while it has focus. Activating it moves focus by the same rule as a
+finished route (steps 2 and 3 below): your screen's `[autofocus]` element, else `main` itself — so a
+keyboard user does not tab through the whole menu on every screen (WCAG 2.4.1 Bypass Blocks). Do not put
+another `<main>` in your route screens; the shell already provides it.
+
 ### Focus when a route finishes
 
 On every `route-done` the shell places focus so the keyboard works on the new screen without a
@@ -418,7 +428,7 @@ from either re-implementing what the shell already does, or dropping what it doe
 | Keeping the route mounted underneath | shell | the overlay is independent of routing |
 | Moving focus into the panel when it opens | shell | an `[autofocus]` element in your panel, else its first input control, else `part="overlay-close"` — searched through shadow roots, after the panel's first render, so a panel that is itself a component works the same. If you already moved focus into the panel, the shell leaves it there |
 | Restoring focus when it closes | shell | back to the control that held focus when the panel opened — only if focus fell to `<body>`; if you moved it somewhere on purpose, that stands. With no such control (opened from code), focus goes to `part="main"` |
-| Escape to close | shell | Escape inside the panel fires the same `overlay-close` as the button — you still empty the slot. The shell decides **after** every layer inside the panel has: an Escape consumed there (`preventDefault()` — an open list, popover, drawer or dialog, whenever it was opened) closes only that layer. The shell does not mark the Escape consumed itself |
+| Escape to close | shell | Escape inside the panel fires the same `overlay-close` as the button — you still empty the slot. The panel is a layer in `@iyulab/components`' layer stack: layers stack in the order they opened and one Escape closes the topmost, so a list, popover, drawer or dialog opened inside the panel closes first. The Escape that closes the panel is marked consumed (`defaultPrevented`); an Escape pressed outside the panel is left alone. For an app surface of your own, `OverlayManager.openLayer` joins the same order |
 | **A backdrop / dimmed scrim** | **consumer** | the panel is opaque and full-bleed by design; add a scrim inside your panel if you want one |
 | **Announcing the panel to assistive tech** | **consumer** | put `role`/`aria-label` (or `aria-modal`, if you have made it modal) on *your* panel — the shell does not know what it holds |