@djangocfg/layouts 1.2.6 → 1.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "1.2.6",
+  "version": "1.2.7",
   "description": "Layout system and components for Unrealon applications",
   "author": {
     "name": "DjangoCFG",
@@ -53,9 +53,9 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^1.2.6",
-    "@djangocfg/og-image": "^1.2.6",
-    "@djangocfg/ui": "^1.2.6",
+    "@djangocfg/api": "^1.2.7",
+    "@djangocfg/og-image": "^1.2.7",
+    "@djangocfg/ui": "^1.2.7",
     "@hookform/resolvers": "^5.2.0",
     "consola": "^3.4.2",
     "lucide-react": "^0.468.0",
@@ -76,7 +76,7 @@
     "vidstack": "0.6.15"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^1.2.6",
+    "@djangocfg/typescript-config": "^1.2.7",
     "@types/node": "^24.7.2",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.1",

package/src/layouts/AppLayout/AppLayout.tsx

@@ -6,12 +6,19 @@
  * - Applies correct layout automatically
  * - Manages all state through context
  * - Zero prop drilling
+ * - Optional Django CFG admin mode with iframe integration
  *
  * Usage in _app.tsx:
  * ```tsx
+ * // Standard usage
  * <AppLayout config={appLayoutConfig}>
  *   <Component {...pageProps} />
  * </AppLayout>
+ *
+ * // Django CFG admin mode (with iframe integration)
+ * <AppLayout config={appLayoutConfig} isCfgAdmin={true}>
+ *   <Component {...pageProps} />
+ * </AppLayout>
  * ```
  */
 
@@ -25,6 +32,7 @@ import { Seo, PageProgress, ErrorBoundary } from './components';
 import { PublicLayout } from './layouts/PublicLayout';
 import { PrivateLayout } from './layouts/PrivateLayout';
 import { AuthLayout } from './layouts/AuthLayout';
+import { CfgLayout } from './layouts/CfgLayout';
 import { determineLayoutMode, getRedirectUrl } from './utils';
 import { useAuth } from '../../auth';
 import type { AppLayoutConfig } from './types';
@@ -41,9 +49,13 @@ export interface AppLayoutProps {
   /**
    * Force a specific layout regardless of route
    * Overrides automatic layout detection
+   *
    * @example forceLayout="public" - always use PublicLayout
+   * @example forceLayout="private" - always use PrivateLayout
+   * @example forceLayout="auth" - always use AuthLayout
+   * @example forceLayout="admin" - Django CFG admin mode with iframe integration
    */
-  forceLayout?: 'public' | 'private' | 'auth';
+  forceLayout?: 'public' | 'private' | 'auth' | 'admin';
   /**
    * Font family to apply globally
    * Accepts Next.js font object or CSS font-family string
@@ -73,7 +85,7 @@ function LayoutRouter({
 }: {
   children: ReactNode;
   disableLayout?: boolean;
-  forceLayout?: 'public' | 'private' | 'auth';
+  forceLayout?: 'public' | 'private' | 'auth' | 'admin';
   config: AppLayoutConfig;
 }) {
   const router = useRouter();
@@ -85,8 +97,9 @@ function LayoutRouter({
     setIsMounted(true);
   }, []);
 
+  const isAdminMode = forceLayout === 'admin';
   // If layout is disabled, render children directly (providers still active!)
-  if (disableLayout) {
+  if (disableLayout || isAdminMode) {
     return <>{children}</>;
   }
 
@@ -122,10 +135,11 @@ function LayoutRouter({
   }
 
   // Determine layout mode for non-private routes
-  const getLayoutMode = (): 'public' | 'auth' => {
+  const getLayoutMode = (): 'public' | 'auth' | 'admin' => {
     if (forceLayout === 'auth') return 'auth';
     if (forceLayout === 'public') return 'public';
     if (isAuthRoute) return 'auth';
+    if (isAdminMode) return 'admin';
     return 'public';
   };
 
@@ -133,6 +147,9 @@ function LayoutRouter({
 
   // Render appropriate layout
   switch (layoutMode) {
+    case 'admin':
+      return <CfgLayout>{children}</CfgLayout>;
+      break;
     // Public routes: render immediately (SSR enabled)
     case 'public':
       return <PublicLayout>{children}</PublicLayout>;
@@ -192,6 +209,9 @@ export function AppLayout({ children, config, disableLayout = false, forceLayout
   const supportEmail = config.errors?.supportEmail;
   const onError = config.errors?.onError;
 
+  // Determine if admin mode is enabled (Django CFG iframe integration)
+  const isAdminMode = forceLayout === 'admin';
+
   const content = (
     <>
       {/* Global Font Styles */}
@@ -202,29 +222,33 @@ export function AppLayout({ children, config, disableLayout = false, forceLayout
       )}
 
       <CoreProviders config={config}>
-        <AppContextProvider config={config} showPackageVersions={showPackageVersions}>
-          {/* SEO Meta Tags */}
-          <Seo
-            pageConfig={{
-              title: config.app.name,
-              description: config.app.description,
-              ogImage: {
+        {/* CfgLayout must be inside CoreProviders to access AuthProvider */}
+        {/* Only enable ParentSync when in admin mode */}
+        <CfgLayout enableParentSync={isAdminMode}>
+          <AppContextProvider config={config} showPackageVersions={showPackageVersions}>
+            {/* SEO Meta Tags */}
+            <Seo
+              pageConfig={{
                 title: config.app.name,
-                subtitle: config.app.description,
-              },
-            }}
-            icons={config.app.icons}
-            siteUrl={config.app.siteUrl}
-          />
-
-          {/* Loading Progress Bar */}
-          <PageProgress />
-
-          {/* Smart Layout Router */}
-          <LayoutRouter disableLayout={disableLayout} forceLayout={forceLayout} config={config}>
-            {children}
-          </LayoutRouter>
-        </AppContextProvider>
+                description: config.app.description,
+                ogImage: {
+                  title: config.app.name,
+                  subtitle: config.app.description,
+                },
+              }}
+              icons={config.app.icons}
+              siteUrl={config.app.siteUrl}
+            />
+
+            {/* Loading Progress Bar */}
+            <PageProgress />
+
+            {/* Smart Layout Router */}
+            <LayoutRouter disableLayout={disableLayout} forceLayout={forceLayout} config={config}>
+              {children}
+            </LayoutRouter>
+          </AppContextProvider>
+        </CfgLayout>
       </CoreProviders>
     </>
   );

