@djangocfg/layouts 2.1.427 → 2.1.428

package/README.md

@@ -13,38 +13,45 @@ pnpm add @djangocfg/layouts
 ```
 
 ```css
-/* before @import "tailwindcss" */
-@import "@djangocfg/ui-nextjs/styles";
+/* Golden path — bundles Tailwind + tokens + base + utilities, layer-safe */
+@import "@djangocfg/ui-core/styles/full";
 @import "@djangocfg/layouts/styles";
-@import "tailwindcss";
 ```
 
-Peers: `@djangocfg/ui-core`, `@djangocfg/ui-nextjs`, React 19, Next.js 16+, Tailwind CSS 4.
+Peers: `@djangocfg/ui-core`, React 19, Next.js 16+, Tailwind CSS 4.
 
 ---
 
 ## Quick start
 
-`AppLayout` wraps `BaseApp` (theme, auth, analytics, SWR, toasts) and routes the page to the right shell based on path:
+Two responsibilities, kept separate:
+
+1. **Providers** — mount `BaseApp` ONCE at the app root (theme, auth, i18n, SWR,
+   monitor, toasts). It's framework-agnostic (works in Wails/Vite too).
+2. **Per-section shell** — each Next.js **route-group `layout.tsx`** imports the
+   matching shell (`PrivateLayout` / `PublicLayout`) and passes its own config.
+   No runtime layout-router, no `enabledPath` matching.
 
 ```tsx
-<AppLayout
-  layouts={{
-    public:  { component: PublicLayout,  enabledPath: ['/', '/legal'] },
-    private: { component: PrivateLayout, enabledPath: ['/dashboard'] },
-    admin:   { component: AdminLayout,   enabledPath: '/admin' },
-    noLayoutPaths: ['/embed'],
-  }}
-  baseApp={{ project: 'my-app', theme: { defaultTheme: 'system' }, auth: { apiUrl: '…' } }}
-  i18n={{ locale, locales, onLocaleChange: changeLocale, routing }}
->
+// app/[locale]/layout.tsx — providers, once
+import { BaseApp } from '@djangocfg/layouts';
+<BaseApp project="my-app" theme={{ defaultTheme: 'system' }}
+         auth={{ apiUrl: '…', routes: { auth: '/auth' } }}
+         i18n={{ locale, locales, onLocaleChange: changeLocale, routing }}>
   {children}
