@donotdev/ui 0.0.2 → 0.0.4

package/dist/utils/assetResolver.d.ts

@@ -1,7 +1,7 @@
 /**
  * Asset formats interface
  *
- * @version 0.0.1
+ * @version 0.0.3
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
@@ -14,7 +14,7 @@ export interface AssetFormats {
 /**
  * Favicon set interface
  *
- * @version 0.0.1
+ * @version 0.0.3
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
@@ -58,7 +58,7 @@ interface AssetManifest {
  * Modern asset resolution with format preference and browser capability detection
  * Follows Next.js Image optimization patterns
  *
- * @version 0.0.1
+ * @version 0.0.3
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
@@ -126,7 +126,7 @@ export declare class AssetResolver {
 /**
  * Utility function for logo resolution
  *
- * @version 0.0.1
+ * @version 0.0.3
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
@@ -134,7 +134,7 @@ export declare function resolveLogo(customPath?: string): string;
 /**
  * Utility function for favicon resolution
  *
- * @version 0.0.1
+ * @version 0.0.3
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */

package/dist/utils/assetResolver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assetResolver.d.ts","sourceRoot":"","sources":["../../src/utils/assetResolver.ts"],"names":[],"mappings":"AAaA;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,cAAc;IACtB,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;KACtB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,GAAG,CAAC,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,CAAC,EAAE;QACd,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACrB,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB;AAKD;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAA0B;IAE9C;;OAEG;IACH,MAAM,CAAC,iBAAiB,IAAI,cAAc;IAyC1C;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAmBlC;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAYzC;;OAEG;IACH,MAAM,CAAC,gBAAgB,IAAI,aAAa,GAAG,IAAI;IAM/C;;;;OAIG;IACH,MAAM,CAAC,iBAAiB,IAAI,MAAM,GAAG,IAAI;IAKzC;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM;IAe/C;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAgB/B;;;OAGG;IACH,MAAM,CAAC,iBAAiB,IAAI,UAAU;IAkDtC;;OAEG;IACH,MAAM,CAAC,cAAc,IAAI,MAAM;IAuB/B;;;OAGG;IACH,MAAM,CAAC,UAAU,IAAI,IAAI;IASzB;;OAEG;IACH,MAAM,CAAC,YAAY;;;;;;;;CAQpB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,UAAU,CAE9C;AAgBD,eAAe,aAAa,CAAC"}
+{"version":3,"file":"assetResolver.d.ts","sourceRoot":"","sources":["../../src/utils/assetResolver.ts"],"names":[],"mappings":"AAaA;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,cAAc;IACtB,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;CACf;AAED,UAAU,aAAa;IACrB,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;KACtB,CAAC;IACF,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,GAAG,CAAC,EAAE,UAAU,CAAC;KAClB,CAAC;IACF,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,aAAa,CAAC,EAAE;QACd,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACrB,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC;CAChB;AAKD;;;;;;;GAOG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAA0B;IAE9C;;OAEG;IACH,MAAM,CAAC,iBAAiB,IAAI,cAAc;IAyC1C;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,mBAAmB;IAmBlC;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAYzC;;OAEG;IACH,MAAM,CAAC,gBAAgB,IAAI,aAAa,GAAG,IAAI;IAM/C;;;;OAIG;IACH,MAAM,CAAC,iBAAiB,IAAI,MAAM,GAAG,IAAI;IAKzC;;;OAGG;IACH,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM;IAe/C;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAgB/B;;;OAGG;IACH,MAAM,CAAC,iBAAiB,IAAI,UAAU;IA6DtC;;OAEG;IACH,MAAM,CAAC,cAAc,IAAI,MAAM;IAuB/B;;;OAGG;IACH,MAAM,CAAC,UAAU,IAAI,IAAI;IASzB;;OAEG;IACH,MAAM,CAAC,YAAY;;;;;;;;CAQpB;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,UAAU,CAE9C;AAgBD,eAAe,aAAa,CAAC"}

package/dist/utils/assetResolver.js

@@ -3,7 +3,7 @@
  * @fileoverview Modern asset resolution system for DoNotDev
  * @description Handles logo and favicon resolution with format preferences and fallbacks
  *
