really fix keepAlive component and add docs for isAlive

Author: chiefcll

docs/primitives/KeepAlive.md

@@ -32,6 +32,27 @@ const AppRoutes = () => {
 
 In the example above, the `Browse` component's state will be preserved. When you navigate away and then back to a `/browse/...` URL, the page will render instantly from the cache, showing exactly what was there before.
 
+### Suspending Effects for Cached Routes
+
+When a route is cached and hidden (unmounted from view but kept in memory), its reactive SolidJS context remains active. This means any `createEffect` blocks that depend on global signals or stores will continue to run in the background.
+
+To prevent background effects from running when the page is inactive, `KeepAliveRoute` injects an `isAlive` accessor into your component's props. You should use `isAlive()` to halt effects early.
+
+```jsx
+import { createEffect } from 'solid-js';
+
+const Browse = (props) => {
+  createEffect(() => {
+    // Return early to prevent the effect from running in the background when cached
+    if (!props.isAlive()) return;
+
+    console.log('Page is active and visible!');
+  });
+
+  return <view>...</view>;
+};
+```
+
 ### IMPORTANT PRELOAD TIPS
 
 If using preload functions with props

src/primitives/KeepAlive.tsx

@@ -175,16 +175,19 @@ export const KeepAliveRoute = <S extends string>(
   const key = props.id || props.path;
   let savedFocusedElement: ElementNode | undefined;
 
-  let existing = keepAliveRouteElements.get(key);
-  if (!existing) {
-    const [isAlive, setIsAlive] = s.createSignal(true);
-    keepAliveRouteElements.set(key, {
-      id: key,
-      isAlive,
-      setIsAlive,
-    } as any);
-    existing = keepAliveRouteElements.get(key);
-  }
+  const getExisting = () => {
+    let existing = keepAliveRouteElements.get(key);
+    if (!existing) {
+      const [isAlive, setIsAlive] = s.createSignal(true);
+      existing = {
+        id: key,
+        isAlive,
+        setIsAlive,
+      } as any;
+      keepAliveRouteElements.set(key, existing!);
+    }
+    return existing!;
+  };
 
   const onRemove = chainFunctions(props.onRemove, (elm: ElementNode) => {
     savedFocusedElement = activeElement() as ElementNode;
@@ -212,35 +215,24 @@ export const KeepAliveRoute = <S extends string>(
 
   const preload = props.preload
     ? (preloadProps: RoutePreloadFuncArgs) => {
-        let existing = keepAliveRouteElements.get(key);
+        let existing = getExisting();
 
         if (
-          existing &&
           existing.children &&
           (props.shouldDispose?.(key) ||
             (existing.children as unknown as ElementNode)?.destroyed)
         ) {
           (existing.children as unknown as ElementNode).destroy();
           existing.dispose?.();
           keepAliveRouteElements.delete(key);
-          existing = undefined;
+          existing = getExisting();
         }
 
-        if (!existing || !existing.dispose) {
+        if (!existing.dispose) {
           return s.createRoot((dispose) => {
-            const [isAlive, setIsAlive] =
-              existing?.isAlive && existing?.setIsAlive
-                ? [existing.isAlive, existing.setIsAlive]
-                : s.createSignal(true);
-            storeKeepAliveRoute({
-              id: key,
-              owner: s.getOwner(),
-              dispose,
-              children: null,
-              isAlive,
-              setIsAlive,
-            });
-            return props.preload!({ ...preloadProps, isAlive });
+            existing.owner = s.getOwner();
+            existing.dispose = dispose;
+            return props.preload!({ ...preloadProps, isAlive: existing.isAlive! });
           });
         } else if (existing.children) {
           (existing.children as unknown as ElementNode)?.setFocus();
@@ -259,7 +251,7 @@ export const KeepAliveRoute = <S extends string>(
       {...props}
       preload={preload}
       component={(childProps) => {
-        const existing = keepAliveRouteElements.get(key)!;
+        const existing = getExisting();
         return (
           <KeepAliveRouteInternal
             id={key}