feat(app-shell): useUrlOverlay primitive + URL-addressable shortcuts dialog (ADR-0054 Phase 2) (#1882)

Generalizes the Phase 1 command-palette fix into a reusable overlay primitive
and brings a second navigable overlay to the contract.

- **useUrlOverlay(key)** — router-aware hook storing a navigable overlay's open
  state in a `?<key>=1` URL param: idempotent open (C1), deep-linkable /
  restore-on-reload / back-forward (C3). `alias`/`value`/`replace` configurable.
  8 unit tests (MemoryRouter).
- **CommandPaletteProvider** refactored onto useUrlOverlay (`?palette=1`,
  `?cmdk=1` alias) — behavior unchanged, ~50 lines of bespoke URL logic removed.
- **KeyboardShortcutsDialog** is now URL-addressable (`?shortcuts=1`) and gains a
  click entry in the header Help menu (C2) — it was previously reachable ONLY via
  the `?` key (now an accelerator) with toggle-as-open `useState`. Adds
  `data-testid="overlay:keyboard-shortcuts"`.
- The shared overlay primitives already forward `data-testid` + emit Radix
  `data-state`; documented in the README (no code change needed).

Verified in-browser (agent-browser / CDP): palette click-open + `?palette=1`
deep-link still work post-refactor; the shortcuts dialog opens via the Help-menu
click, via `?shortcuts=1` deep-link, and via the `?` accelerator; no a11y errors.

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

.changeset/url-overlay-primitive.md

@@ -0,0 +1,15 @@
+---
+"@object-ui/app-shell": patch
+---
+
+feat(app-shell): useUrlOverlay primitive + URL-addressable keyboard-shortcuts dialog (ADR-0054 Phase 2)
+
+Adds `useUrlOverlay(key)` — a reusable, router-aware hook that stores a navigable
+overlay's open state in a `?<key>=1` URL param (idempotent open, deep-linkable,
+restore-on-reload, back/forward; `alias`/`value`/`replace` configurable). The
+command palette is refactored onto it (behavior unchanged: `?palette=1`, `?cmdk=1`
+alias). The keyboard-shortcuts dialog becomes URL-addressable (`?shortcuts=1`) and
+gains a click entry in the header Help menu — previously it was only reachable via
+the `?` key (which remains an accelerator). Generalizes ADR-0054 invariants C1/C3
+beyond the Phase 1 reference fix; the shared overlay primitives already carry
+`data-testid` + Radix `data-state`, documented in the README.

packages/app-shell/README.md

@@ -462,6 +462,37 @@ Designed to be deterministic for automated (AI) browser testing — see
   input. Value-injection (`el.value = …`) does **not** fire React's `onChange`;
   drive it with a real-input / CDP-keystroke driver so the debounced fetch fires.
 
+## URL-addressable overlays (`useUrlOverlay`)
+
+`useUrlOverlay(key)` is the reusable building block behind the command palette's
+URL-addressable open state (ADR-0054 C3). It stores a navigable overlay's open
+state in a `?<key>=1` search param instead of component `useState`, so the
+overlay is deep-linkable, restores on reload, and works with back/forward — and
+its open path is idempotent (C1).
+
+```tsx
+import { useUrlOverlay } from '@object-ui/app-shell';
+
+function HelpMenu() {
+  const { open, setOpen, openOverlay } = useUrlOverlay('shortcuts');
+  // Header button (any component under the router):  onClick={openOverlay}
+  // Dialog (elsewhere, reads the same param):        <Dialog open={open} onOpenChange={setOpen}>
+  // Deep-link that opens on load:                    /apps/foo?shortcuts=1
+}
+```
+
+Because state lives in the URL, a trigger and the overlay it controls need no
+shared provider or prop-drilling — they just use the same `key`. The
+command palette (`?palette=1`, `?cmdk=1` alias) and the keyboard-shortcuts dialog
+(`?shortcuts=1`, openable from the Help menu — no longer `?`-key-only) both build
+on it. `replace`/`alias`/`value` are configurable.
+
+The shared overlay primitives in `@object-ui/components`
+(`Dialog`/`Sheet`/`Drawer`/`Popover`/`DropdownMenu`/`AlertDialog`) already forward
+a `data-testid` onto their content element and emit Radix `data-state="open|closed"`,
+so overlays are locatable and their open/closed state is machine-readable by
+construction (C4).
+
 ## Compatibility
 
 - **React:** 18.x or 19.x