- * @version 0.0.1
+ * @version 0.0.3
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
@@ -14,7 +14,7 @@ import { getDndevConfig, isClient, isDev } from '@donotdev/core';
  * Modern asset resolution with format preference and browser capability detection
  * Follows Next.js Image optimization patterns
  *
- * @version 0.0.1
+ * @version 0.0.3
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
@@ -164,38 +164,49 @@ export class AssetResolver {
         const manifest = this.getAssetManifest();
         if (manifest?.favicon?.set) {
             const set = manifest.favicon.set;
+            // Use icon-512x512.png as fallback (generated from logo.svg)
+            const fallbackIcon = this.assetExists('/icon-512x512.png')
+                ? '/icon-512x512.png'
+                : this.assetExists('/icon-192x192.png')
+                    ? '/icon-192x192.png'
+                    : '/logo.svg';
             // Filter out null values and provide framework fallbacks
             const resolvedSet = {
                 svg: set.svg || '/favicon.svg',
                 ico: set.ico || '/favicon.ico',
-                png16: set.png16 || '/logo.png',
-                png32: set.png32 || '/logo.png',
-                apple180: set.apple180 || '/logo.png',
-                android192: set.android192 || '/logo.png',
-                android512: set.android512 || '/logo.png',
+                png16: set.png16 || fallbackIcon,
+                png32: set.png32 || fallbackIcon,
+                apple180: set.apple180 || fallbackIcon,
+                android192: set.android192 || fallbackIcon,
+                android512: set.android512 || fallbackIcon,
             };
             this.cache.set(cacheKey, resolvedSet);
             return resolvedSet;
         }
-        // Manual detection fallback
+        // Manual detection fallback - use generated icons instead of logo.png
+        const fallbackIcon = this.assetExists('/icon-512x512.png')
+            ? '/icon-512x512.png'
+            : this.assetExists('/icon-192x192.png')
+                ? '/icon-192x192.png'
+                : '/logo.svg';
         const faviconSet = {
             svg: this.assetExists('/favicon.svg') ? '/favicon.svg' : '/logo.svg',
             ico: this.assetExists('/favicon.ico') ? '/favicon.ico' : '/favicon.svg',
             png16: this.assetExists('/favicon-16x16.png')
                 ? '/favicon-16x16.png'
-                : '/logo.png',
+                : fallbackIcon,
             png32: this.assetExists('/favicon-32x32.png')
                 ? '/favicon-32x32.png'
-                : '/logo.png',
+                : fallbackIcon,
             apple180: this.assetExists('/apple-touch-icon.png')
                 ? '/apple-touch-icon.png'
-                : '/logo.png',
+                : fallbackIcon,
             android192: this.assetExists('/icon-192x192.png')
                 ? '/icon-192x192.png'
-                : '/logo.png',
+                : fallbackIcon,
             android512: this.assetExists('/icon-512x512.png')
                 ? '/icon-512x512.png'
-                : '/logo.png',
+                : fallbackIcon,
         };
         this.cache.set(cacheKey, faviconSet);
         return faviconSet;
@@ -248,7 +259,7 @@ export class AssetResolver {
 /**
  * Utility function for logo resolution
  *
- * @version 0.0.1
+ * @version 0.0.3
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
@@ -258,7 +269,7 @@ export function resolveLogo(customPath) {
 /**
  * Utility function for favicon resolution
  *
- * @version 0.0.1
+ * @version 0.0.3
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */

package/dist/utils/index.d.ts

@@ -13,4 +13,5 @@ export * from './useStripeBillingSafe';
 export * from './useBillingVisibility';
 export * from './useCrudSafe';
 export * from './useOAuthSafe';
+export * from './tList';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,cAAc,iBAAiB,CAAC;AAChC,cAAc,eAAe,CAAC;AAC9B,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,SAAS,CAAC"}

package/dist/utils/index.js

@@ -14,3 +14,4 @@ export * from './useStripeBillingSafe';
 export * from './useBillingVisibility';
 export * from './useCrudSafe';
 export * from './useOAuthSafe';
+export * from './tList';

package/dist/utils/tList.d.ts

@@ -0,0 +1,30 @@
+import type { LucideIcon } from 'lucide-react';
+import type { TFunction } from 'i18next';
+import type { ReactNode } from 'react';
+/**
+ * Renders a translated array as a List with optional icon
+ *
+ * Opinionated helper that reduces boilerplate for the common pattern:
+ * `<List icon={<CheckCircle size={16} />} items={translateArray(t, key, count)} />`
+ *
+ * @param t - Translation function from useTranslation
+ * @param key - Translation key prefix for the array
+ * @param count - Maximum number of items to fetch
+ * @param icon - Lucide icon, null for no icon, or undefined for default (CheckCircle)
+ * @param size - Optional icon size (default: 16)
+ * @returns ReactNode containing the List component
+ *
+ * @example
+ * ```tsx
+ * // With default icon (CheckCircle)
+ * <Card content={tList(t, 'features.items', 4)} />
+ *
+ * // With custom icon
+ * <Card content={tList(t, 'features.items', 4, Star)} />
+ *
+ * // Without icon (for emoji-prefixed labels like "🚀 Kick-off")
+ * <Card content={tList(t, 'features.items', 4, null)} />
+ * ```
+ */
+export declare function tList(t: TFunction, key: string, count: number, icon?: LucideIcon | null, size?: number): ReactNode;
+//# sourceMappingURL=tList.d.ts.map

package/dist/utils/tList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tList.d.ts","sourceRoot":"","sources":["../../src/utils/tList.tsx"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAevC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,KAAK,CACnB,CAAC,EAAE,SAAS,EACZ,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,UAAU,GAAG,IAAmB,EACtC,IAAI,GAAE,MAAqB,GAC1B,SAAS,CAUX"}

package/dist/utils/tList.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// packages/ui/src/utils/tList.tsx
+/**
+ * @fileoverview Translated List helper
+ * @description Opinionated helper for rendering translated content as List
+ *
+ * @version 0.0.1
+ * @since 0.0.4
+ * @author AMBROISE PARK Consulting
+ */
+import { CheckCircle } from 'lucide-react';
+import { List } from '@donotdev/components';
+import { translateArray } from '@donotdev/core';
+/**
+ * Framework default icon for list items
+ */
+const DEFAULT_ICON = CheckCircle;
+/**
+ * Framework default icon size (matches --icon-sm)
+ */
+const DEFAULT_SIZE = 16;
+/**
+ * Renders a translated array as a List with optional icon
+ *
+ * Opinionated helper that reduces boilerplate for the common pattern:
+ * `<List icon={<CheckCircle size={16} />} items={translateArray(t, key, count)} />`
+ *
+ * @param t - Translation function from useTranslation
+ * @param key - Translation key prefix for the array
+ * @param count - Maximum number of items to fetch
+ * @param icon - Lucide icon, null for no icon, or undefined for default (CheckCircle)
+ * @param size - Optional icon size (default: 16)
+ * @returns ReactNode containing the List component
+ *
+ * @example
+ * ```tsx
+ * // With default icon (CheckCircle)
+ * <Card content={tList(t, 'features.items', 4)} />
+ *
+ * // With custom icon
+ * <Card content={tList(t, 'features.items', 4, Star)} />
+ *
+ * // Without icon (for emoji-prefixed labels like "🚀 Kick-off")
+ * <Card content={tList(t, 'features.items', 4, null)} />
+ * ```
+ */
+export function tList(t, key, count, icon = DEFAULT_ICON, size = DEFAULT_SIZE) {
+    const Icon = icon;
+    const iconElement = Icon ? _jsx(Icon, { size: size }) : undefined;
+    return (_jsx(List, { icon: iconElement, items: translateArray(t, key, count), style: { listStyle: 'none', paddingInlineStart: 0 } }));
+}

package/dist/utils/useAuthSafe.d.ts

@@ -3,18 +3,31 @@
  * @description Provides auth functionality when @donotdev/auth is installed,
  * gracefully degrades to no-op when not installed.
  *
- * **How it works:**
- * 1. Import @donotdev/auth (Vite aliases to empty module if not installed)
- * 2. Check if useAuth export exists
- * 3. If exists → use real hook | If not → use stub
- *
- * **Why this pattern:**
- * - Vite aliases missing packages to empty modules at build time
- * - Decision is made ONCE at import time, never changes
- * - No conditional hook calls = no Rules of Hooks violations
- * - Real hook handles all runtime state (Firebase, consent) internally
- *
- * @version 0.0.1
+ * ## CRITICAL: DO NOT USE DYNAMIC IMPORTS
+ *
+ * This file MUST use sync `import * as authModule from '@donotdev/auth'`
+ * at module level. DO NOT refactor to use async `import('@donotdev/auth').then(...)`.
+ *
+ * ### Why sync import is required:
+ *
+ * 1. **Bundler aliasing**: Vite/webpack alias missing packages to empty modules
+ *    at BUILD TIME. The import completes immediately (no async).
+ *
+ * 2. **Rules of Hooks**: If we use async dynamic import:
+ *    - First render: `realUseAuth = null` → uses stub (0 hooks)
+ *    - Async completes: `realUseAuth = useAuth` → now has hooks
+ *    - Next render: React sees different hook count → CRASH
+ *
+ * 3. **Monorepo gotcha**: Dynamic imports resolve workspace packages even when
+ *    the consuming app doesn't have them as dependencies. This causes the
+ *    real hook to activate unexpectedly → Rules of Hooks violation.
+ *
+ * 4. **Decision is immutable**: With sync import, `authModule?.useAuth` is
+ *    evaluated ONCE at module load. It's either the real hook or undefined.
+ *    This never changes during the app lifecycle.
+ *
+ * @see docs/development/GRACEFUL_DEGRADATION.md
+ * @version 0.0.4
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */

package/dist/utils/useAuthSafe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAuthSafe.d.ts","sourceRoot":"","sources":["../../src/utils/useAuthSafe.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAkB9C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAKvE;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,SAAoC,CAAC"}
+{"version":3,"file":"useAuthSafe.d.ts","sourceRoot":"","sources":["../../src/utils/useAuthSafe.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAoB9C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,OAAO,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAKvE;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,SAAoC,CAAC"}

package/dist/utils/useAuthSafe.js

@@ -1,7 +1,9 @@
 // packages/ui/src/utils/useAuthSafe.ts
 import { DEGRADED_AUTH_API } from '@donotdev/core';
+// Sync import - bundler aliases to empty module if not installed
+// Decision made ONCE at module load time, never changes
 import * as authModule from '@donotdev/auth';
-// Check if real hook exists (will be undefined if Vite aliased to empty module)
+// Extract useAuth if available (undefined if package not installed/aliased)
 const realUseAuth = authModule?.useAuth;
 /**
  * Stub that returns degraded auth values.

package/dist/utils/useAuthVisibility.d.ts

@@ -20,9 +20,9 @@ export interface AuthVisibilityState {
  * Hook to determine auth UI visibility and loading states
  *
  * **Visibility Rules:**
- * - Hide if `!initialized || !isAvailable` (not ready or not installed)
- * - Show with loading if `loading` during operations (user action in progress)
- * - Show normal UI when `initialized && isAvailable && !loading`
+ * - Hide if `status !== 'ready' || !isAvailable` (not ready or not installed)
+ * - Show with loading if `status === 'initializing'` during operations
+ * - Show normal UI when `status === 'ready' && isAvailable`
  *
  * @returns AuthVisibilityState with visibility flags
  *

package/dist/utils/useAuthVisibility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAuthVisibility.d.ts","sourceRoot":"","sources":["../../src/utils/useAuthVisibility.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,IAAI,mBAAmB,CAkBvD"}
+{"version":3,"file":"useAuthVisibility.d.ts","sourceRoot":"","sources":["../../src/utils/useAuthVisibility.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,IAAI,mBAAmB,CAqBvD"}

package/dist/utils/useAuthVisibility.js

@@ -1,25 +1,26 @@
 // packages/ui/src/utils/useAuthVisibility.ts
 /**
  * @fileoverview useAuthVisibility Hook
- * @description Determines when to show/hide auth UI based on initialization and loading states
+ * @description Determines when to show/hide auth UI based on feature status
  *
  * This hook encapsulates the common pattern for auth UI visibility:
- * - Hide if not initialized or not available (not ready yet)
- * - Show with loading state during operations (user action in progress)
- * - Show normal UI when ready
+ * - Hide if status !== 'ready' or not available (not ready yet)
+ * - Show with loading state during initialization
+ * - Show normal UI when status === 'ready'
  *
- * @version 0.0.1
+ * @version 0.0.3
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
+import { useMemo } from 'react';
 import { useAuthSafe } from './useAuthSafe';
 /**
  * Hook to determine auth UI visibility and loading states
  *
  * **Visibility Rules:**
- * - Hide if `!initialized || !isAvailable` (not ready or not installed)
- * - Show with loading if `loading` during operations (user action in progress)
- * - Show normal UI when `initialized && isAvailable && !loading`
+ * - Hide if `status !== 'ready' || !isAvailable` (not ready or not installed)
+ * - Show with loading if `status === 'initializing'` during operations
+ * - Show normal UI when `status === 'ready' && isAvailable`
  *
  * @returns AuthVisibilityState with visibility flags
  *
@@ -41,19 +42,22 @@ import { useAuthSafe } from './useAuthSafe';
  * ```
  */
 export function useAuthVisibility() {
-    const initialized = useAuthSafe('initialized');
-    const authStateChecked = useAuthSafe('authStateChecked');
-    const loading = useAuthSafe('loading');
+    // Read all values first - each triggers subscription
+    const status = useAuthSafe('status');
     const isAvailable = useAuthSafe('isAvailable');
     const user = useAuthSafe('user');
-    const shouldHide = !initialized || !isAvailable;
-    const isLoading = Boolean(loading);
-    const isReady = initialized && isAvailable && authStateChecked;
-    const isAuthenticated = Boolean(user);
-    return {
-        shouldHide,
-        isLoading,
-        isReady,
-        isAuthenticated,
-    };
+    // Derive all visibility state atomically from current values
+    // useMemo ensures consistent state within a single render
+    return useMemo(() => {
+        const shouldHide = status !== 'ready' || !isAvailable;
+        const isLoading = status === 'initializing';
+        const isReady = status === 'ready' && isAvailable;
+        const isAuthenticated = Boolean(user);
+        return {
+            shouldHide,
+            isLoading,
+            isReady,
+            isAuthenticated,
+        };
+    }, [status, isAvailable, user]);
 }

package/dist/utils/useBillingVisibility.d.ts

@@ -17,8 +17,8 @@ export interface BillingVisibilityState {
  *
  * **Visibility Rules:**
  * - Hide if `!isAvailable` (not installed/configured)
- * - Show with loading if `loading` during operations (user action in progress)
- * - Show normal UI when `isAvailable && !loading`
+ * - Show with loading if `status === 'initializing'` during operations
+ * - Show normal UI when `isAvailable && status === 'ready'`
  *
  * @returns BillingVisibilityState with visibility flags
  *

package/dist/utils/useBillingVisibility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useBillingVisibility.d.ts","sourceRoot":"","sources":["../../src/utils/useBillingVisibility.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,oBAAoB,IAAI,sBAAsB,CA2B7D"}
+{"version":3,"file":"useBillingVisibility.d.ts","sourceRoot":"","sources":["../../src/utils/useBillingVisibility.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,UAAU,EAAE,OAAO,CAAC;IAEpB;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,oBAAoB,IAAI,sBAAsB,CA0B7D"}

package/dist/utils/useBillingVisibility.js

@@ -1,14 +1,14 @@
 // packages/ui/src/utils/useBillingVisibility.ts
 /**
  * @fileoverview useBillingVisibility Hook
- * @description Determines when to show/hide billing UI based on availability and loading states
+ * @description Determines when to show/hide billing UI based on feature status
  *
  * This hook encapsulates the common pattern for billing UI visibility:
  * - Hide if not available (not installed/configured)
- * - Show with loading state during operations
- * - Show normal UI when ready
+ * - Show with loading state during initialization
+ * - Show normal UI when status === 'ready'
  *
- * @version 0.0.1
+ * @version 0.0.3
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
@@ -19,8 +19,8 @@ import { useStripeBillingSafe } from './useStripeBillingSafe';
  *
  * **Visibility Rules:**
  * - Hide if `!isAvailable` (not installed/configured)
- * - Show with loading if `loading` during operations (user action in progress)
- * - Show normal UI when `isAvailable && !loading`
+ * - Show with loading if `status === 'initializing'` during operations
+ * - Show normal UI when `isAvailable && status === 'ready'`
  *
  * @returns BillingVisibilityState with visibility flags
  *
@@ -42,16 +42,15 @@ import { useStripeBillingSafe } from './useStripeBillingSafe';
 export function useBillingVisibility() {
     // Get auth state for billing (required for isAvailable to work)
     const user = useAuthSafe('user');
-    const initialized = useAuthSafe('initialized');
-    const authStateChecked = useAuthSafe('authStateChecked');
-    const authState = { user, initialized, authStateChecked };
-    const loading = useStripeBillingSafe('loading', authState);
+    const status = useAuthSafe('status');
+    const authState = { user, status };
+    const billingStatus = useStripeBillingSafe('status', authState);
     const isAvailable = useStripeBillingSafe('isAvailable', authState);
     const shouldHide = !isAvailable;
-    const isLoading = Boolean(loading);
-    const isReady = isAvailable;
+    const isLoading = billingStatus === 'initializing';
+    const isReady = isAvailable && billingStatus === 'ready';
     console.log('[useBillingVisibility]', {
-        loading,
+        billingStatus,
         isAvailable,
         shouldHide,
         isLoading,

package/dist/utils/useCrudSafe.d.ts

@@ -17,7 +17,7 @@ interface UseCrudOptions<T> {
  * @example
  * ```typescript
  * const crud = useCrudSafe('users', { backend: 'firestore', schema: UserSchema });
- * const { data, loading, error, get, set } = crud;
+ * const { data, status, error, get, set } = crud;
  * ```
  */
 export declare function useCrudSafe<T = unknown>(collection: string, options?: UseCrudOptions<T>): CrudAPI<T>;

package/dist/utils/useCrudSafe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useCrudSafe.d.ts","sourceRoot":"","sources":["../../src/utils/useCrudSafe.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAK3D,KAAK,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAE7C,UAAU,cAAc,CAAC,CAAC;IACxB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;CACzB;AAeD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,OAAO,EACrC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,cAAc,CAAC,CAAC,CAAM,GAC9B,OAAO,CAAC,CAAC,CAAC,CAKZ;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,SAAoC,CAAC"}
+{"version":3,"file":"useCrudSafe.d.ts","sourceRoot":"","sources":["../../src/utils/useCrudSafe.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAK3D,KAAK,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAE7C,UAAU,cAAc,CAAC,CAAC;IACxB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;CACzB;AAeD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,CAAC,GAAG,OAAO,EACrC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,cAAc,CAAC,CAAC,CAAM,GAC9B,OAAO,CAAC,CAAC,CAAC,CAKZ;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,SAAoC,CAAC"}

package/dist/utils/useCrudSafe.js

@@ -4,18 +4,31 @@
  * @description Provides CRUD functionality when @donotdev/crud is installed,
  * gracefully degrades to no-op when not installed.
  *
- * **How it works:**
- * 1. Import @donotdev/crud (Vite aliases to empty module if not installed)
- * 2. Check if useCrud export exists
- * 3. If exists → use real hook | If not → use stub
- *
- * **Why this pattern:**
- * - Vite aliases missing packages to empty modules at build time
- * - Decision is made ONCE at import time, never changes
- * - No conditional hook calls = no Rules of Hooks violations
- * - Real hook handles all runtime state (Firebase, consent) internally
- *
- * @version 0.0.1
+ * ## CRITICAL: DO NOT USE DYNAMIC IMPORTS
+ *
+ * This file MUST use sync `import * as crudModule from '@donotdev/crud'`
+ * at module level. DO NOT refactor to use async `import('@donotdev/crud').then(...)`.
+ *
+ * ### Why sync import is required:
+ *
+ * 1. **Bundler aliasing**: Vite/webpack alias missing packages to empty modules
+ *    at BUILD TIME. The import completes immediately (no async).
+ *
+ * 2. **Rules of Hooks**: If we use async dynamic import:
+ *    - First render: `realUseCrud = null` → uses stub (0 hooks)
+ *    - Async completes: `realUseCrud = useCrud` → now has hooks
+ *    - Next render: React sees different hook count → CRASH
+ *
+ * 3. **Monorepo gotcha**: Dynamic imports resolve workspace packages even when
+ *    the consuming app doesn't have them as dependencies. This causes the
+ *    real hook to activate unexpectedly → Rules of Hooks violation.
+ *
+ * 4. **Decision is immutable**: With sync import, `crudModule?.useCrud`
+ *    is evaluated ONCE at module load. It's either the real hook or undefined.
+ *    This never changes during the app lifecycle.
+ *
+ * @see docs/development/GRACEFUL_DEGRADATION.md
+ * @version 0.0.4
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */
@@ -43,7 +56,7 @@ function useCrudStub() {
  * @example
  * ```typescript
  * const crud = useCrudSafe('users', { backend: 'firestore', schema: UserSchema });
- * const { data, loading, error, get, set } = crud;
+ * const { data, status, error, get, set } = crud;
  * ```
  */
 export function useCrudSafe(collection, options = {}) {

package/dist/utils/useOAuthSafe.d.ts

@@ -3,18 +3,31 @@
  * @description Provides OAuth functionality when @donotdev/oauth is installed,
  * gracefully degrades to no-op when not installed.
  *
- * **How it works:**
- * 1. Import @donotdev/oauth (Vite aliases to empty module if not installed)
- * 2. Check if useOAuth export exists
- * 3. If exists → use real hook | If not → use stub
- *
- * **Why this pattern:**
- * - Vite aliases missing packages to empty modules at build time
- * - Decision is made ONCE at import time, never changes
- * - No conditional hook calls = no Rules of Hooks violations
- * - Real hook handles all runtime state (credentials, consent) internally
- *
- * @version 0.0.1
+ * ## CRITICAL: DO NOT USE DYNAMIC IMPORTS
+ *
+ * This file MUST use sync `import * as oauthModule from '@donotdev/oauth'`
+ * at module level. DO NOT refactor to use async `import('@donotdev/oauth').then(...)`.
+ *
+ * ### Why sync import is required:
+ *
+ * 1. **Bundler aliasing**: Vite/webpack alias missing packages to empty modules
+ *    at BUILD TIME. The import completes immediately (no async).
+ *
+ * 2. **Rules of Hooks**: If we use async dynamic import:
+ *    - First render: `realUseOAuth = null` → uses stub (0 hooks)
+ *    - Async completes: `realUseOAuth = useOAuth` → now has hooks
+ *    - Next render: React sees different hook count → CRASH
+ *
+ * 3. **Monorepo gotcha**: Dynamic imports resolve workspace packages even when
+ *    the consuming app doesn't have them as dependencies. This causes the
+ *    real hook to activate unexpectedly → Rules of Hooks violation.
+ *
+ * 4. **Decision is immutable**: With sync import, `oauthModule?.useOAuth`
+ *    is evaluated ONCE at module load. It's either the real hook or undefined.
+ *    This never changes during the app lifecycle.
+ *
+ * @see docs/development/GRACEFUL_DEGRADATION.md
+ * @version 0.0.2
  * @since 0.0.1
  * @author AMBROISE PARK Consulting
  */

package/dist/utils/useOAuthSafe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useOAuthSafe.d.ts","sourceRoot":"","sources":["../../src/utils/useOAuthSafe.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAkB/C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,GAAG,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAK1E;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,SAAqC,CAAC"}
+{"version":3,"file":"useOAuthSafe.d.ts","sourceRoot":"","sources":["../../src/utils/useOAuthSafe.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAkB/C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,QAAQ,EAAE,GAAG,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAK1E;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,SAAqC,CAAC"}