svelte-firekit 0.2.4 → 0.2.6

package/README.md

@@ -7,6 +7,8 @@ A complete Firebase integration library for **Svelte 5** and **SvelteKit**. Buil
 - SSR-safe — all services degrade gracefully on the server
 - Works without SvelteKit (`$app/*`, `$env/*` are never imported)
 
+**Documentation:** [sveltefirekit.com](https://sveltefirekit.com/)
+
 ---
 
 ## Installation
@@ -162,28 +164,41 @@ try {
 
 ```ts
 // Wait for auth to initialize (useful for SSR / load functions)
-const user = await firekitUser.waitForAuth();
+const user = await firekitUser.waitForAuth();        // 10s timeout (default)
+const user = await firekitUser.waitForAuth(5_000);   // custom timeout in ms
 ```
 
 ### Auth components
 
+All auth components wait for Firebase Auth to initialize before rendering. Use the optional `fallback` snippet to show a loading state.
+
 ```svelte
-<SignedIn>  <p>Only shown when signed in</p>  </SignedIn>
-<SignedOut> <p>Only shown when signed out</p> </SignedOut>
+<SignedIn>
+  {#snippet children(user)}<p>Welcome, {user.displayName}</p>{/snippet}
+  {#snippet fallback()}<p>Loading...</p>{/snippet}
+</SignedIn>
+
+<SignedOut>
+  {#snippet children(signIn)}<button onclick={signIn}>Sign in</button>{/snippet}
+  {#snippet fallback()}<p>Loading...</p>{/snippet}
+</SignedOut>
 
 <!-- Route guard with redirect callback -->
 <AuthGuard requireAuth={true} onUnauthorized={() => goto('/login')}>
-  <p>Protected content</p>
+  {#snippet children(user, signOut)}<p>Protected content</p>{/snippet}
+  {#snippet fallback()}<p>Loading...</p>{/snippet}
 </AuthGuard>
 
 <!-- Custom guard with async checks (e.g. role verification) -->
 <CustomGuard
   verificationChecks={[
-    async () => { const doc = await getDoc(...); return doc.data()?.role === 'admin'; }
+    async (user) => user.emailVerified,
+    async (user) => { const doc = await getDoc(...); return doc.data()?.role === 'admin'; }
   ]}
   onUnauthorized={() => goto('/403')}
 >
-  <p>Admin only</p>
+  {#snippet children(user, signOut)}<p>Admin only</p>{/snippet}
+  {#snippet fallback()}<p>Checking permissions...</p>{/snippet}
 </CustomGuard>
 ```
 
@@ -415,16 +430,44 @@ List files:
 {#each dir.items as item}<p>{item.name}</p>{/each}
 ```
 
-Using the `<DownloadURL>` and `<UploadTask>` components:
+### File upload validation
+
+Validate files before uploading — checks size, MIME type, and image dimensions.
+
+```ts
+import { validateFile } from 'svelte-firekit';
+
+const result = await validateFile(file, {
+  maxSize: 5 * 1024 * 1024,          // 5 MB
+  accept: ['image/png', 'image/jpeg', '.webp'],
+  maxWidth: 2048,
+  maxHeight: 2048,
+  minWidth: 100
+});
+
+if (!result.valid) {
+  result.errors.forEach((e) => console.log(e.code, e.message));
+}
+```
+
+The `<UploadTask>` component supports an optional `validate` prop and `invalid` snippet:
+
+```svelte
+<UploadTask path="uploads/{file.name}" {file} validate={{ maxSize: 5_000_000, accept: ['image/*'] }}>
+  {#snippet uploading(task)}<progress value={task.progress} max={100} />{/snippet}
+  {#snippet complete(url)}<img src={url} alt="uploaded" />{/snippet}
+  {#snippet invalid(result)}
+    {#each result.errors as err}<p class="error">{err.message}</p>{/each}
+  {/snippet}
+</UploadTask>
+```
+
+Using the `<DownloadURL>` component:
 
 ```svelte
 <DownloadURL path="images/avatar.jpg">
   {#snippet data(url)}<img src={url} />{/snippet}
 </DownloadURL>
-
-<UploadTask path="uploads/file.jpg" {file}>
-  {#snippet data({ progress, downloadURL })}<progress value={progress} max={100} />{/snippet}
-</UploadTask>
 ```
 
 ---
@@ -566,6 +609,44 @@ firekitInAppMessaging.unsuppress();
 
 ---
 
+## Network / Offline Status
+
+Track browser connectivity and Firestore sync state reactively.
+
+```svelte
+<script lang="ts">
+  import { firekitNetwork } from 'svelte-firekit';
+</script>
+
+{#if !firekitNetwork.online}
+  <p>You're offline. Changes will sync when reconnected.</p>
+{:else if firekitNetwork.hasPendingWrites}
+  <p>Saving...</p>
+{:else}
+  <p>All changes saved</p>
+{/if}
+```
+
+Using the `<NetworkStatus>` component:
+
+```svelte
+<NetworkStatus>
+  {#snippet online()}<span class="green">Connected</span>{/snippet}
+  {#snippet offline()}<span class="red">Offline</span>{/snippet}
+  {#snippet pending()}<span>Saving...</span>{/snippet}
+</NetworkStatus>
+```
+
+Manual control:
+
+```ts
+await firekitNetwork.goOffline();   // force offline mode
+await firekitNetwork.goOnline();    // reconnect
+firekitNetwork.trackWrite();        // mark a pending write
+```
+
+---
+
 ## Presence
 
 ```ts
@@ -656,6 +737,7 @@ const data = await posts.waitForReady();
 | `firekitAnalytics` | Analytics event logging |
 | `firekitMessaging` | Firebase Cloud Messaging |
 | `firekitInAppMessaging` | In-App Messaging suppression control |
+| `firekitNetwork` | Reactive network/offline status |
 | `firekitAppCheck` | App Check initialization |
 
 ### Reactive classes
@@ -676,6 +758,12 @@ const data = await posts.waitForReady();
 | `FirekitCallable` / `firekitCallable()` | Typed Cloud Function caller |
 | `FirekitCallableFromURL` / `firekitCallableFromURL()` | Cloud Function by URL |
 
+### Utilities
+
+| Import | Description |
+|---|---|
+| `validateFile()` | Pre-upload file validation (size, type, dimensions) |
+
 ### Components
 
 | Component | Description |
@@ -689,7 +777,8 @@ const data = await posts.waitForReady();
 | `<Collection>` | Reactive Firestore collection |
 | `<Node>` | Reactive RTDB node |
 | `<DownloadURL>` | Storage download URL |
-| `<UploadTask>` | Resumable file upload |
+| `<UploadTask>` | Resumable file upload with optional validation |
+| `<NetworkStatus>` | Network/sync status display |
 
 ---
 

package/dist/components/NetworkStatus.svelte

@@ -0,0 +1,37 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { firekitNetwork } from '../services/network.svelte.js';
+
+	/**
+	 * Renders snippets based on network/sync status.
+	 *
+	 * @example
+	 * ```svelte
+	 * <NetworkStatus>
+	 *   {#snippet online()}<span class="dot green" />{/snippet}
+	 *   {#snippet offline()}<span class="dot red">Offline</span>{/snippet}
+	 *   {#snippet pending()}<span>Saving...</span>{/snippet}
+	 * </NetworkStatus>
+	 * ```
+	 */
+	let {
+		online: onlineSnippet,
+		offline: offlineSnippet,
+		pending: pendingSnippet
+	}: {
+		/** Rendered when online and all writes are synced. */
+		online?: Snippet;
+		/** Rendered when the browser is offline. */
+		offline?: Snippet;
+		/** Rendered when there are pending Firestore writes. */
+		pending?: Snippet;
+	} = $props();
+</script>
+
+{#if !firekitNetwork.online && offlineSnippet}
+	{@render offlineSnippet()}
+{:else if firekitNetwork.hasPendingWrites && pendingSnippet}
+	{@render pendingSnippet()}
+{:else if firekitNetwork.online && onlineSnippet}
+	{@render onlineSnippet()}
+{/if}

package/dist/components/NetworkStatus.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    /** Rendered when online and all writes are synced. */
+    online?: Snippet;
+    /** Rendered when the browser is offline. */
+    offline?: Snippet;
+    /** Rendered when there are pending Firestore writes. */
+    pending?: Snippet;
+};
+declare const NetworkStatus: import("svelte").Component<$$ComponentProps, {}, "">;
+type NetworkStatus = ReturnType<typeof NetworkStatus>;
+export default NetworkStatus;

package/dist/components/UploadTask.svelte

@@ -2,16 +2,20 @@
 	import type { Snippet } from 'svelte';
 	import type { UploadMetadata } from 'firebase/storage';
 	import { FirekitUploadTask, type UploadState } from '../services/storage.svelte.js';
+	import { validateFile } from '../utils/validation.js';
+	import type { FileValidationOptions, FileValidationResult } from '../types/storage.js';
 
 	/**
 	 * Manages a Firebase Storage upload with reactive progress.
-	 *
-	 * Exposes upload controls (pause, resume, cancel) and progress state
-	 * to the `uploading` snippet.
+	 * Optionally validates the file before uploading.
 	 *
 	 * @example
 	 * ```svelte
-	 * <UploadTask path="uploads/{file.name}" {file}>
+	 * <UploadTask
+	 *   path="uploads/{file.name}"
+	 *   {file}
+	 *   validate={{ maxSize: 5 * 1024 * 1024, accept: ['image/*'] }}
+	 * >
 	 *   {#snippet uploading(task)}
 	 *     <progress value={task.progress} max={100} />
 	 *     <button onclick={task.pause}>Pause</button>
@@ -19,6 +23,11 @@
 	 *   {#snippet complete(url)}
 	 *     <img src={url} alt="uploaded" />
 	 *   {/snippet}
+	 *   {#snippet invalid(result)}
+	 *     {#each result.errors as err}
+	 *       <p class="error">{err.message}</p>
+	 *     {/each}
+	 *   {/snippet}
 	 * </UploadTask>
 	 * ```
 	 */
@@ -26,9 +35,11 @@
 		path,
 		file,
 		metadata,
+		validate,
 		uploading: uploadingSnippet,
 		complete: completeSnippet,
-		error: errorSnippet
+		error: errorSnippet,
+		invalid: invalidSnippet
 	}: {
 		/** Storage destination path. */
 		path: string;
@@ -36,6 +47,8 @@
 		file: Blob | Uint8Array | ArrayBuffer;
 		/** Optional upload metadata (content type, custom metadata, etc.). */
 		metadata?: UploadMetadata;
+		/** Optional validation rules. Only applied when `file` is a File instance. */
+		validate?: FileValidationOptions;
 		/**
 		 * Rendered while the upload is active.
 		 * Receives an object with `{ progress, state, bytesTransferred, totalBytes, pause, resume, cancel }`.
@@ -51,25 +64,55 @@
 		}]>;
 		/** Rendered after a successful upload. Receives the download URL. */
 		complete?: Snippet<[string]>;
-		/** Rendered on error. */
+		/** Rendered on upload error. */
 		error?: Snippet<[Error]>;
+		/** Rendered when validation fails. Receives the validation result with errors. */
+		invalid?: Snippet<[FileValidationResult]>;
 	} = $props();
 
-	const task = new FirekitUploadTask(path, file, metadata);
+	let validationResult = $state<FileValidationResult | null>(null);
+	let task = $state<FirekitUploadTask | null>(null);
+	let started = false;
+
+	// Run validation (if configured) then start upload.
+	// Uses $effect so Svelte properly tracks the prop references.
+	$effect(() => {
+		if (started) return;
+		started = true;
+
+		if (validate && file instanceof File) {
+			validateFile(file, validate).then((result) => {
+				validationResult = result;
+				if (result.valid) {
+					task = new FirekitUploadTask(path, file as Blob, metadata);
+				}
+			});
+		} else {
+			task = new FirekitUploadTask(path, file, metadata);
+		}
+	});
 </script>
 
-{#if task.error && errorSnippet}
-	{@render errorSnippet(task.error)}
-{:else if task.completed && completeSnippet && task.downloadURL}
-	{@render completeSnippet(task.downloadURL)}
-{:else if task.active && uploadingSnippet}
-	{@render uploadingSnippet({
-		progress: task.progress,
-		state: task.state,
-		bytesTransferred: task.bytesTransferred,
-		totalBytes: task.totalBytes,
-		pause: () => task.pause(),
-		resume: () => task.resume(),
-		cancel: () => task.cancel()
-	})}
+{#if validationResult && !validationResult.valid}
+	{#if invalidSnippet}
+		{@render invalidSnippet(validationResult)}
+	{:else if errorSnippet}
+		{@render errorSnippet(new Error(validationResult.errors.map((e) => e.message).join('; ')))}
+	{/if}
+{:else if task}
+	{#if task.error && errorSnippet}
+		{@render errorSnippet(task.error)}
+	{:else if task.completed && completeSnippet && task.downloadURL}
+		{@render completeSnippet(task.downloadURL)}
+	{:else if task.active && uploadingSnippet}
+		{@render uploadingSnippet({
+			progress: task.progress,
+			state: task.state,
+			bytesTransferred: task.bytesTransferred,
+			totalBytes: task.totalBytes,
+			pause: () => task!.pause(),
+			resume: () => task!.resume(),
+			cancel: () => task!.cancel()
+		})}
+	{/if}
 {/if}

package/dist/components/UploadTask.svelte.d.ts

@@ -1,6 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { UploadMetadata } from 'firebase/storage';
 import { type UploadState } from '../services/storage.svelte.js';
+import type { FileValidationOptions, FileValidationResult } from '../types/storage.js';
 type $$ComponentProps = {
     /** Storage destination path. */
     path: string;
@@ -8,6 +9,8 @@ type $$ComponentProps = {
     file: Blob | Uint8Array | ArrayBuffer;
     /** Optional upload metadata (content type, custom metadata, etc.). */
     metadata?: UploadMetadata;
+    /** Optional validation rules. Only applied when `file` is a File instance. */
+    validate?: FileValidationOptions;
     /**
      * Rendered while the upload is active.
      * Receives an object with `{ progress, state, bytesTransferred, totalBytes, pause, resume, cancel }`.
@@ -25,8 +28,10 @@ type $$ComponentProps = {
     ]>;
     /** Rendered after a successful upload. Receives the download URL. */
     complete?: Snippet<[string]>;
-    /** Rendered on error. */
+    /** Rendered on upload error. */
     error?: Snippet<[Error]>;
+    /** Rendered when validation fails. Receives the validation result with errors. */
+    invalid?: Snippet<[FileValidationResult]>;
 };
 declare const UploadTask: import("svelte").Component<$$ComponentProps, {}, "">;
 type UploadTask = ReturnType<typeof UploadTask>;

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export { FirekitRemoteConfig, firekitRemoteConfig, type FirekitRemoteConfigOptio
 export { firekitPerformance, type PerformanceTrace } from './services/performance.js';
 export { firekitMessaging, type MessagePayload } from './services/messaging.svelte.js';
 export { firekitAnalytics } from './services/analytics.js';
+export { firekitNetwork } from './services/network.svelte.js';
 export { loadFirestoreBundle, getNamedQuery } from './services/bundles.js';
 export { default as FirebaseApp } from './components/FirebaseApp.svelte';
 export { default as SignedIn } from './components/SignedIn.svelte';
@@ -31,5 +32,6 @@ export { default as Collection } from './components/Collection.svelte';
 export { default as Node } from './components/Node.svelte';
 export { default as DownloadURL } from './components/DownloadURL.svelte';
 export { default as UploadTask } from './components/UploadTask.svelte';
+export { default as NetworkStatus } from './components/NetworkStatus.svelte';
 export * from './types/index.js';
 export * from './utils/index.js';

package/dist/index.js

@@ -32,6 +32,8 @@ export { firekitPerformance } from './services/performance.js';
 export { firekitMessaging } from './services/messaging.svelte.js';
 // ─── Analytics ────────────────────────────────────────────────────────────────
 export { firekitAnalytics } from './services/analytics.js';
+// ─── Network / Offline ───────────────────────────────────────────────────────
+export { firekitNetwork } from './services/network.svelte.js';
 // ─── Firestore bundles ────────────────────────────────────────────────────────
 export { loadFirestoreBundle, getNamedQuery } from './services/bundles.js';
 // ─── Components ──────────────────────────────────────────────────────────────
@@ -45,6 +47,7 @@ export { default as Collection } from './components/Collection.svelte';
 export { default as Node } from './components/Node.svelte';
 export { default as DownloadURL } from './components/DownloadURL.svelte';
 export { default as UploadTask } from './components/UploadTask.svelte';
+export { default as NetworkStatus } from './components/NetworkStatus.svelte';
 // ─── Types ───────────────────────────────────────────────────────────────────
 export * from './types/index.js';
 // ─── Utilities ───────────────────────────────────────────────────────────────

package/dist/services/ai.svelte.js

@@ -210,7 +210,19 @@ export class FirekitChat {
         // Seed history from initialHistory
         for (const turn of initialHistory) {
             const text = turn.parts
-                .map((p) => ('text' in p ? p.text : ''))
+                .map((p) => {
+                if ('text' in p)
+                    return p.text;
+                if ('inlineData' in p)
+                    return '[image]';
+                if ('fileData' in p)
+                    return '[file]';
+                if ('functionCall' in p)
+                    return `[function: ${p.functionCall.name}]`;
+                if ('functionResponse' in p)
+                    return `[function response: ${p.functionResponse.name}]`;
+                return '[unknown part]';
+            })
                 .filter(Boolean)
                 .join('');
             this._history.push({

package/dist/services/analytics.js

@@ -41,7 +41,11 @@ class FirekitAnalytics {
             if (!supported)
                 return;
             this._analytics = getAnalytics(getApp());
-        })();
+        })().catch((err) => {
+            // Reset so next call retries instead of returning a rejected promise forever
+            this._initPromise = null;
+            throw err;
+        });
         return this._initPromise;
     }
     async _get() {

package/dist/services/auth.d.ts

@@ -18,8 +18,8 @@ declare class FirekitAuth {
     private recaptchaVerifiers;
     private constructor();
     static getInstance(): FirekitAuth;
-    private bootstrap;
     private getAuth;
+    private getFirestore;
     private syncToFirestore;
     private profile;
     signInWithEmail(email: string, password: string): Promise<SignInResult>;

package/dist/services/auth.js

@@ -20,9 +20,8 @@ class FirekitAuth {
     firestore = null;
     recaptchaVerifiers = new Map();
     constructor() {
-        if (typeof window !== 'undefined') {
-            this.bootstrap();
-        }
+        // Do NOT bootstrap here — Firebase config may not be set yet.
+        // Auth and Firestore instances are resolved lazily via getAuth() / getFirestore().
     }
     static getInstance() {
         if (!FirekitAuth.instance) {
@@ -30,20 +29,6 @@ class FirekitAuth {
         }
         return FirekitAuth.instance;
     }
-    bootstrap() {
-        try {
-            this.auth = firebaseService.getAuthInstance();
-            try {
-                this.firestore = firebaseService.getDbInstance();
-            }
-            catch {
-                this.firestore = null;
-            }
-        }
-        catch {
-            // Firebase not yet configured — services will be accessed lazily
-        }
-    }
     getAuth() {
         if (!this.auth) {
             this.auth = firebaseService.getAuthInstance();
@@ -53,10 +38,22 @@ class FirekitAuth {
         }
         return this.auth;
     }
+    getFirestore() {
+        if (!this.firestore) {
+            try {
+                this.firestore = firebaseService.getDbInstance();
+            }
+            catch {
+                this.firestore = null;
+            }
+        }
+        return this.firestore;
+    }
     async syncToFirestore(user) {
-        if (!this.firestore)
+        const fs = this.getFirestore();
+        if (!fs)
             return;
-        await updateUserInFirestore(this.firestore, user);
+        await updateUserInFirestore(fs, user);
     }
     profile(user) {
         return mapFirebaseUserToProfile(user);
@@ -327,9 +324,10 @@ class FirekitAuth {
             if (currentPassword)
                 await this.reauthenticate(currentPassword);
             // Soft-delete record in Firestore before removing auth
-            if (this.firestore) {
+            const fs = this.getFirestore();
+            if (fs) {
                 try {
-                    await setDoc(doc(this.firestore, 'users', user.uid), { deleted: true, deletedAt: serverTimestamp() }, { merge: true });
+                    await setDoc(doc(fs, 'users', user.uid), { deleted: true, deletedAt: serverTimestamp() }, { merge: true });
                 }
                 catch {
                     // Non-blocking
@@ -560,16 +558,22 @@ class FirekitAuth {
     }
     // ─── Utility getters ─────────────────────────────────────────────────────────
     getCurrentUser() {
-        return this.auth?.currentUser ?? null;
+        try {
+            return this.getAuth().currentUser;
+        }
+        catch {
+            return null;
+        }
     }
     isAuthenticated() {
-        return this.auth?.currentUser !== null && !this.auth?.currentUser?.isAnonymous;
+        const user = this.getCurrentUser();
+        return user !== null && !user.isAnonymous;
     }
     isAnonymous() {
-        return this.auth?.currentUser?.isAnonymous ?? false;
+        return this.getCurrentUser()?.isAnonymous ?? false;
     }
     isEmailVerified() {
-        return this.auth?.currentUser?.emailVerified ?? false;
+        return this.getCurrentUser()?.emailVerified ?? false;
     }
     async cleanup() {
         this.recaptchaVerifiers.forEach((v) => v.clear());

package/dist/services/messaging.svelte.d.ts

@@ -33,6 +33,7 @@ declare class FirekitMessaging {
     private _messaging;
     private _unsubscribeMessage;
     private _requesting;
+    private _listening;
     private constructor();
     static getInstance(): FirekitMessaging;
     get token(): string | null;

package/dist/services/messaging.svelte.js

@@ -40,6 +40,7 @@ class FirekitMessaging {
     _messaging = null;
     _unsubscribeMessage = null;
     _requesting = false;
+    _listening = false;
     constructor() {
         this._initPermissionState();
     }
@@ -161,7 +162,10 @@ class FirekitMessaging {
     }
     // ── Foreground messages ───────────────────────────────────────────────────
     _listenForMessages(msg) {
+        if (this._listening)
+            return;
         this._unsubscribeMessage?.();
+        this._listening = true;
         this._unsubscribeMessage = onMessage(msg, (payload) => {
             this._lastMessage = payload;
             this._messages = [...this._messages, payload];
@@ -185,6 +189,7 @@ class FirekitMessaging {
     dispose() {
         this._unsubscribeMessage?.();
         this._unsubscribeMessage = null;
+        this._listening = false;
     }
 }
 export const firekitMessaging = FirekitMessaging.getInstance();

package/dist/services/mutations.js

@@ -46,7 +46,7 @@ async function withRetry(fn, retryConfig) {
             }
         }
     }
-    throw lastError;
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
 }
 /**
  * Firestore document mutations — add, set, update, delete, batch, transaction.

package/dist/services/network.svelte.d.ts

@@ -0,0 +1,71 @@
+import { NetworkError } from '../types/network.js';
+/**
+ * Reactive network/offline status store.
+ *
+ * Tracks browser connectivity, Firestore sync state, and pending writes.
+ * Provides manual control to go offline/online.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { firekitNetwork } from 'svelte-firekit';
+ * </script>
+ *
+ * {#if !firekitNetwork.online}
+ *   <p>You're offline. Changes will sync when reconnected.</p>
+ * {/if}
+ *
+ * {#if firekitNetwork.hasPendingWrites}
+ *   <p>Saving...</p>
+ * {:else}
+ *   <p>All changes saved</p>
+ * {/if}
+ * ```
+ */
+declare class FirekitNetwork {
+    private static instance;
+    private _online;
+    private _synced;
+    private _hasPendingWrites;
+    private _initialized;
+    private _error;
+    private _firestoreEnabled;
+    private _listening;
+    private _db;
+    private _syncUnsub;
+    private _onlineHandler;
+    private _offlineHandler;
+    private constructor();
+    static getInstance(): FirekitNetwork;
+    private ensureListening;
+    /**
+     * Called by FirebaseApp or lazily on first getter access.
+     * Safe to call multiple times.
+     */
+    initialize(): void;
+    /** Whether the browser has network connectivity. */
+    get online(): boolean;
+    /** Whether all Firestore snapshots are in sync with the server. */
+    get synced(): boolean;
+    /** Whether there are unconfirmed Firestore writes. */
+    get hasPendingWrites(): boolean;
+    /** Whether the network store has been initialized. */
+    get initialized(): boolean;
+    /** Last error from network operations. */
+    get error(): NetworkError | null;
+    /** Whether Firestore network is currently enabled. */
+    get firestoreEnabled(): boolean;
+    /**
+     * Call this when you perform a Firestore write to track pending state.
+     * Uses `waitForPendingWrites` to automatically clear when the write is acknowledged.
+     */
+    trackWrite(): void;
+    /** Enables Firestore network access (reconnects to server). */
+    goOnline(): Promise<void>;
+    /** Disables Firestore network access (forces offline mode). */
+    goOffline(): Promise<void>;
+    clearError(): void;
+    dispose(): void;
+}
+export declare const firekitNetwork: FirekitNetwork;
+export {};

package/dist/services/network.svelte.js

@@ -0,0 +1,167 @@
+import { onSnapshotsInSync, enableNetwork, disableNetwork, waitForPendingWrites } from 'firebase/firestore';
+import { firebaseService } from '../firebase.js';
+import { NetworkError, NetworkErrorCode } from '../types/network.js';
+/**
+ * Reactive network/offline status store.
+ *
+ * Tracks browser connectivity, Firestore sync state, and pending writes.
+ * Provides manual control to go offline/online.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { firekitNetwork } from 'svelte-firekit';
+ * </script>
+ *
+ * {#if !firekitNetwork.online}
+ *   <p>You're offline. Changes will sync when reconnected.</p>
+ * {/if}
+ *
+ * {#if firekitNetwork.hasPendingWrites}
+ *   <p>Saving...</p>
+ * {:else}
+ *   <p>All changes saved</p>
+ * {/if}
+ * ```
+ */
+class FirekitNetwork {
+    static instance;
+    // ── Reactive state ──────────────────────────────────────────────────────
+    _online = $state(typeof navigator !== 'undefined' ? navigator.onLine : true);
+    _synced = $state(true);
+    _hasPendingWrites = $state(false);
+    _initialized = $state(false);
+    _error = $state(null);
+    _firestoreEnabled = $state(true);
+    // ── Internal ────────────────────────────────────────────────────────────
+    _listening = false;
+    _db = null;
+    _syncUnsub = null;
+    _onlineHandler = null;
+    _offlineHandler = null;
+    constructor() { }
+    static getInstance() {
+        if (!FirekitNetwork.instance) {
+            FirekitNetwork.instance = new FirekitNetwork();
+        }
+        return FirekitNetwork.instance;
+    }
+    ensureListening() {
+        if (this._listening || typeof window === 'undefined')
+            return;
+        try {
+            const db = firebaseService.getDbInstance();
+            if (!db)
+                return;
+            this._listening = true;
+            // Browser online/offline events
+            this._onlineHandler = () => { this._online = true; };
+            this._offlineHandler = () => { this._online = false; };
+            window.addEventListener('online', this._onlineHandler);
+            window.addEventListener('offline', this._offlineHandler);
+            // Firestore sync state — fires when all active listeners are caught up
+            this._syncUnsub = onSnapshotsInSync(db, () => {
+                this._synced = true;
+                this._hasPendingWrites = false;
+            });
+            this._db = db;
+            this._initialized = true;
+        }
+        catch {
+            // Firestore not configured yet — will retry on next getter access
+        }
+    }
+    /**
+     * Called by FirebaseApp or lazily on first getter access.
+     * Safe to call multiple times.
+     */
+    initialize() {
+        this.ensureListening();
+    }
+    // ── Public getters (reactive) ───────────────────────────────────────────
+    /** Whether the browser has network connectivity. */
+    get online() { this.ensureListening(); return this._online; }
+    /** Whether all Firestore snapshots are in sync with the server. */
+    get synced() { this.ensureListening(); return this._synced; }
+    /** Whether there are unconfirmed Firestore writes. */
+    get hasPendingWrites() { this.ensureListening(); return this._hasPendingWrites; }
+    /** Whether the network store has been initialized. */
+    get initialized() { return this._initialized; }
+    /** Last error from network operations. */
+    get error() { return this._error; }
+    /** Whether Firestore network is currently enabled. */
+    get firestoreEnabled() { return this._firestoreEnabled; }
+    // ── Methods ─────────────────────────────────────────────────────────────
+    /**
+     * Call this when you perform a Firestore write to track pending state.
+     * Uses `waitForPendingWrites` to automatically clear when the write is acknowledged.
+     */
+    trackWrite() {
+        this._hasPendingWrites = true;
+        this._synced = false;
+        if (this._db) {
+            waitForPendingWrites(this._db)
+                .then(() => {
+                this._hasPendingWrites = false;
+                this._synced = true;
+            })
+                .catch(() => {
+                // Firestore may have been disabled
+            });
+        }
+    }
+    /** Enables Firestore network access (reconnects to server). */
+    async goOnline() {
+        try {
+            const db = firebaseService.getDbInstance();
+            if (!db)
+                throw new NetworkError(NetworkErrorCode.FIRESTORE_UNAVAILABLE, 'Firestore is not available.');
+            await enableNetwork(db);
+            this._firestoreEnabled = true;
+            this._error = null;
+        }
+        catch (err) {
+            if (err instanceof NetworkError)
+                throw err;
+            const error = new NetworkError(NetworkErrorCode.ENABLE_NETWORK_FAILED, 'Failed to enable network.', err);
+            this._error = error;
+            throw error;
+        }
+    }
+    /** Disables Firestore network access (forces offline mode). */
+    async goOffline() {
+        try {
+            const db = firebaseService.getDbInstance();
+            if (!db)
+                throw new NetworkError(NetworkErrorCode.FIRESTORE_UNAVAILABLE, 'Firestore is not available.');
+            await disableNetwork(db);
+            this._firestoreEnabled = false;
+            this._error = null;
+        }
+        catch (err) {
+            if (err instanceof NetworkError)
+                throw err;
+            const error = new NetworkError(NetworkErrorCode.DISABLE_NETWORK_FAILED, 'Failed to disable network.', err);
+            this._error = error;
+            throw error;
+        }
+    }
+    clearError() {
+        this._error = null;
+    }
+    dispose() {
+        this._listening = false;
+        this._syncUnsub?.();
+        this._syncUnsub = null;
+        if (this._onlineHandler) {
+            window.removeEventListener('online', this._onlineHandler);
+            this._onlineHandler = null;
+        }
+        if (this._offlineHandler) {
+            window.removeEventListener('offline', this._offlineHandler);
+            this._offlineHandler = null;
+        }
+        this._initialized = false;
+    }
+}
+export const firekitNetwork = FirekitNetwork.getInstance();

package/dist/services/presence.svelte.d.ts

@@ -23,6 +23,7 @@ declare class FirekitPresence {
     private _geo;
     private _connectedUnsub;
     private _currentUser;
+    private _visibilityListenerAdded;
     private constructor();
     static getInstance(): FirekitPresence;
     get initialized(): boolean;

package/dist/services/presence.svelte.js

@@ -174,9 +174,11 @@ class FirekitPresence {
     _geo = null;
     _connectedUnsub = null;
     _currentUser = null;
+    _visibilityListenerAdded = false;
     constructor() {
         if (typeof window !== 'undefined') {
             document.addEventListener('visibilitychange', this._onVisibilityChange);
+            this._visibilityListenerAdded = true;
         }
     }
     static getInstance() {
@@ -236,10 +238,15 @@ class FirekitPresence {
         if (!db)
             throw new PresenceError(PresenceErrorCode.DATABASE_ERROR, 'Realtime Database is not initialized.');
         const connectedRef = ref(db, '.info/connected');
-        this._connectedUnsub = onValue(connectedRef, async (snap) => {
+        this._connectedUnsub = onValue(connectedRef, (snap) => {
             if (snap.val() === true) {
-                await this.setPresence('online');
-                await this._setupDisconnectHandler();
+                this.setPresence('online')
+                    .then(() => this._setupDisconnectHandler())
+                    .catch((err) => {
+                    this._error = err instanceof PresenceError
+                        ? err
+                        : new PresenceError(PresenceErrorCode.DATABASE_ERROR, err.message, err);
+                });
             }
             else {
                 this._status = 'offline';
@@ -377,8 +384,9 @@ class FirekitPresence {
         this._geo?.dispose();
         this._connectedUnsub?.();
         this._connectedUnsub = null;
-        if (typeof document !== 'undefined') {
+        if (this._visibilityListenerAdded) {
             document.removeEventListener('visibilitychange', this._onVisibilityChange);
+            this._visibilityListenerAdded = false;
         }
         this._initialized = false;
         this._status = 'offline';

package/dist/services/remote-config.svelte.js

@@ -92,6 +92,9 @@ export class FirekitRemoteConfig {
             },
             error: (err) => {
                 this._error = err instanceof Error ? err : new Error(String(err));
+                // Clean up the broken subscription so it doesn't keep firing errors
+                this._unsubscribe?.();
+                this._unsubscribe = null;
             },
             complete: () => { }
         });

package/dist/services/storage.svelte.js

@@ -197,6 +197,7 @@ export class FirekitUploadTask {
                 if (this._storageRef) {
                     this._downloadURL = await getDownloadURL(this._storageRef);
                 }
+                this._error = null;
                 this._state = 'success';
                 this._progress = 100;
             });

package/dist/types/index.d.ts

@@ -5,3 +5,5 @@ export * from './collection.js';
 export * from './mutations.js';
 export * from './presence.js';
 export * from './analytics.js';
+export * from './storage.js';
+export * from './network.js';

package/dist/types/index.js

@@ -5,3 +5,5 @@ export * from './collection.js';
 export * from './mutations.js';
 export * from './presence.js';
 export * from './analytics.js';
+export * from './storage.js';
+export * from './network.js';

package/dist/types/network.d.ts

@@ -0,0 +1,10 @@
+export declare enum NetworkErrorCode {
+    FIRESTORE_UNAVAILABLE = "network/firestore-unavailable",
+    ENABLE_NETWORK_FAILED = "network/enable-network-failed",
+    DISABLE_NETWORK_FAILED = "network/disable-network-failed"
+}
+export declare class NetworkError extends Error {
+    code: NetworkErrorCode;
+    originalError?: unknown | undefined;
+    constructor(code: NetworkErrorCode, message: string, originalError?: unknown | undefined);
+}

package/dist/types/network.js

@@ -0,0 +1,16 @@
+export var NetworkErrorCode;
+(function (NetworkErrorCode) {
+    NetworkErrorCode["FIRESTORE_UNAVAILABLE"] = "network/firestore-unavailable";
+    NetworkErrorCode["ENABLE_NETWORK_FAILED"] = "network/enable-network-failed";
+    NetworkErrorCode["DISABLE_NETWORK_FAILED"] = "network/disable-network-failed";
+})(NetworkErrorCode || (NetworkErrorCode = {}));
+export class NetworkError extends Error {
+    code;
+    originalError;
+    constructor(code, message, originalError) {
+        super(message);
+        this.code = code;
+        this.originalError = originalError;
+        this.name = 'NetworkError';
+    }
+}

package/dist/types/storage.d.ts

@@ -0,0 +1,34 @@
+export interface FileValidationOptions {
+    /** Maximum file size in bytes. */
+    maxSize?: number;
+    /** Minimum file size in bytes. */
+    minSize?: number;
+    /** Allowed MIME types or extensions. Supports wildcards like `'image/*'` and extensions like `'.jpg'`. */
+    accept?: string[];
+    /** Maximum image width in pixels. Only checked for image files. */
+    maxWidth?: number;
+    /** Maximum image height in pixels. Only checked for image files. */
+    maxHeight?: number;
+    /** Minimum image width in pixels. Only checked for image files. */
+    minWidth?: number;
+    /** Minimum image height in pixels. Only checked for image files. */
+    minHeight?: number;
+}
+export declare enum FileValidationErrorCode {
+    FILE_TOO_LARGE = "validation/file-too-large",
+    FILE_TOO_SMALL = "validation/file-too-small",
+    INVALID_MIME_TYPE = "validation/invalid-mime-type",
+    IMAGE_TOO_WIDE = "validation/image-too-wide",
+    IMAGE_TOO_TALL = "validation/image-too-tall",
+    IMAGE_TOO_NARROW = "validation/image-too-narrow",
+    IMAGE_TOO_SHORT = "validation/image-too-short",
+    DIMENSION_CHECK_FAILED = "validation/dimension-check-failed"
+}
+export interface FileValidationError {
+    code: FileValidationErrorCode;
+    message: string;
+}
+export interface FileValidationResult {
+    valid: boolean;
+    errors: FileValidationError[];
+}

package/dist/types/storage.js

@@ -0,0 +1,11 @@
+export var FileValidationErrorCode;
+(function (FileValidationErrorCode) {
+    FileValidationErrorCode["FILE_TOO_LARGE"] = "validation/file-too-large";
+    FileValidationErrorCode["FILE_TOO_SMALL"] = "validation/file-too-small";
+    FileValidationErrorCode["INVALID_MIME_TYPE"] = "validation/invalid-mime-type";
+    FileValidationErrorCode["IMAGE_TOO_WIDE"] = "validation/image-too-wide";
+    FileValidationErrorCode["IMAGE_TOO_TALL"] = "validation/image-too-tall";
+    FileValidationErrorCode["IMAGE_TOO_NARROW"] = "validation/image-too-narrow";
+    FileValidationErrorCode["IMAGE_TOO_SHORT"] = "validation/image-too-short";
+    FileValidationErrorCode["DIMENSION_CHECK_FAILED"] = "validation/dimension-check-failed";
+})(FileValidationErrorCode || (FileValidationErrorCode = {}));

package/dist/utils/index.d.ts

@@ -2,3 +2,4 @@ export * from './errors.js';
 export * from './providers.js';
 export * from './user.js';
 export * from './firestore.js';
+export * from './validation.js';

package/dist/utils/index.js

@@ -2,3 +2,4 @@ export * from './errors.js';
 export * from './providers.js';
 export * from './user.js';
 export * from './firestore.js';
+export * from './validation.js';

package/dist/utils/validation.d.ts

@@ -0,0 +1,20 @@
+import { type FileValidationOptions, type FileValidationResult } from '../types/storage.js';
+/**
+ * Validates a File against the given options.
+ * Returns a result with `valid: true` if all checks pass, or `valid: false` with an array of errors.
+ *
+ * @example
+ * ```ts
+ * const result = await validateFile(file, {
+ *   maxSize: 5 * 1024 * 1024,
+ *   accept: ['image/png', 'image/jpeg', '.webp'],
+ *   maxWidth: 2048,
+ *   maxHeight: 2048
+ * });
+ *
+ * if (!result.valid) {
+ *   console.log(result.errors);
+ * }
+ * ```
+ */
+export declare function validateFile(file: File, options: FileValidationOptions): Promise<FileValidationResult>;

package/dist/utils/validation.js

@@ -0,0 +1,147 @@
+import { FileValidationErrorCode } from '../types/storage.js';
+/** Common extension-to-MIME mappings for the `accept` option. */
+const EXT_TO_MIME = {
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.png': 'image/png',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.bmp': 'image/bmp',
+    '.ico': 'image/x-icon',
+    '.avif': 'image/avif',
+    '.pdf': 'application/pdf',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.ogg': 'audio/ogg',
+    '.json': 'application/json',
+    '.csv': 'text/csv',
+    '.txt': 'text/plain',
+    '.zip': 'application/zip'
+};
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function matchesMime(fileType, fileName, pattern) {
+    // Extension pattern: '.jpg'
+    if (pattern.startsWith('.')) {
+        const expectedMime = EXT_TO_MIME[pattern.toLowerCase()];
+        if (expectedMime)
+            return fileType === expectedMime;
+        // Fallback: check the file name extension
+        return fileName.toLowerCase().endsWith(pattern.toLowerCase());
+    }
+    // Wildcard MIME: 'image/*'
+    if (pattern.endsWith('/*')) {
+        const prefix = pattern.slice(0, -1); // 'image/'
+        return fileType.startsWith(prefix);
+    }
+    // Exact MIME: 'image/png'
+    return fileType === pattern;
+}
+function getImageDimensions(file) {
+    return new Promise((resolve, reject) => {
+        const url = URL.createObjectURL(file);
+        const img = new Image();
+        img.onload = () => {
+            URL.revokeObjectURL(url);
+            resolve({ width: img.naturalWidth, height: img.naturalHeight });
+        };
+        img.onerror = () => {
+            URL.revokeObjectURL(url);
+            reject(new Error('Failed to load image for dimension check.'));
+        };
+        img.src = url;
+    });
+}
+/**
+ * Validates a File against the given options.
+ * Returns a result with `valid: true` if all checks pass, or `valid: false` with an array of errors.
+ *
+ * @example
+ * ```ts
+ * const result = await validateFile(file, {
+ *   maxSize: 5 * 1024 * 1024,
+ *   accept: ['image/png', 'image/jpeg', '.webp'],
+ *   maxWidth: 2048,
+ *   maxHeight: 2048
+ * });
+ *
+ * if (!result.valid) {
+ *   console.log(result.errors);
+ * }
+ * ```
+ */
+export async function validateFile(file, options) {
+    const errors = [];
+    // ── Size checks ──────────────────────────────────────────────────────────
+    if (options.maxSize !== undefined && file.size > options.maxSize) {
+        errors.push({
+            code: FileValidationErrorCode.FILE_TOO_LARGE,
+            message: `File size ${formatBytes(file.size)} exceeds maximum ${formatBytes(options.maxSize)}.`
+        });
+    }
+    if (options.minSize !== undefined && file.size < options.minSize) {
+        errors.push({
+            code: FileValidationErrorCode.FILE_TOO_SMALL,
+            message: `File size ${formatBytes(file.size)} is below minimum ${formatBytes(options.minSize)}.`
+        });
+    }
+    // ── MIME type check ──────────────────────────────────────────────────────
+    if (options.accept && options.accept.length > 0) {
+        const accepted = options.accept.some((pattern) => matchesMime(file.type, file.name, pattern));
+        if (!accepted) {
+            errors.push({
+                code: FileValidationErrorCode.INVALID_MIME_TYPE,
+                message: `File type "${file.type || 'unknown'}" is not accepted. Allowed: ${options.accept.join(', ')}.`
+            });
+        }
+    }
+    // ── Image dimension checks ───────────────────────────────────────────────
+    const needsDimensions = options.maxWidth !== undefined ||
+        options.maxHeight !== undefined ||
+        options.minWidth !== undefined ||
+        options.minHeight !== undefined;
+    if (needsDimensions && file.type.startsWith('image/')) {
+        try {
+            const { width, height } = await getImageDimensions(file);
+            if (options.maxWidth !== undefined && width > options.maxWidth) {
+                errors.push({
+                    code: FileValidationErrorCode.IMAGE_TOO_WIDE,
+                    message: `Image width ${width}px exceeds maximum ${options.maxWidth}px.`
+                });
+            }
+            if (options.maxHeight !== undefined && height > options.maxHeight) {
+                errors.push({
+                    code: FileValidationErrorCode.IMAGE_TOO_TALL,
+                    message: `Image height ${height}px exceeds maximum ${options.maxHeight}px.`
+                });
+            }
+            if (options.minWidth !== undefined && width < options.minWidth) {
+                errors.push({
+                    code: FileValidationErrorCode.IMAGE_TOO_NARROW,
+                    message: `Image width ${width}px is below minimum ${options.minWidth}px.`
+                });
+            }
+            if (options.minHeight !== undefined && height < options.minHeight) {
+                errors.push({
+                    code: FileValidationErrorCode.IMAGE_TOO_SHORT,
+                    message: `Image height ${height}px is below minimum ${options.minHeight}px.`
+                });
+            }
+        }
+        catch {
+            errors.push({
+                code: FileValidationErrorCode.DIMENSION_CHECK_FAILED,
+                message: 'Could not read image dimensions for validation.'
+            });
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "svelte-firekit",
-	"version": "0.2.4",
+	"version": "0.2.6",
 	"description": "A Svelte library for Firebase integration",
 	"license": "MIT",
 	"author": "Giovani Rodriguez",