@djangocfg/layouts 2.1.426 → 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.426",
+  "version": "2.1.428",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -89,13 +89,12 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.426",
-    "@djangocfg/centrifugo": "^2.1.426",
-    "@djangocfg/debuger": "^2.1.426",
-    "@djangocfg/i18n": "^2.1.426",
-    "@djangocfg/monitor": "^2.1.426",
-    "@djangocfg/ui-core": "^2.1.426",
-    "@djangocfg/ui-nextjs": "^2.1.426",
+    "@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",
@@ -126,15 +125,14 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.426",
-    "@djangocfg/centrifugo": "^2.1.426",
-    "@djangocfg/debuger": "^2.1.426",
-    "@djangocfg/i18n": "^2.1.426",
-    "@djangocfg/monitor": "^2.1.426",
-    "@djangocfg/typescript-config": "^2.1.426",
-    "@djangocfg/ui-core": "^2.1.426",
-    "@djangocfg/ui-nextjs": "^2.1.426",
-    "@djangocfg/ui-tools": "^2.1.426",
+    "@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)
@@ -54,7 +61,6 @@ import { ErrorBoundary } from '../../components/errors/ErrorBoundary';
 import { ErrorTrackingProvider } from '../../components/errors/ErrorsTracker';
 import { AnalyticsProvider } from '../../snippets/Analytics';
 import { AuthDialog } from '../../snippets/AuthDialog';
-import { A2HSHint, PWAPageResumeManager, PwaProvider } from '@djangocfg/ui-nextjs/pwa';
 
 import type { BaseLayoutProps } from '../types/layout.types';
 import { LayoutI18nProvider } from './LayoutI18nProvider';
@@ -71,8 +77,7 @@ export type BaseAppProps = BaseLayoutProps;
  * BaseApp - Core providers wrapper for any React/Next.js app
  *
  * Includes: ThemeProvider, TooltipProvider, SWRConfig, AuthProvider, AnalyticsProvider,
- * CentrifugoProvider, PwaProvider, ErrorTrackingProvider,
- * ErrorBoundary (optional)
+ * CentrifugoProvider, ErrorTrackingProvider, ErrorBoundary (optional)
  * Also renders global Toaster and PageProgress components
  */
 export function BaseApp({
@@ -85,7 +90,6 @@ export function BaseApp({
   errorTracking,
   errorBoundary,
   swr,
-  pwaInstall,
   monitor,
   debug,
   i18n,
@@ -97,10 +101,6 @@ export function BaseApp({
   // ErrorBoundary is enabled by default
   const enableErrorBoundary = errorBoundary?.enabled !== false;
 
-  // Check if PWA Install is enabled
-  const pwaInstallEnabled = pwaInstall?.enabled === true;
-  const showInstallHint = pwaInstallEnabled && pwaInstall?.showInstallHint !== false;
-
   // Centrifugo configuration
   const centrifugoUrl = centrifugo?.url || process.env.NEXT_PUBLIC_CENTRIFUGO_URL;
   const centrifugoEnabled = centrifugo?.enabled !== false;
@@ -150,51 +150,35 @@ export function BaseApp({
                   return result.data.token;
                 }}
               >
-                <PwaProvider enabled={pwaInstallEnabled}>
-                  <ErrorTrackingProvider
-                    validation={errorTracking?.validation}
-                    cors={errorTracking?.cors}
-                    network={errorTracking?.network}
-                    onError={errorTracking?.onError}
-                    onMonitorCapture={(d) => FrontendMonitor.capture(errorDetailToMonitorEvent(d))}
-                  >
-                    <MonitorProvider {...monitorConfig} />
-                    <LayoutI18nProvider value={i18n}>
-                      {i18n?.routing ? (
-                        <NextIntlLinkBridge routing={i18n.routing}>{children}</NextIntlLinkBridge>
-                      ) : (
-                        children
-                      )}
-                    </LayoutI18nProvider>
-                    <NextTopLoader
-                      color="var(--primary)"
-                      height={3}
-                      showSpinner={false}
-                      shadow="0 0 10px var(--primary), 0 0 5px var(--primary)"
-                    />
-
-                    {/* PWA Install Hint */}
-                    {showInstallHint && (
-                      <A2HSHint
-                        resetAfterDays={pwaInstall?.resetAfterDays}
-                        delayMs={pwaInstall?.delayMs}
-                        logo={pwaInstall?.logo}
-                      />
-                    )}
-
-                    {/* PWA Page Resume Manager */}
-                    {pwaInstallEnabled && pwaInstall?.resumeLastPage && (
-                      <PWAPageResumeManager enabled={true} />
+                <ErrorTrackingProvider
+                  validation={errorTracking?.validation}
+                  cors={errorTracking?.cors}
+                  network={errorTracking?.network}
+                  onError={errorTracking?.onError}
+                  onMonitorCapture={(d) => FrontendMonitor.capture(errorDetailToMonitorEvent(d))}
+                >
+                  <MonitorProvider {...monitorConfig} />
+                  <LayoutI18nProvider value={i18n}>
+                    {i18n?.routing ? (
+                      <NextIntlLinkBridge routing={i18n.routing}>{children}</NextIntlLinkBridge>
+                    ) : (
+                      children
                     )}
-
-                    {/* Auth Dialog - only when auth is enabled */}
-                    {authEnabled && <AuthDialog authPath={authConfig?.routes?.auth} />}
-
-                    {/* Debug Panel — auto in dev, ?debug=1 in prod, disable with debug={{ enabled: false }} */}
-                    {/* eslint-disable-next-line @typescript-eslint/no-explicit-any */}
-                    <DebugButton enabled={debugEnabled} {...(debugProps as any)} />
-                  </ErrorTrackingProvider>
-                </PwaProvider>
+                  </LayoutI18nProvider>
+                  <NextTopLoader
+                    color="var(--primary)"
+                    height={3}
+                    showSpinner={false}
+                    shadow="0 0 10px var(--primary), 0 0 5px var(--primary)"
+                  />
+
+                  {/* Auth Dialog - only when auth is enabled */}
+                  {authEnabled && <AuthDialog authPath={authConfig?.routes?.auth} />}
+
+                  {/* Debug Panel — auto in dev, ?debug=1 in prod, disable with debug={{ enabled: false }} */}
+                  {/* eslint-disable-next-line @typescript-eslint/no-explicit-any */}
+                  <DebugButton enabled={debugEnabled} {...(debugProps as any)} />
+                </ErrorTrackingProvider>
               </CentrifugoProvider>
             </AnalyticsProvider>
           </AuthProvider>

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.