@rapidmx/web-client 0.16.0 → 0.17.2

package/README.md

@@ -21,39 +21,47 @@ import SettingsShell from "@rapidmx/web-client/shared/components/settings/layout
 
 ## Navigation without page loads
 
-`@rapidrest/react` has no router: every page is a server-rendered document that hydrates only its own page component. The
-`www` pages (Mail, Calendar, Contacts, Tasks, Settings and their subpages) therefore render a small client-side router
-themselves, and go between one another - and between the folders of Mail - without a page load:
-
-- each `apps/www` page's default export is `routedPage("/its/route", Page)` (`apps/www/_routedPage.tsx`). The server
-  renders and the browser hydrates exactly what it did before; the first load is unchanged. `apps/www/_routes.ts` lists the
-  pages, each with a dynamic `import()` so it is a chunk of its own (a test keeps it in step with the files);
-- one `AppShell` chrome (the app rail, header, user menu, impersonation banner, compose windows in progress, the unlock
-  prompt and the idle-key timer) stays mounted, and only the page inside it is replaced. A page's own shell
-  (`MailShell`, `CalendarShell`, ...) still renders `AppShell`; inside the router that is only its children;
-- **links stay ordinary links.** Every same-origin `<a href>` to a route in the table is taken over - plain left clicks
-  only, so ctrl/cmd/shift/middle click, `target`, `download`, `#hash` links and links marked `data-full-reload` keep
-  the browser's behaviour, and pages that are not in the table (the admin and escrow consoles, plugin pages, other sites) are
-  reached with a page load. The address bar always holds the real, shareable URL (`/?mailboxUid=&folderUid=`), and back and
-  forward work;
-- a page's code is fetched when the pointer, focus or a press reaches a link to it, and for the app rail's pages when the
-  browser is idle after load (not with data saving on); if it can't be loaded the router falls back to a page load;
-- after a page change focus moves to the content region (`#app-content`), the window scrolls to the top, `document.title`
-  follows the page and a polite live region announces it.
-
-Code that decides where to go uses the two hooks in `shared/navigation/AppRouter.js`:
+All three apps use `@rapidrest/react`'s client-side router (`router = true` on the server's route, the client built with
+`createViteConfig({ router })`; `@rapidrest/react` is a **peer dependency** here, `>=2.1.0 <3`, because the router's state lives
+in a React context that this package must share with the server's one copy). The server still renders every URL, so first
+loads, reloads and crawlers are unchanged; after the first load a click on an ordinary `<a href>` between two pages of an app
+fetches the next page's props as JSON and swaps the page in. Back and forward work, the address bar always holds the real,
+shareable URL, and anything the router cannot be sure of (a modified click, `target`, `download`, `data-router-ignore`, another
+app's page - the consoles, plugin pages, other sites - or a failure) is left to the browser as a page load.
+
+The admin and escrow pages each render their own shell, so the router just swaps the page. The webmail (`apps/www`) has an **app
+shell**, `apps/www/_shell.tsx` (the router's persistent client layout), which the server renders around every page and the
+browser hydrates with it as one root:
+
+- the one `AppChrome` (the app rail, header, user menu, impersonation banner, compose windows in progress, the unlock prompt,
+  the idle-key timer, the mail connection and the notification pop-ups) stays mounted while only the page inside it is replaced.
+  A page's own shell (`MailShell`, `CalendarShell`, ...) still renders `AppShell`; inside the frame that is only its children;
+- the shell gets the current page's props - `WwwRoute.fetchProps()`'s, the same for every page - so the rail's highlighted app
+  (from the route), the branding, the plugin navigation and the impersonation banner follow the server on every navigation. That is
+  one request to `fetchProps()` per page change (warm for most, since the router prefetches a plain link on hover and the four rail
+  pages' code when the browser is idle);
+- **a folder is a shallow navigation.** `<a data-router-shallow>` (the Mail folder links), `navigate()` to the same path with another
+  query (`useNavigate()`, below) and `useSearchParams()`' setter keep the page instance and its state and only change the location;
+- after a page change the router moves focus to the content region (`#app-content`), scrolls to the top and announces the page's
+  title in a polite live region (all set by the shell with `useNavigationEffects()`); the tab's title is each page's `title`
+  export (`pageTitle("Calendar")`: `Acme Mail: Calendar`), rendered by the server and sent with every navigation, with the unread
+  count kept in front of it; the content region is `aria-busy` while the next page loads.
+
+Code that decides where to go uses `useNavigate()` from `shared/navigation/index.js` and reads the location with the library's
+hooks:
 
 ```tsx
-import { useLocation, useNavigate } from "@rapidmx/web-client/shared/navigation/AppRouter.js";
+import { useLocation, useSearchParams } from "@rapidrest/react/client";
+import { useNavigate } from "@rapidmx/web-client/shared/navigation/index.js";
 
-const navigate = useNavigate(); // navigate("/contacts"), navigate("/?mailboxUid=a&folderUid=b", { replace: true })
-const { pathname, search, hash } = useLocation(); // empty until read after the first render, so server and browser agree
+const navigate = useNavigate(); // navigate("/contacts"); navigate("/?mailboxUid=a&folderUid=b") keeps the page (same path)
+const { pathname, search, hash } = useLocation(); // the request's on the server and while hydrating; `hash` is empty there
+const [params, setParams] = useSearchParams(); // setParams({ folderUid: "x" }) is shallow by default
 ```
 
-`navigate()` changes the page without a load when the URL is a route of the app and is an ordinary navigation otherwise
-(outside the router too, where it is `window.location.href = ...`). Page props are the same for every `www` page except
-`params`, which the router recomputes from the URL. Plugin pages are not part of the router (they render their own
-`AppShell` chrome) and are opened with a page load.
+`navigate()` changes the page without a load when the URL is a page of the app, and is an ordinary navigation otherwise (outside a
+router too). An admin or escrow page that leads to another page of its console after a save goes there with `useRouter().navigate`.
+Plugin pages are not part of the router (they render their own `AppShell` chrome) and are opened with a page load.
 
 The compose window, the reading pane, S/MIME and the emoji list are also chunks of their own, loaded on demand or fetched
 when the browser is idle, so a page's first JavaScript is React and what the first screen draws.

package/apps/admin/distribution-lists/new/index.tsx

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React, { FormEvent, useState } from "react";
+import { useRouter } from "@rapidrest/react/client";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { createDistributionList } from "@rapidmx/react-shared/admin/distributionListsApi.js";
 import AdminShell, { AdminShellProps } from "../../../shared/components/admin/layout/AdminShell.js";
@@ -22,6 +23,7 @@ export default function NewDistributionListPage(props: Omit<AdminShellProps, "ac
 }
 
 function NewDistributionListForm() {
+    const { navigate } = useRouter();
     const [primarySmtpAddress, setPrimarySmtpAddress] = useState("");
     const [name, setName] = useState("");
     const [description, setDescription] = useState("");
@@ -48,7 +50,7 @@ function NewDistributionListForm() {
                 name: name.trim(),
                 description: description.trim() || undefined,
             });
-            window.location.href = `/admin/distribution-lists/${encodeURIComponent(list.uid)}`;
+            void navigate(`/admin/distribution-lists/${encodeURIComponent(list.uid)}`);
         } catch (err) {
             setError(err instanceof ApiRequestError ? err.message : "Could not create the distribution list.");
         } finally {

package/apps/admin/domains/[uid].tsx

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React, { useState } from "react";
+import { useRouter } from "@rapidrest/react/client";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { deleteDomain, Domain, updateDomain } from "@rapidmx/react-shared/admin/domainsApi.js";
 import AdminShell, { AdminShellProps } from "../../shared/components/admin/layout/AdminShell.js";
@@ -24,6 +25,7 @@ export default function DomainDetailPage(props: Omit<AdminShellProps, "active">
 }
 
 function DomainDetailContent({ uid }: { uid: string }) {
+    const { navigate } = useRouter();
     const [domain, setDomain] = useState<Domain | null>(null);
     const [confirmingDelete, setConfirmingDelete] = useState(false);
     const [deleting, setDeleting] = useState(false);
@@ -48,7 +50,7 @@ function DomainDetailContent({ uid }: { uid: string }) {
         setDeleteError(null);
         try {
             await deleteDomain(domain!.uid, domain!.version);
-            window.location.href = "/admin/domains";
+            void navigate("/admin/domains");
         } catch (err) {
             setDeleteError(err instanceof ApiRequestError ? err.message : "Could not delete this domain.");
             setDeleting(false);

package/apps/admin/domains/new/index.tsx

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React, { FormEvent, useEffect, useState } from "react";
+import { useRouter } from "@rapidrest/react/client";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { createDomain, Domain, listDomains } from "@rapidmx/react-shared/admin/domainsApi.js";
 import AdminShell, { AdminShellProps } from "../../../shared/components/admin/layout/AdminShell.js";
@@ -22,6 +23,7 @@ export default function NewDomainPage(props: Omit<AdminShellProps, "active">) {
 }
 
 function NewDomainForm() {
+    const { navigate } = useRouter();
     const [name, setName] = useState("");
     const [aliasOf, setAliasOf] = useState("");
     // Only an existing, non-alias domain can be aliased (no chains) - see `Domain.aliasOf`'s own doc comment
@@ -48,7 +50,7 @@ function NewDomainForm() {
         setSaving(true);
         try {
             const domain = await createDomain({ name: name.trim(), aliasOf: aliasOf || undefined });
-            window.location.href = `/admin/domains/${encodeURIComponent(domain.uid)}`;
+            void navigate(`/admin/domains/${encodeURIComponent(domain.uid)}`);
         } catch (err) {
             setError(err instanceof ApiRequestError ? err.message : "Could not create the domain.");
         } finally {

package/apps/admin/escrow-scopes/[uid].tsx

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React, { FormEvent, useEffect, useState } from "react";
+import { useRouter } from "@rapidrest/react/client";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { toDatetimeLocal } from "@rapidmx/react-shared/util/dateInput.js";
 import {
@@ -118,6 +119,7 @@ export default function EscrowScopeDetailPage(props: Omit<AdminShellProps, "acti
 }
 
 function EscrowScopeDetailContent({ uid, adminUid }: { uid: string; adminUid?: string }) {
+    const { navigate } = useRouter();
     const [original, setOriginal] = useState<EscrowScope | null>(null);
     const [name, setName] = useState("");
     const [description, setDescription] = useState("");
@@ -225,7 +227,7 @@ function EscrowScopeDetailContent({ uid, adminUid }: { uid: string; adminUid?: s
         setDeleteError(null);
         try {
             await deleteEscrowScope(original!.uid, original!.version);
-            window.location.href = "/admin/escrow-scopes";
+            void navigate("/admin/escrow-scopes");
         } catch (err) {
             // Most commonly a 409 ("referenced by an existing Matter") — see `deleteEscrowScope()`'s own
             // doc comment - surfaced as-is rather than special-cased.

package/apps/admin/escrow-scopes/new/index.tsx

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React, { FormEvent, useState } from "react";
+import { useRouter } from "@rapidrest/react/client";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { createEscrowScope } from "@rapidmx/react-shared/admin/escrowScopesApi.js";
 import AdminShell, { AdminShellProps } from "../../../shared/components/admin/layout/AdminShell.js";
@@ -26,6 +27,7 @@ export default function NewEscrowScopePage(props: Omit<AdminShellProps, "active"
 }
 
 function NewEscrowScopeForm({ adminUid }: { adminUid?: string }) {
+    const { navigate } = useRouter();
     const [name, setName] = useState("");
     const [description, setDescription] = useState("");
     const [keyAndHolders, setKeyAndHolders] = useState(emptyEscrowScopeKeyAndHoldersValue());
@@ -74,7 +76,7 @@ function NewEscrowScopeForm({ adminUid }: { adminUid?: string }) {
                 requiredHolders: keyAndHolders.requiredHolders,
                 notifySubjectOnAccess: keyAndHolders.notifySubjectOnAccess,
             });
-            window.location.href = `/admin/escrow-scopes/${encodeURIComponent(created.uid)}`;
+            void navigate(`/admin/escrow-scopes/${encodeURIComponent(created.uid)}`);
         } catch (err) {
             setError(err instanceof ApiRequestError ? err.message : "Could not create the escrow scope.");
         } finally {

package/apps/admin/index.tsx

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React, { useEffect, useState } from "react";
+import { useRouter } from "@rapidrest/react/client";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { listMailboxes, Mailbox } from "@rapidmx/react-shared/mail/mailApi.js";
 import { reopenSetup } from "@rapidmx/react-shared/admin/setupApi.js";
@@ -24,6 +25,7 @@ export default function MailboxesListPage(props: Omit<AdminShellProps, "active">
 }
 
 function MailboxesListContent() {
+    const { navigate } = useRouter();
     const [page, setPage] = useState(0);
     const [mailboxes, setMailboxes] = useState<Mailbox[]>([]);
     const [loading, setLoading] = useState(true);
@@ -47,7 +49,7 @@ function MailboxesListContent() {
         setReopening(true);
         try {
             await reopenSetup();
-            window.location.href = "/admin/setup";
+            void navigate("/admin/setup");
         } catch (err) {
             setError(err instanceof ApiRequestError ? err.message : "Could not reopen setup.");
             setReopening(false);

package/apps/admin/mailboxes/[uid].tsx

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React, { useEffect, useState } from "react";
+import { useRouter } from "@rapidrest/react/client";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { deleteMailbox, getMailbox, impersonateUser, Mailbox } from "@rapidmx/react-shared/mail/mailApi.js";
 import AdminShell, { AdminShellProps } from "../../shared/components/admin/layout/AdminShell.js";
@@ -34,6 +35,7 @@ function MailboxDetailContent({
     currentUserUid,
 }: { uid: string; currentUserUid?: string } & Pick<AdminShellProps, "impersonationBaseUrl">) {
     const [mailbox, setMailbox] = useState<Mailbox | null>(null);
+    const { navigate } = useRouter();
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState<string | null>(null);
     const [confirmingAccess, setConfirmingAccess] = useState(false);
@@ -84,7 +86,7 @@ function MailboxDetailContent({
         try {
             await deleteMailbox(mailbox!.uid, mailbox!.version, { erase: eraseData });
             // The Mailboxes page it goes to lists what a delete without `erase` kept, and how far an erasure has got.
-            window.location.href = "/admin";
+            void navigate("/admin");
         } catch (err) {
             // Most commonly a 409 if this mailbox is a custodian on an open legal hold (restapi's own
             // `assertNotOnLegalHold()`, naming the blocking Matter uid(s)) - surfaced as-is, same as

package/apps/admin/mailboxes/new/index.tsx

@@ -3,10 +3,12 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React from "react";
+import { useRouter } from "@rapidrest/react/client";
 import AdminShell, { AdminShellProps } from "../../../shared/components/admin/layout/AdminShell.js";
 import MailboxCreateForm from "../../../shared/components/admin/settings/MailboxCreateForm.js";
 
 export default function NewMailboxPage(props: Omit<AdminShellProps, "active">) {
+    const { navigate } = useRouter();
     return (
         <AdminShell {...props} active="mailboxes">
             <div className="max-w-xl">
@@ -19,7 +21,7 @@ export default function NewMailboxPage(props: Omit<AdminShellProps, "active">) {
                 <MailboxCreateForm
                     cancelHref="/admin"
                     onCreated={(mailbox) => {
-                        window.location.href = `/admin/mailboxes/${encodeURIComponent(mailbox.uid)}`;
+                        void navigate(`/admin/mailboxes/${encodeURIComponent(mailbox.uid)}`);
                     }}
                 />
             </div>

package/apps/admin/transport-rules/new/index.tsx

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React, { FormEvent, useState } from "react";
+import { useRouter } from "@rapidrest/react/client";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import {
     createTransportRule,
@@ -34,6 +35,7 @@ export default function NewTransportRulePage(props: Omit<AdminShellProps, "activ
 }
 
 function NewTransportRuleForm() {
+    const { navigate } = useRouter();
     const [name, setName] = useState("");
     const [rule, setRule] = useState<RuleBuilderValue<TransportRuleConditions, TransportRuleAction>>({
         enabled: true,
@@ -73,7 +75,7 @@ function NewTransportRuleForm() {
         setSaving(true);
         try {
             const created = await createTransportRule({ name: name.trim(), ...rule });
-            window.location.href = `/admin/transport-rules/${encodeURIComponent(created.uid)}`;
+            void navigate(`/admin/transport-rules/${encodeURIComponent(created.uid)}`);
         } catch (err) {
             setError(err instanceof ApiRequestError ? err.message : "Could not create the transport rule.");
         } finally {

package/apps/escrow/matters/new/index.tsx

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React, { FormEvent, useState } from "react";
+import { useRouter } from "@rapidrest/react/client";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { toDatetimeLocal } from "@rapidmx/react-shared/util/dateInput.js";
 import { createMatter } from "@rapidmx/react-shared/admin/mattersApi.js";
@@ -24,6 +25,7 @@ export default function NewMatterPage(props: Omit<EscrowShellProps, "active">) {
 }
 
 function NewMatterForm() {
+    const { navigate } = useRouter();
     const [name, setName] = useState("");
     const [description, setDescription] = useState("");
     // No dropdown here: `EscrowScope` (BaseEscrowScopeRoute) is trusted-admin-only end to end, so this
@@ -72,7 +74,7 @@ function NewMatterForm() {
                 dateRangeStart: new Date(dateRangeStart).toISOString(),
                 dateRangeEnd: new Date(dateRangeEnd).toISOString(),
             });
-            window.location.href = `/escrow/matters/${encodeURIComponent(created.uid)}`;
+            void navigate(`/escrow/matters/${encodeURIComponent(created.uid)}`);
         } catch (err) {
             setError(err instanceof ApiRequestError ? err.message : "Could not create the matter.");
         } finally {

package/apps/shared/components/admin/layout/AdminShell.tsx

@@ -4,6 +4,7 @@
 ///////////////////////////////////////////////////////////////////////////////
 import "../../../styles/app.css";
 import React, { PropsWithChildren, ReactNode, useEffect, useState } from "react";
+import { useRouter } from "@rapidrest/react/client";
 import {
     HiOutlineClipboardDocumentList,
     HiOutlineClock,
@@ -184,6 +185,7 @@ export function adminNavItems(pluginNav?: PluginNav): NavItem[] {
  * 403 `api-103` (elevated, but not an administrator), any other 403, and 401 mean "no administrator access".
  */
 export default function AdminShell({ active, userUid, authServerUrl, pluginNav, children }: PropsWithChildren<AdminShellProps>) {
+    const { navigate } = useRouter();
     const [status, setStatus] = useState<Status>("checking");
     const [error, setError] = useState<string | null>(null);
     const [menuOpen, setMenuOpen] = useState(false);
@@ -207,7 +209,8 @@ export default function AdminShell({ active, userUid, authServerUrl, pluginNav,
                 if (active !== "setup") {
                     try {
                         if ((await getSetupStatus()).required) {
-                            window.location.href = SETUP_ITEM.href;
+                            // Replacing this page in the history, which would otherwise send the back button round again.
+                            void navigate(SETUP_ITEM.href, { replace: true });
                             return;
                         }
                     } catch {

package/apps/shared/components/admin/setup/SetupWizard.tsx

@@ -3,6 +3,7 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import React, { FormEvent, useEffect, useRef, useState } from "react";
+import { useRouter } from "@rapidrest/react/client";
 import { HiCheck } from "react-icons/hi2";
 import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
 import { getRetentionPolicy } from "@rapidmx/react-shared/admin/retentionPolicyApi.js";
@@ -61,6 +62,7 @@ export interface SetupWizardProps {
  * except the domain can be passed over and configured later from the admin console.
  */
 export default function SetupWizard({ userUid }: SetupWizardProps) {
+    const { navigate } = useRouter();
     const [step, setStep] = useState<SetupStepId | null>(null);
     const [status, setStatus] = useState<SetupStatus | undefined>();
     const [domains, setDomains] = useState<Domain[]>([]);
@@ -162,7 +164,7 @@ export default function SetupWizard({ userUid }: SetupWizardProps) {
             // Let a step still being recorded land first, so it can't arrive after setup is marked finished.
             await progress.current.running;
             await completeSetup();
-            window.location.href = "/admin";
+            void navigate("/admin");
         } catch (err) {
             setError(errorMessage(err, "Could not finish setup."));
             setFinishing(false);

package/apps/shared/components/calendar/layout/CalendarShell.tsx

@@ -9,7 +9,7 @@ import { Folder, Mailbox, listFolders, listMailboxes } from "@rapidmx/react-shar
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Skeleton, { SkeletonList } from "@rapidmx/react-shared/components/feedback/Skeleton.js";
 import AppShell, { AppShellProps } from "../../layout/AppShell.js";
-import { useLocationSearch } from "../../../navigation/AppRouter.js";
+import { useLocation } from "../../../navigation/index.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 import { orderMailboxes, primaryMailboxUid } from "../../../mail/primaryMailbox.js";
 
@@ -84,7 +84,7 @@ export default function CalendarShell({
 
     // Read from the router's location, so a mailbox change (a link, or `navigate()`) takes effect without a page load - and in an
     // effect, not during render, so the server render and the hydrating render agree.
-    const search = useLocationSearch();
+    const { search } = useLocation();
     useEffect(() => {
         setRequestedMailboxUid(new URLSearchParams(search).get("mailboxUid"));
     }, [search]);

package/apps/shared/components/contacts/layout/ContactsShell.tsx

@@ -10,7 +10,7 @@ import { Folder, Mailbox, listFolders, listMailboxes } from "@rapidmx/react-shar
 import Alert from "@rapidmx/react-shared/components/feedback/Alert.js";
 import Skeleton, { SkeletonList } from "@rapidmx/react-shared/components/feedback/Skeleton.js";
 import AppShell, { AppShellProps } from "../../layout/AppShell.js";
-import { useLocationSearch, useNavigate } from "../../../navigation/AppRouter.js";
+import { useLocation, useNavigate } from "../../../navigation/index.js";
 import MailboxProvisioning from "../../layout/MailboxProvisioning.js";
 import { orderMailboxes, primaryMailboxUid } from "../../../mail/primaryMailbox.js";
 
@@ -60,7 +60,7 @@ export default function ContactsShell({
 
     // Read from the router's location, so a mailbox change (a link, or `navigate()`) takes effect without a page load - and in an
     // effect, not during render, so the server render and the hydrating render agree.
-    const search = useLocationSearch();
+    const { search } = useLocation();
     const navigate = useNavigate();
     useEffect(() => {
         setRequestedMailboxUid(new URLSearchParams(search).get("mailboxUid"));

package/apps/shared/components/layout/AppShell.tsx

@@ -3,7 +3,7 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import "../../styles/app.css";
-import React, { PropsWithChildren, useEffect, useRef, useState } from "react";
+import React, { PropsWithChildren, useEffect, useLayoutEffect, useRef, useState } from "react";
 import type { IconType } from "react-icons";
 import {
     HiOutlineCalendarDays,
@@ -12,6 +12,7 @@ import {
     HiOutlinePuzzlePiece,
     HiOutlineUsers,
 } from "react-icons/hi2";
+import { useRouter } from "@rapidrest/react/client";
 import { useRedirectIfUnauthenticated } from "@rapidmx/react-shared/auth/session.js";
 import { getSetupStatus } from "@rapidmx/react-shared/admin/setupApi.js";
 import { stopImpersonating } from "@rapidmx/react-shared/mail/mailApi.js";
@@ -34,7 +35,7 @@ import { clearPinnedSignerCache } from "../mail/pinnedSigners.js";
 import { mergePluginNavItems, PluginNav, PluginNavProps } from "../../plugins/pluginNav.js";
 import { useInAppFrame } from "../../navigation/frameContext.js";
 import { APP_HREFS } from "../../navigation/appHrefs.js";
-import { useNavigate } from "../../navigation/routerContext.js";
+import { useNavigate } from "../../navigation/index.js";
 import { GlobalShortcuts } from "../../keyboard/GlobalShortcuts.js";
 import { ShortcutProvider } from "../../keyboard/ShortcutProvider.js";
 import ShortcutsDialog from "../../keyboard/ShortcutsDialog.js";
@@ -138,12 +139,9 @@ export function appRailItems(pluginNav?: PluginNav): NavItem[] {
     );
 }
 
-/** What only the persistent frame (`AppRouter`) passes to the chrome it keeps mounted. */
+/** What only the persistent frame (`apps/www/_shell.tsx`) passes to the chrome it keeps mounted. */
 export interface AppChromeProps extends AppShellProps {
-    /** Changes whenever the router shows a different page: the chrome then moves focus to the content, scrolls to its top,
-     * sets the document title and announces the page. Absent outside the router, when nothing does. */
-    routeKey?: string;
-    /** The router is loading the next page's code - the content is `aria-busy`. */
+    /** The router is loading the next page - the content is `aria-busy`. */
     busy?: boolean;
     /** A screen that takes over the window (`FrameTakeover`) is showing: the rail, header, banner and footer are hidden - not
      * unmounted, so what is inside them (and the page in the content region) keeps its state. */
@@ -156,8 +154,8 @@ export interface AppChromeProps extends AppShellProps {
  * Each app's own shell (e.g. `MailShell`) renders its own contextual sidebar + content as `children`, inside
  * the area to the right of the icon rail and below the header.
  *
- * Rendered by `AppRouter`, once, for the life of the page, so that moving between apps replaces only `children` - see
- * `AppShell` below for what a page's own shell renders instead.
+ * Rendered by the webmail's app shell (`apps/www/_shell.tsx`, the router's persistent client layout), once, for the life of the
+ * page, so that moving between apps replaces only `children` - see `AppShell` below for what a page's own shell renders instead.
  */
 export function AppChrome({
     active,
@@ -170,7 +168,6 @@ export function AppChrome({
     branding: initialBranding,
     appearance,
     pluginNav,
-    routeKey,
     busy,
     hideChrome,
     children,
@@ -198,6 +195,7 @@ export function AppChrome({
     // the router (`AppShell` rendered as a page's own chrome: tests, plugin pages) it stays off, and a Mail shell owns its connection itself.
     const inFrame = useInAppFrame();
     const navigate = useNavigate();
+    const { pathname } = useRouter();
     const mail = useMailConnection({ userUid, enabled: inFrame, open: navigate });
     // A signing certificate the user asked for is announced when it is issued (or fails), on whichever page they are - see the hook.
     useSigningEnrollmentWatcher({ userUid, mailboxes: mail.mailboxes, enabled: inFrame });
@@ -301,32 +299,21 @@ export function AppChrome({
         }
     }
 
-    // What the persistent frame (`AppRouter`) needs on top of a page that never changes: the document title follows the page, and
-    // after the router replaces the page the keyboard focus, the scroll position and a screen reader are told about it - a
-    // page load did all of that by itself. Nothing here runs for a page shown outside the router (`routeKey` is undefined).
-    const contentRef = useRef<HTMLDivElement>(null);
-    const [announcement, setAnnouncement] = useState("");
-    const firstRouteKeyRef = useRef(routeKey);
-    const pageLabel = active === "settings" ? "Settings" : appRailItems(pluginNav).find((app) => app.id === active)?.label;
+    // The tab's title in the frame is each page's own (its `title` export: rendered by the server, set again by the router on every navigation),
+    // but `useBranding()` above sets it to the branding's title once its fetch answers - a title for a page that has none. The page's is put back:
+    // the layout effect reads it before that hook's effect runs, this one (declared after it) writes it back.
+    const pageTitleRef = useRef("");
+    useLayoutEffect(() => {
+        pageTitleRef.current = document.title;
+    }, [fetchedBranding?.title]);
     useEffect(() => {
-        if (routeKey !== undefined) {
-            const brand = branding?.title || branding?.companyName || "RapidMX";
-            document.title = pageLabel ? `${brand}: ${pageLabel}` : brand;
+        if (inFrame) {
+            document.title = pageTitleRef.current;
         }
-    }, [routeKey, pageLabel, branding]);
-    // After the title effect above, so a page change (which rewrites the title) is followed by the unread count going back in front of it.
-    useUnreadTitle(inboxUnreadTotal(mail.mailboxFolders, mail.folderCounts.counts), {
-        enabled: inFrame,
-        resetKey: `${routeKey}|${pageLabel}|${branding?.title}|${branding?.companyName}`,
-    });
-    useEffect(() => {
-        if (routeKey === undefined || routeKey === firstRouteKeyRef.current) {
-            return;
-        }
-        setAnnouncement(pageLabel ?? "");
-        contentRef.current?.focus({ preventScroll: true });
-        window.scrollTo(0, 0);
-    }, [routeKey]);
+    }, [fetchedBranding?.title, inFrame]);
+    // The router sets the document's title to the page's own whenever the page changes, which drops the unread count this puts in front
+    // of it, so a new pathname is what puts the count back. (A folder change is shallow and keeps the title.)
+    useUnreadTitle(inboxUnreadTotal(mail.mailboxFolders, mail.folderCounts.counts), { enabled: inFrame, resetKey: pathname });
 
     if (!userUid) {
         return <div className="min-h-screen" />;
@@ -442,7 +429,6 @@ export function AppChrome({
                         {/* The one pop-up stack for the whole app: right under the header row, so it never covers the account menu. */}
                         <NotificationCenter />
                         <div
-                            ref={contentRef}
                             id="app-content"
                             tabIndex={-1}
                             aria-busy={busy || undefined}
@@ -452,11 +438,6 @@ export function AppChrome({
                         </div>
                     </div>
                 </div>
-                {routeKey !== undefined && (
-                    <div role="status" aria-live="polite" className="sr-only">
-                        {announcement}
-                    </div>
-                )}
                 {!hideChrome && <FrameBrandingFooter parsed={footer} userMenu={menuInFooter ? renderUserMenu("up") : undefined} appTitle={activeLabel} />}
             </div>
             </ComposeProvider>
@@ -470,9 +451,9 @@ export function AppChrome({
 
 /**
  * What a page's own shell (`MailShell`, `CalendarShell`, ...) renders around its content. Outside the client-side router it
- * is the whole `AppChrome`, as it always was. Inside it (`AppRouter`) the chrome is already mounted above the page - and stays
- * mounted as the page is replaced - so this is only its children; everything it would have been given comes from the router
- * frame instead (the props are the same for every page, and `active` is the route's).
+ * is the whole `AppChrome`, as it always was. Inside it (the router's app shell, `apps/www/_shell.tsx`) the chrome is already mounted above the
+ * page - and stays mounted as the page is replaced - so this is only its children; everything it would have been given comes from
+ * the shell instead (the props are the same for every page, and `active` is the route's).
  */
 export default function AppShell(props: PropsWithChildren<AppShellProps>) {
     const inFrame = useInAppFrame();

package/apps/shared/components/mail/ConversationThreadPane.tsx

@@ -577,6 +577,7 @@ export default function ConversationThreadPane({
                                     onReceiptHandled={patchMessage}
                                     onScheduledSendCanceled={removeMessage}
                                     onArchived={removeMessage}
+                                    onChanged={patchMessage}
                                     labels={labels}
                                     onLabelsChanged={patchMessage}
                                     onLabelCreated={onLabelCreated}