feat(core): sync document.title with the active route

AppShell now keeps the browser tab title in sync with the current page,
removing per-app boilerplate that every consumer would otherwise need.

The tab reads "<page> · <title>", where <page> is the current breadcrumb
leaf — including any useOverrideBreadcrumb override, so detail pages get
their record name in the tab for free — and <title> is the AppShell
`title` prop. A single internal DocumentTitle component mounted in the
root route drives this for every page; no per-page wiring. When no
`title` is set the tab shows just the page name, and when nothing
resolves the static index.html title is left untouched.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: erickteowarang

.changeset/document-title-sync.md

@@ -0,0 +1,5 @@
+---
+"@tailor-platform/app-shell": minor
+---
+
+Sync the browser tab title (`document.title`) with the active route. AppShell now sets the tab to `"<page> · <title>"`, where `<page>` is the current breadcrumb leaf (including any `useOverrideBreadcrumb` override, so detail pages show their record name automatically) and `<title>` is the `title` prop passed to `<AppShell>`. Works for every page with no per-page wiring; when no `title` is set the tab shows just the page name, and when nothing resolves the static `index.html` title is left untouched.

packages/core/src/components/appshell.tsx

@@ -33,7 +33,13 @@ import type { PageEntry } from "@/fs-routes/types";
  */
 type SharedAppShellProps = React.PropsWithChildren<{
   /**
-   * App shell title
+   * App shell title.
+   *
+   * Also used as the suffix of the browser tab title: AppShell keeps
+   * `document.title` in sync with the active page as `"<page> · <title>"`
+   * (the page part is the current breadcrumb leaf, including any
+   * {@link useOverrideBreadcrumb} override). When omitted, the tab shows just
+   * the page title.
    */
   title?: string;
 

packages/core/src/components/document-title.test.tsx

@@ -0,0 +1,63 @@
+import { render, waitFor } from "@testing-library/react";
+import { describe, it, expect, beforeEach } from "vitest";
+import { MemoryRouter } from "react-router";
+import {
+  AppShellConfigContext,
+  type RootConfiguration,
+} from "@/contexts/appshell-context";
+import { BreadcrumbOverrideProvider } from "@/contexts/breadcrumb-context";
+import { useOverrideBreadcrumb } from "@/hooks/use-override-breadcrumb";
+import { DEFAULT_LOCALE } from "@/lib/i18n";
+import { DocumentTitle } from "./document-title";
+
+const configurations: RootConfiguration = {
+  modules: [],
+  settingsResources: [],
+  locale: DEFAULT_LOCALE,
+  errorBoundary: null!,
+};
+
+// Registers an override for the current route the same way a detail page would.
+const Override = ({ title }: { title: string }) => {
+  useOverrideBreadcrumb(title);
+  return null;
+};
+
+const renderAt = (path: string, title: string | undefined, override?: string) =>
+  render(
+    <MemoryRouter initialEntries={[path]}>
+      <AppShellConfigContext.Provider value={{ title, configurations }}>
+        <BreadcrumbOverrideProvider>
+          {override ? <Override title={override} /> : null}
+          <DocumentTitle />
+        </BreadcrumbOverrideProvider>
+      </AppShellConfigContext.Provider>
+    </MemoryRouter>,
+  );
+
+describe("DocumentTitle", () => {
+  beforeEach(() => {
+    document.title = "initial";
+  });
+
+  it("sets '<page> · <app>' from the leaf segment and app title", async () => {
+    renderAt("/orders/123", "My App");
+    // No module mapping, so the leaf title falls back to the decoded segment.
+    await waitFor(() => expect(document.title).toBe("123 · My App"));
+  });
+
+  it("uses just the page title when no app title is provided", async () => {
+    renderAt("/orders/123", undefined);
+    await waitFor(() => expect(document.title).toBe("123"));
+  });
+
+  it("applies a breadcrumb override to the tab title", async () => {
+    renderAt("/orders/123", "My App", "Order #123");
+    await waitFor(() => expect(document.title).toBe("Order #123 · My App"));
+  });
+
+  it("leaves the static title untouched when nothing resolves", async () => {
+    renderAt("/", undefined);
+    await waitFor(() => expect(document.title).toBe("initial"));
+  });
+});

packages/core/src/components/document-title.tsx

@@ -0,0 +1,44 @@
+import { useEffect } from "react";
+import { useAppShellConfig } from "@/contexts/appshell-context";
+import { useBreadcrumbOverride } from "@/contexts/breadcrumb-context";
+import { usePathSegments } from "@/components/dynamic-breadcrumb";
+
+const SEPARATOR = " · ";
+
+/**
+ * Keeps `document.title` in sync with the active route.
+ *
+ * The browser tab reads `"<page> · <app>"`, where:
+ * - `<page>` is the last breadcrumb segment for the current path, with any
+ *   {@link useOverrideBreadcrumb} override applied — so a detail page that sets
+ *   a record name (e.g. an order number) gets it in the tab for free, with no
+ *   extra wiring.
+ * - `<app>` is the `title` prop passed to `<AppShell>`.
+ *
+ * Rendered once inside the router (see `createRootRoute`) so it tracks every
+ * navigation; consumers never wire titles per page. When neither a page title
+ * nor an app title resolves, the static `<title>` from `index.html` is left
+ * untouched.
+ *
+ * @internal
+ */
+export const DocumentTitle = () => {
+  const { title: appTitle } = useAppShellConfig();
+  const { basePath, segments } = usePathSegments();
+  const { overrides } = useBreadcrumbOverride();
+
+  const leaf = segments.at(-1);
+  let pageTitle: string | undefined;
+  if (leaf) {
+    const leafFullPath = basePath ? `/${basePath}/${leaf.path}` : `/${leaf.path}`;
+    pageTitle = overrides.get(leafFullPath) ?? leaf.title;
+  }
+
+  const nextTitle = [pageTitle, appTitle].filter(Boolean).join(SEPARATOR);
+
+  useEffect(() => {
+    if (nextTitle) document.title = nextTitle;
+  }, [nextTitle]);
+
+  return null;
+};

packages/core/src/routing/router.tsx

@@ -4,6 +4,7 @@ import type { RouteObject } from "react-router";
 import { createContentRoutes, wrapErrorBoundary } from "./routes";
 import { useAppShellConfig, type RootConfiguration } from "@/contexts/appshell-context";
 import { createNavItemsLoader } from "@/routing/navigation";
+import { DocumentTitle } from "@/components/document-title";
 
 // ============================================================================
 // Root Route
@@ -41,7 +42,12 @@ const createRootRoute = (params: {
   return {
     id: loaderID,
     loader,
-    element: children,
+    element: (
+      <>
+        <DocumentTitle />
+        {children}
+      </>
+    ),
     children: routeChildren,
     // Hydration fallback is unused in CSR-only usage of AppShell.
     // Return null to silence hydration warnings.