@djangocfg/layouts 2.1.607 → 2.1.608

package/src/components/account/useAccountModel.tsx

@@ -0,0 +1,76 @@
+/**
+ * What the account menu shows, shared by every place it can live (sidebar footer, top bar avatar): the user, the
+ * display fields and the menu items. One source, so the menus can never drift apart.
+ */
+
+'use client';
+
+import React from 'react';
+
+import { useAuth } from '@djangocfg/api/auth';
+import type { MenuItem } from '@djangocfg/ui-core/components';
+
+import type { UserMenuGroup, UserMenuLocaleConfig } from '../../layouts/types';
+import { useAccountMenuItems } from './useAccountMenuItems';
+
+export interface AccountView {
+  source: 'user' | 'dev-fallback';
+  displayName: string;
+  email: string | null;
+  avatarUrl: string;
+  plan: string | null;
+}
+
+export interface UseAccountModelOptions {
+  /** App link groups. */
+  groups?: UserMenuGroup[];
+  /** Plan shown after the name in the footer trigger. */
+  plan?: string | null;
+  i18n?: UserMenuLocaleConfig;
+  /** Extra items between the groups and Sign out (language, app links). */
+  extra?: MenuItem[];
+  /** Settings rows in the menu. @default true */
+  settings?: boolean;
+  /** Identity block above the items: the `email` (default) or a name + email `card`. */
+  identity?: 'email' | 'card';
+}
+
+export function useAccountModel({ groups, plan = null, i18n, settings = true, extra, identity = 'email' }: UseAccountModelOptions = {}) {
+  const { user } = useAuth();
+
+  /**
+   * When `useAuth` returns a real user we use it; otherwise (dev only) a placeholder keeps the menu reachable for
+   * debugging. Production stays strict: callers render nothing without a user.
+   */
+  const account = React.useMemo<AccountView>(() => {
+    if (user) {
+      return {
+        source: 'user',
+        displayName: user.display_username || user.email || 'User',
+        email: user.email ?? null,
+        avatarUrl: user.avatar ?? '',
+        plan,
+      };
+    }
+    return {
+      source: 'dev-fallback',
+      displayName: 'Guest (dev)',
+      email: null,
+      avatarUrl: '',
+      plan: plan ?? 'No session',
+    };
+  }, [user, plan]);
+
+  const headerLabel: React.ReactNode =
+    identity === 'card' ? (
+      <div className="flex flex-col space-y-1">
+        <p className="text-sm font-medium leading-none">{account.displayName}</p>
+        <p className="text-xs leading-none text-muted-foreground">{account.email}</p>
+      </div>
+    ) : (
+      account.email ?? (account.source === 'dev-fallback' ? 'No active session' : null)
+    );
+  const menuItems = useAccountMenuItems({ groups, label: headerLabel, i18n, settings, extra });
+
+  return { user, account, menuItems };
+}

package/src/components/errors/AppErrorFallback.test.tsx

@@ -0,0 +1,33 @@
+// @vitest-environment jsdom
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { describe, expect, it, vi } from 'vitest';
+
+import { AppErrorFallback } from './AppErrorFallback';
+
+vi.mock('@djangocfg/i18n', () => ({
+  getT: (key: string) => key,
+}));
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function render(props = {}) {
+  const host = document.createElement('div');
+  act(() => createRoot(host).render(<AppErrorFallback {...props} />));
+  return host;
+}
+
+describe('AppErrorFallback', () => {
+  it('renders exactly one action button', () => {
+    const host = render();
+    const buttons = host.querySelectorAll('button');
+    expect(buttons).toHaveLength(1);
+    expect(buttons[0]!.textContent).toBe('layouts.errors.refreshPage');
+  });
+
+  it('keeps one button when a support email is shown', () => {
+    const host = render({ supportEmail: 'help@example.com' });
+    expect(host.querySelectorAll('button')).toHaveLength(1);
+    expect(host.querySelector('a[href="mailto:help@example.com"]')).not.toBeNull();
+  });
+});

package/src/components/errors/AppErrorFallback.tsx