package/src/layouts/AppLayout/components/PackageVersions/packageVersions.config.ts

@@ -16,36 +16,36 @@ export interface PackageInfo {
 /**
  * Package versions registry
  * Auto-synced from package.json files
- * Last updated: 2025-10-27T16:32:06.128Z
+ * Last updated: 2025-10-28T04:15:24.707Z
  */
 const PACKAGE_VERSIONS: PackageInfo[] = [
   {
     "name": "@djangocfg/ui",
-    "version": "1.2.6"
+    "version": "1.2.7"
   },
   {
     "name": "@djangocfg/api",
-    "version": "1.2.6"
+    "version": "1.2.7"
   },
   {
     "name": "@djangocfg/layouts",
-    "version": "1.2.6"
+    "version": "1.2.7"
   },
   {
     "name": "@djangocfg/markdown",
-    "version": "1.2.6"
+    "version": "1.2.7"
   },
   {
     "name": "@djangocfg/og-image",
-    "version": "1.2.6"
+    "version": "1.2.7"
   },
   {
     "name": "@djangocfg/eslint-config",
-    "version": "1.2.6"
+    "version": "1.2.7"
   },
   {
     "name": "@djangocfg/typescript-config",
-    "version": "1.2.6"
+    "version": "1.2.7"
   }
 ];
 

package/src/layouts/AppLayout/index.ts

@@ -29,3 +29,15 @@ export { useLayoutMode, useNavigation } from './hooks';
 export { PublicLayout } from './layouts/PublicLayout';
 export { PrivateLayout } from './layouts/PrivateLayout';
 export { AuthLayout } from './layouts/AuthLayout';
+
+// CfgLayout - Django CFG iframe integration
+export { CfgLayout } from './layouts/CfgLayout';
+export { useCfgApp, useApp } from './layouts/CfgLayout';
+export { ParentSync, AuthStatusSync } from './layouts/CfgLayout';
+export type {
+  CfgLayoutConfig,
+  UseCfgAppReturn,
+  UseCfgAppOptions,
+  UseAppReturn,
+  UseAppOptions
+} from './layouts/CfgLayout';

package/src/layouts/AppLayout/layouts/CfgLayout/CfgLayout.tsx

@@ -0,0 +1,104 @@
+// ============================================================================
+// CfgLayout - Django CFG Layout with iframe Integration
+// ============================================================================
+// Universal layout component that handles:
+// - iframe embedding detection
+// - Parent ↔ iframe communication (postMessage)
+// - Theme synchronization from Django Unfold
+// - Auth token passing from parent window (automatically sets in API client)
+// - Auth status reporting to parent window
+// - Automatic layout disable in iframe mode
+//
+// This is a lightweight wrapper that can be used with any layout system
+// (AppLayout, custom layouts, etc.)
+
+'use client';
+
+import React, { ReactNode } from 'react';
+import { ParentSync } from './components';
+import { useCfgApp } from './hooks';
+import type { CfgLayoutConfig } from './types';
+import { api } from '@djangocfg/api';
+
+export interface CfgLayoutProps {
+  children: ReactNode;
+  config?: CfgLayoutConfig;
+  /**
+   * Whether to render ParentSync component
+   * Set to false if you want to handle sync manually
+   * @default true
+   */
+  enableParentSync?: boolean;
+}
+
+/**
+ * CfgLayout - Universal Layout Component for Django CFG
+ *
+ * Provides iframe integration features:
+ * - Auto-detects iframe embedding
+ * - Syncs theme from parent window (Django Unfold)
+ * - Receives auth tokens from parent window and automatically sets them in API client
+ * - Sends auth status to parent window
+ * - Provides useApp hook data via context
+ *
+ * Usage:
+ * ```tsx
+ * // Wrap your app in _app.tsx - no config needed!
+ * <CfgLayout>
+ *   <AppLayout config={appLayoutConfig}>
+ *     <Component {...pageProps} />
+ *   </AppLayout>
+ * </CfgLayout>
+ * ```
+ *
+ * Or with custom auth handler:
+ * ```tsx
+ * <CfgLayout config={{
+ *   onAuthTokenReceived: (authToken, refreshToken) => {
+ *     // Custom logic before/after setting tokens
+ *     console.log('Tokens received');
+ *   }
+ * }}>
+ *   <AppLayout config={appLayoutConfig}>
+ *     <Component {...pageProps} />
+ *   </AppLayout>
+ * </CfgLayout>
+ * ```
+ *
+ * Use useCfgApp hook directly:
+ * ```tsx
+ * import { useCfgApp } from '@djangocfg/layouts/CfgLayout';
+ *
+ * function MyComponent() {
+ *   const { isEmbedded, disableLayout, parentTheme } = useCfgApp();
+ *   // ...
+ * }
+ * ```
+ */
+export function CfgLayout({
+  children,
+  config,
+  enableParentSync = true
+}: CfgLayoutProps) {
+  // useCfgApp hook is called here to initialize iframe communication
+  // Automatically sets tokens in API client when received from parent
+  useCfgApp({
+    onAuthTokenReceived: (authToken, refreshToken) => {
+      // Always set tokens in API client
+      api.setToken(authToken, refreshToken);
+
+      // Call custom handler if provided
+      if (config?.onAuthTokenReceived) {
+        config.onAuthTokenReceived(authToken, refreshToken);
+      }
+    }
+  });
+
+  return (
+    <>
+      {/* ParentSync handles theme sync and auth status reporting */}
+      {enableParentSync && <ParentSync />}
+      {children}
+    </>
+  );
+}

package/src/layouts/AppLayout/layouts/CfgLayout/README.md

@@ -0,0 +1,389 @@
+# CfgLayout - Django CFG Layout with iframe Integration
+
+Universal layout component for Django CFG applications that handles iframe embedding, theme synchronization, and authentication communication.
+
+**Note:** CfgLayout is now integrated into AppLayout. For most use cases, use `AppLayout` with `isCfgAdmin={true}` instead of using CfgLayout directly.
+
+## Features
+
+- 🖼️ **iframe Embedding Detection** - Automatically detects when running inside an iframe
+- 🎨 **Theme Synchronization** - Syncs theme from Django Unfold parent window
+- 🔐 **Auth Token Passing** - Receives JWT tokens from parent window via postMessage
+- 📤 **Auth Status Reporting** - Sends authentication status to parent window
+- 📏 **Auto Resize** - Automatically adjusts iframe height based on content
+- 🔒 **Secure Communication** - Origin validation for postMessage security
+- ⚡ **Lightweight** - Minimal overhead, works with any layout system
+
+## Installation
+
+Already included in `@djangocfg/layouts` package.
+
+## Recommended Usage (via AppLayout)
+
+### Simple - Enable Django CFG Admin Mode
+
+```tsx
+// apps/admin/src/pages/_app.tsx
+import { AppLayout } from '@djangocfg/layouts';
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <AppProviders>
+      <AppLayout config={appLayoutConfig} isCfgAdmin={true}>
+        <Component {...pageProps} />
+      </AppLayout>
+    </AppProviders>
+  );
+}
+```
+
+**That's it!** Setting `isCfgAdmin={true}` automatically:
+- Wraps your app with CfgLayout
+- Sets up iframe communication
+- Handles auth token passing
+- Syncs theme from parent window
+
+## Direct Usage (Advanced)
+
+If you need more control, you can use CfgLayout directly:
+
+### 1. Wrap your app with CfgLayout (Zero Config!)
+
+```tsx
+// apps/admin/src/pages/_app.tsx
+import { CfgLayout, AppLayout } from '@djangocfg/layouts';
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <CfgLayout>
+      <AppLayout config={appLayoutConfig}>
+        <Component {...pageProps} />
+      </AppLayout>
+    </CfgLayout>
+  );
+}
+```
+
+**That's it!** Auth tokens are automatically set in the API client when received from parent window.
+
+### 2. With custom auth handler (optional)
+
+```tsx
+// Only if you need additional logic when tokens are received
+<CfgLayout
+  config={{
+    onAuthTokenReceived: (authToken, refreshToken) => {
+      // Tokens are already set in API client automatically
+      console.log('Tokens received!');
+      // Your custom logic here
+    }
+  }}
+>
+  <AppLayout config={appLayoutConfig}>
+    <Component {...pageProps} />
+  </AppLayout>
+</CfgLayout>
+```
+
+## Hook Usage
+
+### Use useCfgApp hook to access embedding state
+
+```tsx
+import { useCfgApp } from '@djangocfg/layouts';
+
+function MyComponent() {
+  const { isEmbedded, disableLayout, parentTheme } = useCfgApp();
+
+  return (
+    <div>
+      {isEmbedded && <p>Running in iframe mode</p>}
+      <p>Current theme from parent: {parentTheme}</p>
+    </div>
+  );
+}
+```
+
+### Use with AppLayout's disableLayout prop
+
+```tsx
+import { AppLayout, useCfgApp } from '@djangocfg/layouts';
+
+function MyApp({ Component, pageProps }) {
+  const { disableLayout } = useCfgApp();
+
+  return (
+    <AppLayout
+      config={config}
+      disableLayout={disableLayout}
+      isCfgAdmin={true}
+    >
+      <Component {...pageProps} />
+    </AppLayout>
+  );
+}
+```
+
+## API Reference
+
+### AppLayout with isCfgAdmin
+
+**Recommended approach:**
+
+```typescript
+<AppLayout
+  config={appLayoutConfig}
+  isCfgAdmin={true}  // ← Enables Django CFG admin mode
+  fontFamily={manrope.style.fontFamily}
+>
+  {children}
+</AppLayout>
+```
+
+### CfgLayout Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | Required | Your app content |
+| `config` | `CfgLayoutConfig` | `{}` | Configuration object |
+| `enableParentSync` | `boolean` | `true` | Enable automatic theme/auth sync |
+
+### CfgLayoutConfig
+
+**All options are optional!** CfgLayout works with zero configuration.
+
+```typescript
+interface CfgLayoutConfig {
+  // Optional: Called when auth tokens are received from parent
+  // Note: Tokens are ALWAYS automatically set in API client
+  // Use this only if you need additional custom logic
+  onAuthTokenReceived?: (authToken, refreshToken?) => void;
+
+  // Enable/disable theme sync (default: true)
+  enableThemeSync?: boolean;
+
+  // Enable/disable auth status sync (default: true)
+  enableAuthStatusSync?: boolean;
+}
+```
+
+### useCfgApp Hook
+
+```typescript
+const {
+  isEmbedded,        // true if running in iframe
+  isStandalone,      // true if running as PWA
+  disableLayout,     // true if layout should be disabled
+  referrer,          // parent URL if embedded
+  isMounted,         // true after client-side mount
+  parentTheme,       // 'light' | 'dark' | null
+  parentThemeMode,   // 'auto' | 'light' | 'dark' | null
+} = useCfgApp({
+  onAuthTokenReceived: (authToken, refreshToken) => {
+    // Handle tokens (optional - tokens are auto-set in API client)
+  }
+});
+```
+
+**Note:** `useApp` is also exported as an alias for backward compatibility.
+
+## postMessage Communication Protocol
+
+### Parent → iframe
+
+| Message Type | Data | Description |
+|-------------|------|-------------|
+| `parent-theme` | `{ theme: 'dark'\|'light', themeMode: 'auto'\|'dark'\|'light' }` | Theme from Django Unfold |
+| `parent-auth` | `{ authToken, refreshToken }` | JWT authentication tokens |
+
+### iframe → Parent
+
+| Message Type | Data | Description |
+|-------------|------|-------------|
+| `iframe-ready` | `{ url, referrer }` | iframe loaded successfully |
+| `iframe-auth-status` | `{ isAuthenticated, isLoading, hasUser }` | Auth status update |
+| `iframe-resize` | `{ height }` | Content height changed |
+| `iframe-navigation` | `{ path, route }` | User navigated to new page |
+
+## Advanced Usage
+
+### Manual Theme Sync
+
+```tsx
+import { useCfgApp } from '@djangocfg/layouts';
+import { useThemeContext } from '@djangocfg/ui';
+
+function MyThemeSync() {
+  const { isEmbedded, parentTheme } = useCfgApp();
+  const { setTheme } = useThemeContext();
+
+  useEffect(() => {
+    if (isEmbedded && parentTheme) {
+      setTheme(parentTheme);
+    }
+  }, [isEmbedded, parentTheme, setTheme]);
+
+  return null;
+}
+```
+
+### Disable Auto Sync
+
+```tsx
+<CfgLayout enableParentSync={false}>
+  {/* Handle sync manually */}
+</CfgLayout>
+```
+
+### URL Override
+
+Force iframe mode via URL:
+```
+https://example.com/admin/?embed=true
+```
+
+Disable iframe mode:
+```
+https://example.com/admin/?embed=false
+```
+
+## Integration with Django
+
+See Django template at: `src/django_cfg/templates/admin/index.html`
+
+The Django template uses an iframe to load the Next.js app:
+```html
+<iframe
+  id="nextjs-dashboard-iframe"
+  src="{% nextjs_admin_url 'private' %}"
+  title="Next.js Dashboard"
+></iframe>
+```
+
+## Components
+
+### ParentSync
+
+Handles bidirectional communication with parent window. Automatically included when using `isCfgAdmin={true}`.
+
+```tsx
+import { ParentSync } from '@djangocfg/layouts';
+
+// Usually placed inside AppLayout (automatic with isCfgAdmin={true})
+<AuthProvider>
+  <ThemeProvider>
+    <ParentSync />
+    {children}
+  </ThemeProvider>
+</AuthProvider>
+```
+
+## Security Considerations
+
+- All postMessage communications validate origins
+- Tokens are only accepted from expected parent origins
+- iframe uses sandbox attribute with specific permissions
+- localStorage is used for token persistence (XSS protection needed)
+
+## Migration from Old API
+
+**Old approach:**
+```tsx
+import { AppLayout, CfgLayout, useCfgApp } from '@djangocfg/layouts';
+
+function AppLayoutWrapper() {
+  const { disableLayout, isEmbedded } = useCfgApp();
+  return (
+    <AppLayout disableLayout={disableLayout}>
+      {children}
+    </AppLayout>
+  );
+}
+
+export default function App() {
+  return (
+    <CfgLayout>
+      <AppLayoutWrapper>
+        {children}
+      </AppLayoutWrapper>
+    </CfgLayout>
+  );
+}
+```
+
+**New approach:**
+```tsx
+import { AppLayout } from '@djangocfg/layouts';
+
+export default function App({ Component, pageProps }) {
+  return (
+    <AppLayout config={appLayoutConfig} isCfgAdmin={true}>
+      <Component {...pageProps} />
+    </AppLayout>
+  );
+}
+```
+
+## Troubleshooting
+
+### Theme not syncing
+- Check parent window is sending `parent-theme` messages
+- Verify ThemeProvider is in component tree
+- Enable debug logging in `useApp.ts`
+
+### Auth tokens not working
+- Tokens are automatically set in API client
+- Check parent window sends `parent-auth` message
+- Inspect localStorage for tokens: `auth_token`, `refresh_token`
+
+### Layout not hiding in iframe
+- Use `isCfgAdmin={true}` on AppLayout (recommended)
+- Or manually pass `disableLayout` from `useCfgApp()` hook
+- Try URL override: `?embed=true`
+
+### Static export build fails
+- Make sure ParentSync is wrapped with SSR protection (already handled)
+- Check that `useAuth()` is only called on client-side
+- Verify `'use client'` directive is present in components
+
+## Examples
+
+**Simple Django CFG Admin:**
+```tsx
+<AppLayout config={config} isCfgAdmin={true}>
+  <Component {...pageProps} />
+</AppLayout>
+```
+
+**With custom font:**
+```tsx
+<AppLayout
+  config={config}
+  isCfgAdmin={true}
+  fontFamily={manrope.style.fontFamily}
+>
+  <Component {...pageProps} />
+</AppLayout>
+```
+
+**With custom auth logic:**
+```tsx
+<CfgLayout
+  config={{
+    onAuthTokenReceived: (token, refresh) => {
+      console.log('Tokens received from parent');
+      // Additional custom logic
+    }
+  }}
+>
+  <AppLayout config={config}>
+    <Component {...pageProps} />
+  </AppLayout>
+</CfgLayout>
+```
+
+## Related Files
+
+- Django Template: `src/django_cfg/templates/admin/index.html`
+- Django Views: `src/django_cfg/apps/frontend/views.py`
+- Example App: `src/@frontend/apps/admin/src/pages/_app.tsx`

package/src/layouts/AppLayout/layouts/CfgLayout/components/ParentSync.tsx

@@ -0,0 +1,149 @@
+// ============================================================================
+// Parent Sync Component
+// ============================================================================
+// Handles all synchronization between iframe and parent window:
+// - Theme sync (parent → iframe)
+// - Auth status sync (iframe → parent)
+// Must be used inside AuthProvider and ThemeProvider contexts
+
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useAuth } from '../../../../../auth';
+import { useThemeContext } from '@djangocfg/ui';
+import { useCfgApp } from '../hooks/useApp';
+
+/**
+ * ParentSync Component
+ *
+ * Handles bidirectional communication with parent window when embedded:
+ * 1. Receives theme updates from parent (Django Unfold) and applies to ThemeProvider
+ * 2. Sends auth status to parent when authentication state changes
+ *
+ * Usage:
+ * - Place inside AppLayout (after AuthProvider and ThemeProvider)
+ * - Automatically handles all iframe ↔ parent communication
+ *
+ * Note: Safe for static export - only runs on client-side after hydration
+ */
+export function ParentSync() {
+  const [isClient, setIsClient] = useState(false);
+
+  // Wait for client-side hydration to avoid SSR/static export errors
+  useEffect(() => {
+    setIsClient(true);
+  }, []);
+
+  // Early return during SSR/static export
+  if (!isClient) {
+    return null;
+  }
+
+  return <ParentSyncClient />;
+}
+
+/**
+ * Client-only component that uses auth context
+ * Separated to avoid SSR issues during static export
+ */
+function ParentSyncClient() {
+  const auth = useAuth();
+  const { setTheme } = useThemeContext();
+  const { isEmbedded, isMounted, parentTheme } = useCfgApp();
+
+  // 1. Sync theme from parent → iframe
+  useEffect(() => {
+    if (isEmbedded && parentTheme) {
+      // console.log('[ParentSync] 🎨 Syncing theme from parent:', parentTheme);
+      setTheme(parentTheme);
+    }
+  }, [isEmbedded, parentTheme, setTheme]);
+
+  // 2. Send auth status from iframe → parent
+  useEffect(() => {
+    // Only send if embedded and mounted
+    if (!isEmbedded || !isMounted) {
+      // console.log('[ParentSync] Skipping auth sync - not embedded or not mounted:', {
+      //   isEmbedded,
+      //   isMounted
+      // });
+      return;
+    }
+
+    const authData = {
+      isAuthenticated: auth.isAuthenticated,
+      isLoading: auth.isLoading,
+      hasUser: !!auth.user
+    };
+
+    // console.log('[ParentSync] 📤 Sending auth status to parent:', authData);
+
+    try {
+      window.parent.postMessage({
+        type: 'iframe-auth-status',
+        data: authData
+      }, '*');
+      // console.log('[ParentSync] ✅ Auth status sent successfully');
+    } catch (e) {
+      console.error('[ParentSync] ❌ Failed to send auth status:', e);
+    }
+  }, [auth.isAuthenticated, auth.isLoading, auth.user, isEmbedded, isMounted]);
+
+  // 3. Send iframe height changes to parent for auto-resize
+  useEffect(() => {
+    // Only send if embedded and mounted
+    if (!isEmbedded || !isMounted) {
+      return;
+    }
+
+    // Function to send height to parent
+    const sendHeight = () => {
+      const height = document.documentElement.scrollHeight;
+      // console.log('[ParentSync] 📏 Sending height to parent:', height);
+
+      try {
+        window.parent.postMessage({
+          type: 'iframe-resize',
+          data: { height }
+        }, '*');
+      } catch (e) {
+        console.error('[ParentSync] ❌ Failed to send height:', e);
+      }
+    };
+
+    // Send initial height
+    sendHeight();
+
+    // Watch for content height changes with ResizeObserver
+    const resizeObserver = new ResizeObserver(() => {
+      sendHeight();
+    });
+
+    // Observe body element for size changes
+    resizeObserver.observe(document.body);
+
+    // Also observe on route changes (for Next.js)
+    const handleRouteChange = () => {
+      // Delay to allow content to render
+      setTimeout(sendHeight, 100);
+    };
+
+    // Listen for Next.js router events if available
+    if (typeof window !== 'undefined') {
+      window.addEventListener('popstate', handleRouteChange);
+    }
+
+    return () => {
+      resizeObserver.disconnect();
+      if (typeof window !== 'undefined') {
+        window.removeEventListener('popstate', handleRouteChange);
+      }
+    };
+  }, [isEmbedded, isMounted]);
+
+  // This component doesn't render anything
+  return null;
+}
+
+// Export with old name for backward compatibility
+export { ParentSync as AuthStatusSync };