-</AppLayout>
+</BaseApp>
+
+// app/[locale]/(pages)/private/layout.tsx — the private shell
+import { PrivateLayout } from '@djangocfg/layouts';
+<PrivateLayout sidebar={sidebar} header={header}>{children}</PrivateLayout>
 ```
 
-Use `BaseApp` directly when you don't need route-based layout switching — see [AppLayout README](./src/layouts/AppLayout/README.md) for the matching rules, `noLayoutPaths`, `publicChrome`, and `i18n.routing` plumbing.
+See the [**BaseApp README**](./src/layouts/AppLayout/README.md) for the full
+provider surface and the Next.js vs Wails wiring, and the demo app
+(`apps/demo/app/_layouts`) for a complete reference.
 
-> **Pass `i18n`** when using `next-intl` or any locale-prefixed routing. Without it, the path matcher can mis-strip 2-letter segments (e.g. `/ui/*` treated as locale `ui`).
+> **Pass `i18n`** when using `next-intl` or any locale-prefixed routing, so the
+> link bridge and locale switcher resolve correctly.
 
 ---
 
@@ -55,8 +62,9 @@ Use `BaseApp` directly when you don't need route-based layout switching — see
 | **`PublicLayout`** | Marketing / docs. Slots for navbar (`Floating`/`Flush`/`Minimal`) + footer + locale + auth controls. | [README](./src/layouts/PublicLayout/README.md) |
 | **`PrivateLayout`** | Authenticated app shell — sidebar (collapsible icon rail, accordion groups, rail/featured/CTA slots) + popover account footer. | [README](./src/layouts/PrivateLayout/README.md) |
 | **`AuthLayout`** | Sign-in / sign-up flows. Shell-based: `centered` (default) or `split` (two-column desktop). | [README](./src/layouts/AuthLayout/README.md) |
-| **`AdminLayout`** | Admin console. | — |
-| **`ProfileLayout`** | Profile page — see below. |  |
+
+> **Admin** is not a separate layout — use `PrivateLayout` with an admin `sidebar`
+> config in your `app/.../admin/layout.tsx`.
 
 ### `AuthLayout` shells
 
@@ -115,7 +123,7 @@ import { useLocaleSwitcher } from '@djangocfg/nextjs/i18n/client';
 import { routing } from '@djangocfg/nextjs/i18n/routing';
 
 const { locale, locales, changeLocale } = useLocaleSwitcher();
-<AppLayout i18n={{ locale, locales, onLocaleChange: changeLocale, routing }}>...</AppLayout>
+<BaseApp i18n={{ locale, locales, onLocaleChange: changeLocale, routing }}>...</BaseApp>
 ```
 
 When `routing` is set, `BaseApp` mounts a locale-aware `<Link>` adapter so every layout-rendered link keeps the active locale prefix. Drop it for default-locale-only apps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.427",
+  "version": "2.1.428",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -89,12 +89,12 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.427",
-    "@djangocfg/centrifugo": "^2.1.427",
-    "@djangocfg/debuger": "^2.1.427",
-    "@djangocfg/i18n": "^2.1.427",
-    "@djangocfg/monitor": "^2.1.427",
-    "@djangocfg/ui-core": "^2.1.427",
+    "@djangocfg/api": "^2.1.428",
+    "@djangocfg/centrifugo": "^2.1.428",
+    "@djangocfg/debuger": "^2.1.428",
+    "@djangocfg/i18n": "^2.1.428",
+    "@djangocfg/monitor": "^2.1.428",
+    "@djangocfg/ui-core": "^2.1.428",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -125,14 +125,14 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.427",
-    "@djangocfg/centrifugo": "^2.1.427",
-    "@djangocfg/debuger": "^2.1.427",
-    "@djangocfg/i18n": "^2.1.427",
-    "@djangocfg/monitor": "^2.1.427",
-    "@djangocfg/typescript-config": "^2.1.427",
-    "@djangocfg/ui-core": "^2.1.427",
-    "@djangocfg/ui-tools": "^2.1.427",
+    "@djangocfg/api": "^2.1.428",
+    "@djangocfg/centrifugo": "^2.1.428",
+    "@djangocfg/debuger": "^2.1.428",
+    "@djangocfg/i18n": "^2.1.428",
+    "@djangocfg/monitor": "^2.1.428",
+    "@djangocfg/typescript-config": "^2.1.428",
+    "@djangocfg/ui-core": "^2.1.428",
+    "@djangocfg/ui-tools": "^2.1.428",
     "@types/node": "^25.2.3",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",

package/src/components/errors/ErrorsTracker/components/ErrorToast.tsx

@@ -8,6 +8,8 @@
 
 import React from 'react';
 
+import { isDev } from '@djangocfg/ui-core/lib';
+
 import { extractDomain, formatErrorTitle, formatZodIssues, safeZodIssues } from '../utils/formatters';
 import { ErrorButtons } from './ErrorButtons';
 
@@ -106,6 +108,17 @@ function buildNetworkDescription(
     parts.push(`Status: ${detail.statusCode}`);
   }
 
+  // DPoP (RFC 9449) 401s are easy to mistake for a plain auth failure. In dev,
+  // add a clear hint pointing at the cause. Detected from the backend's error
+  // message (codes dpop_proof_required / dpop_proof_invalid). Dev-only so end
+  // users never see internal proof wording.
+  const looksDpop =
+    detail.statusCode === 401 && /dpop/i.test(detail.error || '');
+  const dpopHint = isDev && looksDpop
+    ? 'DPoP: this token is sender-constrained — the request needs a valid DPoP proof '
+      + 'signed by the in-browser key. A copied/replayed token will 401.'
+    : null;
+
   return (
     <div className="flex flex-col gap-2 text-sm">
       {parts.length > 0 && (
@@ -116,6 +129,12 @@ function buildNetworkDescription(
 
       <div className="opacity-90">{detail.error}</div>
 
+      {dpopHint && (
+        <div className="rounded-md bg-amber-500/10 px-2 py-1 text-xs text-amber-600 dark:text-amber-400">
+          {dpopHint}
+        </div>
+      )}
+
       <ErrorButtons detail={detail} />
     </div>
   );

package/src/components/errors/ErrorsTracker/utils/curl-generator.ts

@@ -6,6 +6,7 @@
  * Generates cURL commands from API request details with authentication token
  */
 
