@djangocfg/ui-core 2.1.409 → 2.1.411

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.409",
+  "version": "2.1.411",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -95,14 +95,14 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.409",
+    "@djangocfg/i18n": "^2.1.411",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
     "next": ">=14.0.0",
-    "react": "^19.1.0",
+    "react": "^19.2.4",
     "react-device-detect": "^2.2.3",
-    "react-dom": "^19.1.0",
+    "react-dom": "^19.2.4",
     "react-hook-form": "^7.69.0",
     "tailwindcss": "^4.1.18",
     "zod": "^4.3.6",
@@ -166,13 +166,13 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.409",
-    "@djangocfg/typescript-config": "^2.1.409",
-    "@types/node": "^24.7.2",
-    "@types/react": "^19.1.0",
-    "@types/react-dom": "^19.1.0",
+    "@djangocfg/i18n": "^2.1.411",
+    "@djangocfg/typescript-config": "^2.1.411",
+    "@types/node": "^25.2.3",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
     "lucide-react": "^0.545.0",
-    "next": "^16.2.4",
+    "next": "^16.2.2",
     "typescript": "^5.9.3"
   },
   "publishConfig": {

package/src/components/navigation/context-menu/index.tsx

@@ -47,7 +47,7 @@ const ContextMenuSubContent = React.forwardRef<
   <ContextMenuPrimitive.SubContent
     ref={ref}
     className={cn(
-      "z-150 min-w-32 overflow-hidden rounded-[var(--radius-popover)] border bg-popover backdrop-blur-xl p-1 text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+      "z-[700] min-w-32 overflow-hidden rounded-[var(--radius-popover)] border bg-popover backdrop-blur-xl p-1 text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
       className
     )}
     {...props}
@@ -63,7 +63,7 @@ const ContextMenuContent = React.forwardRef<
     <ContextMenuPrimitive.Content
       ref={ref}
       className={cn(
-        "z-150 max-h-[--radix-context-menu-content-available-height] min-w-32 overflow-y-auto overflow-x-hidden rounded-[var(--radius-popover)] border bg-popover backdrop-blur-xl p-1 text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+        "z-[700] max-h-[--radix-context-menu-content-available-height] min-w-32 overflow-y-auto overflow-x-hidden rounded-[var(--radius-popover)] border bg-popover backdrop-blur-xl p-1 text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
         className
       )}
       {...props}

package/src/components/navigation/dropdown-menu/index.tsx

@@ -48,7 +48,7 @@ const DropdownMenuSubContent = React.forwardRef<
   <DropdownMenuPrimitive.SubContent
     ref={ref}
     className={cn(
-      "z-600 min-w-32 overflow-hidden rounded-[var(--radius-popover)] border bg-popover backdrop-blur-xl p-1 text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+      "z-[700] min-w-32 overflow-hidden rounded-[var(--radius-popover)] border bg-popover backdrop-blur-xl p-1 text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
       className
     )}
     {...props}
@@ -66,7 +66,7 @@ const DropdownMenuContent = React.forwardRef<
       ref={ref}
       sideOffset={sideOffset}
       className={cn(
-        "z-600 max-h-[var(--radix-dropdown-menu-content-available-height)] min-w-32 overflow-y-auto overflow-x-hidden rounded-[var(--radius-popover)] border bg-popover backdrop-blur-xl p-1 text-popover-foreground shadow-md",
+        "z-[700] max-h-[var(--radix-dropdown-menu-content-available-height)] min-w-32 overflow-y-auto overflow-x-hidden rounded-[var(--radius-popover)] border bg-popover backdrop-blur-xl p-1 text-popover-foreground shadow-md",
         "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
         className
       )}

package/src/components/navigation/menubar/index.tsx

@@ -95,7 +95,7 @@ const MenubarSubContent = React.forwardRef<
   <MenubarPrimitive.SubContent
     ref={ref}
     className={cn(
-      "z-150 min-w-32 overflow-hidden rounded-[var(--radius-popover)] border bg-popover backdrop-blur-xl p-1 text-popover-foreground shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+      "z-[700] min-w-32 overflow-hidden rounded-[var(--radius-popover)] border bg-popover backdrop-blur-xl p-1 text-popover-foreground shadow-lg data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
       className
     )}
     {...props}
@@ -118,7 +118,7 @@ const MenubarContent = React.forwardRef<
         alignOffset={alignOffset}
         sideOffset={sideOffset}
         className={cn(
-          "z-150 min-w-48 overflow-hidden rounded-[var(--radius-popover)] border bg-popover backdrop-blur-xl p-1 text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+          "z-[700] min-w-48 overflow-hidden rounded-[var(--radius-popover)] border bg-popover backdrop-blur-xl p-1 text-popover-foreground shadow-md data-[state=open]:animate-in data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
           className
         )}
         {...props}

package/src/components/overlay/hover-card/index.tsx

@@ -20,7 +20,7 @@ const HoverCardContent = React.forwardRef<
     align={align}
     sideOffset={sideOffset}
     className={cn(
-      "z-150 w-64 rounded-[var(--radius-popover)] border bg-popover backdrop-blur-xl p-4 text-popover-foreground shadow-md outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+      "z-[700] w-64 rounded-[var(--radius-popover)] border bg-popover backdrop-blur-xl p-4 text-popover-foreground shadow-md outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
       className
     )}
     {...props}

package/src/components/select/select.tsx

@@ -159,8 +159,15 @@ const SelectItem = React.forwardRef<
     key?: React.Key;
     icon?: React.ComponentType<{ className?: string }>;
     badge?: string | React.ReactNode;
+    /**
+     * Optional secondary line shown under the label in the dropdown.
+     * Rendered OUTSIDE `SelectPrimitive.ItemText`, so it does NOT
+     * appear in the trigger — only `children` (the label) does. Use
+     * this for two-line options whose trigger must stay single-line.
+     */
+    description?: React.ReactNode;
   }