package/src/layouts/AppLayout/layouts/CfgLayout/components/index.ts

@@ -0,0 +1 @@
+export { ParentSync, AuthStatusSync } from './ParentSync';

package/src/layouts/AppLayout/layouts/CfgLayout/hooks/index.ts

@@ -0,0 +1,6 @@
+export { useCfgApp } from './useApp';
+export type { UseCfgAppReturn, UseCfgAppOptions } from './useApp';
+
+// Backward compatibility alias
+export { useCfgApp as useApp } from './useApp';
+export type { UseCfgAppReturn as UseAppReturn, UseCfgAppOptions as UseAppOptions } from './useApp';

package/src/layouts/AppLayout/layouts/CfgLayout/hooks/useApp.ts

@@ -0,0 +1,282 @@
+// ============================================================================
+// CfgApp Hook - Application State and Embedding Detection
+// ============================================================================
+
+'use client';
+
+import { useState, useEffect } from 'react';
+import { useRouter } from 'next/router';
+
+export interface UseCfgAppReturn {
+  /**
+   * Whether the app is embedded in an iframe
+   */
+  isEmbedded: boolean;
+
+  /**
+   * Whether the app is running in standalone mode (PWA)
+   */
+  isStandalone: boolean;
+
+  /**
+   * Whether to disable the layout (useful for iframes)
+   */
+  disableLayout: boolean;
+
+  /**
+   * The referrer URL if embedded
+   */
+  referrer: string | null;
+
+  /**
+   * Whether the app has been mounted on the client
+   */
+  isMounted: boolean;
+
+  /**
+   * The theme received from parent (if embedded)
+   */
+  parentTheme: 'light' | 'dark' | null;
+
+  /**
+   * The theme mode from parent ('dark', 'light', 'auto')
+   */
+  parentThemeMode: string | null;
+
+  /**
+   * Handler for setting auth token (used by parent window)
+   */
+  setToken?: (authToken: string, refreshToken?: string) => void;
+}
+
+export interface UseCfgAppOptions {
+  /**
+   * Handler for setting auth token when received from parent
+   */
+  onAuthTokenReceived?: (authToken: string, refreshToken?: string) => void;
+}
+
+/**
+ * Custom hook for detecting app embedding and providing app-level state
+ *
+ * Features:
+ * - Detects iframe embedding
+ * - Detects URL-based embedding (`?embed=true`)
+ * - Detects standalone PWA mode
+ * - Provides referrer information
+ * - Handles postMessage communication with parent window
+ * - Syncs theme from parent window
+ * - Receives auth tokens from parent window
+ * - SSR-safe (returns default values on server)
+ *
+ * Usage:
+ * ```tsx
+ * const { isEmbedded, disableLayout, referrer, parentTheme } = useCfgApp({
+ *   onAuthTokenReceived: (authToken, refreshToken) => {
+ *     api.setToken(authToken, refreshToken);
+ *   }
+ * });
+ *
+ * return (
+ *   <AppLayout disableLayout={disableLayout}>
+ *     {isEmbedded && <div>Running in embedded mode from {referrer}</div>}
+ *   </AppLayout>
+ * );
+ * ```
+ */
+export function useCfgApp(options?: UseCfgAppOptions): UseCfgAppReturn {
+  const router = useRouter();
+  const [isMounted, setIsMounted] = useState(false);
+  const [isEmbedded, setIsEmbedded] = useState(false);
+  const [isStandalone, setIsStandalone] = useState(false);
+  const [referrer, setReferrer] = useState<string | null>(null);
+  const [parentTheme, setParentTheme] = useState<'light' | 'dark' | null>(null);
+  const [parentThemeMode, setParentThemeMode] = useState<string | null>(null);
+
+  useEffect(() => {
+    // Debug logging (uncomment for debugging)
+    // console.log('[useCfgApp] Hook initializing...');
+    setIsMounted(true);
+
+    // Check if running in iframe
+    const inIframe = window.self !== window.top;
+    // console.log('[useCfgApp] Iframe detection:', { inIframe });
+    setIsEmbedded(inIframe);
+
+    // Check if running as standalone PWA
+    const standalone = window.matchMedia('(display-mode: standalone)').matches;
+    setIsStandalone(standalone);
+
+    // Get referrer if embedded
+    if (inIframe && document.referrer) {
+      // console.log('[useCfgApp] Referrer:', document.referrer);
+      setReferrer(document.referrer);
+    }
+
+    // Setup resize observer and interval for iframe height updates
+    let resizeObserver: ResizeObserver | null = null;
+    let checkHeightInterval: NodeJS.Timeout | null = null;
+
+    // Notify parent window that iframe is ready
+    if (inIframe) {
+      try {
+        // console.log('[useCfgApp] Sending iframe-ready message to parent');
+        window.parent.postMessage({
+          type: 'iframe-ready',
+          data: {
+            url: window.location.href,
+            referrer: document.referrer
+          }
+        }, '*'); // Use '*' or specific origin for security
+        // console.log('[useCfgApp] iframe-ready message sent');
+      } catch (e) {
+        console.error('[useCfgApp] Failed to notify parent:', e);
+      }
+
+      // Send current content height (both increases and decreases)
+      const sendHeight = () => {
+        try {
+          // Use body.scrollHeight to avoid iframe height feedback loop
+          // document.documentElement.scrollHeight includes iframe's own height!
+          const bodyScrollHeight = document.body.scrollHeight;
+          const bodyOffsetHeight = document.body.offsetHeight;
+          const height = Math.max(bodyScrollHeight, bodyOffsetHeight);
+
+          window.parent.postMessage({
+            type: 'iframe-resize',
+            data: { height }
+          }, '*');
+        } catch (e) {
+          console.error('[useCfgApp] Failed to send height:', e);
+        }
+      };
+
+      // Send height immediately after mount
+      setTimeout(sendHeight, 100);
+
+      // Watch for content size changes using ResizeObserver
+      resizeObserver = new ResizeObserver(() => {
+        sendHeight();
+      });
+
+      // Observe document body for size changes
+      resizeObserver.observe(document.body);
+
+      // Also observe on route changes and after data loads
+      checkHeightInterval = setInterval(sendHeight, 1000);
+    }
+
+    // Listen for messages from parent window
+    const handleMessage = (event: MessageEvent) => {
+      // console.log('[useCfgApp] Message received:', {
+      //   origin: event.origin,
+      //   type: event.data?.type,
+      //   data: event.data?.data
+      // });
+
+      // Verify origin for security (optional - adjust for your needs)
+      // if (event.origin !== window.location.origin) return;
+
+      const { type, data } = event.data || {};
+
+      switch (type) {
+        case 'parent-auth':
+          // console.log('[useCfgApp] Processing parent-auth message');
+          // Receive authentication tokens from parent
+          if (data?.authToken && options?.onAuthTokenReceived) {
+            try {
+              // console.log('[useCfgApp] Calling onAuthTokenReceived');
+              options.onAuthTokenReceived(data.authToken, data.refreshToken);
+              // console.log('[useCfgApp] Auth tokens received from parent');
+            } catch (e) {
+              console.error('[useCfgApp] Failed to process auth tokens:', e);
+            }
+          }
+          break;
+
+        case 'parent-theme':
+          // console.log('[useCfgApp] Processing parent-theme message');
+          // Receive theme from parent
+          if (data?.theme) {
+            try {
+              // console.log('[useCfgApp] Setting theme:', {
+              //   theme: data.theme,
+              //   themeMode: data.themeMode
+              // });
+              setParentTheme(data.theme);
+              if (data.themeMode) {
+                setParentThemeMode(data.themeMode);
+              }
+              // console.log('[useCfgApp] Theme received from parent:', data.theme, 'mode:', data.themeMode);
+            } catch (e) {
+              console.error('[useCfgApp] Failed to process theme:', e);
+            }
+          }
+          break;
+
+        case 'parent-resize':
+          // Handle parent window resize (optional)
+          // console.log('[useCfgApp] Parent resized:', data);
+          break;
+
+        default:
+          // if (type) {
+          //   console.log('[useCfgApp] Unknown message type:', type);
+          // }
+          break;
+      }
+    };
+
+    // console.log('[useCfgApp] Adding message event listener');
+    window.addEventListener('message', handleMessage);
+
+    return () => {
+      // console.log('[useCfgApp] Cleaning up message event listener');
+      window.removeEventListener('message', handleMessage);
+
+      // Cleanup resize observer and interval
+      if (resizeObserver) {
+        resizeObserver.disconnect();
+      }
+      if (checkHeightInterval) {
+        clearInterval(checkHeightInterval);
+      }
+    };
+  }, [options]);
+
+  // Notify parent about route changes
+  useEffect(() => {
+    if (!isEmbedded || !isMounted) return;
+
+    try {
+      window.parent.postMessage({
+        type: 'iframe-navigation',
+        data: {
+          path: router.asPath,
+          route: router.pathname
+        }
+      }, '*');
+    } catch (e) {
+      console.error('[iframe] Failed to notify parent about navigation:', e);
+    }
+  }, [router.asPath, router.pathname, isEmbedded, isMounted]);
+
+  // Check URL parameter for embed mode
+  const embedParam = router.query.embed === 'true' || router.query.embed === '1';
+
+  // Determine if layout should be disabled
+  // Disable layout if:
+  // 1. Running in iframe AND no explicit embed=false param
+  // 2. URL has embed=true param
+  const shouldDisableLayout = (isEmbedded && router.query.embed !== 'false') || embedParam;
+
+  return {
+    isEmbedded,
+    isStandalone,
+    disableLayout: shouldDisableLayout,
+    referrer,
+    isMounted,
+    parentTheme,
+    parentThemeMode,
+  };
+}