+import { auth, dpopEnabled } from '@djangocfg/api';
 import consola from 'consola';
 
 export interface CurlOptions {
@@ -19,18 +20,19 @@ export interface CurlOptions {
 }
 
 /**
- * Get authentication token from localStorage
+ * Get the current access token via the shared auth store.
+ *
+ * Must go through `auth.getToken()` — it reads the live token from whichever
+ * backend the app configured (localStorage *or* cookie) under the canonical
+ * `cfg.access_token` key. Reading raw localStorage keys here (the old
+ * `access_token`/`token`/`auth_token` guesses) never matched and always
+ * returned null, so the copied cURL had no Authorization header.
  */
 export function getAuthToken(): string | null {
   if (typeof window === 'undefined') return null;
 
   try {
-    // Priority order: access_token > token > auth_token
-    const token = localStorage.getItem('access_token') ||
-                  localStorage.getItem('token') ||
-                  localStorage.getItem('auth_token');
-
-    return token;
+    return auth.getToken();
   } catch (error) {
     consola.error('Failed to get auth token:', error);
     return null;
@@ -84,8 +86,20 @@ export function generateCurl(options: CurlOptions): string {
     ...headers,
   };
 
-  // Add Authorization header if token exists
-  if (token) {
+  const dpop = dpopEnabled;
+  let preamble = '';
+
+  if (dpop) {
+    // DPoP on → the Bearer token is non-replayable from a terminal. Offer the
+    // API-key path instead (the supported way to script the API), with a
+    // placeholder the user fills from Settings → API keys.
+    allHeaders['X-API-Key'] = '<your-api-key>';
+    preamble =
+      '# This endpoint is DPoP-protected: a copied Bearer token returns 401\n' +
+      '# (it is bound to a non-extractable in-browser key, proof expires ~60s).\n' +
+      '# For scripts, use an API key — get one at: Settings → API keys.\n';
+  } else if (token) {
+    // No DPoP → a Bearer token works in a terminal as-is.
     allHeaders['Authorization'] = `Bearer ${token}`;
   }
 
@@ -102,7 +116,7 @@ export function generateCurl(options: CurlOptions): string {
   }
 
   // Join with line continuation
-  return curlParts.join(' \\\n  ');
+  return preamble + curlParts.join(' \\\n  ');
 }
 
 /**

package/src/components/errors/README.md

@@ -0,0 +1,63 @@
+# Errors — boundaries + runtime error tracking
+
+In-app error surfacing for `@djangocfg/layouts`: React error boundaries, a global
+runtime error tracker, and developer-facing toasts (with a Copy-as-cURL action).
+
+## Pieces
+
+| File | What it does |
+|------|--------------|
+| `ErrorBoundary.tsx` | React error boundary with a friendly fallback. |
+| `MonitorBoundary.tsx` | Error boundary that also reports to `@djangocfg/monitor`. |
+| `ErrorLayout.tsx` | Full-page error layout (`getErrorContent` / `ERROR_CODES`). |
+| `ErrorsTracker/` | Global runtime tracker — listens for error CustomEvents and shows toasts. |
+
+## ErrorsTracker
+
+`ErrorTrackingProvider` listens on `window` for typed error events dispatched by
+the generated API client and runtime, then renders a Sonner toast per error.
+
+Tracked error types: `validation` (zod response mismatch), `network` (failed/4xx/5xx
+requests, incl. a CORS heuristic), `centrifugo` (WS), and `runtime` (uncaught JS).
+
+```tsx
+import { ErrorTrackingProvider } from '@djangocfg/layouts'; // (or the module path)
+
+<ErrorTrackingProvider
+  validation={{ enabled: true }}
+  network={{ enabled: true, showStatusCode: true }}
+>
+  {children}
+</ErrorTrackingProvider>
+```
+
+### Toast actions
+
+Each toast has **Copy error** (JSON to clipboard) and, for requests, **Copy cURL**.
+
+### Copy-as-cURL + DPoP
+
+`utils/curl-generator.ts` builds a runnable cURL from the failed request:
+
+- **DPoP off** — includes `Authorization: Bearer <token>` (read live via
+  `auth.getToken()`), so the command works as-is in a terminal.
+- **DPoP on** (`dpopEnabled` from `@djangocfg/api`) — a copied Bearer token would
+  just `401` (it is bound to a non-extractable in-browser key and needs a fresh
+  proof that can't leave the browser). So the cURL instead emits an
+  `X-API-Key: <your-api-key>` placeholder plus a comment pointing to
+  **Settings → API keys** — the supported way to script the API (Stripe/GitHub
+  model). See `@djangocfg/nextjs/@docs/DPOP.md`.
+
+### DPoP error hint
+
+A `401` whose body mentions DPoP (`dpop_proof_required` / `dpop_proof_invalid`)
+gets an extra **dev-only** hint in the toast explaining it's a sender-constraint
+failure, so it isn't mistaken for a plain auth error. End users never see the
+internal proof wording (gated by `isDev`).
+
+## Notes
+
+- Env/feature flags come from the single source of truth: `isDev` from
+  `@djangocfg/ui-core/lib`, `dpopEnabled` from `@djangocfg/api`.
+- Errors also flow to `@djangocfg/monitor` → `@djangocfg/debuger` panel for
+  inspection regardless of toast visibility.

package/src/layouts/AppLayout/BaseApp.tsx

@@ -1,6 +1,13 @@
 /**
  * BaseApp - Core Providers Wrapper
  *
+ * The canonical provider stack for ANY React host — it is framework-agnostic and
+ * does NOT depend on Next.js routing. Use it directly as the single top-level
+ * wrapper in environments that have no Next.js app router: **Wails desktop**,
+ * Electron, Vite/SPA, plain React. (In Next.js apps it's mounted once in the
+ * root `[locale]/layout.tsx`; per-route shells are chosen by native route-group
+ * `layout.tsx` files, not by this component.)
+ *
  * Provides essential app-wide providers:
  * - ThemeProvider (light/dark/system theme)
  * - TooltipProvider (tooltip positioning)

package/src/layouts/AppLayout/README.md

@@ -1,88 +1,103 @@
-# AppLayout
+# BaseApp — provider stack
 
-Smart layout router + all-in-one providers wrapper for Next.js apps.
+`BaseApp` is the **single, framework-agnostic provider wrapper** for any React
+host. It mounts theme, auth, i18n, SWR, error tracking, monitor, the debug
+panel, and the router adapter — everything an app needs *above* the page tree.
 
-Picks `public` / `private` / `admin` layout based on the current pathname, mounts `BaseApp` (theme, auth, analytics, centrifugo, SWR, error boundary, monitor, PWA), and optionally forces a theme on specific routes.
+There is **no `AppLayout` layout-router** anymore. Picking which shell
+(public / private / admin) wraps a route is the job of **native Next.js
+route-group `layout.tsx` files**, not a runtime path-matcher. This is simpler,
+RSC-friendly, and supports per-segment `loading.tsx` / `error.tsx`.
+
+## Where it goes
+
+### Next.js — mount once at the app root
 
 ```tsx
-import { AppLayout } from '@djangocfg/layouts';
-
-<AppLayout
-  layouts={{
-    public: { component: PublicLayout, enabledPath: ['/', '/about'] },
-    private: { component: DashboardLayout, enabledPath: '/dashboard' },
-    admin: { component: AdminLayout, enabledPath: '/admin' },
-    noLayoutPaths: ['/embed', '/print'],
-    themeOverrides: [
-      { path: '/', theme: 'dark' },              // landing always dark
-      { path: ['/legal', '/legal/**'], theme: 'light' }, // legal always light
-    ],
-  }}
-  baseApp={{
-    theme: { defaultTheme: 'system', storageKey: 'myapp-theme' },
-    auth: { apiUrl: settings.api.baseUrl },
-    analytics: { googleTrackingId: 'G-...' },
-  }}
->
-  {children}
-</AppLayout>
+// app/[locale]/layout.tsx  (or app/layout.tsx)
+import { BaseApp } from '@djangocfg/layouts';
+
+export default function RootLayout({ children }) {
+  return (
+    <html><body>
+      <BaseApp
+        project="my-app"
+        theme={{ defaultTheme: 'system', storageKey: 'myapp-theme' }}
+        auth={{ apiUrl: process.env.NEXT_PUBLIC_API_URL,
+                routes: { auth: '/auth', defaultCallback: '/private' } }}
+        // analytics / centrifugo / monitor / errorTracking / debug — all optional
+      >
+        {children}
+      </BaseApp>
+    </body></html>
+  );
+}
 ```
 
-## Path matcher
+Then each section owns its shell via a route-group layout:
 
-All `enabledPath` / `themeOverrides[].path` fields use the same matcher:
+```tsx
+// app/[locale]/(pages)/private/layout.tsx
+import { PrivateLayout } from '@djangocfg/layouts';
+export default function PrivateRouteLayout({ children }) {
+  return <PrivateLayout sidebar={sidebar} header={header}>{children}</PrivateLayout>;
+}
 
-| Pattern | Matches |
-|---|---|
-| `/dashboard` | `/dashboard`, `/dashboard/anything` (prefix) |
-| `/projects/*/edit` | `/projects/123/edit` (single segment) |
-| `/admin/**` | `/admin`, `/admin/a/b/c` (any depth) |
-| `['/a', '/b']` | any of the listed paths |
+// app/[locale]/(marketing)/layout.tsx
+import { PublicLayout } from '@djangocfg/layouts';
+export default function PublicRouteLayout({ children }) {
+  return <PublicLayout navbar={<MyNavbar/>} footer={<MyFooter/>}>{children}</PublicLayout>;
+}
+```
 
-Pathname is stripped of the locale prefix before matching (`/ru/dashboard` → `/dashboard`).
+`/auth/*` and other fullscreen pages just live outside those groups — no
+`noLayoutPaths` config needed; they simply aren't wrapped.
 
-## themeOverrides
+> **Admin** is not a separate layout — it's `PrivateLayout` with a different
+> `sidebar` config in `app/.../admin/layout.tsx`.
 
-Per-route theme override — evaluated top-to-bottom, first match wins. While the pathname matches, the forced theme is applied via `next-themes`. When you navigate away, the user's previous choice is restored from `localStorage`.
+### Non-Next.js (Wails / Electron / Vite / plain React)
 
-```ts
-themeOverrides: [
-  { path: '/', theme: 'dark' },
-  { path: '/legal/**', theme: 'light' },
-]
-```
+`BaseApp` does not depend on Next routing — use it directly as the top-level
+wrapper. This is exactly how the Wails desktop app mounts the framework.
 
-Use this for marketing landings that must always be dark, legal/compliance pages that must always be readable, or print views that must always be light — without locking the whole app.
+```tsx
+import { BaseApp } from '@djangocfg/layouts';
 
-For a local, scoped override (a single section that needs different CSS vars without touching the global theme), use `<ForceTheme>` from `@djangocfg/ui-nextjs/theme` instead.
+export function App() {
+  return <BaseApp project="desktop" theme={{ defaultTheme: 'dark' }}>{routes}</BaseApp>;
+}
+```
 
-## Full config surface
+## Config surface
 
 ```ts
-interface AppLayoutProps {
-  layouts?: {
-    public?: { component; enabledPath? };
-    private?: { component; enabledPath? };
-    admin?: { component; enabledPath? };
-    noLayoutPaths?: string | string[];
-    authPath?: string;                 // default '/auth' — always fullscreen
-    publicChrome?: AppLayoutPublicChrome; // navbar/footer defaults
-    themeOverrides?: ThemeOverrideRule[];
-  };
-  baseApp?: {
-    project?; theme?; auth?; analytics?; centrifugo?;
-    errorTracking?; errorBoundary?; swr?; pwaInstall?;
-    monitor?; debug?;
-  };
-  i18n?: I18nLayoutConfig;
+interface BaseAppProps {
   children: ReactNode;
+  project?: string;            // monitor.project + debug panel title default
+  theme?: ThemeConfig;         // defaultTheme, storageKey, style preset
+  auth?: AuthConfig | false;   // false = no AuthProvider (fully public app)
+  analytics?: AnalyticsConfig; // Google Analytics
+  centrifugo?: CentrifugoConfig;
+  errorTracking?: ErrorTrackingConfig;
+  errorBoundary?: ErrorBoundaryConfig; // enabled by default
+  swr?: SWRConfigOptions;
+  monitor?: MonitorConfig;
+  debug?: DebugConfig;         // debug panel (auto in dev / ?debug=1 in prod)
+  i18n?: I18nLayoutConfig;     // locale + routing for the link bridge
 }
 ```
 
-Top-level shortcuts (`theme`, `auth`, `analytics`, `publicLayout`, …) mirror the nested fields and are merged — nested wins.
+## Per-route forced theme (optional)
+
+To force a theme on a subtree (e.g. an always-dark marketing landing) without
+locking the whole app, wrap that route-group's layout with `<ThemeOverride>` /
+`<ForceTheme>` (re-exported here from `@djangocfg/ui-core/theme`). Because shell
+selection is now per route-group, the override lives right where the route does.
 
 ## Related
 
-- `BaseApp` — the provider stack. Exported separately if you need it without the layout router.
-- `ForceTheme` / `ThemeOverride` (`@djangocfg/ui-nextjs/theme`) — theme primitives used by `themeOverrides`.
-- `ErrorLayout` (`@djangocfg/layouts/components`) — universal error page for `error.tsx` / `not-found.tsx`.
+- `PrivateLayout` / `PublicLayout` — the per-section shells (see their READMEs).
+- `ErrorLayout` (`@djangocfg/layouts/components`) — universal error page for
+  `error.tsx` / `not-found.tsx`.
+- `ForceTheme` / `ThemeOverride` (`@djangocfg/ui-core/theme`) — theme primitives.

package/src/layouts/AppLayout/index.ts

@@ -1,25 +1,18 @@
 /**
- * AppLayout exports
+ * Provider stack exports.
+ *
+ * `BaseApp` is the canonical, framework-agnostic provider wrapper (theme, auth,
+ * i18n, monitor, error tracking…). Mount it ONCE at the app root. In Next.js
+ * apps, per-route shells are chosen by native route-group `layout.tsx` files
+ * (each imports `PrivateLayout` / `PublicLayout` and passes its own config) —
+ * there is no runtime layout-router component here anymore.
  */
 
-export { AppLayout } from './AppLayout';
-export type {
-  AppLayoutProps,
-  AppLayoutLayoutsConfig,
-  AppLayoutBaseAppConfig,
-  AppLayoutLayoutComponentProps,
-  AppLayoutPublicChrome,
-  LayoutMode,
-  I18nLayoutConfig,
-  PublicMainTopSpacing,
-  PublicMainBottomSpacing,
-} from './AppLayout';
-
-export { mergeAppLayoutPublicChrome } from './AppLayout';
-
 export { BaseApp } from './BaseApp';
 export type { BaseAppProps } from './BaseApp';
 
+export type { I18nLayoutConfig } from '../types';
+
 export {
   LayoutI18nProvider,
   useLayoutI18n,
@@ -27,8 +20,9 @@ export {
 } from './LayoutI18nProvider';
 export type { LayoutI18nProviderProps } from './LayoutI18nProvider';
 
-// Re-export theme-override primitives so consumers can import both the
-// AppLayout config surface and the rule/theme types from one place.
+// Re-export theme-override primitives so consumers can force a theme on a
+// subtree (e.g. an always-dark marketing route) without depending on ui-core
+// internals directly.
 export {
   ThemeOverride,
   resolveForcedTheme,
@@ -40,4 +34,3 @@ export type {
   ThemeOverrideProps,
   ForcedTheme,
 } from '@djangocfg/ui-core/theme';
-

package/src/layouts/PrivateLayout/PrivateLayout.tsx

@@ -13,7 +13,6 @@ import React, { ReactNode } from 'react';
 import { Preloader } from '@djangocfg/ui-core/components';
 import { SidebarInset, SidebarProvider } from '@djangocfg/ui-core/components';
 
-import type { AppLayoutPublicChrome } from '../AppLayout/AppLayout';
 import type { LayoutVisualConfig } from '../types';
 import { PrivateContent, PrivateSidebar } from './components';
 import { useAuthGuard } from './hooks';

package/src/layouts/PrivateLayout/README.md

@@ -17,6 +17,36 @@ The auth guard redirects to `header.authPath` when there's no session. Pass `req
 
 ---
 
+## Wiring (canonical)
+
+Mount it in the **route-group `layout.tsx`** that owns the authenticated section
+— a thin config wrapper. Providers (`BaseApp`) live once at the app root; this
+file just chooses the private shell and feeds it sidebar/header config:
+
+```tsx
+// app/[locale]/(pages)/private/layout.tsx
+'use client';
+import { PrivateLayout } from '@djangocfg/layouts';
+import { usePathname } from '@djangocfg/nextjs/i18n/navigation';
+
+export default function PrivateRouteLayout({ children }) {
+  const pathname = usePathname();
+  return (
+    <PrivateLayout sidebar={sidebar} header={header} pathname={pathname}>
+      {children}
+    </PrivateLayout>
+  );
+}
+```
+
+**Admin** is the same component with a different `sidebar` — there is no separate
+`AdminLayout`. Put it in `app/.../admin/layout.tsx` with an admin menu config.
+
+See the demo app (`apps/demo/app/_layouts/PrivateLayout.tsx`) for a complete
+thin-wrapper reference, and the **BaseApp README** for the provider root.
+
+---
+
 ## Visual variants
 
 `boxed` (default) — `<SidebarInset>` becomes a rounded card; the wrapper paints `bg-sidebar` so the brand colour bleeds to the viewport edges. Mobile (<md) degrades to full-bleed automatically.

package/src/layouts/PrivateLayout/components/PrivateContent.tsx

@@ -1,6 +1,6 @@
 /**
  * Private layout main column — on narrow viewports a fixed menu FAB (`SidebarTrigger`) + scrollable area.
- * On viewports below `md`, the desktop sidebar is off-canvas; the trigger opens the `Drawer` from ui-nextjs sidebar.
+ * On viewports below `md`, the desktop sidebar is off-canvas; the trigger opens the `Drawer` from the ui-core sidebar.
  */
 
 'use client';

package/src/layouts/PrivateLayout/hooks/useAuthGuard.ts

@@ -33,17 +33,26 @@ export function useAuthGuard({
   const router = useRouter();
   const [isRedirecting, setIsRedirecting] = useState(false);
 
+  // Auth state lives in the browser (storage), so the server always renders
+  // unauthenticated → the preloader. Keep the first client render identical to
+  // the server (preloader) until mounted, then switch to the real auth result.
+  // Without this, the SSR preloader vs the hydrated shell is a hydration
+  // mismatch (logged as "Invalid HTML tag nesting" / regenerated tree).
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+
   useEffect(() => {
-    if (!requireAuth) return;
+    if (!mounted || !requireAuth) return;
     if (!authLoading && !isAuthenticated && !isRedirecting) {
       const currentUrl = window.location.pathname + window.location.search;
       saveRedirectUrl(currentUrl);
       setIsRedirecting(true);
       router.push(authPath);
     }
-  }, [requireAuth, isAuthenticated, authLoading, isRedirecting, router, saveRedirectUrl, authPath]);
+  }, [mounted, requireAuth, isAuthenticated, authLoading, isRedirecting, router, saveRedirectUrl, authPath]);
 
-  const isLoading = requireAuth && (authLoading || isRedirecting || !isAuthenticated);
+  const isLoading =
+    !mounted || (requireAuth && (authLoading || isRedirecting || !isAuthenticated));
   const loadingText = isRedirecting ? 'Redirecting to login...' : 'Authenticating...';
 
   return {

package/src/layouts/PrivateLayout/types.ts

@@ -7,7 +7,6 @@
 import type { ReactNode } from 'react';
 import type { LucideIcon } from 'lucide-react';
 
-import type { AppLayoutPublicChrome } from '../AppLayout/AppLayout';
 import type { SettingsDialogProps } from '../SettingsLayout/types';
 import type { LayoutVisualConfig } from '../types';
 import type { UserMenuConfig } from '../types';
@@ -224,8 +223,6 @@ export interface PrivateLayoutProps {
    * embeds where there's no real session. Default `true` (guard on).
    */
   requireAuth?: boolean;
-  /** Reserved for `AppLayout` passthrough (`publicChrome`); unused in this layout. */
-  publicChrome?: AppLayoutPublicChrome;
   /**
    * Mount the global SettingsDialog (Claude-style master/detail settings modal,
    * hash-URL driven, openable via `useSettingsDialog()`). Pass a config object