@fuzdev/fuz_app 0.116.0 → 0.117.1

package/dist/ui/AccountSessions.svelte

@@ -41,7 +41,7 @@
 
 <section>
 	<h2>
-		sessions
+		Sessions
 		{#if account_sessions.active_count > 0}
 			<span class="chip color_a">{account_sessions.active_count} active</span>
 		{/if}

package/dist/ui/AdminAccounts.svelte

@@ -41,7 +41,7 @@
 </script>
 
 <section>
-	<h1>accounts</h1>
+	<h1>Accounts</h1>
 	{#if admin_accounts.account_count > 0}
 		<p>
 			<span class="chip color_a">

package/dist/ui/AdminAuditLog.svelte

@@ -75,7 +75,7 @@
 </script>
 
 <section>
-	<h1>audit log</h1>
+	<h1>Audit Log</h1>
 
 	<div class="row mb_md gap_md" style:align-items="end">
 		<label class="mb_0">

package/dist/ui/AdminInvites.svelte

@@ -53,10 +53,11 @@
 </script>
 
 <section>
-	<h1>invites</h1>
-	<section>
+	<h1>Invites</h1>
+	<fieldset>
+		<legend>Signup</legend>
 		<OpenSignupToggle />
-	</section>
+	</fieldset>
 	{#if admin_invites.invite_count > 0}
 		<p>
 			<span class="chip color_a">
@@ -73,7 +74,7 @@
 		}}
 	>
 		<fieldset class="row gap_sm">
-			<legend>invite target</legend>
+			<legend>Invite Target</legend>
 			<label class="grow">
 				<div class="title">email</div>
 				<input

package/dist/ui/AdminInvites.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AdminInvites.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/AdminInvites.svelte"],"names":[],"mappings":"AAuJA,QAAA,MAAM,YAAY,2DAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}
+{"version":3,"file":"AdminInvites.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/AdminInvites.svelte"],"names":[],"mappings":"AAwJA,QAAA,MAAM,YAAY,2DAAwC,CAAC;AAC3D,KAAK,YAAY,GAAG,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;AACpD,eAAe,YAAY,CAAC"}

package/dist/ui/AdminOverview.svelte

@@ -84,7 +84,7 @@
 <div class="overview">
 	<section>
 		<div class="panel-header">