@@ -0,0 +1,42 @@
+/**
+ * AppErrorFallback — the one localized crash screen for Next app layouts.
+ *
+ * Exactly ONE action: "Refresh Page" (hard reload). A soft `reset()` re-mounts
+ * the same broken tree and usually crashes again, so it is not offered as a
+ * second near-identical button. Used by `BaseApp` (via UiProviders) and
+ * `ErrorBoundary`.
+ */
+
+'use client';
+
+import { getT } from '@djangocfg/i18n';
+
+export interface AppErrorFallbackProps {
+  supportEmail?: string;
+}
+
+export function AppErrorFallback({ supportEmail }: AppErrorFallbackProps) {
+  return (
+    <div className="flex min-h-screen items-center justify-center bg-background p-4">
+      <div className="max-w-md w-full space-y-4 text-center">
+        <h1 className="text-2xl font-bold text-foreground">{getT('layouts.errors.somethingWentWrong')}</h1>
+        <p className="text-muted-foreground">{getT('layouts.errors.tryRefreshing')}</p>
+        {supportEmail && (
+          <p className="text-sm text-muted-foreground">
+            {getT('layouts.errors.persistsContact', { email: '' })}{' '}
+            <a href={`mailto:${supportEmail}`} className="text-primary hover:underline">
+              {supportEmail}
+            </a>
+          </p>
+        )}
+        <button
+          type="button"
+          onClick={() => window.location.reload()}
+          className="rounded-md bg-primary px-4 py-2 text-primary-foreground hover:bg-primary/90"
+        >
+          {getT('layouts.errors.refreshPage')}
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/components/errors/ErrorBoundary.tsx

@@ -13,7 +13,7 @@
 import { useMemo, type ComponentType, type ErrorInfo, type ReactNode } from 'react';
 
 import { Boundary, type BoundaryRenderProps } from '@djangocfg/ui-core/components';
-import { getT } from '@djangocfg/i18n';
+import { AppErrorFallback } from './AppErrorFallback';
 
 interface ErrorBoundaryProps {
   children: ReactNode;
@@ -21,50 +21,13 @@ interface ErrorBoundaryProps {
   onError?: (error: Error, errorInfo: ErrorInfo) => void;
 }
 
-/** Localized fullscreen fallback. `reset()` re-mounts the tree (ui-core); we
- *  also offer a hard reload, matching the prior behavior. */
-function makeFallback(supportEmail?: string) {
-  return function ErrorFallback({ reset }: BoundaryRenderProps) {
-    const title = getT('layouts.errors.somethingWentWrong');
-    const description = getT('layouts.errors.tryRefreshing');
-    const refreshButton = getT('layouts.errors.refreshPage');
-    return (
-      <div className="flex min-h-screen items-center justify-center bg-background p-4">
-        <div className="max-w-md w-full space-y-4 text-center">
-          <h1 className="text-2xl font-bold text-foreground">{title}</h1>
-          <p className="text-muted-foreground">{description}</p>
-          {supportEmail && (
-            <p className="text-sm text-muted-foreground">
-              {getT('layouts.errors.persistsContact', { email: '' })}{' '}
-              <a
-                href={`mailto:${supportEmail}`}
-                className="text-primary hover:underline"
-              >
-                {supportEmail}
-              </a>
-            </p>
-          )}
-          <button
-            onClick={() => {
-              reset();
-              // Hard reload as a fallback if a pure reset can't recover.
-              window.location.reload();
-            }}
-            className="px-4 py-2 bg-primary text-primary-foreground rounded-md hover:bg-primary/90"
-          >
-            {refreshButton}
-          </button>
-        </div>
-      </div>
-    );
-  };
-}
-
 export function ErrorBoundary({ children, supportEmail, onError }: ErrorBoundaryProps) {
   // Memoize so the boundary's FallbackComponent identity is stable across
   // renders (no remount churn).
   const Fallback = useMemo<ComponentType<BoundaryRenderProps>>(
-    () => makeFallback(supportEmail),
+    () => function ErrorFallback() {
+      return <AppErrorFallback supportEmail={supportEmail} />;
+    },
     [supportEmail],
   );
   return (

package/src/components/errors/ErrorLayout.tsx

@@ -17,9 +17,10 @@
 
 'use client';
 
-import React, { useMemo } from 'react';
+import React, { useEffect, useMemo } from 'react';
 
 import { Button } from '@djangocfg/ui-core/components';
+import { canAutoReloadForChunk, isChunkLoadError, reloadForChunkError } from '@djangocfg/ui-core/lib';
 import { useAppT } from '@djangocfg/i18n';
 
 import { getErrorContent } from './errorConfig';
@@ -54,6 +55,14 @@ export interface ErrorLayoutProps {
    * it finally matters.
    */
   statusUrl?: string;
+  /**
+   * The caught error (`global-error.tsx` / `error.tsx` receive it as `error`).
+   * When it is a stale-chunk failure (ChunkLoadError, cancelled `/_next/static`
+   * fetch after a deploy) the page reloads ONCE (sessionStorage loop guard) and
+   * renders nothing meanwhile; if the reload already happened, the normal error
+   * screen is shown.
+   */
+  error?: unknown;
 }
 
 /**
@@ -82,8 +91,13 @@ export function ErrorLayout({
   illustration,
   supportEmail = 'support@example.com',
   statusUrl,
+  error,
 }: ErrorLayoutProps) {
   const t = useAppT();
+  const staleChunk = error !== undefined && isChunkLoadError(error);
+  useEffect(() => {
+    if (staleChunk) reloadForChunkError();
+  }, [staleChunk]);
 
   const labels = useMemo(() => ({
     goBack: t('layouts.errors.goBack'),
@@ -121,6 +135,8 @@ export function ErrorLayout({
     window.location.href = '/';
   };
 
+  if (staleChunk && canAutoReloadForChunk()) return null;
+
   return (
     <div className="min-h-screen flex items-center justify-center px-4 bg-background">
       <div className="max-w-2xl w-full text-center space-y-8">

package/src/components/errors/README.md

@@ -11,11 +11,16 @@ All boundaries here build on the single `Boundary` primitive in
 
 | File | What it does |
 |------|--------------|
-| `ErrorBoundary.tsx` | Thin wrapper over ui-core `Boundary` — i18n fallback + support email (for direct use; `BaseApp` no longer wraps it). |
+| `AppErrorFallback.tsx` | The one localized crash screen: title, text, support email, ONE "Refresh Page" button (hard reload). Used by `BaseApp` and `ErrorBoundary`. |
+| `ErrorBoundary.tsx` | Thin wrapper over ui-core `Boundary` — renders `AppErrorFallback` (for direct use; `BaseApp` no longer wraps it). |
 | `MonitorBoundary.tsx` | ui-core `Boundary` that also reports to `@djangocfg/devtools`. |
 | `ErrorLayout.tsx` | Full-page error layout (`getErrorContent` / `ERROR_CODES`). |
 | `ErrorsTracker/` | Global runtime tracker — listens for error CustomEvents and shows toasts. |
 
+## Stale chunks after a deploy
+
+A chunk-load failure (ChunkLoadError, "Loading chunk N failed", dynamic import failure, cancelled fetch of `/_next/static/...`) is a stale tab, not a crash: the page reloads ONCE instead of showing the error screen. Logic lives in `@djangocfg/ui-core/lib` (`chunk-reload.ts`), wired in `Boundary` (render errors), `UiProviders` (window `error` + `unhandledrejection`) and `ErrorLayout error={error}` (`global-error.tsx`). Loop guard: `sessionStorage` key `djangocfg:chunk-reload-at`, 30 s window; with storage blocked no auto reload. Tests: `chunkReload.test.ts`, `AppErrorFallback.test.tsx`.
+
 ## ErrorLayout — `statusUrl`
 
 `ErrorLayout` takes an optional `statusUrl`, rendered as a secondary link beside

package/src/components/errors/chunkReload.test.ts

@@ -0,0 +1,89 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  CHUNK_RELOAD_STORAGE_KEY,
+  CHUNK_RELOAD_WINDOW_MS,
+  canAutoReloadForChunk,
+  installChunkReloadListeners,
+  isChunkLoadError,
+  isStaticAssetLoadEvent,
+  reloadForChunkError,
+} from '@djangocfg/ui-core/lib';
+
+describe('isChunkLoadError', () => {
+  it.each([
+    ['ChunkLoadError by name', Object.assign(new Error('x'), { name: 'ChunkLoadError' })],
+    ['webpack JS chunk', new Error('Loading chunk 123 failed.\n(error: /_next/static/chunks/123.js)')],
+    ['webpack CSS chunk', new Error('Loading CSS chunk 45 failed.')],
+    ['Chrome dynamic import', new TypeError('Failed to fetch dynamically imported module: /_next/static/a.js')],
+    ['Firefox dynamic import', new TypeError('error loading dynamically imported module')],
+    ['Safari module script', new TypeError('Importing a module script failed.')],
+    ['cancelled fetch of static asset', new TypeError('Failed to fetch /_next/static/chunks/app/page-abc.js')],
+    ['aborted static asset via stack', Object.assign(new Error('signal is aborted'), { stack: 'at https://x.io/_next/static/chunks/1.js:1' })],
+    ['string reason', 'Loading chunk 9 failed.'],
+  ])('detects %s', (_n, err) => expect(isChunkLoadError(err)).toBe(true));
+
+  it.each([
+    ['ordinary error', new Error('Cannot read properties of undefined')],
+    ['API fetch failure', new TypeError('Failed to fetch https://api.example.com/items')],
+    ['null', null],
+    ['undefined', undefined],
+  ])('ignores %s', (_n, err) => expect(isChunkLoadError(err)).toBe(false));
+});
+
+describe('isStaticAssetLoadEvent', () => {
+  it('matches failed script/link under /_next/static and nothing else', () => {
+    const script = document.createElement('script');
+    script.src = 'https://x.io/_next/static/chunks/1.js';
+    const other = document.createElement('script');
+    other.src = 'https://cdn.io/lib.js';
+    const link = document.createElement('link');
+    link.href = 'https://x.io/_next/static/css/a.css';
+    const mk = (target: Element) => Object.defineProperty(new Event('error'), 'target', { value: target });
+    expect(isStaticAssetLoadEvent(mk(script))).toBe(true);
+    expect(isStaticAssetLoadEvent(mk(link))).toBe(true);
+    expect(isStaticAssetLoadEvent(mk(other))).toBe(false);
+  });
+});
+
+describe('reload guard', () => {
+  const reload = vi.fn();
+  beforeEach(() => {
+    sessionStorage.clear();
+    reload.mockClear();
+    Object.defineProperty(window, 'location', { configurable: true, value: { ...window.location, reload } });
+  });
+  afterEach(() => vi.restoreAllMocks());
+
+  it('reloads once, then blocks a second reload inside the window', () => {
+    expect(reloadForChunkError(1_000)).toBe(true);
+    expect(sessionStorage.getItem(CHUNK_RELOAD_STORAGE_KEY)).toBe('1000');
+    expect(reloadForChunkError(1_000 + 5_000)).toBe(false);
+    expect(reload).toHaveBeenCalledTimes(1);
+  });
+
+  it('allows another reload after the window passes', () => {
+    reloadForChunkError(1_000);
+    expect(canAutoReloadForChunk(1_000 + CHUNK_RELOAD_WINDOW_MS + 1)).toBe(true);
+  });
+
+  it('never reloads when sessionStorage is unusable (no loop risk)', () => {
+    vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+      throw new Error('denied');
+    });
+    expect(canAutoReloadForChunk()).toBe(false);
+    expect(reloadForChunkError()).toBe(false);
+    expect(reload).not.toHaveBeenCalled();
+  });
+
+  it('window listeners reload once for an unhandled chunk rejection', () => {
+    const off = installChunkReloadListeners();
+    const ev = new Event('unhandledrejection') as Event & { reason?: unknown };
+    ev.reason = new Error('Loading chunk 7 failed.');
+    window.dispatchEvent(ev);
+    window.dispatchEvent(ev);
+    expect(reload).toHaveBeenCalledTimes(1);
+    off();
+  });
+});

package/src/components/errors/index.ts

@@ -3,6 +3,8 @@
  */
 
 export { ErrorBoundary } from './ErrorBoundary';
+export { AppErrorFallback } from './AppErrorFallback';
+export type { AppErrorFallbackProps } from './AppErrorFallback';
 export { MonitorBoundary } from './MonitorBoundary';
 export type { MonitorBoundaryProps } from './MonitorBoundary';
 export { ErrorLayout } from './ErrorLayout';

package/src/layouts/AppLayout/BaseApp.tsx

@@ -54,65 +54,20 @@ import { useScrollToTop } from '@djangocfg/ui-core/hooks';
 import { NextRouterAdapter, NextLinkProvider } from '@djangocfg/ui-core/adapters/nextjs';
 import { NextIntlLinkBridge } from './NextIntlLinkBridge';
 import { ThemeProvider } from '@djangocfg/ui-core/theme';
-import type { BoundaryRenderProps } from '@djangocfg/ui-core/components';
-import { getT } from '@djangocfg/i18n';
+import { AppErrorFallback } from '../../components/errors/AppErrorFallback';
 import { ErrorTrackingProvider } from '../../components/errors/ErrorsTracker';
 import { AnalyticsProvider } from '../../snippets/Analytics';
 import { AuthDialog } from '../../snippets/AuthDialog';
 
 import type { BaseLayoutProps } from '../types/layout.types';
 import { LayoutI18nProvider } from '../../shared/LayoutI18nProvider';
+import { ProjectNameProvider } from '../../shared/ProjectContext';
 
 import React from 'react';
 
 // For backwards compatibility, re-export as BaseAppProps
 export type BaseAppProps = BaseLayoutProps;
 
-/**
- * Localized crash fallback fed into UiProviders' built-in Boundary. Renders the
- * i18n'd "something went wrong" screen + optional support email. `reset()`
- * re-mounts (soft recover); the Reload button hard-reloads when a soft reset
- * can't recover (e.g. the crash is in a provider above the boundary's subtree).
- */
-function AppErrorFallback({
-  reset,
-  supportEmail,
-}: BoundaryRenderProps & { supportEmail?: string }) {
-  const title = getT('layouts.errors.somethingWentWrong');
-  const description = getT('layouts.errors.tryRefreshing');
-  const retry = getT('layouts.errors.refreshPage');
-  return (
-    <div className="flex min-h-screen items-center justify-center bg-background p-4">
-      <div className="max-w-md w-full space-y-4 text-center">
-        <h1 className="text-2xl font-bold text-foreground">{title}</h1>
-        <p className="text-muted-foreground">{description}</p>
-        {supportEmail && (
-          <p className="text-sm text-muted-foreground">
-            {getT('layouts.errors.persistsContact', { email: '' })}{' '}
-            <a href={`mailto:${supportEmail}`} className="text-primary hover:underline">
-              {supportEmail}
-            </a>
-          </p>
-        )}
-        <div className="flex items-center justify-center gap-2">
-          <button
-            onClick={reset}
-            className="rounded-md bg-primary px-4 py-2 text-primary-foreground hover:bg-primary/90"
-          >
-            {retry}
-          </button>
-          <button
-            onClick={() => window.location.reload()}
-            className="rounded-md border border-border px-4 py-2 text-foreground hover:bg-muted"
-          >
-            {getT('layouts.errors.refreshPage')}
-          </button>
-        </div>
-      </div>
-    </div>
-  );
-}
-
 /**
  * Lands every forward navigation at the top of the page.
  *
@@ -189,9 +144,7 @@ export function BaseApp({
         onError={errorBoundary?.onError}
         errorFallback={
           enableErrorBoundary
-            ? (props) => (
-                <AppErrorFallback {...props} supportEmail={errorBoundary?.supportEmail} />
-              )
+            ? () => <AppErrorFallback supportEmail={errorBoundary?.supportEmail} />
             : undefined
         }
       >
@@ -214,11 +167,13 @@ export function BaseApp({
                 <ScrollToTop />
                 <Devtools {...devtoolsProps} />
                 <LayoutI18nProvider value={i18n}>
-                  {i18n?.routing ? (
-                    <NextIntlLinkBridge routing={i18n.routing}>{children}</NextIntlLinkBridge>
-                  ) : (
-                    children
-                  )}
+                  <ProjectNameProvider value={project}>
+                    {i18n?.routing ? (
+                      <NextIntlLinkBridge routing={i18n.routing}>{children}</NextIntlLinkBridge>
+                    ) : (
+                      children
+                    )}
+                  </ProjectNameProvider>
                 </LayoutI18nProvider>
                 <NextTopLoader
                   color="var(--primary)"

package/src/layouts/AppLayout/index.ts

@@ -13,6 +13,7 @@ export type { BaseAppProps } from './BaseApp';
 
 export type { I18nLayoutConfig } from '../types';
 
+export { ProjectNameProvider, useProjectName } from '../../shared/ProjectContext';
 export {
   LayoutI18nProvider,
   useLayoutI18n,

package/src/layouts/PrivateLayout/PrivateLayout.tsx

@@ -14,7 +14,13 @@
 
 import React from 'react';
 
+import { useAuth } from '@djangocfg/api/auth';
+import { useLandingRoute } from './hooks/useLandingRoute';
+import { useProjectName } from '../../shared/ProjectContext';
 import { Preloader } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+import { SHELL_CLASS } from './geometry';
 import { SidebarInset, SidebarProvider } from '@djangocfg/ui-core/components';
 
 import { ForbiddenState, PrivateContent, PrivateSidebar } from './components';
@@ -55,6 +61,7 @@ export function PrivateLayout({
   children,
   sidebar,
   header,
+  topBar,
   pathname,
   contentPadding = 'default',
   contentScroll = 'auto',
@@ -73,9 +80,26 @@ export function PrivateLayout({
   const { providerStyle, providerClassName, insetClassName, sidebarVariant } =
     useLayoutVisual(visual);
 
+  // The account avatar lives in the top bar for a signed-in user unless `topBar.account === false`.
+  const { user } = useAuth();
+  // Bar title: topBar.title > header.title > the BaseApp project name > nothing. Only the last two link home.
+  const projectName = useProjectName();
+  const landing = useLandingRoute();
+  const barTitle = topBar?.title ?? (header?.title?.trim() || projectName || undefined);
+  const barHref = header?.href || sidebar?.homeHref || landing || '/';
+  const accountInBar = Boolean(user) && topBar?.account !== false;
+
   const defaultOpen = useSidebarDefaultOpen();
   const sidebarWidth = useSidebarWidth(Boolean(sidebar) && sidebar?.resizable !== false);
 
+  // Marks <html> while a private shell is mounted: base.css locks html/body (no document scroll, no rubber band)
+  // in an installed app, for private pages only. Public pages never carry it and stay scrollable.
+  React.useEffect(() => {
+    const root = document.documentElement;
+    root.setAttribute('data-private-shell', '');
+    return () => root.removeAttribute('data-private-shell');
+  }, []);
+
   if (isLoading) {
     return (
       <Preloader
@@ -99,7 +123,7 @@ export function PrivateLayout({
     <SidebarProvider
       defaultOpen={defaultOpen}
       style={{ ...providerStyle, ...sidebarWidth.style }}
-      className={providerClassName}
+      className={cn(SHELL_CLASS, providerClassName)}
       data-sidebar-resizing={sidebarWidth.dragging || undefined}
     >
       <SidebarWidthContext.Provider value={sidebarWidth}>
@@ -110,6 +134,7 @@ export function PrivateLayout({
               header={header}
               pathname={pathname}
               variant={sidebarVariant}
+              accountInBar={accountInBar}
             />
           )}
 
@@ -118,6 +143,12 @@ export function PrivateLayout({
               padding={contentPadding}
               scroll={contentScroll}
               hasSidebar={Boolean(sidebar)}
+              pathname={pathname}
+              title={barTitle}
+              titleHref={topBar?.title == null && barTitle ? barHref : undefined}
+              actions={topBar?.actions}
+              showAccount={accountInBar}
+              header={header}
               visual={visual}
             >
               {children}

package/src/layouts/PrivateLayout/README.md

@@ -1,6 +1,6 @@
 # PrivateLayout
 
-Authenticated app shell — a docked, resizable sidebar + scrollable content area. Collapsed, a trigger remains and hovering it peeks the sidebar open over the page; on mobile it is a drawer.
+Authenticated app shell — a docked, resizable sidebar + scrollable content area. Collapsed, a top bar remains and resting at the left screen edge peeks the sidebar open over the page (the toggle itself only clicks); on mobile it is a drawer.
 
 ```tsx
 <PrivateLayout
@@ -137,7 +137,7 @@ For pages like Kanban boards where the shell must be exactly one viewport tall a
 | Field | Type | Notes |
 |---|---|---|
 | `groups` | `SidebarGroupConfig[]` | Nav items grouped under labels. Set `group.label = ''` to render flat (no header). |
-| `homeHref` | `string` | Brand link target. |
+| `homeHref` | `string` | Brand link target. Order: `header.href` > `sidebar.homeHref` > auth `routes.defaultCallback` (the private landing page set in `BaseApp` `auth.routes`) > `/`. |
 | `menuStart` / `menuEnd` | `ReactNode` | Free slots above / below `groups` in the scrollable column. |
 | `menuStartShowOnCollapsed` / `menuEndShowOnCollapsed` | `boolean` | Deprecated, no effect (no icon rail). |
 | `resizable` | `boolean` | Drag the sidebar edge (14–24rem, remembered under `cfg.layouts.sidebar-width`; double-click resets). Default `true`. |
@@ -163,7 +163,7 @@ For pages like Kanban boards where the shell must be exactly one viewport tall a
 
 | Field | Type | Notes |
 |---|---|---|
-| `label`, `href`, `icon`, `tooltip` | — | Standard nav item fields. |
+| `label`, `href`, `icon` | — | Standard nav item fields (`tooltip` is deprecated, no effect). |
 | `settingsSection` | section id | Instead of `href`: a row that opens the Settings dialog on that section. Rendered only while the mounted dialog lists the section (no dead door), active while the dialog shows it. Type it with `SidebarItem<AppSectionId>` (see [SettingsLayout](../SettingsLayout/README.md#typed-section-ids)). |
 | `badge` | `string \| number` | Trailing badge content. |
 | `badgeVariant` | `'count' \| 'pill'` | Visual style. `'pill'` is accent-tinted (e.g. "lite"/"new"); `'count'` is neutral (default). |
@@ -279,7 +279,23 @@ const header: HeaderConfig = {
 | State | Behaviour |
 |---|---|
 | Docked | Width from `--sidebar-width`; drag the right edge, arrow keys, double-click to reset. |
-| Collapsed (desktop) | Hidden. A trigger stays top-left in a 48px top bar (in flow, so content never sits under it); hovering the trigger (or the free area around it) floats the sidebar over the page. The panel stays while the pointer is on it or a menu opened from it is open; Esc, navigation and moving away close it. Clicking the trigger docks it. |
-| Mobile (< md) | Drawer up to 22rem: 44px rows, 14px text, 18px icons, 8px side padding, 12px vertical body padding, close button. The drawer header and footer respect the safe areas (at least 1rem). The trigger is a 40px ghost button in a 48px in-flow top bar (also for `contentPadding="none"` pages) that adds `env(safe-area-inset-top)`. |
+| Collapsed (desktop) | Hidden. The top bar (toggle top-left, title, actions, avatar) shows; resting the pointer at the left screen edge (not on the toggle) floats the sidebar over the page. The panel stays while the pointer is on it or a menu opened from it is open; Esc, navigation and moving away close it. Clicking the trigger docks it. |
+| Mobile (< md) | Drawer 88vw wide (max 22rem, the dimmed strip taps it closed) and full height (`fixed inset-y-0`: the real visible area in a browser tab and in an iOS standalone PWA): 40px rows (44px hit area), 14px text, 20px icons, 8px container gutter + 10px row padding (icon column and logo at 18px; dividers, highlighted rows and footer share the 8px gutter), header is the brand only (48px under safe-top, no toggle or close button; it closes by backdrop tap, swipe, Escape or navigating). Three zones: pinned header (gets a bottom hairline once the nav scrolls), the nav as the ONLY scroller (`overscroll-contain`), pinned footer with a full-width top border and its own background; the drawer panel itself is `overflow-hidden` (`DrawerContent bare`). Header and footer respect the safe areas on top, bottom and sides (at least 1rem vertically). On a phone (below md) the layout draws a plain top bar: `safe-top + 3rem` tall (`--layout-bar-height`, `0px` from md up and without a sidebar), `bg-background` with a 1px bottom border, holding the sidebar toggle (the same ghost button as in the sidebar header) and `header.title`. It overlays the content column and slides away (`transform`, 200ms) on scroll-down and back on scroll-up or at the top, using the same `useNavbarScroll` policy as `PublicLayout` driven by the content scroller; it stays while the drawer is open, a field has focus, or the page is not scrollable. Content starts below the bar for every page, so pages do nothing; apps may use `--layout-bar-height` to offset their own sticky elements. `PrivateLayout` takes `topBar={{ title, actions }}` (types: `PrivateTopBarConfig`): `title` replaces `header.title` in the bar, `actions` is a ReactNode on the right (vertically centred, never shrinks the toggle; the title takes the rest and truncates). The same bar shows on desktop while the sidebar is collapsed (static, no auto-hide) and carries the account avatar for a signed-in user (`topBar.account={false}` to opt out); on a phone the drawer then has no footer account. Recommended actions are compact ghost icon `Button`s (36px); several are fine, keep them few. The toggle stays left and is not configurable. It is rendered by the phone bar only; desktop shows nothing (the sidebar is the navigation). |
 
-Row metrics (`geometry.ts`): desktop rows 36px, mobile rows 44px (touch target), both `text-sm` with 16px (desktop) or 18px (mobile) icons and group labels in `text-xs`. Safe-area insets only exist when the host app sets `viewportFit: "cover"` in its Next.js `viewport` export; without it the offsets fall back to the fixed minimums.
+Row metrics (`geometry.ts`): desktop rows 36px, mobile rows 40px (with a 44px hit area from an invisible `::after`), both `text-sm` with 16px (desktop) or 20px (mobile) icons and group labels in `text-xs`. Safe-area insets only exist when the host app sets `viewportFit: "cover"` in its Next.js `viewport` export; without it the offsets fall back to the fixed minimums. For an installed iOS PWA also set `appleWebApp.statusBarStyle` (`black-translucent` draws the page under the status bar and relies on the insets; `default` keeps it below). The drawer height is pinned with `inset-y-0` rather than `100dvh`, which can disagree with the visible area in standalone mode.
+
+
+## Installed app (PWA) support
+
+- Detection: `useDisplayMode()` / `useIsPwa()` from `@djangocfg/ui-core/hooks` (the `display-mode` media query, iOS `navigator.standalone`, Android TWA referrer). The server and hydration render say `browser`; for first-paint styling use CSS: `UiProviders` sets `<html data-display-mode="browser|standalone|fullscreen|minimal-ui|window-controls-overlay">`.
+- Tokens (ui-core `base.css`): `--safe-top/right/bottom/left` (= `--app-safe-*` if set, else `env(safe-area-inset-*)`), `--app-height: 100dvh`. Tokens are for layout and spacing; the hook is for behaviour (hide an "install app" prompt, show a back button).
+- Host requirements for a good PWA: `viewport-fit=cover` (`viewport.viewportFit = 'cover'`), `appleWebApp: { capable: true, statusBarStyle }` (`black-translucent` draws the page under the status bar and needs the insets; `default` keeps it below), a manifest with `display: 'standalone'`, and `themeColor`. `createViewport({ themeColor, viewportFit: 'cover' })` and `createManifestMetadata({ ..., statusBarStyle })` from `@djangocfg/nextjs` set them.
+- Storybook: toolbar items "Display mode" and "Safe area" emulate an installed iPhone; see the PhonePwa* stories.
+
+## The shell never scrolls the document
+
+`PrivateLayout` is exactly one dynamic viewport tall (`h-[var(--app-height,100dvh)] overflow-hidden`, `SHELL_CLASS`): the (desktop) trigger bar is `shrink-0`, the content below it is `flex-1 min-h-0` and owns the scroll (per `contentScroll`). While mounted it sets `data-private-shell` on `<html>`; in an installed app base.css then locks `html`/`body` (`height: 100%; overflow: hidden; overscroll-behavior: none`), so pressing and dragging the top bar cannot move the page. Public pages never carry the attribute and stay scrollable. Consequences for pages: sticky elements and `window.scrollTo` now relate to the content region, not the window; the layout scrolls its content back to the top when `pathname` changes. Do not wrap the layout in `min-h-screen` / `h-screen`. On iOS < 16, `overscroll-behavior` is ignored, so a rubber band at the very edge can only be ruled out on a real device.
+
+## Brand title and link
+
+The product name is semibold (16px on desktop, 14px on a phone, theme type scale), one line, truncated. Title order: `header.title` > `BaseApp` `project` name > none (monogram only). The brand (sidebar header, phone drawer header) and the default top bar title link to `header.href` (default `sidebar.homeHref`, else `/`) through the router `Link` (target order: `header.href` > `sidebar.homeHref` > auth `defaultCallback` > `/`); the drawer closes on click. A custom `header.brand` node is not wrapped; `topBar.title` is shown as given.