Add source-of-truth loading state methods (v1.0.12)

The root issue: isLoading flag gets out of sync with actual in-flight requests,
especially with reactive frameworks calling .it() multiple times.

Solution: Provide direct access to the source of truth - the in-flight request map.

New Public API Methods:
- isItemLoading(typeName, id, level): Check if specific item is loading
- hasAnyInFlightRequests(): Check if ANY requests are in-flight

Key Changes:
1. Added isItemLoading() to check G.inFlightItm map directly
2. Added hasAnyInFlightRequests() for global loading state
3. Updated fetchItem() to sync isLoading with actual in-flight state
4. Added in-flight counts to devtools snapshot
5. Exported both methods in public API
6. Documented usage patterns and examples

Why This Fixes the Bug:
Instead of relying on state flags (isLoading) that can desync during reactive
cycles, developers can now query the actual in-flight request map. This is the
single source of truth that can't get out of sync.

Usage Pattern (Alpine.js):
  get isLoadingAuth() {
    return DL.isItemLoading('me', 'current')  // Always accurate!
  }

DevTools Support:
  const snapshot = DL.devtools()
  snapshot.inFlight.totalCount      // Number of in-flight requests
  snapshot.inFlight.hasAnyInFlight  // Boolean
  snapshot.inFlight.items           // Array of in-flight items
  snapshot.inFlight.collections     // Array of in-flight collections

Version: 1.0.11 → 1.0.12

Author: YidiDev

docs/reference/core.md

@@ -1028,6 +1028,123 @@ await updateInvoice(42, { status: 'paid' })
 
 ---
 
+## `isItemLoading(typeName, id, level)`
+
+Checks if a specific item is currently being fetched (has an in-flight request). This is the **source of truth** for loading state, checking the actual in-flight request map rather than relying on the `isLoading` flag.
+
+### Signature
+
+```typescript
+function isItemLoading(
+  typeName: string,
+  id: any,
+  level?: string | null
+): boolean
+```
+
+### Parameters
+
+- **`typeName`**: The type name (registered via `createType`)
+- **`id`**: The item identifier
+- **`level`** (optional): The level name (null for default level)
+
+### Returns: boolean
+
+Returns `true` if there is an active fetch in progress for this exact item/level combination, `false` otherwise.
+
+### Example
+
+```javascript
+// Check if user is loading
+const loading = DL.isItemLoading('user', 123)
+console.log('User 123 is loading:', loading)
+
+// Check specific level
+const detailsLoading = DL.isItemLoading('user', 123, 'detailed')
+console.log('User 123 details loading:', detailsLoading)
+
+// Use in reactive getters for accurate loading state
+get isLoadingAuth() {
+  return DL.isItemLoading('me', 'current')
+}
+```
+
+### Why Use This Instead of `ref.meta.isLoading`?
+
+The `isLoading` flag can sometimes be out of sync with reality due to timing issues with reactive frameworks. `isItemLoading()` checks the **actual in-flight request map**, which is the single source of truth.
+
+```javascript
+// ❌ May be inaccurate with reactive frameworks
+get isLoadingAuth() {
+  const meRef = Alpine.store('lib').it('me', 'current')
+  return meRef.meta.isLoading
+}
+
+// ✅ Always accurate - checks actual in-flight requests
+get isLoadingAuth() {
+  return DL.isItemLoading('me', 'current')
+}
+```
+
+---
+
+## `hasAnyInFlightRequests()`
+
+Checks if there are ANY in-flight requests (items or collections) across the entire application. Useful for global loading indicators.
+
+### Signature
+
+```typescript
+function hasAnyInFlightRequests(): boolean
+```
+
+### Returns: boolean
+
+Returns `true` if there are any active fetches in progress, `false` if all requests have completed.
+
+### Example
+
+```javascript
+// Global loading indicator
+const showGlobalSpinner = DL.hasAnyInFlightRequests()
+
+// Alpine.js example
+Alpine.store('app', {
+  get isLoading() {
+    return DL.hasAnyInFlightRequests()
+  }
+})
+
+// React example
+function GlobalLoadingIndicator() {
+  const [isLoading, setIsLoading] = React.useState(false)
+  
+  React.useEffect(() => {
+    const interval = setInterval(() => {
+      setIsLoading(DL.hasAnyInFlightRequests())
+    }, 100)
+    
+    return () => clearInterval(interval)
+  }, [])
+  
+  return isLoading ? <Spinner /> : null
+}
+```
+
+### Use in DevTools
+
+Both methods are also exposed in the devtools snapshot:
+
+```javascript
+const snapshot = DL.devtools()
+console.log('In-flight items:', snapshot.inFlight.items)
+console.log('In-flight collections:', snapshot.inFlight.collections)
+console.log('Total in-flight:', snapshot.inFlight.totalCount)
+console.log('Has any in-flight:', snapshot.inFlight.hasAnyInFlight)
+```
+
+---
+
 ## Summary
 
 **Core Methods:**