-			<h3>accounts</h3>
+			<h3>Accounts</h3>
 			<a href={resolve('/admin/accounts' as any)} class="text_50 font_size_sm">view all &rarr;</a>
 		</div>
 		{#if accounts.list.loading}
@@ -126,7 +126,7 @@
 
 	<section>
 		<div class="panel-header">
-			<h3>sessions</h3>
+			<h3>Sessions</h3>
 			<a href={resolve('/admin/sessions' as any)} class="text_50 font_size_sm">view all &rarr;</a>
 		</div>
 		{#if sessions.list.loading}
@@ -156,7 +156,7 @@
 
 	<section>
 		<div class="panel-header">
-			<h3>invites</h3>
+			<h3>Invites</h3>
 			<a href={resolve('/admin/invites' as any)} class="text_50 font_size_sm">view all &rarr;</a>
 		</div>
 		{#if invites.list.loading}
@@ -201,7 +201,7 @@
 
 	<section>
 		<div class="panel-header">
-			<h3>recent activity</h3>
+			<h3>Recent Activity</h3>
 			<a href={resolve('/admin/audit-log' as any)} class="text_50 font_size_sm">view all &rarr;</a>
 		</div>
 		{#if audit_log.list.loading}
@@ -229,7 +229,7 @@
 
 	<section>
 		<div class="panel-header">
-			<h3>security</h3>
+			<h3>Security</h3>
 			<a href={resolve('/admin/audit-log' as any)} class="text_50 font_size_sm">audit log &rarr;</a>
 		</div>
 		{#if audit_log.list.loading}
@@ -267,7 +267,7 @@
 
 	<section>
 		<div class="panel-header">
-			<h3>system</h3>
+			<h3>System</h3>
 		</div>
 		{#if app_settings.list.loading}
 			<p class="text_50">loading...</p>

package/dist/ui/AdminRoleGrantHistory.svelte

@@ -38,10 +38,10 @@
 </script>
 
 <section>
-	<h1>role_grant history</h1>
+	<h1>Role-Grant History</h1>
 
 	{#if audit_log.role_grant_history.loading}
-		<p class="text_50">loading role_grant history...</p>
+		<p class="text_50">loading role-grant history...</p>
 	{:else if audit_log.role_grant_history.error}
 		<p class="color_c_50">{audit_log.role_grant_history.error}</p>
 	{:else}

package/dist/ui/AdminSessions.svelte

@@ -32,7 +32,7 @@
 </script>
 
 <section>
-	<h1>active sessions</h1>
+	<h1>Active Sessions</h1>
 	{#if admin_sessions.active_count > 0}
 		<p>
 			<span class="chip color_a">{admin_sessions.active_count} active</span>

package/dist/ui/AdminSettings.svelte

@@ -16,10 +16,10 @@
 </script>
 
 <section>
-	<h1>settings</h1>
-	<h2>signup</h2>
+	<h1>Settings</h1>
+	<h2>Signup</h2>
 	<OpenSignupToggle />
-	<h2>authentication</h2>
+	<h2>Authentication</h2>
 	{#if auth_state.account}
 		<p>Logged in as <strong>{auth_state.account.username}</strong>.</p>
 	{:else}

package/dist/ui/AdminSurface.svelte

@@ -39,7 +39,7 @@
 </script>
 
 <section>
-	<h1>surface</h1>
+	<h1>Surface</h1>
 	<p class="text_50">API routes, middleware, schemas, environment, and events.</p>
 
 	{#if loading}

package/dist/ui/AppShell.svelte

@@ -16,10 +16,26 @@
 	 * default, so the browser's close requests stay intact; it does nothing
 	 * while a modal (`:modal`) is open, or when a window `keydown` listener
 	 * registered before the overlay opened swallows it (a contextmenu, say).
-	 * Closing with Escape or the keyboard shortcut returns focus to what
-	 * opened the overlay, or else to the toggle, when focus was inside the
-	 * sidebar or had fallen to the body (as it does when the content goes
-	 * inert).
+	 *
+	 * The open overlay is a modal dialog: the sidebar takes `role="dialog"`,
+	 * `aria-modal`, `tabindex="-1"`, and `sidebar_label` as its name, and
+	 * focus moves into it, to its first control that takes focus, else to the
+	 * sidebar itself — the content went inert and dropped it. The attributes
+	 * key on the open overlay, which reads the viewport — that's what keeps
+	 * the wide sidebar from ever being a dialog — and the server render
+	 * matches hydration because the overlay always starts closed, as with the
+	 * content's `inert`. `aria-modal` lets assistive tech hide everything
+	 * outside the sidebar, the built-in toggle included, so a sidebar whose
+	 * screen-reader users need a close control beyond Escape and navigation
+	 * renders its own.
+	 *
+	 * Closing with Escape, the keyboard shortcut, or a scrim click returns
+	 * focus to what opened the overlay, or else to the first element whose
+	 * `aria-controls` names the sidebar's id and that takes it — when focus
+	 * was inside the sidebar or had fallen to the body. The id is the state's
+	 * `sidebar_id` when set, so a toggle outside the shell can carry
+	 * `aria-controls` too; Safari doesn't focus a clicked button, so without
+	 * it a mouse-opened overlay has no opener to return to.
 	 *
 	 * The shell's rules sit in two cascade layers nested under `fuz_app`.
 	 * `fuz_app.app_shell_base`, in the scoped style, holds the base and state
@@ -69,10 +85,15 @@
 
 	import { SidebarState, sidebar_state_context } from './sidebar_state.svelte.js';
 
+	// what can take focus from the keyboard, narrowed further by `tabIndex`
+	const FOCUSABLE_SELECTOR =
+		'a[href], area[href], button, input, select, textarea, iframe, summary, [tabindex], [contenteditable]';
+
 	const {
 		children,
 		sidebar,
 		sidebar_width = 180,
+		sidebar_label = 'sidebar',
 		sidebar_state: sidebar_state_prop,
 		keyboard_shortcut = false,
 		show_toggle = true,
@@ -87,6 +108,12 @@
 		 * @default 180
 		 */
 		sidebar_width?: number;
+		/**
+		 * Accessible name for the sidebar while it's the narrow-mode overlay,
+		 * announced as a modal dialog.
+		 * @default 'sidebar'
+		 */
+		sidebar_label?: string;
 		/** Optional pre-built `SidebarState` for sharing visibility across shells. */
 		sidebar_state?: SidebarState;
 		/**
@@ -108,7 +135,7 @@
 		 * `class="app-shell-toggle"` so it stacks above the sidebar and scrim
 		 * (it renders as a direct child of the root) — the z-index applies only
 		 * to a positioned button, so position it (e.g. `position: fixed`) — and
-		 * `aria-controls={sidebar_id}` so Escape can return focus to it.
+		 * `aria-controls={sidebar_id}` so closing can return focus to it.
 		 * `show_sidebar` is viewport-dependent: the server renders it as in wide
 		 * mode, so rendering it as visible content changes on hydration at
 		 * narrow widths — attributes are repaired, but key visible content on
@@ -120,7 +147,6 @@
 	} = $props();
 
 	const uid = $props.id();
-	const sidebar_id = `${uid}-sidebar`;
 
 	let fallback_sidebar_state: SidebarState | undefined;
 	const get_sidebar_state = sidebar_state_context.set(
@@ -128,14 +154,14 @@
 	);
 	const sidebar_state = $derived(get_sidebar_state());
 
+	const sidebar_id = $derived(sidebar_state.sidebar_id ?? `${uid}-sidebar`);
+
 	// viewport-free, so the server and hydration renders agree
 	const wide_open = $derived(sidebar_state.enabled && sidebar_state.show_sidebar_wide);
 	const narrow_open = $derived(sidebar_state.enabled && sidebar_state.show_sidebar_narrow);
 	// viewport-dependent, only for `inert` and input handling (always `false` in SSR)
 	const overlay_open = $derived(sidebar_state.narrow && narrow_open);
 
-	const toggle_selector = `[aria-controls="${sidebar_id}"]`;
-
 	const button_title = $derived(
 		(sidebar_state.show_sidebar ? 'hide sidebar' : 'show sidebar') +
 			(keyboard_shortcut ? ` [${keyboard_shortcut}]` : '')
@@ -170,26 +196,49 @@
 		if (should_return_focus) return_focus();
 	};
 
+	// focuses `el`, returning whether it took focus — disabled, hidden, and
+	// inert elements refuse it
+	const try_focus = (el: HTMLElement): boolean => {
+		el.focus();
+		return document.activeElement === el;
+	};
+
 	// the opener if it's still there and takes focus, else the first toggle that
 	// does — Safari doesn't focus a clicked button, so the opener can be `null`
 	const return_focus = (): void => {
-		if (opener?.isConnected) {
-			opener.focus();
-			if (document.activeElement === opener) return;
+		if (opener?.isConnected && try_focus(opener)) return;
+		for (const toggle of document.querySelectorAll<HTMLElement>('[aria-controls]')) {
+			// `aria-controls` is an id list
+			const ids = toggle.getAttribute('aria-controls')!.split(/\s+/);
+			if (ids.includes(sidebar_id) && try_focus(toggle)) return;
 		}
-		for (const toggle of document.querySelectorAll<HTMLElement>(toggle_selector)) {
-			toggle.focus();
-			if (document.activeElement === toggle) return;
+	};
+
+	// the first control in the sidebar that takes focus, else the sidebar itself
+	// (`tabindex="-1"` while it's the overlay); `tabIndex` screens out what only
+	// script can focus
+	const focus_sidebar = (): void => {
+		if (!sidebar_el) return;
+		for (const el of sidebar_el.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)) {
+			if (el.tabIndex >= 0 && try_focus(el)) return;
 		}
+		sidebar_el.focus();
 	};
 
-	// while the overlay is open, remember what had focus (to return it on Escape)
-	// and listen for Escape — registered now, not at mount, so window listeners
-	// mounted earlier (a contextmenu's, say) see Escape first and can swallow it
+	// while the overlay is open, remember what had focus (to return it on
+	// close), move focus into the sidebar — the content just went inert, which
+	// drops its focus — and listen for Escape, registered now, not at mount, so
+	// window listeners mounted earlier (a contextmenu's, say) see Escape first
+	// and can swallow it
 	$effect(() => {
 		if (!overlay_open) return;
 		const active = document.activeElement;
-		opener = active instanceof HTMLElement && active !== document.body ? active : null;
+		// never an element in the sidebar, which hides again on close
+		opener =
+			active instanceof HTMLElement && active !== document.body && !sidebar_el?.contains(active)
+				? active
+				: null;
+		focus_sidebar();
 		return on(window, 'keydown', on_escape);
 	});
 </script>
@@ -267,11 +316,7 @@
 		{@render children()}
 	</div>
 	<!-- pointer-only dismissal; Escape is the keyboard path -->
-	<div
-		class="app-shell-scrim"
-		aria-hidden="true"
-		onclick={() => sidebar_state.close_narrow()}
-	></div>
+	<div class="app-shell-scrim" aria-hidden="true" onclick={close_overlay}></div>
 	{#if show_toggle && sidebar_state.enabled}
 		{#if toggle_button}
 			{@render toggle_button({
@@ -295,7 +340,20 @@
 			</button>
 		{/if}
 	{/if}
-	<div class="app-shell-sidebar" id={sidebar_id} bind:this={sidebar_el}>
+	<!-- open, the overlay is a modal dialog whose `tabindex="-1"` makes it focus's
+		fallback target; the wide sidebar stays a plain element, so a click on its
+		background doesn't take focus. The a11y rule can't see the value is only
+		ever -1. -->
+	<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+	<div
+		class="app-shell-sidebar"
+		id={sidebar_id}
+		role={overlay_open ? 'dialog' : undefined}
+		aria-modal={overlay_open ? 'true' : undefined}
+		aria-label={overlay_open ? sidebar_label : undefined}
+		tabindex={overlay_open ? -1 : undefined}
+		bind:this={sidebar_el}
+	>
 		{@render sidebar()}
 	</div>
 </div>

package/dist/ui/AppShell.svelte.d.ts

@@ -15,10 +15,26 @@
      * default, so the browser's close requests stay intact; it does nothing
      * while a modal (`:modal`) is open, or when a window `keydown` listener
      * registered before the overlay opened swallows it (a contextmenu, say).
-     * Closing with Escape or the keyboard shortcut returns focus to what
-     * opened the overlay, or else to the toggle, when focus was inside the
-     * sidebar or had fallen to the body (as it does when the content goes
-     * inert).
+     *
+     * The open overlay is a modal dialog: the sidebar takes `role="dialog"`,
+     * `aria-modal`, `tabindex="-1"`, and `sidebar_label` as its name, and
+     * focus moves into it, to its first control that takes focus, else to the
+     * sidebar itself — the content went inert and dropped it. The attributes
+     * key on the open overlay, which reads the viewport — that's what keeps
+     * the wide sidebar from ever being a dialog — and the server render
+     * matches hydration because the overlay always starts closed, as with the
+     * content's `inert`. `aria-modal` lets assistive tech hide everything
+     * outside the sidebar, the built-in toggle included, so a sidebar whose
+     * screen-reader users need a close control beyond Escape and navigation
+     * renders its own.
+     *
+     * Closing with Escape, the keyboard shortcut, or a scrim click returns
+     * focus to what opened the overlay, or else to the first element whose
+     * `aria-controls` names the sidebar's id and that takes it — when focus
+     * was inside the sidebar or had fallen to the body. The id is the state's
+     * `sidebar_id` when set, so a toggle outside the shell can carry
+     * `aria-controls` too; Safari doesn't focus a clicked button, so without
+     * it a mouse-opened overlay has no opener to return to.
      *
      * The shell's rules sit in two cascade layers nested under `fuz_app`.
      * `fuz_app.app_shell_base`, in the scoped style, holds the base and state
@@ -70,6 +86,12 @@ type $$ComponentProps = SvelteHTMLElements['div'] & {
      * @default 180
      */
     sidebar_width?: number;
+    /**
+     * Accessible name for the sidebar while it's the narrow-mode overlay,
+     * announced as a modal dialog.
+     * @default 'sidebar'
+     */
+    sidebar_label?: string;
     /** Optional pre-built `SidebarState` for sharing visibility across shells. */
     sidebar_state?: SidebarState;
     /**
@@ -91,7 +113,7 @@ type $$ComponentProps = SvelteHTMLElements['div'] & {
      * `class="app-shell-toggle"` so it stacks above the sidebar and scrim
      * (it renders as a direct child of the root) — the z-index applies only
      * to a positioned button, so position it (e.g. `position: fixed`) — and
-     * `aria-controls={sidebar_id}` so Escape can return focus to it.
+     * `aria-controls={sidebar_id}` so closing can return focus to it.
      * `show_sidebar` is viewport-dependent: the server renders it as in wide
      * mode, so rendering it as visible content changes on hydration at
      * narrow widths — attributes are repaired, but key visible content on

package/dist/ui/AppShell.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AppShell.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/AppShell.svelte"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4DI;AACJ,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAK1D,OAAO,EAAE,YAAY,EAAyB,MAAM,2BAA2B,CAAC;AAE/E,KAAK,gBAAgB,GAAI,kBAAkB,CAAC,KAAK,CAAC,GAAG;IACpD,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACnC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,OAAO,CACtB;QAAC;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,OAAO,CAAC;YAAC,MAAM,EAAE,MAAM,IAAI,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE;KAAC,CAClF,CAAC;CACF,CAAC;AAyJH,QAAA,MAAM,QAAQ,sDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"AppShell.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/AppShell.svelte"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4EI;AACJ,OAAO,EAAa,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAK1D,OAAO,EAAE,YAAY,EAAyB,MAAM,2BAA2B,CAAC;AAE/E,KAAK,gBAAgB,GAAI,kBAAkB,CAAC,KAAK,CAAC,GAAG;IACpD,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACnC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,OAAO,CACtB;QAAC;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,YAAY,EAAE,OAAO,CAAC;YAAC,MAAM,EAAE,MAAM,IAAI,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE;KAAC,CAClF,CAAC;CACF,CAAC;AAsLH,QAAA,MAAM,QAAQ,sDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}

package/dist/ui/CLAUDE.md

@@ -76,7 +76,8 @@ pattern rather than reintroducing prop-drilling.
 ## Shell + layout
 
 - `AppShell.svelte` — sidebar-and-main shell. Props: `children`,
-  `sidebar` (Snippet), `sidebar_width = 180`, `sidebar_state?`,
+  `sidebar` (Snippet), `sidebar_width = 180`, `sidebar_label = 'sidebar'`
+  (the open overlay's accessible name), `sidebar_state?`,
   `keyboard_shortcut?`, `show_toggle?`, `toggle_button?` (receives
   `{title, show_sidebar, toggle, sidebar_id}`). Provisions
   `sidebar_state_context` internally (creates one `SidebarState` if the
@@ -84,7 +85,8 @@ pattern rather than reintroducing prop-drilling.
   (`afterNavigate` from `$app/navigation`). The toggle renders only while
   `show_toggle && sidebar_state.enabled`, before the sidebar in the DOM;
   the built-in one is a disclosure (`aria-expanded` + `aria-controls`
-  pointing at the sidebar's `$props.id()` id) with the static name
+  pointing at the sidebar's id — `SidebarState.sidebar_id` when set, else
+  one from `$props.id()`) with the static name
   `aria-label="sidebar"`, a dynamic `title`, `aria-keyshortcuts` when
   `keyboard_shortcut` is set, and a `←` glyph CSS mirrors when closed.
   The shortcut acts only while the sidebar is enabled, on the current
@@ -100,6 +102,12 @@ pattern rather than reintroducing prop-drilling.
     attributes are repaired on hydration, but visible content keyed on it
     changes at narrow widths, so key visible content on CSS or the
     viewport-free fields.
+  - **Toggles outside the shell** (a top nav's hamburger) set
+    `SidebarState`'s `sidebar_id` option and carry
+    `aria-controls={sidebar_state.sidebar_id}`, so the focus fallback finds
+    them too. `aria-controls` is read as an id list. A set id assumes one
+    shell per state — shells sharing it at the same time would render the
+    same id.
   - **Two modes, split by `SidebarState.narrow_query`.** Wide: the sidebar
     sits beside the content (padded by `--sidebar_offset`) and follows
     `show_sidebar_wide`. Narrow: it starts closed and opens as an overlay
@@ -107,8 +115,24 @@ pattern rather than reintroducing prop-drilling.
     content is `inert` while open. The overlay closes on navigation
     (`afterNavigate` inside `AppShell` — consumers write nothing), Escape,
     a scrim click, and widening out of narrow mode (a crossing `$effect`).
-    Not `role="dialog"` — the same element is the persistent sidebar at
-    wide, so no focus trap.
+  - **The open overlay is a modal dialog.** While it's open the sidebar
+    carries `role="dialog"`, `aria-modal="true"`, and `aria-label` from
+    `sidebar_label`. They key on the open overlay (`overlay_open`), which
+    reads the viewport — that's what keeps the persistent wide sidebar (the
+    same element) from ever being a dialog — and the server render matches
+    hydration because the overlay always starts closed, as with `inert`.
+    Opening moves
+    focus into it — the content went `inert`, which dropped focus — to the
+    first control that takes focus (`tabIndex >= 0`, checked after each
+    `focus()`), else to the sidebar itself, `tabindex="-1"` while it's the
+    overlay (script-focusable, skipped by Tab; the wide sidebar has none, so
+    a click on its background leaves focus where it was). No focus trap:
+    `inert` already keeps Tab out of the content, and the built-in toggle
+    stays Tab-reachable as a close control. `aria-modal` lets assistive
+    tech hide everything outside the sidebar, the toggle included
+    (Chromium keeps it exposed; WebKit may not), so a sidebar whose
+    screen-reader users need a close control beyond Escape and navigation
+    renders its own.
   - **Escape** is a window `keydown` listener registered by an `$effect`
     only while the overlay is open, so listeners registered earlier (a
     contextmenu's, mounted with the page) see Escape first and can swallow
@@ -120,12 +144,12 @@ pattern rather than reintroducing prop-drilling.
     focus returns. When focus was inside the sidebar or had fallen to `body`
     (opening from the content makes it `inert`, which drops focus there), it
     goes back to the opener if still connected and focusable, else to the
-    first `[aria-controls="<sidebar_id>"]` that takes focus (Safari doesn't
-    focus a clicked button, so the opener can be `null`). A narrow-mode
-    close from `keyboard_shortcut` goes through the same close-and-return
-    path; wide mode just toggles. The shortcut bails on an open modal too,
-    so pressing it inside a dialog opened from the overlay doesn't close the
-    overlay behind it.
+    first `[aria-controls]` naming the sidebar's id that takes focus (Safari
+    doesn't focus a clicked button, so the opener can be `null`). A
+    narrow-mode close from `keyboard_shortcut` or a scrim click goes through
+    the same close-and-return path; wide mode just toggles. The shortcut
+    bails on an open modal too, so pressing it inside a dialog opened from
+    the overlay doesn't close the overlay behind it.
   - **No hydration flash.** The mode rules sit in two cascade layers
     nested under `fuz_app`. `@layer fuz_app.app_shell_base` in the scoped
     `<style>` holds the base and state rules, which apply in both modes;
@@ -208,7 +232,9 @@ pattern rather than reintroducing prop-drilling.
   `enabled?` (reactive getter overriding the internal field) and
   `narrow_query?` (`null` disables narrow mode; must contain parentheses
   since it feeds both CSS `media` and `MediaQuery`, which would auto-wrap a
-  paren-less query while CSS wouldn't — throws in DEV). Visibility is two
+  paren-less query while CSS wouldn't — throws in DEV), and `sidebar_id?`
+  (the sidebar element's id, read back as the readonly `sidebar_id`, `null`
+  when unset — for toggles outside `AppShell`). Visibility is two
   viewport-free fields, `show_sidebar_wide` (default `true`, the desktop
   preference narrow interactions never touch) and `show_sidebar_narrow`
   (default `false`). `narrow` is the viewport match (`false` in SSR);
@@ -509,7 +535,8 @@ format_scope, global_label)` helper — `global_label = null` renders no
   `format_scope?: FormatScope` prop — same shape as the context, prop
   wins when supplied.
 - `sidebar_state_context` — `() => SidebarState`. Provisioned by
-  `AppShell`.
+  `AppShell`. A toggle reading it for `aria-controls` needs the state's
+  `sidebar_id` option set (see Shell + layout).
 
 ## Popovers
 

package/dist/ui/RoleGrantOfferHistory.svelte

@@ -82,7 +82,7 @@
 </script>
 
 <section>
-	<h2>offer history</h2>
+	<h2>Offer History</h2>
 
 	{#if role_grant_offers.list_history.loading}
 		<p class="text_50">loading history...</p>

package/dist/ui/RoleGrantOfferInbox.svelte

@@ -46,7 +46,7 @@
 </script>
 
 <section class="role-grant-offer-inbox">
-	<h2>pending offers</h2>
+	<h2>Pending Offers</h2>
 
 	{#if role_grant_offers.list.error ||
 		role_grant_offers.accept.error ||

package/dist/ui/SurfaceExplorer.svelte

@@ -133,7 +133,7 @@
 		{/if}
 	</div>
 
-	<h3>routes</h3>
+	<h3>Routes</h3>
 	<div class="mb_sm">
 		<label>
 			<div class="title">auth filter</div>
@@ -218,7 +218,7 @@
 		</div>
 	{/if}
 
-	<h3>middleware</h3>
+	<h3>Middleware</h3>
 	{#if surface.middleware.length === 0}
 		<p class="text_50">no middleware</p>
 	{:else}
@@ -247,7 +247,7 @@
 	{/if}
 
 	{#if surface.env.length}
-		<h3>environment</h3>
+		<h3>Environment</h3>
 		<div style:overflow-x="auto">
 			<table>
 				<thead>
@@ -275,7 +275,7 @@
 	{/if}
 
 	{#if surface.events.length}
-		<h3>events</h3>
+		<h3>Events</h3>
 		<div style:overflow-x="auto">
 			<table>
 				<thead>
@@ -319,7 +319,7 @@
 	{/if}
 
 	{#if surface.rpc_endpoints.length}
-		<h3>rpc endpoints</h3>
+		<h3>RPC Endpoints</h3>
 		{#each surface.rpc_endpoints as endpoint (endpoint.path)}
 			<div class="row" style:gap="var(--space_sm)" style:align-items="center">
 				<code>{endpoint.path}</code>
@@ -380,7 +380,7 @@
 	{/if}
 
 	{#if surface.ws_endpoints.length}
-		<h3>websocket endpoints</h3>
+		<h3>WebSocket Endpoints</h3>
 		{#each surface.ws_endpoints as endpoint (endpoint.path)}
 			<div
 				class="row"
@@ -458,7 +458,7 @@
 	{/if}
 
 	{#if surface.diagnostics.length}
-		<h3>diagnostics</h3>
+		<h3>Diagnostics</h3>
 		<div style:overflow-x="auto">
 			<table>
 				<thead>

package/dist/ui/sidebar_state.svelte.d.ts

@@ -42,11 +42,22 @@ export interface SidebarStateOptions {
      * @default SIDEBAR_NARROW_QUERY_DEFAULT
      */
     narrow_query?: string | null;
+    /**
+     * The sidebar element's `id`. Set it when a toggle outside `AppShell` needs
+     * `aria-controls` — the relationship closing the overlay also follows to
+     * return focus when the opener didn't take it (Safari doesn't focus a
+     * clicked button). Omitted, `AppShell` generates one, which only its own
+     * toggle knows. Set, it assumes one shell per state: shells mounted at
+     * the same time with this state would render the same id.
+     */
+    sidebar_id?: string;
 }
 export declare class SidebarState {
     #private;
     /** The media query for narrow mode, or `null` when narrow mode is disabled. */
     readonly narrow_query: string | null;
+    /** The sidebar element's `id`, or `null` to let `AppShell` generate one. */
+    readonly sidebar_id: string | null;
     /**
      * Whether the sidebar shows beside the content outside narrow mode — the
      * desktop preference. Narrow-mode interactions never touch it.
@@ -57,7 +68,7 @@ export declare class SidebarState {
     /**
      * Creates the state, subscribing to `narrow_query` unless it is `null`.
      *
-     * @param options - enabled getter and narrow-mode query
+     * @param options - enabled getter, narrow-mode query, and sidebar id
      * @throws Error in DEV when `narrow_query` has no parentheses — `MediaQuery`
      *   would auto-wrap it but CSS `media` would not, so they'd disagree
      */

package/dist/ui/sidebar_state.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sidebar_state.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/sidebar_state.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH;;;GAGG;AACH,eAAO,MAAM,4BAA4B,uBAAuB,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;2CAAwB,YAAY;4BAAZ,YAAY;uBAAZ,YAAY,WAAZ,YAAY;CAAG,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;IACxB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,qBAAa,YAAY;;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAErC;;;OAGG;IACH,iBAAiB,EAAE,OAAO,CAAoB;IAE9C,+CAA+C;IAC/C,mBAAmB,EAAE,OAAO,CAAqB;IAMjD;;;;;;OAMG;gBACS,OAAO,CAAC,EAAE,mBAAmB;IAazC,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,OAAO,EAEzB;IAED;;;;;OAKG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;;OAIG;IACH,IAAI,YAAY,IAAI,OAAO,CAG1B;IAED,IAAI,YAAY,CAAC,KAAK,EAAE,OAAO,EAM9B;IAED;;;;OAIG;IACH,cAAc,CAAC,KAAK,GAAE,OAA4B,GAAG,IAAI;IAIzD;;;;OAIG;IACH,YAAY,IAAI,IAAI;IAIpB;;;;;;OAMG;IACH,QAAQ,IAAI,MAAM,IAAI;CAStB"}
+{"version":3,"file":"sidebar_state.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/sidebar_state.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH;;;GAGG;AACH,eAAO,MAAM,4BAA4B,uBAAuB,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;2CAAwB,YAAY;4BAAZ,YAAY;uBAAZ,YAAY,WAAZ,YAAY;CAAG,CAAC;AAE1E,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,OAAO,CAAC;IACxB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,YAAY;;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAErC,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnC;;;OAGG;IACH,iBAAiB,EAAE,OAAO,CAAoB;IAE9C,+CAA+C;IAC/C,mBAAmB,EAAE,OAAO,CAAqB;IAMjD;;;;;;OAMG;gBACS,OAAO,CAAC,EAAE,mBAAmB;IAczC,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,OAAO,EAEzB;IAED;;;;;OAKG;IACH,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED;;;;OAIG;IACH,IAAI,YAAY,IAAI,OAAO,CAG1B;IAED,IAAI,YAAY,CAAC,KAAK,EAAE,OAAO,EAM9B;IAED;;;;OAIG;IACH,cAAc,CAAC,KAAK,GAAE,OAA4B,GAAG,IAAI;IAIzD;;;;OAIG;IACH,YAAY,IAAI,IAAI;IAIpB;;;;;;OAMG;IACH,QAAQ,IAAI,MAAM,IAAI;CAStB"}

package/dist/ui/sidebar_state.svelte.js

@@ -28,6 +28,8 @@ export const sidebar_state_context = create_context();
 export class SidebarState {
     /** The media query for narrow mode, or `null` when narrow mode is disabled. */
     narrow_query;
+    /** The sidebar element's `id`, or `null` to let `AppShell` generate one. */
+    sidebar_id;
     /**
      * Whether the sidebar shows beside the content outside narrow mode — the
      * desktop preference. Narrow-mode interactions never touch it.
@@ -41,7 +43,7 @@ export class SidebarState {
     /**
      * Creates the state, subscribing to `narrow_query` unless it is `null`.
      *
-     * @param options - enabled getter and narrow-mode query
+     * @param options - enabled getter, narrow-mode query, and sidebar id
      * @throws Error in DEV when `narrow_query` has no parentheses — `MediaQuery`
      *   would auto-wrap it but CSS `media` would not, so they'd disagree
      */
@@ -52,6 +54,7 @@ export class SidebarState {
             throw new Error(`SidebarState narrow_query must include parentheses, got '${narrow_query}' — try '(${narrow_query})'`);
         }
         this.narrow_query = narrow_query;
+        this.sidebar_id = options?.sidebar_id ?? null;
         this.#narrow_media = narrow_query === null ? null : new MediaQuery(narrow_query, false);
     }
     get enabled() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.116.0",
+  "version": "0.117.1",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",