@donotdev/core 0.0.3 → 0.0.5

package/next/index.d.ts

@@ -0,0 +1,1476 @@
+import * as React from 'react';
+import { ReactNode } from 'react';
+
+// packages/core/types/src/auth/constants.ts
+
+
+
+// =============================================================================
+// User Role Constants
+// =============================================================================
+
+/**
+ * Standard user role names
+ * Apps can override these by providing their own role constants
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+declare const USER_ROLES = {
+  GUEST: 'guest',
+  USER: 'user',
+  ADMIN: 'admin',
+} as const;
+
+/**
+ * Type for user role names
+ * Apps can extend this with their own custom roles
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+type UserRole = (typeof USER_ROLES)[keyof typeof USER_ROLES] | string;
+
+// =============================================================================
+// Subscription Tier Constants
+// =============================================================================
+
+/**
+ * Standard subscription tier names
+ * Apps can override these by providing their own tier constants
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+declare const SUBSCRIPTION_TIERS = {
+  FREE: 'free',
+  PRO: 'pro',
+  PREMIUM: 'premium',
+} as const;
+
+/**
+ * Type for subscription tier names
+ * Apps can extend this with their own custom tiers
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+type SubscriptionTier =
+  | (typeof SUBSCRIPTION_TIERS)[keyof typeof SUBSCRIPTION_TIERS]
+  | string;
+
+// packages/core/types/src/common/index.ts
+
+
+
+// =============================================================================
+// PLATFORM CONSTANTS
+// =============================================================================
+
+/**
+ * Supported platform identifiers
+ * @constant
+ */
+declare const PLATFORMS = {
+  VITE: 'vite',
+  NEXTJS: 'nextjs',
+  UNKNOWN: 'unknown',
+} as const;
+
+/**
+ * Platform type derived from PLATFORMS constant
+ */
+type Platform = (typeof PLATFORMS)[keyof typeof PLATFORMS];
+
+// =============================================================================
+// ENVIRONMENT CONSTANTS
+// =============================================================================
+
+/**
+ * Supported environment modes
+ * @constant
+ */
+declare const ENVIRONMENTS = {
+  DEVELOPMENT: 'development',
+  PRODUCTION: 'production',
+  TEST: 'test',
+} as const;
+
+/**
+ * Environment mode type derived from ENVIRONMENTS constant
+ */
+type EnvironmentMode = (typeof ENVIRONMENTS)[keyof typeof ENVIRONMENTS];
+
+// =============================================================================
+// CONTEXT CONSTANTS
+// =============================================================================
+
+/**
+ * Supported execution contexts
+ * @constant
+ */
+declare const CONTEXTS = {
+  CLIENT: 'client',
+  SERVER: 'server',
+  BUILD: 'build',
+} as const;
+
+/**
+ * Context type derived from CONTEXTS constant
+ */
+type Context = (typeof CONTEXTS)[keyof typeof CONTEXTS];
+
+// =============================================================================
+// STORAGE CONSTANTS
+// =============================================================================
+
+/**
+ * Supported storage backend types
+ * @constant
+ */
+declare const STORAGE_TYPES = {
+  LOCAL: 'localStorage',
+  SESSION: 'sessionStorage',
+  INDEXED_DB: 'indexedDB',
+  MEMORY: 'memory',
+} as const;
+
+/**
+ * Storage type derived from STORAGE_TYPES constant
+ */
+type StorageType = (typeof STORAGE_TYPES)[keyof typeof STORAGE_TYPES];
+
+// =============================================================================
+// PWA CONSTANTS
+// =============================================================================
+
+/**
+ * PWA display modes
+ * @constant
+ */
+declare const PWA_DISPLAY_MODES = {
+  STANDALONE: 'standalone',
+  FULLSCREEN: 'fullscreen',
+  MINIMAL_UI: 'minimal-ui',
+  BROWSER: 'browser',
+} as const;
+
+/**
+ * PWA display mode type derived from PWA_DISPLAY_MODES constant
+ */
+type PWADisplayMode =
+  (typeof PWA_DISPLAY_MODES)[keyof typeof PWA_DISPLAY_MODES];
+
+/**
+ * PWA asset types
+ * @constant
+ */
+declare const PWA_ASSET_TYPES = {
+  MANIFEST: 'manifest',
+  SERVICE_WORKER: 'service-worker',
+  ICON: 'icon',
+} as const;
+
+/**
+ * PWA asset type derived from PWA_ASSET_TYPES constant
+ */
+type PWAAssetType =
+  (typeof PWA_ASSET_TYPES)[keyof typeof PWA_ASSET_TYPES];
+
+// =============================================================================
+// ROUTE DISCOVERY CONSTANTS
+// =============================================================================
+
+/**
+ * Route discovery sources
+ * @constant
+ */
+declare const ROUTE_SOURCES = {
+  AUTO: 'auto-discovery',
+  MANUAL: 'manual',
+  HYBRID: 'hybrid',
+} as const;
+
+/**
+ * Route source type derived from ROUTE_SOURCES constant
+ */
+type RouteSource = (typeof ROUTE_SOURCES)[keyof typeof ROUTE_SOURCES];
+
+// =============================================================================
+// AUTHENTICATION TYPES
+// =============================================================================
+
+/**
+ * Page-level authentication requirements
+ * @description Used in PageMeta and NavigationRoute for route-level auth
+ */
+type PageAuth =
+  | boolean
+  | {
+      /** Whether authentication is required */
+      required?: boolean;
+      /** Required user role */
+      role?: UserRole;
+      /** Required subscription tier */
+      tier?: SubscriptionTier;
+      /** Custom validation function */
+      validate?: (role: string, tier: string) => boolean;
+    };
+
+// =============================================================================
+// PAGE METADATA TYPES
+// =============================================================================
+
+/**
+ * Page metadata interface for route discovery and configuration
+ *
+ * @remarks
+ * **ALL PROPERTIES ARE OPTIONAL** - Framework provides smart defaults:
+ *
+ * - `auth`: false (public) by default - YOU must specify auth requirements explicitly
+ * - `title`: Auto-extracted from filename (ShowcasePage → "Showcase")
+ * - `entity`: Auto-extracted from path (pages/showcase/ → "showcase")
+ * - `action`: Auto-extracted from filename patterns (ListPage → "list", FormPage → "form")
+ * - `route`: Only needed for custom paths or dynamic routes like :id, :slug
+ *
+ * @example Simple page (no meta needed):
+ * ```tsx
+ * export function HomePage() {
+ *   return <PageContainer>...</PageContainer>;
+ * }
+ * // Framework provides: auth=false, title from home.title, entity=home
+ * ```
+ *
+ * @example Dynamic route (just define the path you want):
+ * ```tsx
+ * export const meta: PageMeta = {
+ *   route: '/blog/:slug'  // Creates /blog/:slug
+ * };
+ * // Framework provides: auth=false, title from blog.title, entity=blog
+ * ```
+ *
+ * @example Auth-required (developer must be explicit):
+ * ```tsx
+ * export const meta: PageMeta = {
+ *   auth: { required: true }  // YOU decide what needs auth
+ * };
+ * ```
+ */
+interface PageMeta {
+  /** Authentication requirements for this route */
+  auth?: PageAuth;
+
+  /** Route configuration - just define the exact path you want */
+  route?: string | { params?: string[] };
+
+  /** Page title (optional - framework auto-extracts from filename if not provided) */
+  title?: string;
+
+  /**
+   * Translation/SEO namespace for this page
+   * @description Used for meta tags and translations
+   */
+  namespace?: string;
+
+  /**
+   * Icon for navigation (optional - framework provides smart defaults)
+   * @description **ONLY lucide-react JSX components** - extracted as component name string at build time for tree-shaking.
+   *
+   * **RESTRICTIONS:**
+   * - ✅ Only: `<Rocket />`, `<ShoppingCart />`, `<Home />` (lucide-react JSX components)
+   * - ❌ NOT: Emojis (`"🚀"`), strings (`"Rocket"`), or custom ReactNode
+   *
+   * **Why?** This is for build-time extraction and tree-shaking. The component name is extracted and stored as a string.
+   *
+   * **For flexible icons** (emojis, strings, custom components), use the `Icon` component directly in your JSX, not in PageMeta.
+   *
+   * @example
+   * ```tsx
+   * import { Rocket } from 'lucide-react';
+   * export const meta: PageMeta = {
+   *   icon: <Rocket />  // ✅ Correct - lucide-react component
+   * };
+   * ```
+   *
+   * @example
+   * ```tsx
+   * // ❌ WRONG - Don't use emojis or strings in PageMeta
+   * export const meta: PageMeta = {
+   *   icon: "🚀"  // ❌ Not supported in PageMeta
+   * };
+   * ```
+   */
+  icon?: ReactNode;
+
+  /**
+   * Hide from navigation menu (default: false - shows in navigation)
+   * @description Set to true to exclude this route from navigation menus
+   * @default false
+   * @example
+   * ```tsx
+   * export const meta: PageMeta = {
+   *   hideFromMenu: true // Won't appear in HeaderNavigation, Sidebar, etc.
+   * };
+   * ```
+   */
+  hideFromMenu?: boolean;
+}
+
+/**
+ * Route metadata (discovery-generated)
+ * @description Complete route metadata including auto-discovered fields from RouteDiscovery
+ *
+ * This extends PageMeta with fields that are automatically discovered from file paths:
+ * - `entity`: Auto-extracted from path (pages/showcase/ → "showcase")
+ * - `action`: Auto-extracted from filename patterns (ListPage → "list", FormPage → "form")
+ *
+ * These fields are always present in discovered routes but cannot be set in PageMeta.
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface RouteMeta extends PageMeta {
+  /** Entity/domain grouping - auto-discovered from file path (not user-configurable) */
+  entity?: string;
+  /** Action type for route categorization - auto-discovered from filename patterns (not user-configurable) */
+  action?: string | null;
+  /** File path where route was discovered */
+  file?: string;
+}
+
+// =============================================================================
+// PLUGIN CONFIGURATION TYPES
+// =============================================================================
+
+/**
+ * i18n Plugin Configuration
+ * @description Configuration for internationalization system
+ */
+interface I18nPluginConfig {
+  /** Mapping of language → namespace → loader function */
+  mapping: Record<string, Record<string, () => Promise<any>>>;
+  /** List of available language codes */
+  languages: string[];
+  /** List of eagerly loaded namespace identifiers */
+  eager: string[];
+  /** Fallback language code */
+  fallback: string;
+  /** Preloaded translation content (optional) */
+  content?: Record<string, Record<string, any>>;
+  /** Storage configuration */
+  storage: {
+    /** Storage backend type */
+    type: StorageType;
+    /** Storage key prefix */
+    prefix: string;
+    /** Time-to-live in seconds */
+    ttl: number;
+    /** Whether to encrypt stored data */
+    encryption: boolean;
+    /** Maximum storage size in bytes */
+    maxSize: number;
+  };
+  /** Performance configuration */
+  performance: {
+    /** Maximum cache size */
+    cacheSize: number;
+    /** Error cache TTL in seconds */
+    errorCacheTTL: number;
+  };
+  /** Discovery manifest metadata */
+  manifest: {
+    /** Total number of translation files */
+    totalFiles: number;
+    /** Total number of namespaces */
+    totalNamespaces: number;
+    /** Total number of languages */
+    totalLanguages: number;
+    /** Number of eagerly loaded namespaces */
+    eagerNamespaces: number;
+    /** ISO timestamp of generation */
+    generatedAt: string;
+  };
+  /** Whether debug mode is enabled */
+  debug: boolean;
+}
+
+/**
+ * Routes Plugin Configuration
+ * @description Complete route configuration populated by discovery system
+ */
+interface RoutesPluginConfig {
+  /**
+   * Array of discovered routes
+   * @description All routes discovered by the route discovery system
+   */
+  mapping: Array<{
+    /**
+     * URL path for the route (platform-agnostic)
+     * @description The URL path that users see in their browser
+     * @example '/showcase/layouts', '/users/:id', '/dashboard'
+     */
+    path: string;
+
+    /**
+     * Lazy component reference (Vite-specific)
+     * @description React.lazy() component for code splitting
+     * @example lazy(() => import("/src/pages/showcase/LayoutsPage"))
+     */
+    component: any;
+
+    /**
+     * Absolute file system path (Next.js-specific)
+     * @description The absolute path to the component file
+     * @example '/src/pages/showcase/LayoutsPage.tsx'
+     */
+    importPath: string;
+
+    /**
+     * Export name for named exports
+     * @example 'HomePage', 'AboutPage'
+     */
+    exportName?: string;
+
+    /**
+     * Authentication configuration (platform-agnostic)
+     * @description Defines whether the route requires authentication
+     */
+    auth: PageAuth;
+
+    /**
+     * Route metadata (platform-agnostic)
+     * @description Additional information about the route, including auto-discovered fields
+     */
+    meta: RouteMeta;
+  }>;
+
+  /**
+   * Discovery metadata and statistics
+   * @description Information about the route discovery process
+   */
+  manifest: {
+    /** Total number of discovered routes */
+    totalRoutes: number;
+    /** Number of routes requiring authentication */
+    authRequired: number;
+    /** Number of public routes */
+    publicRoutes: number;
+    /** Source of routes (auto-discovery vs manual) */
+    source: RouteSource;
+    /** ISO timestamp when routes were generated */
+    generatedAt: string;
+  };
+}
+
+/**
+ * Themes Plugin Configuration
+ * @description Configuration for theme discovery and management
+ */
+interface ThemesPluginConfig {
+  /** Mapping of theme names to theme configurations */
+  mapping: Record<string, any>;
+  /** Array of discovered themes */
+  discovered: Array<{
+    /** Theme identifier */
+    name: string;
+    /** Human-readable theme name */
+    displayName: string;
+    /** Whether this is a dark theme */
+    isDark: boolean;
+    /** Theme metadata */
+    meta: {
+      /** Icon identifier */
+      icon: string;
+      /** Theme description */
+      description?: string;
+      /** Theme category */
+      category?: string;
+      /** Theme author */
+      author?: string;
+      /** Additional metadata */
+      [key: string]: any;
+    };
+    /** Source file path */
+    source: string;
+    /** Whether theme is essential (cannot be disabled) */
+    essential: boolean;
+  }>;
+  /** CSS custom property variables */
+  variables: Record<string, string>;
+  /** Utility class mappings */
+  utilities: Record<string, Record<string, string>>;
+  /** Discovery manifest metadata */
+  manifest: {
+    /** Total number of discovered themes */
+    totalThemes: number;
+    /** Total number of CSS variables */
+    totalVariables: number;
+    /** Total number of utility classes */
+    totalUtilities: number;
+    /** ISO timestamp of generation */
+    generatedAt: string;
+  };
+}
+
+/**
+ * Assets Plugin Configuration
+ * @description Configuration for static asset management
+ */
+interface AssetsPluginConfig {
+  /** Mapping of asset paths to asset metadata */
+  mapping: Record<string, any>;
+  /** SVG content of logo.svg for inline rendering with CSS variable theming */
+  logoSvgContent?: string | null;
+  /** Discovery manifest metadata */
+  manifest: {
+    /** Total number of discovered assets */
+    totalAssets: number;
+    /** ISO timestamp of generation */
+    generatedAt: string;
+  };
+}
+
+/**
+ * PWA Plugin Configuration
+ * @description Configuration for Progressive Web App features
+ */
+interface PWAPluginConfig {
+  /** Array of PWA assets */
+  assets: Array<{
+    /** Type of PWA asset */
+    type: PWAAssetType;
+    /** Asset file path */
+    path: string;
+    /** Asset file size in bytes */
+    size?: number;
+    /** Asset content (for inline assets) */
+    content?: any;
+    /** Asset format (for images) */
+    format?: string;
+    /** Asset purpose (for icons) */
+    purpose?: string;
+  }>;
+  /** PWA manifest configuration */
+  manifest: {
+    /** Application name */
+    name: string;
+    /** Short application name */
+    short_name: string;
+    /** Application description */
+    description: string;
+    /** Start URL */
+    start_url: string;
+    /** Display mode */
+    display: PWADisplayMode;
+    /** Background color */
+    background_color: string;
+    /** Theme color */
+    theme_color: string;
+    /** Array of app icons */
+    icons: Array<{
+      /** Icon source path */
+      src: string;
+      /** Icon sizes (e.g., '192x192') */
+      sizes: string;
+      /** Icon MIME type */
+      type: string;
+      /** Icon purpose (e.g., 'any', 'maskable') */
+      purpose: string;
+    }>;
+  };
+  /** Discovery manifest metadata */
+  manifestInfo: {
+    /** Total number of PWA assets */
+    totalAssets: number;
+    /** Total number of icons */
+    totalIcons: number;
+    /** Whether service worker is present */
+    hasServiceWorker: boolean;
+    /** ISO timestamp of generation */
+    generatedAt: string;
+  };
+}
+
+/**
+ * Features Plugin Configuration
+ * @description Configuration for feature discovery and enablement
+ *
+ * @remarks
+ * This interface defines the structure for feature discovery data that is populated
+ * at build time and made available at runtime for feature availability checking.
+ *
+ * @example
+ * ```typescript
+ * // Generated by feature discovery system
+ * const featuresConfig: FeaturesPluginConfig = {
+ *   available: ['auth', 'billing', 'i18n', 'oauth'],
+ *   enabled: ['auth', 'i18n'],
+ *   overridden: false
+ * };
+ * ```
+ */
+interface FeaturesPluginConfig {
+  /**
+   * List of all available features discovered in packages/features/
+   * @example ['auth', 'billing', 'i18n', 'oauth']
+   */
+  available: string[];
+}
+
+// =============================================================================
+// FRAMEWORK CONFIGURATION
+// =============================================================================
+
+/**
+ * Complete DoNotDev framework configuration structure
+ * @description Single source of truth for all framework configuration
+ *
+ * @remarks
+ * All discovery plugins add their data to this unified config.
+ * Available at runtime via globalThis._DNDEV_CONFIG_ or window._DNDEV_CONFIG_
+ */
+interface DndevFrameworkConfig {
+  /** Framework platform (Vite or Next.js) */
+  platform: Platform;
+  /** Current environment mode */
+  mode: EnvironmentMode;
+  /** Framework version */
+  version: string;
+  /** Execution context */
+  context: Context;
+  /** Unix timestamp of config generation */
+  timestamp: number;
+  /** i18n plugin configuration (optional) */
+  i18n?: I18nPluginConfig;
+  /** Routes plugin configuration (optional) */
+  routes?: RoutesPluginConfig;
+  /** Themes plugin configuration (optional) */
+  themes?: ThemesPluginConfig;
+  /** Assets plugin configuration (optional) */
+  assets?: AssetsPluginConfig;
+  /** PWA plugin configuration (optional) */
+  pwa?: PWAPluginConfig;
+  /** Features plugin configuration (optional) */
+  features?: FeaturesPluginConfig;
+  /** Environment variables (VITE_* variables from .env files) */
+  env?: Record<string, string>;
+}
+
+// =============================================================================
+// GLOBAL AUGMENTATIONS
+// =============================================================================
+
+declare global {
+  interface Window {
+    /**
+     * Single source of truth for all DoNotDev framework configuration
+     * @description Set by platform detection and populated by discovery plugins
+     */
+    _DNDEV_CONFIG_?: DndevFrameworkConfig;
+
+    /**
+     * Global store registry for singleton Zustand stores
+     * @description Ensures single instance across code-split chunks
+     */
+    _DNDEV_STORES_?: Record<string, any>;
+
+    /** PapaParse CSV parser library (external) */
+    Papa?: {
+      parse: (input: string | File, config?: any) => any;
+      unparse: (data: any[], config?: any) => string;
+    };
+
+    /** Sentry error tracking library (external) */
+    Sentry?: {
+      captureException: (error: unknown) => void;
+      withScope: (callback: (scope: any) => void) => void;
+      getClient: () => { close: () => Promise<boolean> } | undefined;
+    };
+
+    /**
+     * Google APIs (Maps, One Tap, etc.)
+     * @description Unified type for all Google services
+     */
+    google?: {
+      /** Google Maps API */
+      maps?: {
+        places?: {
+          AutocompleteService: new () => any;
+          PlacesService: new (element: HTMLElement) => any;
+          PlacesServiceStatus: {
+            OK: string;
+          };
+        };
+        [key: string]: any;
+      };
+      /** Google Identity Services (One Tap) */
+      accounts?: {
+        id?: {
+          initialize: (config: any) => void;
+          prompt: (callback?: (notification: any) => void) => void;
+          cancel?: () => void;
+          disableAutoSelect?: () => void;
+        };
+      };
+      [key: string]: any;
+    };
+
+    /** FedCM Identity Credential API */
+    IdentityCredential?: any;
+  }
+
+  namespace NodeJS {
+    interface ProcessEnv {
+      /** Serialized framework config for Node.js environment */
+      _DNDEV_CONFIG_?: string;
+    }
+  }
+
+  namespace globalThis {
+    /** Framework configuration (same as window._DNDEV_CONFIG_) */
+    var _DNDEV_CONFIG_: DndevFrameworkConfig | undefined;
+    /** Store registry (same as window._DNDEV_STORES_) */
+    var _DNDEV_STORES_: Record<string, any> | undefined;
+
+    // Third-party framework globals (not owned by DoNotDev)
+    var __vite_plugin_react_preamble_installed__: boolean | undefined;
+    var __vite_hmr_port: number | undefined;
+    var __NEXT_DATA__: any | undefined;
+    var __REACT_QUERY_CLIENT__: any | undefined;
+    var __REACT_QUERY_PROVIDER__: any | undefined;
+    var __DNDEV_DEBUG: boolean | undefined;
+    var __FIREBASE_DEMO_MODE__: boolean | undefined;
+    // gc is already defined by Node.js globals - removed to avoid TS 5.9+ conflict
+    var getAvailableThemes: (() => string[]) | undefined;
+  }
+}
+
+type $MergeBy<T, K> = Omit<T, keyof K> & K;
+
+type $PreservedValue<Value, Fallback> = [Value] extends [never] ? Fallback : Value;
+
+/**
+ * This interface can be augmented by users to add types to `i18next` default TypeOptions.
+ *
+ * Usage:
+ * ```ts
+ * // i18next.d.ts
+ * import 'i18next';
+ * declare module 'i18next' {
+ *   interface CustomTypeOptions {
+ *     defaultNS: 'custom';
+ *     returnNull: false;
+ *     returnObjects: false;
+ *     nsSeparator: ':';
+ *     keySeparator: '.';
+ *     compatibilityJSON: 'v4';
+ *     allowObjectInHTMLChildren: false;
+ *     resources: {
+ *       custom: {
+ *         foo: 'foo';
+ *       };
+ *     };
+ *   }
+ * }
+ * ```
+ */
+interface CustomTypeOptions {}
+
+type TypeOptions = $MergeBy<
+  {
+    /** @see {InitOptions.returnNull} */
+    returnNull: false;
+
+    /** @see {InitOptions.returnEmptyString} */
+    returnEmptyString: true;
+
+    /** @see {InitOptions.returnObjects} */
+    returnObjects: false;
+
+    /** @see {InitOptions.keySeparator} */
+    keySeparator: '.';
+
+    /** @see {InitOptions.nsSeparator} */
+    nsSeparator: ':';
+
+    /** @see {InitOptions.pluralSeparator} */
+    pluralSeparator: '_';
+
+    /** @see {InitOptions.contextSeparator} */
+    contextSeparator: '_';
+
+    /** @see {InitOptions.defaultNS} */
+    defaultNS: 'translation';
+
+    /** @see {InitOptions.fallbackNS} */
+    fallbackNS: false;
+
+    /** @see {InitOptions.compatibilityJSON} */
+    compatibilityJSON: 'v4';
+
+    /** @see {InitOptions.resources} */
+    resources: object;
+
+    /**
+     * Flag that allows HTML elements to receive objects. This is only useful for React applications
+     * where you pass objects to HTML elements so they can be replaced to their respective interpolation
+     * values (mostly with Trans component)
+     */
+    allowObjectInHTMLChildren: false;
+
+    /**
+     * Flag that enables strict key checking even if a `defaultValue` has been provided.
+     * This ensures all calls of `t` function don't accidentally use implicitly missing keys.
+     */
+    strictKeyChecks: false;
+
+    /**
+     * Prefix for interpolation
+     */
+    interpolationPrefix: '{{';
+
+    /**
+     * Suffix for interpolation
+     */
+    interpolationSuffix: '}}';
+
+    /** @see {InterpolationOptions.unescapePrefix} */
+    unescapePrefix: '-';
+
+    /** @see {InterpolationOptions.unescapeSuffix} */
+    unescapeSuffix: '';
+
+    /**
+     * Use a proxy-based selector to select a translation.
+     *
+     * Enables features like go-to definition, and better DX/faster autocompletion
+     * for TypeScript developers.
+     *
+     * If you're working with an especially large set of translations and aren't
+     * using context, you set `enableSelector` to `"optimize"` and i18next won't do
+     * any type-level processing of your translations at all.
+     *
+     * With `enableSelector` set to `"optimize"`, i18next is capable of supporting
+     * arbitrarily large/deep translation sets without causing any IDE slowdown
+     * whatsoever.
+     *
+     * @default false
+     */
+    enableSelector: false;
+  },
+  CustomTypeOptions
+>;
+
+type FlatNamespace = $PreservedValue<keyof TypeOptions['resources'], string>;
+type Namespace<T = FlatNamespace> = T | readonly T[];
+
+interface ReportNamespaces {
+  addUsedNamespaces(namespaces: Namespace): void;
+  getUsedNamespaces(): string[];
+}
+
+declare module 'i18next' {
+  // interface i18n {
+  //   reportNamespaces?: ReportNamespaces;
+  // }
+  interface CustomInstanceExtensions {
+    reportNamespaces?: ReportNamespaces;
+  }
+}
+
+type ObjectOrNever = TypeOptions['allowObjectInHTMLChildren'] extends true
+  ? Record<string, unknown>
+  : never;
+
+type ReactI18NextChildren = React.ReactNode | ObjectOrNever;
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicAttributes {
+      i18nIsDynamicList?: boolean;
+    }
+  }
+
+  interface HTMLAttributes<T> {
+    // This union is inspired by the typings for React.ReactNode. We do this to fix "This JSX tag's 'children' prop
+    // expects a single child of type 'ReactI18NextChildren', but multiple children were provided":
+    // https://github.com/DefinitelyTyped/DefinitelyTyped/blob/5a1e9f91ed0143adede394adb3f540e650455f71/types/react/index.d.ts#L268
+    children?: ReactI18NextChildren | Iterable<ReactI18NextChildren>;
+  }
+}
+
+// packages/core/types/src/layout/layoutTypes.ts
+
+
+
+/**
+ * App metadata and branding configuration
+ *
+ * @version 0.0.2
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface AppMetadata {
+  /** Application name */
+  name?: string;
+
+  /** Short application name for mobile/compact displays (defaults to name if not set) */
+  shortName?: string;
+
+  /** Application URL (base URL for production, defaults to localhost in development) */
+  url?: string;
+
+  /** Application description */
+  description?: string;
+
+  /** Social and external links */
+  links?: {
+    /** GitHub repository URL */
+    github?: string;
+    /** Twitter/X profile URL */
+    twitter?: string;
+    /** LinkedIn profile URL */
+    linkedin?: string;
+    /** Support/contact URL */
+    support?: string;
+    /** Documentation URL */
+    docs?: string;
+    /** Blog URL */
+    blog?: string;
+  };
+
+  /** Footer configuration
+   * - `null`: Explicitly hide footer
+   * - `undefined`: Use framework default footer
+   * - `{ copyright?: ..., legalLinks?: ... }`: Custom footer configuration
+   */
+  footer?: {
+    /** Copyright configuration
+     * - `null`: Hide copyright
+     * - `undefined`: Use default (© YEAR appName. All rights reserved)
+     * - `string`: Custom copyright text
+     */
+    copyright?: null | string;
+    /** Legal links configuration
+     * - `null`: Hide legal links
+     * - `Array<{ path, label }>`: Custom legal links (labels can be i18n keys via maybeTranslate)
+     * - `undefined`: Use framework defaults (Privacy Policy, Terms of Service with i18n labels)
+     */
+    legalLinks?: null | Array<{
+      path: string;
+      label: string;
+    }>;
+  } | null;
+
+  /** Additional application metadata */
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Authentication route configuration
+ *
+ * Configure redirect routes for authentication and authorization failures.
+ * Also configures AuthHeader UI behavior (login page, user menu, etc.).
+ * All routes are optional with security-first defaults.
+ *
+ * @example
+ * ```typescript
+ * const authConfig: AuthConfig = {
+ *   authRoute: '/signin',
+ *   roleRoute: '/403',
+ *   tierRoute: '/pricing',
+ *   loginPath: '/login',  // Optional: links to login page (undefined = show providers in header)
+ *   profilePath: '/account',
+ *   authMenuPaths: ['/dashboard', '/settings']
+ * };
+ * ```
+ *
+ * @version 0.0.2
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface AuthConfig {
+  /** Route to redirect when authentication required (default: '/login') */
+  authRoute: string;
+  /** Route to redirect when role insufficient (default: '/404') */
+  roleRoute: string;
+  /** Route to redirect when tier insufficient (default: '/404') */
+  tierRoute: string;
+  /** Optional: Path to login page. If provided, AuthHeader links to login page. If undefined (default), shows providers in header */
+  loginPath?: string;
+  /** Optional: Path to profile page (default: '/profile') */
+  profilePath?: string;
+  /**
+   * Optional: Custom menu items for authenticated user menu dropdown.
+   * Supports route-based items with paths (auto-creates Link).
+   * Icons are auto-resolved from route discovery (PageMeta.icon) if not provided.
+   * For items with onClick handlers, use AuthMenu customItems prop instead.
+   *
+   * @example
+   * ```typescript
+   * authMenuItems: [
+   *   { path: '/dashboard' }, // icon auto-resolved from route
+   *   { path: '/settings', label: 'Settings' }, // override label, icon from route
+   *   { path: '/billing', icon: 'CreditCard' } // override icon
+   * ]
+   * ```
+   */
+  authMenuItems?: Array<{
+    /** Route path (creates Link automatically) */
+    path: string;
+    /** Optional label (falls back to navigation item label or path segment) */
+    label?: string;
+    /** Optional Lucide icon name (string) - overrides route discovery icon */
+    icon?: string;
+  }>;
+  /**
+   * Optional function to handle custom data deletion before account removal
+   * Framework will try/catch this - failures won't block account deletion
+   *
+   * @example
+   * ```typescript
+   * deleteUserFunction: async (userId: string) => {
+   *   // Cancel Stripe subscriptions
+   *   await fetch('/api/billing/cancel', { method: 'POST' });
+   *
+   *   // Delete Firestore user data
+   *   await deleteDoc(doc(db, 'users', userId));
+   *
+   *   // Custom cleanup
+   *   await myCustomCleanup(userId);
+   * }
+   * ```
+   */
+  deleteUserFunction?: (userId: string) => Promise<void>;
+}
+
+/**
+ * SEO configuration
+ *
+ * Configure automatic SEO meta tags and social sharing.
+ *
+ * @example
+ * ```typescript
+ * const seoConfig: SEOConfig = {
+ *   baseUrl: 'https://example.com',
+ *   defaultImage: '/og-image.png',
+ *   twitterHandle: 'mycompany'
+ * };
+ * ```
+ *
+ * @version 0.0.2
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface SEOConfig {
+  /** Enable automatic SEO (default: true) */
+  enabled?: boolean;
+  /** Base URL for SEO files (robots.txt, sitemap.xml) - defaults to appConfig.app.url (set at build time) */
+  baseUrl?: string;
+  /** Site name for SEO - defaults to APP_NAME from app.ts */
+  siteName?: string;
+  /** Crawl delay for robots.txt (default: 1) */
+  crawlDelay?: number;
+  /** Generate robots.txt (default: true) */
+  generateRobotsTxt?: boolean;
+  /** Generate sitemap.xml (default: true) */
+  generateSitemap?: boolean;
+  /** Default namespace for i18n translations (default: 'home') */
+  defaultNamespace?: string;
+  /** Default image for social sharing */
+  defaultImage?: string;
+  /** Twitter handle (without @) */
+  twitterHandle?: string;
+  /** Additional static meta tags */
+  staticTags?: Record<string, string>;
+}
+
+/**
+ * Favicon and PWA configuration
+ *
+ * Configure automatic favicon generation and PWA manifest icons.
+ *
+ * @example
+ * ```typescript
+ * const faviconConfig: FaviconConfig = {
+ *   appName: 'My App',
+ *   themeColor: '#000000',
+ *   backgroundColor: '#ffffff'
+ * };
+ * ```
+ *
+ * @version 0.0.2
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface FaviconConfig {
+  /** Enable automatic favicon system (default: true) */
+  enabled?: boolean;
+  /** App name for PWA manifest */
+  appName?: string;
+  /** Theme color for mobile browsers */
+  themeColor?: string;
+  /** Background color for splash screens */
+  backgroundColor?: string;
+  /** Include PWA manifest icons */
+  includeManifestIcons?: boolean;
+  /** Include Microsoft tile icons */
+  includeMSIcons?: boolean;
+}
+
+/**
+ * Feature flags and debug configuration
+ *
+ * Controls app behavior and GDPR compliance.
+ * Feature availability is auto-detected via env vars/packages.
+ *
+ * @example
+ * ```typescript
+ * const featuresConfig: FeaturesConfig = {
+ *   debug: true,
+ *   offlineTrustEnabled: true,
+ *   requiredCookies: ['necessary', 'analytics']
+ * };
+ * ```
+ *
+ * @version 0.0.2
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface FeaturesConfig {
+  /** Enable debug tools (default: false in production, true in development) */
+  debug?: boolean;
+
+  /**
+   * Enable offline trust for cached claims (default: false)
+   *
+   * When true:
+   * - Online: Always verify with server (don't trust cache)
+   * - Offline: Use cached claims (graceful degradation)
+   *
+   * When false:
+   * - Online: Always verify with server
+   * - Offline: Reject (throw error, require network)
+   *
+   * @default false
+   */
+  offlineTrustEnabled?: boolean;
+
+  /**
+   * Cookie consent categories to display in GDPR banner
+   *
+   * Controls which cookie categories users can consent to.
+   * Framework always includes 'necessary' (cannot be disabled).
+   *
+   * @example
+   * ```typescript
+   * features: {
+   *   requiredCookies: ['necessary', 'functional', 'analytics']
+   * }
+   * ```
+   *
+   * @default ['necessary']
+   */
+  requiredCookies?: string[];
+}
+
+/**
+ * Complete application configuration
+ *
+ * Consolidates all app-level configuration with smart defaults.
+ * Pass only what you need to override - everything has sensible defaults.
+ *
+ * @example
+ * ```typescript
+ * // Minimal configuration
+ * const config: AppConfig = {
+ *   app: { name: 'My App' }
+ * };
+ *
+ * // Full configuration
+ * const config: AppConfig = {
+ *   app: {
+ *     name: 'My App',
+ *     description: 'Professional app'
+ *   },
+ *   auth: {
+ *     authRoute: '/signin',
+ *     roleRoute: '/403',
+ *     tierRoute: '/pricing'
+ *   },
+ *   seo: {
+ *     defaultImage: '/og.png'
+ *   },
+ *   preset: 'landing',
+ *   features: {
+ *     debug: true
+ *   }
+ * };
+ * ```
+ *
+ * @version 0.0.2
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface AppConfig {
+  /** App metadata and branding */
+  app?: AppMetadata;
+  /** Authentication routes - partial override of defaults */
+  auth?: Partial<AuthConfig> | false;
+  /** SEO configuration (set to false to disable) */
+  seo?: SEOConfig | false;
+  /** Favicon configuration (set to false to disable) */
+  favicon?: FaviconConfig | false;
+  /** Layout preset for store initialization (defaults to 'landing' if invalid/empty) */
+  preset?: string;
+  /** Feature flags */
+  features?: FeaturesConfig;
+}
+
+/**
+ * I18n virtual mapping options
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface I18nVirtualMappingOptions {
+  virtualModuleId?: string;
+  eagerNamespaces?: string[];
+}
+
+/**
+ * Base discovery options - DRY type for code, not a config level
+ * HMR options are internal framework concerns (in DEFAULT_OPTIONS only, not user-configurable)
+ * Plugins are always enabled (part of framework) - no enabled option
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface BaseDiscoveryOptions {
+  /** Debug logging (default: false) - cascades from global debug */
+  debug?: boolean;
+  /** Verbose logging (default: true) - cascades from global verbose */
+  verbose?: boolean;
+}
+
+/**
+ * Theme detection options
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface ThemeDetectionOptions extends BaseDiscoveryOptions {
+  /** Theme manifest file name (default: 'theme-manifest.json') */
+  manifestFileName?: string;
+  /** Auto-generate safelist (default: true) */
+  autoSafelist?: boolean;
+}
+
+/**
+ * Route discovery options with virtual module support
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface RouteDiscoveryOptions extends BaseDiscoveryOptions {
+  /** Disable route discovery (default: false) - set to true if using custom router */
+  disabled?: boolean;
+  /** Path to manual routes file relative to vite.config.ts (default: './src/routes.ts') */
+  manualPath?: string;
+  /** Additional patterns to scan beyond centralized patterns */
+  additionalPatterns?: string[];
+}
+
+/**
+ * I18n options
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface I18nOptions extends BaseDiscoveryOptions {
+  useVirtualMapping?: boolean;
+  fallbackLanguage?: string;
+  namespaces?: string[];
+  virtualMapping?: I18nVirtualMappingOptions;
+}
+
+/**
+ * Asset options
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface AssetOptions extends BaseDiscoveryOptions {
+  /** Asset fallback configuration */
+  fallback?: AssetFallbackOptions | false;
+}
+
+/**
+ * Progressive Web App options
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface PWAOptions {
+  /** Enable PWA in production builds (default: false) */
+  enabled?: boolean;
+  /** Enable PWA in development (default: false) */
+  devEnabled?: boolean;
+  /** Debug logging (default: false) */
+  debug?: boolean;
+  /** Override manifest values (auto-discovered from app.ts by default) */
+  manifest?: Record<string, any>;
+  /** Discover build assets for precache (Next.js only, default: true) */
+  discoverBuildAssets?: boolean;
+  /** Override workbox configuration (smart defaults provided) */
+  workbox?: {
+    /** Maximum file size to cache in bytes (default: 5MB) */
+    maximumFileSizeToCacheInBytes?: number;
+    /** Glob patterns for precaching (default: all js, css, html, icons, and fonts) */
+    globPatterns?: string[];
+    /** Glob patterns to ignore */
+    globIgnores?: string[];
+    /** Clean up outdated caches (default: true) */
+    cleanupOutdatedCaches?: boolean;
+    /** Skip waiting for service worker activation (default: true) */
+    skipWaiting?: boolean;
+    /** Claim clients immediately (default: true) */
+    clientsClaim?: boolean;
+    /** Runtime caching strategies (smart defaults provided) */
+    runtimeCaching?: Array<{
+      urlPattern: RegExp | ((options: { request: Request }) => boolean);
+      handler:
+        | 'CacheFirst'
+        | 'NetworkFirst'
+        | 'StaleWhileRevalidate'
+        | 'NetworkOnly'
+        | 'CacheOnly';
+      options?: Record<string, any>;
+    }>;
+    /** Navigation fallback URL (default: '/') */
+    navigateFallback?: string;
+    /** URLs to exclude from navigation fallback */
+    navigateFallbackDenylist?: RegExp[];
+    /** Transform precache manifest (allows custom filtering/modification) */
+    manifestTransforms?: Array<
+      (manifest: Array<{ url: string; revision: string | null }>) => {
+        manifest: Array<{ url: string; revision: string | null }>;
+        warnings?: string[];
+      }
+    >;
+    /** Background sync configuration for offline actions */
+    backgroundSync?:
+      | {
+          /** Queue name for background sync (default: 'background-sync-queue') */
+          queueName?: string;
+          /** Maximum retention time in minutes (default: 24 * 60) */
+          maxRetentionTime?: number;
+          /** URL pattern for background sync routes (default: matches /api/ routes) */
+          urlPattern?: RegExp | ((options: { request: Request }) => boolean);
+        }
+      | false;
+    [key: string]: any; // Allow other workbox options
+  };
+}
+
+/**
+ * Asset fallback options
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface AssetFallbackOptions {
+  /** Enable asset fallback (default: true) */
+  enabled?: boolean;
+  /** Assets to copy (default: from centralized patterns) */
+  assets?: string[];
+  /** Asset patterns to scan (default: from centralized patterns) */
+  assetPatterns?: string[];
+  /** Framework package name (default: '@donotdev/ui') */
+  frameworkPackage?: string;
+  /** Assets path within framework package (default: 'assets') */
+  assetsPath?: string;
+  /** Debug logging (default: false) */
+  debug?: boolean;
+}
+
+/**
+ * Server shim options for blocking server-only imports
+ * Note: serverShim cannot be disabled - framework would crash without it
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface ServerShimOptions {
+  /** Additional imports to block beyond defaults */
+  blockedImports?: string[];
+  /** Debug logging (default: false) */
+  debug?: boolean;
+}
+
+// Next.js Configuration
+
+/**
+ * Next.js configuration options for DNDev applications
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+interface NextConfigOptions {
+  /** App config from app.ts - features and SEO will be extracted automatically (required) */
+  appConfig: AppConfig;
+  /** Debug mode - enables detailed debug logging */
+  debug?: boolean;
+  /** Verbose logging - shows config/search paths (opt-out, auto-disabled in CI) */
+  verbose?: boolean;
+  /** Route discovery configuration (uses DRY RouteDiscoveryOptions) */
+  routes?: RouteDiscoveryOptions & {
+    /** Generate app/** page files (Site template) (default: true) */
+    generateAppPages?: boolean;
+    /** Routing mode for Next.js */
+    routingMode?: 'pages' | 'app';
+    /** Generate authentication middleware */
+    generateMiddleware?: boolean;
+  };
+  /** Internationalization configuration (uses DRY I18nOptions) */
+  i18n?: I18nOptions;
+  /** Theme configuration (uses DRY ThemeDetectionOptions) */
+  themes?: ThemeDetectionOptions;
+  /** Asset configuration (uses DRY AssetOptions) */
+  assets?: AssetOptions;
+  /** Generate route manifest */
+  generateManifest?: boolean;
+  /** PWA configuration */
+  pwa?: PWAOptions;
+  /** Server shim options */
+  serverShim?: ServerShimOptions;
+  /** Standard Next.js config options (webpack, rewrites, headers, etc.) - passed through as-is */
+  [key: string]: any;
+}
+
+/**
+ * Creates a Next.js configuration optimized for DNDev applications
+ *
+ * @version 0.0.1
+ * @since 0.0.1
+ * @author AMBROISE PARK Consulting
+ */
+declare function defineNextConfig(options?: NextConfigOptions): any;
+
+export { defineNextConfig };
+export type { NextConfigOptions };