@sovereignfs/ui 0.45.0 → 0.54.0

package/dist/tokens/primitives.css

@@ -77,6 +77,16 @@
   --sv-font-weight-semibold: 600;
   --sv-font-weight-bold: 700;
 
+  /* In-app text-size control (task 10.2), discharging the pinch-zoom-disabled
+     accessibility debt (runtime/app/layout.tsx sets userScalable: false).
+     Every --sv-font-size-* above is rem-based, so scaling the root font size
+     scales the whole type system with no per-component changes. Driven by
+     [data-text-size] on <html>, set pre-paint by runtime/src/theme-script.ts
+     from the `sv-text-size` cookie — same mechanism as [data-theme]. Like
+     --sv-radius-scale, this is a theme-stable scale token with no separate
+     semantic tier. */
+  --sv-text-size-scale: 1;
+
   /* Icon sizes — scale tokens used directly by the Icon component */
   --sv-icon-size-xs: 0.75rem; /* 12px — inline metadata (e.g. a due-date badge) */
   --sv-icon-size-sm: 1rem; /* 16px — inline with body text */
@@ -130,3 +140,18 @@
     1
   ); /* slight overshoot — playful emphasis, use sparingly */
 }
+
+/* Root font size scales with --sv-text-size-scale — see the token comment
+   above. calc(...  * 100%) keeps the browser/OS text-zoom default intact at
+   scale 1 rather than hardcoding a px value. */
+html {
+  font-size: calc(var(--sv-text-size-scale) * 100%);
+}
+
+:root[data-text-size='large'] {
+  --sv-text-size-scale: 1.125; /* +12.5% */
+}
+
+:root[data-text-size='larger'] {
+  --sv-text-size-scale: 1.25; /* +25% */
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sovereignfs/ui",
-  "version": "0.45.0",
+  "version": "0.54.0",
   "type": "module",
   "description": "Sovereign Design System — design tokens and React components.",
   "keywords": [
@@ -36,16 +36,17 @@
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@storybook/addon-a11y": "^10.4.6",
-    "@storybook/addon-themes": "^10.4.6",
-    "@storybook/react-vite": "^10.4.6",
+    "@playwright/test": "^1.62.1",
+    "@storybook/addon-a11y": "^10.5.5",
+    "@storybook/addon-themes": "^10.5.5",
+    "@storybook/react-vite": "^10.5.5",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "storybook": "^10.4.6",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "storybook": "^10.5.5",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "@sovereignfs/tsconfig": "0.0.0"
@@ -53,7 +54,10 @@
   "scripts": {
     "build": "tsup",
     "storybook": "storybook dev -p 6006",
+    "storybook:visual": "storybook dev -p 6100 --ci --quiet",
     "build-storybook": "storybook build --output-dir storybook-static",
+    "test:visual": "playwright test --config=playwright.visual.config.ts",
+    "test:visual:update": "playwright test --config=playwright.visual.config.ts --update-snapshots",
     "typecheck": "tsc --noEmit"
   },
   "types": "./dist/index.d.ts"

package/src/components/Badge/Badge.tsx

@@ -4,13 +4,7 @@ import styles from './Badge.module.css';
 export type BadgeVariant = 'role' | 'status' | 'mono';
 export type BadgeSize = 'sm' | 'md' | 'lg';
 export type BadgeStatus =
-  | 'active'
-  | 'enabled'
-  | 'deactivated'
-  | 'failed'
-  | 'invited'
-  | 'pending'
-  | 'neutral';
+  'active' | 'enabled' | 'deactivated' | 'failed' | 'invited' | 'pending' | 'neutral';
 
 export interface BadgeProps {
   variant?: BadgeVariant;

package/src/components/DeviceOnlyGate/DeviceOnlyGate.tsx

@@ -0,0 +1,58 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { EmptyState } from '../EmptyState/EmptyState';
+
+export interface DeviceOnlyGateProps {
+  children: ReactNode;
+  /** Defaults to a generic "this app" phrasing — pass the plugin's own name. */
+  surfaceName?: string;
+  /**
+   * The caller's own `isDeviceOnlyTierAvailable()` result (from
+   * `@sovereignfs/sdk/device-client`) — taken as a plain boolean rather than
+   * computed inside this component, so `@sovereignfs/ui` never depends on
+   * `@sovereignfs/sdk` (this package must stay usable standalone, outside the
+   * plugin runtime — RFC 0073).
+   */
+  available: boolean;
+  className?: string;
+}
+
+/**
+ * DeviceOnlyGate — blocks a `device-only`-tier plugin's content from
+ * rendering on a surface that cannot provide the durable, encrypted,
+ * device-auth-gated store that tier requires, showing an explanatory empty
+ * state instead of a broken screen (research 0012, epic tasks 2.33 + 3.36).
+ *
+ * A `device-only` plugin wraps its own root content in this the same way
+ * Console and Account wrap theirs in `OfflineGate` — an opt-in pattern each
+ * surface applies to itself, not a platform-level route gate. The launcher
+ * tile's own "Phone only" badge (`useOfflineTileState`) is advisory UI on top
+ * of this; this component is the actual gate, since a user can always reach a
+ * route directly (a bookmark, a deep link) without passing through the
+ * launcher tile at all.
+ *
+ * **Not a security boundary.** Availability here is a capability signal, not
+ * an authorization check — the real protection for `device-only` data is
+ * that it is encrypted and the key requires device auth to release (epic task
+ * 1.22), so it stays inaccessible regardless of whether this gate is present,
+ * bypassed, or simply never reached (e.g. a hand-crafted request against the
+ * plugin's own API routes).
+ */
+export function DeviceOnlyGate({
+  children,
+  surfaceName,
+  available,
+  className,
+}: DeviceOnlyGateProps) {
+  if (available) return <>{children}</>;
+
+  return (
+    <EmptyState
+      icon="smartphone"
+      heading="Phone only"
+      description={`${surfaceName ?? 'This app'} is only available on a phone with secure storage set up.`}
+      className={className}
+    />
+  );
+}

package/src/components/DeviceOnlyGate/__tests__/DeviceOnlyGate.test.tsx

@@ -0,0 +1,45 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { DeviceOnlyGate } from '../DeviceOnlyGate';
+
+describe('DeviceOnlyGate', () => {
+  afterEach(cleanup);
+
+  it('renders children unchanged when available', () => {
+    render(
+      <DeviceOnlyGate available={true}>
+        <p>Wallet content</p>
+      </DeviceOnlyGate>,
+    );
+    expect(screen.getByText('Wallet content')).toBeDefined();
+  });
+
+  it('replaces children with an explanatory empty state when unavailable', () => {
+    render(
+      <DeviceOnlyGate available={false}>
+        <p>Wallet content</p>
+      </DeviceOnlyGate>,
+    );
+    expect(screen.queryByText('Wallet content')).toBeNull();
+    expect(screen.getByText('Phone only')).toBeDefined();
+  });
+
+  it('names the surface in the message when provided', () => {
+    render(
+      <DeviceOnlyGate available={false} surfaceName="Wallet">
+        <p>Wallet content</p>
+      </DeviceOnlyGate>,
+    );
+    expect(screen.getByText(/Wallet is only available on a phone/)).toBeDefined();
+  });
+
+  it('falls back to generic phrasing with no surface name', () => {
+    render(
+      <DeviceOnlyGate available={false}>
+        <p>Wallet content</p>
+      </DeviceOnlyGate>,
+    );
+    expect(screen.getByText(/This app is only available on a phone/)).toBeDefined();
+  });
+});

package/src/components/DeviceStorageKeyGate/DeviceStorageKeyGate.tsx

@@ -0,0 +1,100 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { EmptyState } from '../EmptyState/EmptyState';
+
+/**
+ * `'checking'` covers the moment before the caller's own async status check
+ * resolves — same transitional-state pattern `EncryptionSection`'s local
+ * `LocalState` uses, so this gate never flashes an empty state before the
+ * real answer is known. `'no-device-auth'` is the hard-block case (RFC 0093
+ * §5, epic task 1.22): the environment supports the tier, but this device
+ * has no passcode, fingerprint, or face unlock configured, so a key cannot
+ * be created here at all — distinct from `'not-set-up'`, where it can.
+ */
+export type DeviceStorageKeyGateStatus =
+  'checking' | 'unsupported' | 'no-device-auth' | 'not-set-up' | 'set-up';
+
+export interface DeviceStorageKeyGateProps {
+  children: ReactNode;
+  /** Defaults to a generic "This app" phrasing — pass the plugin's own name. */
+  surfaceName?: string;
+  /**
+   * The caller's own `getDeviceStorageKeyStatus()` result (from
+   * `@sovereignfs/sdk/device-only-storage`) — taken as a plain status rather
+   * than computed inside this component, so `@sovereignfs/ui` never depends
+   * on `@sovereignfs/sdk` (same boundary `DeviceOnlyGate`'s `available` prop
+   * draws — this package must stay usable standalone, outside the plugin
+   * runtime — RFC 0073).
+   */
+  status: DeviceStorageKeyGateStatus;
+  /**
+   * Rendered under the "not set up" message — typically a link to Account →
+   * Security. Not built in here: this package depends on no router, so the
+   * caller supplies its own navigable element (a plain `<a>`, a framework
+   * `<Link>`, whatever the host app uses).
+   */
+  setupAction?: ReactNode;
+  className?: string;
+}
+
+/**
+ * DeviceStorageKeyGate — blocks a `device-only`-tier plugin's content until
+ * the user has set up their Device Storage Key (RFC 0093 §2, epic task
+ * 1.22). Distinct from `DeviceOnlyGate`: that one checks whether the *tier
+ * itself* is available on this surface (native shell, secure-storage bridge
+ * present); this one checks whether the user has actually completed the
+ * one-time, per-device enrollment that tier depends on. A `device-only`
+ * plugin typically wants both — `DeviceOnlyGate` outermost (no point
+ * checking enrollment on a surface that cannot offer the tier at all), this
+ * gate inside it.
+ *
+ * Enrollment is centralized and decoupled from any single plugin (RFC 0093
+ * §2): a plugin that finds no key set up does not run its own enrollment
+ * ceremony inline. It stops here and points the user at Account → Security —
+ * the one place enrollment happens for every `device-only` plugin on this
+ * device — via `setupAction`, the same opt-in, self-applied pattern
+ * `OfflineGate`/`DeviceOnlyGate` already use for their own surfaces.
+ */
+export function DeviceStorageKeyGate({
+  children,
+  surfaceName,
+  status,
+  setupAction,
+  className,
+}: DeviceStorageKeyGateProps) {
+  if (status === 'checking') return null;
+  if (status === 'set-up') return <>{children}</>;
+
+  if (status === 'unsupported') {
+    return (
+      <EmptyState
+        icon="smartphone"
+        heading="Phone only"
+        description={`${surfaceName ?? 'This app'} needs a security feature (WebAuthn PRF and Origin Private File System support) that isn't available here.`}
+        className={className}
+      />
+    );
+  }
+
+  if (status === 'no-device-auth') {
+    return (
+      <EmptyState
+        icon="alert-triangle"
+        heading="Set up a device passcode"
+        description={`${surfaceName ?? 'This app'} needs a passcode, fingerprint, or face unlock set up on this device before its Device Storage Key can be created. Set one up in your device's system settings, then come back.`}
+        className={className}
+      />
+    );
+  }
+
+  return (
+    <EmptyState
+      icon="lock"
+      heading="Set up your Device Storage Key"
+      description={`${surfaceName ?? 'This app'} keeps its data only on this device, protected by a Device Storage Key you set up once in Account → Security.`}
+      action={setupAction}
+      className={className}
+    />
+  );
+}

package/src/components/DeviceStorageKeyGate/__tests__/DeviceStorageKeyGate.test.tsx

@@ -0,0 +1,119 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+import { cleanup, render, screen } from '@testing-library/react';
+import { DeviceStorageKeyGate } from '../DeviceStorageKeyGate';
+
+describe('DeviceStorageKeyGate', () => {
+  afterEach(cleanup);
+
+  it('renders nothing while checking', () => {
+    const { container } = render(
+      <DeviceStorageKeyGate status="checking">
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it('renders children unchanged once set up', () => {
+    render(
+      <DeviceStorageKeyGate status="set-up">
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.getByText('Notes content')).toBeDefined();
+  });
+
+  it('shows a "Phone only"-style message when the environment is unsupported', () => {
+    render(
+      <DeviceStorageKeyGate status="unsupported">
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.queryByText('Notes content')).toBeNull();
+    expect(screen.getByText('Phone only')).toBeDefined();
+  });
+
+  it('shows the setup message and prompt when not-set-up', () => {
+    render(
+      <DeviceStorageKeyGate status="not-set-up">
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.queryByText('Notes content')).toBeNull();
+    expect(screen.getByText('Set up your Device Storage Key')).toBeDefined();
+  });
+
+  it('names the surface in the not-set-up message when provided', () => {
+    render(
+      <DeviceStorageKeyGate status="not-set-up" surfaceName="Notes">
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.getByText(/Notes keeps its data only on this device/)).toBeDefined();
+  });
+
+  it('falls back to generic phrasing with no surface name', () => {
+    render(
+      <DeviceStorageKeyGate status="not-set-up">
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.getByText(/This app keeps its data only on this device/)).toBeDefined();
+  });
+
+  it('renders the caller-supplied setupAction when not-set-up', () => {
+    render(
+      <DeviceStorageKeyGate
+        status="not-set-up"
+        setupAction={<a href="/account/security">Go to Account → Security</a>}
+      >
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.getByRole('link', { name: 'Go to Account → Security' })).toBeDefined();
+  });
+
+  it('renders no setupAction when unsupported, even if one is passed', () => {
+    render(
+      <DeviceStorageKeyGate
+        status="unsupported"
+        setupAction={<a href="/account/security">Go to Account → Security</a>}
+      >
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.queryByRole('link')).toBeNull();
+  });
+
+  it('shows the hard-block message when no-device-auth', () => {
+    render(
+      <DeviceStorageKeyGate status="no-device-auth">
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.queryByText('Notes content')).toBeNull();
+    expect(screen.getByText('Set up a device passcode')).toBeDefined();
+  });
+
+  it('names the surface in the no-device-auth message when provided', () => {
+    render(
+      <DeviceStorageKeyGate status="no-device-auth" surfaceName="Notes">
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.getByText(/Notes needs a passcode, fingerprint, or face unlock/)).toBeDefined();
+  });
+
+  it('renders no setupAction when no-device-auth, even if one is passed — fixing this is a device settings change, not a Sovereign link', () => {
+    render(
+      <DeviceStorageKeyGate
+        status="no-device-auth"
+        setupAction={<a href="/account/security">Go to Account → Security</a>}
+      >
+        <p>Notes content</p>
+      </DeviceStorageKeyGate>,
+    );
+    expect(screen.queryByRole('link')).toBeNull();
+  });
+});

package/src/components/Dialog/Dialog.tsx

@@ -1,8 +1,12 @@
 'use client';
 
 import { createContext, type ReactNode, useContext, useEffect, useRef, useState } from 'react';
-import { lockBodyScroll, unlockBodyScroll } from '../../scroll-lock';
 import { useMountTransition, usePrefersReducedMotion } from '../../motion';
+import {
+  useOverlayFocusCapture,
+  useOverlayKeyboardTrap,
+  useOverlayScrollLock,
+} from '../../overlay-shell';
 import { OverlayHeader } from '../OverlayHeader/OverlayHeader';
 import styles from './Dialog.module.css';
 
@@ -69,9 +73,6 @@ export interface DialogProps {
   children: ReactNode;
 }
 
-const FOCUSABLE =
-  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
-
 /**
  * Dialog — a modal surface (scrim + panel) for overlay-shell plugins and any
  * plugin that needs a dismissable layer. Router-agnostic: the caller decides
@@ -97,65 +98,13 @@ export function Dialog({
   children,
 }: DialogProps) {
   const panelRef = useRef<HTMLDivElement>(null);
-  const previouslyFocused = useRef<HTMLElement | null>(null);
   const reducedMotion = usePrefersReducedMotion();
   const { mounted, phase } = useMountTransition(open, reducedMotion ? 0 : MOTION_DURATION_MS);
   const [secondRow, setSecondRow] = useState<ReactNode | null>(null);
 
-  // Prevent document-level scroll for the whole mounted lifetime, including
-  // the exit animation — not just while `open` — so the background can't
-  // scroll while the panel is still visibly sliding/fading away. Ref-counted
-  // so nested overlays (e.g. a confirmation dialog inside an overlay plugin)
-  // don't release the lock while a sibling is still open.
-  useEffect(() => {
-    if (!mounted) return;
-    lockBodyScroll();
-    return unlockBodyScroll;
-  }, [mounted]);
-
-  // Capture focus on open; restore it on close/unmount.
-  useEffect(() => {
-    if (!open) return;
-    previouslyFocused.current = document.activeElement as HTMLElement | null;
-    const panel = panelRef.current;
-    const first = panel?.querySelector<HTMLElement>(FOCUSABLE);
-    (first ?? panel)?.focus();
-    return () => previouslyFocused.current?.focus();
-  }, [open]);
-
-  // Keyboard handling: Escape closes, Tab cycles within the panel (focus trap).
-  // Attached at document level so no keyboard listener is needed on the dialog
-  // div itself (which would trigger jsx-a11y/no-noninteractive-element-interactions).
-  useEffect(() => {
-    if (!open) return;
-    function handleKeyDown(e: KeyboardEvent) {
-      if (e.key === 'Escape') {
-        e.stopPropagation();
-        onClose();
-        return;
-      }
-      if (e.key !== 'Tab') return;
-      const panel = panelRef.current;
-      if (!panel) return;
-      const focusable = [...panel.querySelectorAll<HTMLElement>(FOCUSABLE)];
-      const first = focusable[0];
-      const last = focusable.at(-1);
-      if (!first || !last) {
-        e.preventDefault();
-        return;
-      }
-      const active = document.activeElement;
-      if (e.shiftKey && active === first) {
-        e.preventDefault();
-        last.focus();
-      } else if (!e.shiftKey && active === last) {
-        e.preventDefault();
-        first.focus();
-      }
-    }
-    document.addEventListener('keydown', handleKeyDown);
-    return () => document.removeEventListener('keydown', handleKeyDown);
-  }, [open, onClose]);
+  useOverlayScrollLock(mounted);
+  useOverlayFocusCapture(panelRef, open);
+  useOverlayKeyboardTrap(panelRef, open, onClose);
 
   if (!mounted) return null;
   const isOpenPhase = phase === 'open';

package/src/components/Drawer/Drawer.stories.tsx

@@ -75,6 +75,50 @@ export const Closed: Story = {
   ),
 };
 
+function DrawerWithTitleDemo() {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <Button onClick={() => setOpen(true)}>Open drawer</Button>
+      <Drawer open={open} onClose={() => setOpen(false)} title="Apps">
+        <ul style={{ listStyle: 'none', margin: 0, padding: '8px 0' }}>
+          {(['house', 'grid-2x2', 'settings', 'user'] as const).map((icon) => (
+            <li key={icon}>
+              <button
+                onClick={() => setOpen(false)}
+                style={{
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 12,
+                  width: '100%',
+                  padding: '12px 20px',
+                  background: 'none',
+                  border: 'none',
+                  cursor: 'pointer',
+                  fontSize: 15,
+                  color: 'var(--sv-color-text-primary)',
+                  fontFamily: 'system-ui',
+                }}
+              >
+                <Icon name={icon} size="md" aria-hidden />
+                {icon.replace(/-/g, ' ')}
+              </button>
+            </li>
+          ))}
+        </ul>
+      </Drawer>
+    </>
+  );
+}
+
+/** Opt-in `title` prop renders a built-in `OverlayHeader` (title + close)
+ * below the grab handle — hidden by default (see the `Default` story), for
+ * consumers that want one instead of building their own header markup. */
+export const WithTitle: Story = {
+  args: { open: false, onClose: () => {}, children: null },
+  render: (_args) => <DrawerWithTitleDemo />,
+};
+
 /** Play function opens the drawer and asserts its list items are visible. */
 export const OpenViaInteraction: Story = {
   args: { open: false, onClose: () => {}, children: null },

package/src/components/Drawer/Drawer.tsx

@@ -1,8 +1,13 @@
 'use client';
 
-import { type PointerEvent as ReactPointerEvent, type ReactNode, useEffect, useRef } from 'react';
-import { lockBodyScroll, unlockBodyScroll } from '../../scroll-lock';
+import { type PointerEvent as ReactPointerEvent, type ReactNode, useRef } from 'react';
 import { useMountTransition, usePrefersReducedMotion } from '../../motion';
+import {
+  useOverlayFocusCapture,
+  useOverlayKeyboardTrap,
+  useOverlayScrollLock,
+} from '../../overlay-shell';
+import { OverlayHeader } from '../OverlayHeader/OverlayHeader';
 import styles from './Drawer.module.css';
 
 // Matches --sv-motion-duration-base (Drawer.module.css) — see Dialog.tsx's
@@ -22,12 +27,15 @@ export interface DrawerProps {
    *  "half screen or less" convention for Drawer, this is the only other
    *  supported size; taller content should use `Sheet` instead. */
   snapHeight?: 'content' | 'half';
+  /** Renders a built-in `OverlayHeader` (title + close) below the grab
+   *  handle. Omit when the content supplies its own header, or none is
+   *  needed at all — e.g. the mobile shell's Apps drawer, whose grab handle
+   *  and swipe-down/scrim-tap dismissal are enough on their own. Mirrors
+   *  `Sheet`'s identical `title` prop. */
+  title?: string;
   children: ReactNode;
 }
 
-const FOCUSABLE =
-  'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
-
 // Downward drag distance (px) past which releasing dismisses the drawer
 // instead of snapping back open. Distance-only, no velocity tracking — matches
 // the swipe-to-reveal gesture already established in consuming plugins (see
@@ -61,10 +69,10 @@ export function Drawer({
   onClose,
   'aria-label': ariaLabel,
   snapHeight = 'content',
+  title,
   children,
 }: DrawerProps) {
   const panelRef = useRef<HTMLDivElement>(null);
-  const previouslyFocused = useRef<HTMLElement | null>(null);
   const reducedMotion = usePrefersReducedMotion();
   const { mounted, phase } = useMountTransition(open, reducedMotion ? 0 : MOTION_DURATION_MS);
   // Tracks an in-progress handle drag. Kept in a ref (not state) so pointermove
@@ -72,56 +80,9 @@ export function Drawer({
   // same technique as the tasks plugin's swipe-to-reveal rows.
   const dragStartY = useRef<number | null>(null);
 
-  // Locked for the whole mounted lifetime (including the exit animation), not
-  // just while `open` — see Dialog.tsx's identical comment for why.
-  useEffect(() => {
-    if (!mounted) return;
-    lockBodyScroll();
-    return unlockBodyScroll;
-  }, [mounted]);
-
-  useEffect(() => {
-    if (!open) return;
-    previouslyFocused.current = document.activeElement as HTMLElement | null;
-    const panel = panelRef.current;
-    const first = panel?.querySelector<HTMLElement>(FOCUSABLE);
-    (first ?? panel)?.focus();
-    return () => previouslyFocused.current?.focus();
-  }, [open]);
-
-  // Keyboard handling: Escape closes, Tab cycles within the panel (focus trap).
-  // Attached at document level so no keyboard listener is needed on the dialog
-  // div itself (which would trigger jsx-a11y/no-noninteractive-element-interactions).
-  useEffect(() => {
-    if (!open) return;
-    function handleKeyDown(e: KeyboardEvent) {
-      if (e.key === 'Escape') {
-        e.stopPropagation();
-        onClose();
-        return;
-      }
-      if (e.key !== 'Tab') return;
-      const panel = panelRef.current;
-      if (!panel) return;
-      const focusable = [...panel.querySelectorAll<HTMLElement>(FOCUSABLE)];
-      const first = focusable[0];
-      const last = focusable.at(-1);
-      if (!first || !last) {
-        e.preventDefault();
-        return;
-      }
-      const active = document.activeElement;
-      if (e.shiftKey && active === first) {
-        e.preventDefault();
-        last.focus();
-      } else if (!e.shiftKey && active === last) {
-        e.preventDefault();
-        first.focus();
-      }
-    }
-    document.addEventListener('keydown', handleKeyDown);
-    return () => document.removeEventListener('keydown', handleKeyDown);
-  }, [open, onClose]);
+  useOverlayScrollLock(mounted);
+  useOverlayFocusCapture(panelRef, open);
+  useOverlayKeyboardTrap(panelRef, open, onClose);
 
   // Swipe-down-to-dismiss, initiated only from the grab handle (see the
   // component doc comment for why not the whole panel). Drags the panel
@@ -207,6 +168,7 @@ export function Drawer({
           onPointerUp={(e) => releaseDrag(e, true)}
           onPointerCancel={(e) => releaseDrag(e, false)}
         />
+        {title && <OverlayHeader title={title} onClose={onClose} />}
         {children}
       </div>
     </div>