->(({ className, children, icon: Icon, badge, value, ...props }, ref) => (
+>(({ className, children, icon: Icon, badge, description, value, ...props }, ref) => (
   <SelectPrimitive.Item
     ref={ref}
     value={value === '' ? EMPTY_SENTINEL : value}
@@ -177,7 +184,12 @@ const SelectItem = React.forwardRef<
     </span>
     <div className="flex items-center gap-2 flex-1 min-w-0 pr-6">
       {Icon && <Icon className="h-4 w-4 shrink-0" />}
-      <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+      <div className="flex min-w-0 flex-1 flex-col">
+        <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
+        {description && (
+          <span className="text-xs text-muted-foreground">{description}</span>
+        )}
+      </div>
       {badge && (
         <Badge variant="outline" className="text-xs shrink-0">
           {badge}

package/src/hooks/state/index.ts

@@ -3,6 +3,15 @@
 export { useDebounce } from './useDebounce';
 export { useDebouncedCallback } from './useDebouncedCallback';
 export { useLocalStorage } from './useLocalStorage';
+export type { UseLocalStorageOptions, UseLocalStorageReturn } from './useLocalStorage';
 export { useSessionStorage } from './useSessionStorage';
+export type {
+  UseSessionStorageOptions,
+  UseSessionStorageReturn,
+} from './useSessionStorage';
 export { useStoredValue } from './useStoredValue';
-export type { UseStoredValueOptions, StorageType } from './useStoredValue';
+export type {
+  UseStoredValueOptions,
+  UseStoredValueReturn,
+  StorageType,
+} from './useStoredValue';

package/src/hooks/state/useLocalStorage.ts

@@ -1,6 +1,6 @@
 'use client';
 
-import { useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 
 /**
  * Storage wrapper format with metadata
@@ -27,6 +27,20 @@ export interface UseLocalStorageOptions {
   ttl?: number;
 }
 
+/**
+ * Tuple returned by {@link useLocalStorage}.
+ *
+ * The 4th element (`patch`) is always present at runtime, but it only does
+ * something useful when `T` is a plain object — for primitive `T` it falls
+ * back to a plain `setValue` of the partial. See the `patch` JSDoc below.
+ */
+export type UseLocalStorageReturn<T> = readonly [
+  value: T,
+  setValue: (value: T | ((prev: T) => T)) => void,
+  removeValue: () => void,
+  patch: (partial: Partial<T>) => void,
+];
+
 /**
  * Check if data is in new wrapped format with _meta
  */
@@ -50,17 +64,75 @@ function isExpired<T>(wrapped: StorageWrapper<T>): boolean {
   return age > wrapped._meta.ttl;
 }
 
+/** True for a plain object (eligible for shallow-merge `patch`). */
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/**
+ * Same-tab cross-instance pub/sub.
+ *
+ * `window`'s native `storage` event only fires in OTHER tabs — two
+ * `useLocalStorage` hooks on the same key in the SAME tab would never see
+ * each other's writes. This module-level registry closes that gap: every
+ * write notifies all live hook instances for that key so they re-render
+ * with the fresh value. Other-tab sync still rides the `storage` event.
+ */
+const keyListeners = new Map<string, Set<(raw: string | null) => void>>();
+
+function subscribeKey(key: string, fn: (raw: string | null) => void): () => void {
+  let set = keyListeners.get(key);
+  if (!set) {
+    set = new Set();
+    keyListeners.set(key, set);
+  }
+  set.add(fn);
+  return () => {
+    set!.delete(fn);
+    if (set!.size === 0) keyListeners.delete(key);
+  };
+}
+
+/** Notify every same-tab hook instance bound to `key` (skips `self`). */
+function broadcastKey(
+  key: string,
+  raw: string | null,
+  self: (raw: string | null) => void,
+): void {
+  const set = keyListeners.get(key);
+  if (!set) return;
+  for (const fn of set) {
+    if (fn !== self) fn(raw);
+  }
+}
+
 /**
- * Simple localStorage hook with better error handling and optional TTL support
+ * Simple localStorage hook with better error handling and optional TTL support.
  *
  * IMPORTANT: To prevent hydration mismatch, this hook:
  * - Always returns initialValue on first render (same as SSR)
  * - Reads from localStorage only after component mounts
  *
+ * Synchronization (added):
+ * - Same-tab: a module-level pub/sub keyed by storage key — two hooks on the
+ *   same key in one tab stay in sync (the native `storage` event does NOT
+ *   fire in the originating tab, so this is required).
+ * - Cross-tab: the `window` `storage` event keeps other tabs in sync.
+ *
+ * Write coalescing (added):
+ * - State updates synchronously (React stays consistent within the tick),
+ *   but the actual `localStorage.setItem` is flushed once via
+ *   `queueMicrotask`. N `patch`/`setValue` calls in one tick collapse into a
+ *   single write + a single broadcast — no localStorage thrash, no storm of
+ *   `storage` events.
+ *
  * @param key - Storage key
  * @param initialValue - Default value if key doesn't exist
  * @param options - Optional configuration (ttl for auto-expiration)
- * @returns [value, setValue, removeValue] - Current value, setter function, and remove function
+ * @returns `[value, setValue, removeValue, patch]`
+ *   - `patch(partial)` shallow-merges a subset of keys into an object value.
+ *     It is a NO-OP when the partial changes nothing (shallow-equal on the
+ *     touched keys) — no write, no re-render, no `storage` event.
  *
  * @example
  * // Without TTL (backwards compatible)
@@ -71,56 +143,115 @@ function isExpired<T>(wrapped: StorageWrapper<T>): boolean {
  * const [value, setValue] = useLocalStorage('key', 'default', {
  *   ttl: 24 * 60 * 60 * 1000
  * });
+ *
+ * @example
+ * // Partial / grouped updates on an object value
+ * const [prefs, , , patch] = useLocalStorage('prefs', { a: 1, b: 2 });
+ * patch({ b: 3 }); // merges → { a: 1, b: 3 }, only writes if it changed
  */
 export function useLocalStorage<T>(
   key: string,
   initialValue: T,
   options?: UseLocalStorageOptions
-) {
+): UseLocalStorageReturn<T> {
   const ttl = options?.ttl;
   // Always start with initialValue to match SSR
   const [storedValue, setStoredValue] = useState<T>(initialValue);
   const [_isHydrated, setIsHydrated] = useState(false);
   const isInitialized = useRef(false);
 
-  // Read from localStorage after mount (avoids hydration mismatch)
-  useEffect(() => {
-    if (isInitialized.current) return;
-    isInitialized.current = true;
+  // Latest value, readable synchronously by setValue/patch updaters without
+  // adding them to dependency arrays (avoids stale closures across coalesced
+  // calls in the same tick).
+  const valueRef = useRef<T>(initialValue);
+  valueRef.current = storedValue;
 
-    try {
-      const item = window.localStorage.getItem(key);
-      if (item !== null) {
-        // Try to parse as JSON first, fallback to string
-        try {
-          const parsed = JSON.parse(item);
+  // Pending write: the value to flush to localStorage at the next microtask.
+  // `hasPending` guards against scheduling more than one flush per tick.
+  const pendingRef = useRef<{ value: T } | null>(null);
+  const flushScheduledRef = useRef(false);
 
-          // Check if new format with _meta
-          if (isWrappedFormat<T>(parsed)) {
-            // Check TTL expiration
-            if (isExpired(parsed)) {
-              // Expired! Clean up and use initial value
+  /**
+   * Parse a raw localStorage string into a value of T, honoring TTL.
+   * Returns `{ value }` or `null` when the entry is absent / expired.
+   */
+  const parseRaw = useCallback(
+    (raw: string | null): { value: T } | null => {
+      if (raw === null) return null;
+      try {
+        const parsed = JSON.parse(raw);
+        if (isWrappedFormat<T>(parsed)) {
+          if (isExpired(parsed)) {
+            try {
               window.localStorage.removeItem(key);
-              // Keep initialValue (already set)
-            } else {
-              // Not expired, extract value
-              setStoredValue(parsed._value);
+            } catch {
+              // ignore
             }
-          } else {
-            // Old format (backwards compatible)
-            setStoredValue(parsed as T);
+            return null;
           }
-        } catch {
-          // If JSON.parse fails, return as string
-          setStoredValue(item as T);
+          return { value: parsed._value };
         }
+        return { value: parsed as T };
+      } catch {
+        // Not JSON — treat as a raw string value.
+        return { value: raw as T };
       }
+    },
+    [key],
+  );
+
+  // Read from localStorage after mount (avoids hydration mismatch)
+  useEffect(() => {
+    if (isInitialized.current) return;
+    isInitialized.current = true;
+
+    try {
+      const item = window.localStorage.getItem(key);
+      const parsed = parseRaw(item);
+      if (parsed) setStoredValue(parsed.value);
     } catch (error) {
       console.error(`Error reading localStorage key "${key}":`, error);
     }
 
     setIsHydrated(true);
-  }, [key]);
+  }, [key, parseRaw]);
+
+  // Identity used to skip self when broadcasting. The sync effect below owns
+  // the real listener; this ref just lets `broadcastKey` exclude it.
+  const onLocalRef = useRef<(raw: string | null) => void>(() => {});
+
+  // Latest initialValue, read by the sync listener for the removal fallback
+  // without making the effect re-subscribe on every inline-literal render.
+  const initialValueRef = useRef<T>(initialValue);
+  initialValueRef.current = initialValue;
+
+  // Cross-instance (same tab) + cross-tab sync.
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    // Same-tab: re-read whenever a sibling hook on this key writes.
+    // The native `storage` event does NOT fire in the originating tab, so
+    // without this two hooks on one key in one tab would drift apart.
+    const onLocal = (raw: string | null) => {
+      const parsed = parseRaw(raw);
+      setStoredValue(parsed ? parsed.value : initialValueRef.current);
+    };
+    onLocalRef.current = onLocal;
+    const unsubscribe = subscribeKey(key, onLocal);
+
+    // Other tabs: the native `storage` event (never fires in this tab).
+    const onStorage = (e: StorageEvent) => {
+      if (e.key !== key || e.storageArea !== window.localStorage) return;
+      const parsed = parseRaw(e.newValue);
+      setStoredValue(parsed ? parsed.value : initialValueRef.current);
+    };
+    window.addEventListener('storage', onStorage);
+
+    return () => {
+      unsubscribe();
+      window.removeEventListener('storage', onStorage);
+    };
+  }, [key, parseRaw]);
 
   // Check data size and limit
   const checkDataSize = (data: any): boolean => {
@@ -128,13 +259,13 @@ export function useLocalStorage<T>(
       const jsonString = JSON.stringify(data);
       const sizeInBytes = new Blob([jsonString]).size;
       const sizeInKB = sizeInBytes / 1024;
-      
+
       // Limit to 1MB per item
       if (sizeInKB > 1024) {
         console.warn(`Data size (${sizeInKB.toFixed(2)}KB) exceeds 1MB limit for key "${key}"`);
         return false;
       }
-      
+
       return true;
     } catch (error) {
       console.error(`Error checking data size for key "${key}":`, error);
@@ -201,100 +332,184 @@ export function useLocalStorage<T>(
     return JSON.stringify(value);
   };
 
-  // Update localStorage when value changes
-  const setValue = (value: T | ((val: T) => T)) => {
-    try {
-      const valueToStore = value instanceof Function ? value(storedValue) : value;
+  // Low-level write: persist `dataToStore`, with quota recovery. Returns the
+  // raw string actually written (so siblings can be notified with it).
+  const writeRaw = useCallback(
+    (dataToStore: string): void => {
+      try {
+        window.localStorage.setItem(key, dataToStore);
+      } catch (storageError: any) {
+        if (
+          storageError.name === 'QuotaExceededError' ||
+          storageError.code === 22 ||
+          storageError.message?.includes('quota')
+        ) {
+          console.warn('localStorage quota exceeded, clearing old data...');
+          clearOldData();
+          try {
+            window.localStorage.setItem(key, dataToStore);
+          } catch (retryError) {
+            console.error(
+              `Failed to set localStorage key "${key}" after clearing old data:`,
+              retryError,
+            );
+            try {
+              forceClearAll();
+              window.localStorage.setItem(key, dataToStore);
+            } catch (finalError) {
+              console.error(
+                `Failed to set localStorage key "${key}" after force clearing:`,
+                finalError,
+              );
+            }
+          }
+        } else {
+          throw storageError;
+        }
+      }
+    },
+    [key],
+  );
+
+  /**
+   * Schedule a single coalesced flush of the pending value to localStorage.
+   *
+   * Why: a feature may fire several `patch`/`setValue` calls in one tick.
+   * State is updated immediately (React stays correct), but the I/O —
+   * `setItem` + the cross-instance broadcast — is deferred to a microtask
+   * so N updates in one tick become exactly ONE write and ONE broadcast.
+   */
+  const scheduleFlush = useCallback(() => {
+    if (flushScheduledRef.current) return;
+    flushScheduledRef.current = true;
 
-      // Check data size before attempting to save
-      if (!checkDataSize(valueToStore)) {
+    queueMicrotask(() => {
+      flushScheduledRef.current = false;
+      const pending = pendingRef.current;
+      pendingRef.current = null;
+      if (!pending) return;
+      if (typeof window === 'undefined') return;
+
+      if (!checkDataSize(pending.value)) {
         console.warn(`Data size too large for key "${key}", removing key`);
-        // Remove the key if data is too large
         try {
           window.localStorage.removeItem(key);
         } catch {
-          // Ignore errors when removing
+          // ignore
         }
-        // Still update the state
-        setStoredValue(valueToStore);
+        broadcastKey(key, null, onLocalRef.current);
         return;
       }
 
-      setStoredValue(valueToStore);
+      const dataToStore = prepareForStorage(pending.value);
+      try {
+        writeRaw(dataToStore);
+        // Keep sibling hooks on this key in sync within the same tab.
+        broadcastKey(key, dataToStore, onLocalRef.current);
+      } catch (error) {
+        console.error(`Error setting localStorage key "${key}":`, error);
+      }
+    });
+    // prepareForStorage / checkDataSize close over `ttl` + `key`; both stable
+    // enough for this callback's purpose.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key, writeRaw]);
 
-      if (typeof window !== 'undefined') {
-        const dataToStore = prepareForStorage(valueToStore);
+  // Commit a new value: update React state now, queue the write.
+  const commit = useCallback(
+    (next: T) => {
+      setStoredValue(next);
+      valueRef.current = next;
+      pendingRef.current = { value: next };
+      scheduleFlush();
+    },
+    [scheduleFlush],
+  );
 
-        // Try to set the value
-        try {
-          window.localStorage.setItem(key, dataToStore);
-        } catch (storageError: any) {
-          // If quota exceeded, clear old data and try again
-          if (storageError.name === 'QuotaExceededError' ||
-              storageError.code === 22 ||
-              storageError.message?.includes('quota')) {
-            console.warn('localStorage quota exceeded, clearing old data...');
-            clearOldData();
+  // Update localStorage when value changes
+  const setValue = useCallback(
+    (value: T | ((val: T) => T)) => {
+      const next =
+        value instanceof Function ? value(valueRef.current) : value;
+      commit(next);
+    },
+    [commit],
+  );
 
-            // Try again after clearing
-            try {
-              window.localStorage.setItem(key, dataToStore);
-            } catch (retryError) {
-              console.error(`Failed to set localStorage key "${key}" after clearing old data:`, retryError);
-              // If still fails, force clear all and try one more time
-              try {
-                forceClearAll();
-                window.localStorage.setItem(key, dataToStore);
-              } catch (finalError) {
-                console.error(`Failed to set localStorage key "${key}" after force clearing:`, finalError);
-                // If still fails, just update the state without localStorage
-                setStoredValue(valueToStore);
-              }
-            }
-          } else {
-            throw storageError;
-          }
+  /**
+   * Shallow-merge a subset of keys into an object value.
+   *
+   * Safe by design: when every key in `partial` already equals the stored
+   * value (shallow `Object.is` check) this is a NO-OP — no state update, no
+   * write, no `storage` event, no re-render. This makes it cheap to call
+   * `patch` defensively from effects / event handlers.
+   *
+   * When the current value is not a plain object, `patch` degrades to a
+   * plain `setValue(partial as T)` so the call is still well-defined.
+   */
+  const patch = useCallback(
+    (partial: Partial<T>) => {
+      const prev = valueRef.current;
+
+      if (!isPlainObject(prev)) {
+        commit(partial as T);
+        return;
+      }
+
+      // Skip the write entirely when nothing actually changes.
+      let changed = false;
+      for (const k of Object.keys(partial) as Array<keyof T>) {
+        if (!Object.is((prev as T)[k], partial[k])) {
+          changed = true;
+          break;
         }
       }
-    } catch (error) {
-      console.error(`Error setting localStorage key "${key}":`, error);
-      // Still update the state even if localStorage fails
-      const valueToStore = value instanceof Function ? value(storedValue) : value;
-      setStoredValue(valueToStore);
-    }
-  };
+      if (!changed) return;
+
+      commit({ ...prev, ...partial } as T);
+    },
+    [commit],
+  );
 
   // Remove value from localStorage
-  const removeValue = () => {
+  const removeValue = useCallback(() => {
     try {
       setStoredValue(initialValue);
+      valueRef.current = initialValue;
+      // Drop any queued write — it would resurrect the removed entry.
+      pendingRef.current = null;
       if (typeof window !== 'undefined') {
         try {
           window.localStorage.removeItem(key);
         } catch (removeError: any) {
-          // If removal fails due to quota, try to clear some data first
-          if (removeError.name === 'QuotaExceededError' || 
-              removeError.code === 22 || 
-              removeError.message?.includes('quota')) {
+          if (
+            removeError.name === 'QuotaExceededError' ||
+            removeError.code === 22 ||
+            removeError.message?.includes('quota')
+          ) {
             console.warn('localStorage quota exceeded during removal, clearing old data...');
             clearOldData();
-
             try {
               window.localStorage.removeItem(key);
             } catch (retryError) {
-              console.error(`Failed to remove localStorage key "${key}" after clearing:`, retryError);
-              // If still fails, force clear all
+              console.error(
+                `Failed to remove localStorage key "${key}" after clearing:`,
+                retryError,
+              );
               forceClearAll();
             }
           } else {
             throw removeError;
           }
         }
+        broadcastKey(key, null, onLocalRef.current);
       }
     } catch (error) {
       console.error(`Error removing localStorage key "${key}":`, error);
     }
-  };
+    // `initialValue` excluded for the inline-literal reason above.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [key]);
 
-  return [storedValue, setValue, removeValue] as const;
+  return [storedValue, setValue, removeValue, patch] as const;
 }

package/src/hooks/state/useSessionStorage.ts

@@ -27,6 +27,24 @@ export interface UseSessionStorageOptions {
   ttl?: number;
 }
 
+/**
+ * Tuple returned by {@link useSessionStorage}.
+ *
+ * The 4th element (`patch`) shallow-merges a subset of keys when `T` is a
+ * plain object — a no-op when nothing changes. Mirrors `useLocalStorage`.
+ */
+export type UseSessionStorageReturn<T> = readonly [
+  value: T,
+  setValue: (value: T | ((prev: T) => T)) => void,
+  removeValue: () => void,
+  patch: (partial: Partial<T>) => void,
+];
+
+/** True for a plain object (eligible for shallow-merge `patch`). */
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
 /**
  * Check if data is in new wrapped format with _meta
  */
@@ -72,7 +90,7 @@ export function useSessionStorage<T>(
   key: string,
   initialValue: T,
   options?: UseSessionStorageOptions
-) {
+): UseSessionStorageReturn<T> {
   const ttl = options?.ttl;
 
   // Get initial value from sessionStorage or use provided initialValue
@@ -286,5 +304,29 @@ export function useSessionStorage<T>(
     }
   };
 
-  return [storedValue, setValue, removeValue] as const;
+  /**
+   * Shallow-merge a subset of keys into an object value.
+   *
+   * Safe by design: a NO-OP when the partial changes nothing (shallow
+   * `Object.is` check on the touched keys) — no write, no re-render. When
+   * the current value is not a plain object it degrades to `setValue`.
+   */
+  const patch = (partial: Partial<T>) => {
+    const prev = storedValue;
+    if (!isPlainObject(prev)) {
+      setValue(partial as T);
+      return;
+    }
+    let changed = false;
+    for (const k of Object.keys(partial) as Array<keyof T>) {
+      if (!Object.is((prev as T)[k], partial[k])) {
+        changed = true;
+        break;
+      }
+    }
+    if (!changed) return;
+    setValue({ ...prev, ...partial } as T);
+  };
+
+  return [storedValue, setValue, removeValue, patch] as const;
 }

package/src/hooks/state/useStoredValue.ts

@@ -21,6 +21,20 @@ export interface UseStoredValueOptions {
   ttl?: number;
 }
 
+/**
+ * Tuple returned by {@link useStoredValue}.
+ *
+ * The 4th element (`patch`) shallow-merges a subset of keys when `T` is a
+ * plain object — see {@link useLocalStorage}. It is a no-op when no
+ * `storageKey` is supplied.
+ */
+export type UseStoredValueReturn<T> = readonly [
+  value: T,
+  setValue: (value: T | ((prev: T) => T)) => void,
+  removeValue: () => void,
+  patch: (partial: Partial<T>) => void,
+];
+
 /**
  * Unified storage hook that delegates to useLocalStorage or useSessionStorage.
  *
@@ -29,17 +43,17 @@ export interface UseStoredValueOptions {
  *
  * When storageKey is undefined the hook is a no-op:
  *   - returns initialValue as current value
- *   - setValue / removeValue are no-ops
+ *   - setValue / removeValue / patch are no-ops
  * This means adding storageKey to a component has zero overhead when unused.
  *
  * @example
- * const [value, setValue, removeValue] = useStoredValue('my-key', '', { storage: 'session' });
+ * const [value, setValue, removeValue, patch] = useStoredValue('my-key', '', { storage: 'session' });
  */
 export function useStoredValue<T>(
   storageKey: string | undefined,
   initialValue: T,
   options?: UseStoredValueOptions,
-): readonly [T, (value: T | ((prev: T) => T)) => void, () => void] {
+): UseStoredValueReturn<T> {
   const storageType = options?.storage ?? 'local';
   const ttlOption = options?.ttl ? { ttl: options.ttl } : undefined;
 
@@ -62,10 +76,11 @@ export function useStoredValue<T>(
 
   const noopSetValue = useCallback((_value: T | ((prev: T) => T)) => {}, []);
   const noopRemove = useCallback(() => {}, []);
+  const noopPatch = useCallback((_partial: Partial<T>) => {}, []);
 
   // No storageKey — pure no-op, no storage reads/writes
   if (!storageKey) {
-    return [initialValue, noopSetValue, noopRemove] as const;
+    return [initialValue, noopSetValue, noopRemove, noopPatch] as const;
   }
 
   return storageType === 'local' ? localResult : sessionResult;

package/src/styles/theme/tokens.css

@@ -151,7 +151,21 @@
   /* Custom width utilities */
   --width-dropdown: 500px;
 
-  /* Z-index scale */
+  /* Z-index scale
+   *
+   * Overlay tiers, low → high. Each tier must clear the one below it so a
+   * deeper overlay always renders above its trigger surface:
+   *   ≤ 40    page content, sticky headers
+   *   100     floating page furniture (chat dock & companions) — below all overlays
+   *   200     sheet (edge drawer)
+   *   500     side-panel / drawer
+   *   600     modal dialog / alert dialog / command palette
+   *   700     anchored overlays (popover, tooltip, select, dropdown,
+   *           context-menu, menubar, hover-card) — sit above any dialog
+   *           that triggered them
+   *   9999    full-viewport takeovers (e.g. Mermaid fullscreen)
+   * Toasts (Sonner) own the topmost layer via the library's own stacking.
+   */
   --z-index-0: 0;
   --z-index-10: 10;
   --z-index-20: 20;