packages/app-shell/src/chrome/KeyboardShortcutsDialog.tsx

@@ -5,7 +5,7 @@
  * @module
  */
 
-import { useEffect, useState, useMemo } from 'react';
+import { useEffect, useMemo } from 'react';
 import {
   Dialog,
   DialogContent,
@@ -14,6 +14,7 @@ import {
   DialogDescription,
 } from '@object-ui/components';
 import { useObjectTranslation } from '@object-ui/i18n';
+import { useUrlOverlay } from '../hooks/useUrlOverlay';
 
 interface ShortcutEntry {
   keys: string[];
@@ -27,7 +28,10 @@ interface ShortcutGroup {
 
 export function KeyboardShortcutsDialog() {
   const { t } = useObjectTranslation();
-  const [open, setOpen] = useState(false);
+  // URL-addressable (?shortcuts=1) so the dialog is deep-linkable and openable
+  // from the header Help menu, not only via the `?` keyboard accelerator (ADR-0054
+  // C1/C2/C3).
+  const { open, setOpen, toggleOverlay } = useUrlOverlay('shortcuts');
 
   const shortcutGroups: ShortcutGroup[] = useMemo(() => [
     {
@@ -82,17 +86,20 @@ export function KeyboardShortcutsDialog() {
 
       if (e.key === '?' && !e.metaKey && !e.ctrlKey && !e.altKey) {
         e.preventDefault();
-        setOpen(prev => !prev);
+        toggleOverlay();
       }
     }
 
     document.addEventListener('keydown', handleKeyDown);
     return () => document.removeEventListener('keydown', handleKeyDown);
-  }, []);
+  }, [toggleOverlay]);
 
   return (
     <Dialog open={open} onOpenChange={setOpen}>
-      <DialogContent className="sm:max-w-lg max-h-[80vh] overflow-y-auto">
+      <DialogContent
+        className="sm:max-w-lg max-h-[80vh] overflow-y-auto"
+        data-testid="overlay:keyboard-shortcuts"
+      >
         <DialogHeader>
           <DialogTitle>{t('console.shortcuts.title')}</DialogTitle>
           <DialogDescription>

packages/app-shell/src/context/CommandPaletteProvider.tsx

@@ -4,41 +4,27 @@
  * Single source of truth for whether the global ⌘K command palette is open,
  * plus the shared, idempotent commands used to open / close it.
  *
- * Why this exists — ADR-0054 "UI testability contract", Phase 1:
+ * Open state is delegated to {@link useUrlOverlay} (`?palette=1`, `?cmdk=1`
+ * alias), so it is URL-addressable (deep-linkable, restore-on-reload,
+ * back/forward) per ADR-0054 invariant C3, and every "open" affordance — the
+ * top-bar search button, a programmatic caller, a deep-link — shares the same
+ * idempotent `openCommandPalette()` (never a toggle) per C1.
  *
- *  - **C1 (idempotent, direct triggers).** Every "open the palette" affordance —
- *    the top-bar search button, a programmatic caller, a deep-link — calls the
- *    SAME `openCommandPalette()`, which is idempotent (`setOpen(true)`), never a
- *    `toggle()`. Re-issuing "open" when already open is a no-op, so an automated
- *    driver can always *ensure* it is open. The previous header button re-emitted
- *    a synthetic `⌘K` `KeyboardEvent` and relied on the palette's global listener
- *    being mounted and the browser/OS not having reserved `⌘K` — which silently
- *    did nothing under automation (and in `⌘K`-reserving browsers).
- *  - **C3 (URL-addressable state).** Open state lives in the `?palette=1` search
- *    param, not component `useState`, so the palette is deep-linkable
- *    (`/apps/foo?palette=1`), restores on reload, and works with back/forward.
- *
- * `⌘K` stays an *accelerator*: the keydown handler toggles (close-on-repeat is a
- * keyboard nicety), but the OPEN path used by buttons / links / programmatic
+ * `⌘K` stays an *accelerator*: the keydown handler toggles (close-on-repeat is
+ * a keyboard nicety), but the OPEN path used by buttons / links / programmatic
  * callers is the idempotent `openCommandPalette()`.
  *
  * @module
  */
 
 import {
   createContext,
-  useCallback,
   useContext,
   useEffect,
   useMemo,
   type ReactNode,
 } from 'react';
-import { useSearchParams } from 'react-router-dom';
-
-/** Canonical URL param reflecting the palette's open state. */
-const PALETTE_PARAM = 'palette';
-/** Legacy/alias param accepted on read (e.g. `?cmdk=1`). */
-const PALETTE_PARAM_ALIAS = 'cmdk';
+import { useUrlOverlay } from '../hooks/useUrlOverlay';
 
 export interface CommandPaletteContextValue {
   /** Whether the palette is currently open (derived from the URL). */
@@ -55,77 +41,35 @@ export interface CommandPaletteContextValue {
 
 const CommandPaletteContext = createContext<CommandPaletteContextValue | null>(null);
 
-function isOpenParam(params: URLSearchParams): boolean {
-  return params.get(PALETTE_PARAM) === '1' || params.get(PALETTE_PARAM_ALIAS) === '1';
-}
-
 export function CommandPaletteProvider({ children }: { children: ReactNode }) {
-  const [searchParams, setSearchParams] = useSearchParams();
-
-  // Open state is URL-derived (C3): one source of truth that makes the palette
-  // deep-linkable + restore-on-reload, and makes "ensure open" idempotent for
-  // free.
-  const open = isOpenParam(searchParams);
-
-  const setOpen = useCallback(
-    (next: boolean) => {
-      // Truly idempotent: when already in the target state, do nothing — no
-      // redundant history navigation.
-      if (next === isOpenParam(searchParams)) return;
-      const sp = new URLSearchParams(searchParams);
-      if (next) {
-        sp.set(PALETTE_PARAM, '1');
-        sp.delete(PALETTE_PARAM_ALIAS);
-      } else {
-        sp.delete(PALETTE_PARAM);
-        sp.delete(PALETTE_PARAM_ALIAS);
-      }
-      // `replace` — toggling a transient overlay shouldn't pile up history.
-      setSearchParams(sp, { replace: true });
-    },
-    [searchParams, setSearchParams],
-  );
-
-  const openCommandPalette = useCallback(() => setOpen(true), [setOpen]);
-  const closeCommandPalette = useCallback(() => setOpen(false), [setOpen]);
-
-  // Toggle uses the functional updater so it never depends on `open` — keeping
-  // the keydown listener below stable across navigations.
-  const toggleCommandPalette = useCallback(() => {
-    setSearchParams(
-      (prev) => {
-        const sp = new URLSearchParams(prev);
-        if (isOpenParam(sp)) {
-          sp.delete(PALETTE_PARAM);
-          sp.delete(PALETTE_PARAM_ALIAS);
-        } else {
-          sp.set(PALETTE_PARAM, '1');
-          sp.delete(PALETTE_PARAM_ALIAS);
-        }
-        return sp;
-      },
-      { replace: true },
-    );
-  }, [setSearchParams]);
+  const { open, setOpen, openOverlay, closeOverlay, toggleOverlay } = useUrlOverlay('palette', {
+    alias: 'cmdk',
+  });
 
   // ⌘K / Ctrl+K accelerator. Lives here (not in CommandPalette) so the command
   // and its shortcut share one definition and one open-state source. Toggle is
   // fine for the *keyboard* (close-on-repeat); buttons/links/programmatic open
-  // paths use the idempotent openCommandPalette().
+  // paths use the idempotent openOverlay().
   useEffect(() => {
     const onKeyDown = (e: KeyboardEvent) => {
       if (e.key === 'k' && (e.metaKey || e.ctrlKey)) {
         e.preventDefault();
-        toggleCommandPalette();
+        toggleOverlay();
       }
     };
     document.addEventListener('keydown', onKeyDown);
     return () => document.removeEventListener('keydown', onKeyDown);
-  }, [toggleCommandPalette]);
+  }, [toggleOverlay]);
 
   const value = useMemo<CommandPaletteContextValue>(
-    () => ({ open, openCommandPalette, closeCommandPalette, toggleCommandPalette, setOpen }),
-    [open, openCommandPalette, closeCommandPalette, toggleCommandPalette, setOpen],
+    () => ({
+      open,
+      openCommandPalette: openOverlay,
+      closeCommandPalette: closeOverlay,
+      toggleCommandPalette: toggleOverlay,
+      setOpen,
+    }),
+    [open, openOverlay, closeOverlay, toggleOverlay, setOpen],
   );
 
   return (

packages/app-shell/src/hooks/__tests__/useUrlOverlay.test.tsx

@@ -0,0 +1,101 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { MemoryRouter, useLocation } from 'react-router-dom';
+import type { ReactNode } from 'react';
+import { useUrlOverlay } from '../useUrlOverlay';
+
+function wrapperFor(initial: string) {
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return <MemoryRouter initialEntries={[initial]}>{children}</MemoryRouter>;
+  };
+}
+
+function useHarness(key: string, opts?: Parameters<typeof useUrlOverlay>[1]) {
+  const controls = useUrlOverlay(key, opts);
+  const { search } = useLocation();
+  return { ...controls, search };
+}
+
+describe('useUrlOverlay', () => {
+  it('is closed when the param is absent', () => {
+    const { result } = renderHook(() => useHarness('palette'), { wrapper: wrapperFor('/') });
+    expect(result.current.open).toBe(false);
+  });
+
+  it('is open when the param is present on first render (deep-link)', () => {
+    const { result } = renderHook(() => useHarness('palette'), {
+      wrapper: wrapperFor('/apps/foo?palette=1'),
+    });
+    expect(result.current.open).toBe(true);
+  });
+
+  it('openOverlay writes ?key=1 and is idempotent', () => {
+    const { result } = renderHook(() => useHarness('palette'), { wrapper: wrapperFor('/') });
+
+    act(() => result.current.openOverlay());
+    expect(result.current.open).toBe(true);
+    expect(result.current.search).toBe('?palette=1');
+
+    // Idempotent: calling again leaves it open with the same URL (no toggle).
+    act(() => result.current.openOverlay());
+    expect(result.current.open).toBe(true);
+    expect(result.current.search).toBe('?palette=1');
+  });
+
+  it('closeOverlay removes the param', () => {
+    const { result } = renderHook(() => useHarness('palette'), {
+      wrapper: wrapperFor('/?palette=1'),
+    });
+    expect(result.current.open).toBe(true);
+    act(() => result.current.closeOverlay());
+    expect(result.current.open).toBe(false);
+    expect(result.current.search).toBe('');
+  });
+
+  it('toggleOverlay flips open state', () => {
+    const { result } = renderHook(() => useHarness('palette'), { wrapper: wrapperFor('/') });
+    act(() => result.current.toggleOverlay());
+    expect(result.current.open).toBe(true);
+    act(() => result.current.toggleOverlay());
+    expect(result.current.open).toBe(false);
+  });
+
+  it('preserves unrelated params when toggling', () => {
+    const { result } = renderHook(() => useHarness('palette'), {
+      wrapper: wrapperFor('/?tab=details'),
+    });
+    act(() => result.current.openOverlay());
+    expect(result.current.search).toContain('tab=details');
+    expect(result.current.search).toContain('palette=1');
+    act(() => result.current.closeOverlay());
+    expect(result.current.search).toBe('?tab=details');
+  });
+
+  it('reads an alias param as open and normalizes it on write', () => {
+    const { result } = renderHook(() => useHarness('palette', { alias: 'cmdk' }), {
+      wrapper: wrapperFor('/?cmdk=1'),
+    });
+    // alias counts as open
+    expect(result.current.open).toBe(true);
+    // closing clears both the canonical key and the alias
+    act(() => result.current.closeOverlay());
+    expect(result.current.open).toBe(false);
+    expect(result.current.search).toBe('');
+  });
+
+  it('writes the canonical key (not the alias) when opening', () => {
+    const { result } = renderHook(() => useHarness('palette', { alias: 'cmdk' }), {
+      wrapper: wrapperFor('/'),
+    });
+    act(() => result.current.openOverlay());
+    expect(result.current.search).toBe('?palette=1');
+  });
+});

packages/app-shell/src/hooks/index.ts

@@ -16,6 +16,11 @@ export { useObjectActions } from './useObjectActions';
 export { useRecentItems, type RecentItem } from './useRecentItems';
 export { useRecordApprovals, type ApprovalRequestLite } from './useRecordApprovals';
 export { useResponsiveSidebar } from './useResponsiveSidebar';
+export {
+  useUrlOverlay,
+  type UseUrlOverlayOptions,
+  type UrlOverlayControls,
+} from './useUrlOverlay';
 export { useTrackRouteAsRecent, type UseTrackRouteAsRecentOptions } from './useTrackRouteAsRecent';
 export {
   sanitizeChatMessagesForCache,