@@ -1040,10 +1157,13 @@ await updateInvoice(42, { status: 'paid' })
 | `fetchItem()` | Fetch single item and get reactive reference |
 | `fetchCollection()` | Fetch collection IDs and get reactive reference |
 | `applyDirectives()` | Apply server directives to invalidate cache |
+| `isItemLoading()` | Check if specific item has in-flight request (source of truth) |
+| `hasAnyInFlightRequests()` | Check if any requests are in-flight globally |
 | `onChange()` | Subscribe to state changes |
 | `onLifecycle()` | Subscribe to lifecycle events |
 | `clientId()` | Get unique client identifier |
 | `state()` | Get state snapshot (debugging) |
+| `devtools()` | Get detailed devtools snapshot |
 
 **Configuration:**
 

verity/shared/static/lib/core.js

@@ -1236,6 +1236,15 @@ function itemKey(typeName, id, levelName) {
     return `${typeName}:${id}:${toLevelKey(levelName)}`;
 }
 
+function isItemLoading(typeName, id, levelName = null) {
+    const key = itemKey(typeName, id, levelName);
+    return G.inFlightItm.has(key);
+}
+
+function hasAnyInFlightRequests() {
+    return G.inFlightItm.size > 0 || G.inFlightCol.size > 0;
+}
+
 function applyFetchedLevel(T, typeName, id, ref, sourceLevelKey, data, timestamp, qid = null, options = {}) {
     let nextData = { ...(ref.data || {}), ...(data || {}) };
     const nextLevelStamps = { ...ref.meta.levelStamps };
@@ -1698,8 +1707,14 @@ function fetchItem(typeName, id, levelName = null, opts = {}) {
     const ref = ensureItemRef(typeName, id);
     ref.meta.lastUsedAt = nowISO();
     scheduleMemorySweep();
-    // Don't set isLoading here - let _startItemFetch handle it based on whether fetch is actually needed
     _startItemFetch(typeName, id, levelName, { loud: !opts.silent, force: !!opts.force });
+    
+    // Set isLoading based on actual in-flight state (source of truth)
+    const actuallyLoading = isItemLoading(typeName, id, levelName);
+    if (ref.meta.isLoading !== actuallyLoading) {
+        assignRef(ref, { meta: { ...ref.meta, isLoading: actuallyLoading } });
+    }
+    
     return ref;
 }
 
@@ -2038,6 +2053,8 @@ function devtools() {
         inFlight: {
             collections: inFlightCollections,
             items: inFlightItems,
+            totalCount: G.inFlightCol.size + G.inFlightItm.size,
+            hasAnyInFlight: hasAnyInFlightRequests(),
         },
         directiveRegistry: {
             ttlMs: G.directiveRegistry.ttlMs,
@@ -2121,6 +2138,8 @@ const DLCore = {
     disconnectDirectiveSource,
     disconnectSse,
     ingestDirectiveEnvelope,
+    isItemLoading,
+    hasAnyInFlightRequests,
 };
 
 // ES MODULE EXPORTS (for modern bundlers and ES imports)
@@ -2144,6 +2163,8 @@ if (typeof exports !== "undefined") {
     exports.disconnectDirectiveSource = disconnectDirectiveSource;
     exports.disconnectSse = disconnectSse;
     exports.ingestDirectiveEnvelope = ingestDirectiveEnvelope;
+    exports.isItemLoading = isItemLoading;
+    exports.hasAnyInFlightRequests = hasAnyInFlightRequests;
 }
 
 // UMD/Browser compatibility (for script tag loading)