package/src/layouts/AppLayout/layouts/CfgLayout/index.ts

@@ -0,0 +1,20 @@
+/**
+ * CfgLayout - Django CFG Layout with iframe Integration
+ *
+ * Universal layout component for Django CFG applications
+ * Handles iframe embedding, theme sync, and auth communication
+ */
+
+// Main component
+export { CfgLayout } from './CfgLayout';
+export type { CfgLayoutProps } from './CfgLayout';
+
+// Hooks
+export { useCfgApp, useApp } from './hooks';
+export type { UseCfgAppReturn, UseCfgAppOptions, UseAppReturn, UseAppOptions } from './hooks';
+
+// Components
+export { ParentSync, AuthStatusSync } from './components';
+
+// Types
+export type { CfgLayoutConfig } from './types';

package/src/layouts/AppLayout/layouts/CfgLayout/types/index.ts

@@ -0,0 +1,45 @@
+import { ReactNode } from 'react';
+
+/**
+ * Configuration for CfgLayout
+ * All options are optional - CfgLayout works out of the box with zero config
+ */
+export interface CfgLayoutConfig {
+  /**
+   * Optional handler called when auth tokens are received from parent window
+   *
+   * Note: Tokens are ALWAYS automatically set in API client via `api.setToken()`.
+   * Use this callback only if you need additional custom logic.
+   *
+   * @example
+   * ```tsx
+   * <CfgLayout config={{
+   *   onAuthTokenReceived: (authToken, refreshToken) => {
+   *     console.log('Tokens received and set in API client');
+   *     // Additional custom logic here
+   *   }
+   * }}>
+   * ```
+   */
+  onAuthTokenReceived?: (authToken: string, refreshToken?: string) => void;
+
+  /**
+   * Whether to automatically sync theme from parent window
+   * @default true
+   */
+  enableThemeSync?: boolean;
+
+  /**
+   * Whether to automatically send auth status to parent window
+   * @default true
+   */
+  enableAuthStatusSync?: boolean;
+}
+
+/**
+ * Props for CfgLayout component
+ */
+export interface CfgLayoutProps {
+  children: ReactNode;
+  config?: CfgLayoutConfig;
+}

package/src/layouts/index.ts

@@ -11,3 +11,6 @@ export * from './ErrorLayout';
 
 // UILayout - Config-driven UI documentation layout
 export * from './UILayout';
+
+// Note: CfgLayout is now part of AppLayout exports
+// Import it via: import { CfgLayout, useCfgApp } from '@djangocfg/layouts';