From 966d9d04561681c4d710d0f92ef303c07e8239c4 Mon Sep 17 00:00:00 2001
From: Your Name <you@example.com>
Date: Sat, 20 Sep 2025 11:08:45 -0400
Subject: [PATCH] documentation changes

---
 README.md | 93 ++++++++++++++++++++++++++++++++++---------------------
 1 file changed, 58 insertions(+), 35 deletions(-)

diff --git a/README.md b/README.md
index 9b9ec8e..1fda04b 100644
--- a/README.md
+++ b/README.md
@@ -3,61 +3,84 @@ Nostr_Login_Lite
 
 ## API
 
-Configure for login/logout:
+Complete configuration showing all available options:
 
 ```javascript
 await window.NOSTR_LOGIN_LITE.init({
-  theme: 'default',
+  // Theme configuration
+  theme: 'default',  // 'default' | 'dark' | custom theme name
 
+  // 🔐 Authentication persistence configuration
+  persistence: true,        // Enable persistent authentication (default: true)
+  isolateSession: false,    // Use sessionStorage for per-tab isolation (default: false = localStorage)
+
+  // Relay configuration
+  relays: ['wss://relay.damus.io', 'wss://nos.lol'],
+
+  // Authentication methods
   methods: {
-    extension: true,
-    local: true,
-    seedphrase: true,  // ✅ Must be explicitly enabled
-    readonly: true,
-    connect: true,
-    otp: false
+    extension: true,        // Browser extensions (Alby, nos2x, etc.)
+    local: true,            // Manual key entry & generation
+    readonly: true,         // Read-only mode (no signing)
+    connect: true,          // NIP-46 remote signers
+    otp: false              // OTP/DM authentication (not implemented yet)
   },
   
+  // Floating tab configuration
   floatingTab: {
-    enabled: true,
-    hPosition: 0.95,    // Near right edge
-    vPosition: 0.1,     // Near top
+    enabled: true,          // Show/hide floating login tab
+    hPosition: 0.95,        // 0.0 = left edge, 1.0 = right edge
+    vPosition: 0.1,         // 0.0 = top edge, 1.0 = bottom edge
+    offset: { x: 0, y: 0 }, // Fine-tune positioning (pixels)
     
     appearance: {
-      style: 'pill',
-      icon: '[LOGIN]',
-      text: 'Sign In',
-      iconOnly: false
+      style: 'pill',        // 'pill' | 'square' | 'circle'
+      theme: 'auto',        // 'auto' | 'light' | 'dark'
+      icon: '[LOGIN]',      // Text-based icon
+      text: 'Sign In',      // Button text
+      iconOnly: false       // Show icon only (no text)
     },
     
     behavior: {
       hideWhenAuthenticated: false,  // Keep visible after login
-      showUserInfo: true,
-      autoSlide: true
-    },
-    
-    getUserInfo: true,              // ✅ Fetch user profiles
-    getUserRelay: ['wss://relay.laantungir.net']  // Custom relays for profiles
+      showUserInfo: true,            // Show user info when authenticated
+      autoSlide: true,              // Slide animation on hover
+      persistent: false             // Persist across page reloads
+    }
   }
 });
 
+// Control Methods
+NOSTR_LOGIN_LITE.launch();                    // Open login modal
+NOSTR_LOGIN_LITE.logout();                   // Clear authentication state
+NOSTR_LOGIN_LITE.switchTheme('dark');        // Change theme
+NOSTR_LOGIN_LITE.showFloatingTab();          // Show floating tab
+NOSTR_LOGIN_LITE.hideFloatingTab();          // Hide floating tab
+NOSTR_LOGIN_LITE.updateFloatingTab(options); // Update floating tab options
+NOSTR_LOGIN_LITE.toggleFloatingTab();        // Toggle floating tab visibility
 
-// After initialization, you can switch themes dynamically:
-NOSTR_LOGIN_LITE.switchTheme('dark');
-NOSTR_LOGIN_LITE.switchTheme('default');
-
-// Or customize individual theme variables:
-NOSTR_LOGIN_LITE.setThemeVariable('--nl-accent-color', '#00ff00');
-
+// Get Authentication State (Single Source of Truth)
+const authState = NOSTR_LOGIN_LITE.getAuthState();
+const isAuthenticated = !!authState;
+const userInfo = authState; // Contains { method, pubkey, etc. }
 ```
 
-Control methods:
-```javascript
-NOSTR_LOGIN_LITE.showFloatingTab();
-NOSTR_LOGIN_LITE.hideFloatingTab();
-NOSTR_LOGIN_LITE.updateFloatingTab(options);
-NOSTR_LOGIN_LITE.destroyFloatingTab();
-```
+**Authentication Persistence:**
+
+Two-tier configuration system:
+
+1. **`persistence: boolean`** - Master switch for authentication persistence
+   - `true` (default): Save authentication state for automatic restore
+   - `false`: No persistence - user must login fresh every time
+
+2. **`isolateSession: boolean`** - Storage location when persistence is enabled
+   - `false` (default): Use localStorage - shared across tabs/windows
+   - `true`: Use sessionStorage - isolated per tab/window
+
+**Use Cases for Session Isolation (`isolateSession: true`):**
+- Multi-tenant applications where different tabs need different users
+- Testing environments requiring separate authentication per tab
+- Privacy-focused applications that shouldn't share login state across tabs
 
 ## Embedded Modal API