@async/framework 0.7.0 → 0.8.0

package/{framework.js → browser.js}

@@ -94,7 +94,8 @@ const __asyncSignalModule = (() => {
                 router: context.router,
                 loader: context.loader,
                 cache: context.cache,
-                abort: activeAbort
+                abort: activeAbort,
+                scheduler: context.scheduler
               });
             }
             return server;
@@ -108,6 +109,9 @@ const __asyncSignalModule = (() => {
           get cache() {
             return registry._context?.().cache;
           },
+          get scheduler() {
+            return registry._context?.().scheduler;
+          },
           get version() {
             return runVersion;
           },
@@ -184,11 +188,20 @@ const __asyncSignalModule = (() => {
       _bindRegistry(nextRegistry, nextId) {
         registry = nextRegistry;
         registeredId = nextId;
-        queueMicrotask(() => {
+        const start = () => {
           if (registry === nextRegistry && status === "idle") {
             state.refresh();
           }
-        });
+        };
+        const scheduler = registry._context?.().scheduler;
+        if (scheduler) {
+          scheduler.enqueue("async", start, {
+            scope: registeredId,
+            key: `asyncSignal:${registeredId}:initial`
+          });
+        } else {
+          queueMicrotask(start);
+        }
       },
 
       _dispose() {
@@ -224,11 +237,26 @@ const __asyncSignalModule = (() => {
       for (const dependency of dependencies) {
         const dependencyId = String(dependency).split(".")[0];
         if (dependencyId && dependencyId !== registeredId) {
-          dependencyCleanups.add(registry.subscribe(dependency, () => state.refresh()));
+          dependencyCleanups.add(registry.subscribe(dependency, () => scheduleRefresh()));
         }
       }
     }
 
+    function scheduleRefresh() {
+      if (activeAbort && !activeAbort.aborted) {
+        activeAbort.cancel(new Error(`Async signal "${registeredId}" dependency changed.`));
+      }
+      const scheduler = registry?._context?.().scheduler;
+      if (!scheduler) {
+        state.refresh();
+        return;
+      }
+      scheduler.enqueue("async", () => state.refresh(), {
+        scope: registeredId,
+        key: `asyncSignal:${registeredId}:refresh`
+      });
+    }
+
     function notify() {
       for (const subscriber of [...subscribers]) {
         subscriber(state);
@@ -865,7 +893,8 @@ const __signalsModule = (() => {
             server: registry._context?.().server,
             router: registry._context?.().router,
             loader: registry._context?.().loader,
-            cache: registry._context?.().cache
+            cache: registry._context?.().cache,
+            scheduler: registry._context?.().scheduler
           }));
         });
       }
@@ -893,6 +922,8 @@ const __signalsModule = (() => {
     const registryCleanups = new Map();
     const runtimeContext = {};
     const boundEntries = new Set();
+    let subscriptionCounter = 0;
+    let effectCounter = 0;
 
     const registry = attachRegistryInspection({
       register(id, signalLike) {
@@ -968,17 +999,21 @@ const __signalsModule = (() => {
         return createRef(registry, id);
       },
 
-      subscribe(path, fn) {
+      subscribe(path, fn, options = {}) {
         if (typeof fn !== "function") {
           throw new TypeError("subscribe(path, fn) requires a function.");
         }
         const parsed = parsePath(path, entries);
         const entry = requireEntry(entries, parsed.id);
+        const subscriptionId = ++subscriptionCounter;
         return entry.subscribe(() => {
-          fn(registry.get(parsed.path), {
+          scheduleCallback(() => fn(registry.get(parsed.path), {
             id: parsed.id,
             path: parsed.path,
             signal: entry
+          }), {
+            ...options,
+            key: options.key ?? `signal:${parsed.path}:${subscriptionId}`
           });
         });
       },
@@ -996,10 +1031,12 @@ const __signalsModule = (() => {
         return registry.ref(id);
       },
 
-      effect(fn) {
+      effect(fn, options = {}) {
         let cleanup;
         let dependencyCleanups = [];
         let stopped = false;
+        const scheduler = options.scheduler;
+        const effectId = ++effectCounter;
 
         const run = () => {
           if (stopped) {
@@ -1018,10 +1055,22 @@ const __signalsModule = (() => {
             server: runtimeContext.server,
             router: runtimeContext.router,
             loader: runtimeContext.loader,
-            cache: runtimeContext.cache
+            cache: runtimeContext.cache,
+            scheduler: runtimeContext.scheduler
           }));
           cleanup = outcome.value;
-          dependencyCleanups = outcome.dependencies.map((dependency) => registry.subscribe(dependency, run));
+          dependencyCleanups = outcome.dependencies.map((dependency) => registry.subscribe(dependency, scheduleRun));
+        };
+
+        const scheduleRun = () => {
+          if (!scheduler) {
+            run();
+            return;
+          }
+          scheduler.enqueue(options.phase ?? "effect", run, {
+            scope: options.scope,
+            key: options.key ?? `effect:${effectId}`
+          });
         };
 
         run();
@@ -1098,6 +1147,17 @@ const __signalsModule = (() => {
         registryCleanups.set(id, cleanup);
       }
     }
+
+    function scheduleCallback(fn, options = {}) {
+      const scheduler = options.scheduler;
+      if (!scheduler || options.phase === "sync") {
+        return fn();
+      }
+      return scheduler.enqueue(options.phase ?? "effect", fn, {
+        scope: options.scope,
+        key: options.key
+      });
+    }
   }
 
   function normalizeSignal(signalLike) {
@@ -1564,10 +1624,15 @@ const __componentModule = (() => {
       html,
       attach(target) {
         for (const hook of attachHooks) {
-          const cleanup = hook(target);
-          if (typeof cleanup === "function") {
-            cleanups.push(cleanup);
-          }
+          runtime.scheduler?.enqueue("lifecycle", () => {
+            const cleanup = hook(target);
+            if (typeof cleanup === "function") {
+              cleanups.push(cleanup);
+            }
+          }, {
+            scope,
+            key: `attach:${attachHooks.indexOf(hook)}`
+          }) ?? runAttachHook(hook, target);
         }
       },
       mount(target) {
@@ -1575,7 +1640,17 @@ const __componentModule = (() => {
       },
       visible(target, observeVisible) {
         for (const hook of visibleHooks) {
-          const cleanup = observeVisible(target, hook);
+          const cleanup = observeVisible(target, () => {
+            runtime.scheduler?.enqueue("lifecycle", () => {
+              const hookCleanup = hook(target);
+              if (typeof hookCleanup === "function") {
+                cleanups.push(hookCleanup);
+              }
+            }, {
+              scope,
+              key: `visible:${visibleHooks.indexOf(hook)}`
+            }) ?? runVisibleHook(hook, target);
+          });
           if (typeof cleanup === "function") {
             cleanups.push(cleanup);
           }
@@ -1585,6 +1660,7 @@ const __componentModule = (() => {
         while (destroyHooks.length > 0) {
           destroyHooks.pop()?.();
         }
+        runtime.scheduler?.markScopeDestroyed(scope);
         while (cleanups.length > 0) {
           cleanups.pop()?.();
         }
@@ -1593,10 +1669,24 @@ const __componentModule = (() => {
         }
       }
     };
+
+    function runAttachHook(hook, target) {
+      const cleanup = hook(target);
+      if (typeof cleanup === "function") {
+        cleanups.push(cleanup);
+      }
+    }
+
+    function runVisibleHook(hook, target) {
+      const cleanup = hook(target);
+      if (typeof cleanup === "function") {
+        cleanups.push(cleanup);
+      }
+    }
   }
 
   function createComponentContext({ runtime, scope, cleanups, attachHooks, visibleHooks, destroyHooks, renderScopedTemplate }) {
-    const { signals, handlers, loader, server, router, cache } = runtime;
+    const { signals, handlers, loader, server, router, cache, scheduler } = runtime;
     const generatedHandlers = new WeakMap();
     let generatedHandlerCounter = 0;
     let generatedSignalCounter = 0;
@@ -1608,6 +1698,7 @@ const __componentModule = (() => {
       server,
       router,
       cache,
+      scheduler,
 
       signal(name, initial) {
         if (arguments.length === 1) {
@@ -1652,7 +1743,11 @@ const __componentModule = (() => {
       },
 
       effect(fn) {
-        const cleanup = signals.effect(() => fn.call(context));
+        const cleanup = signals.effect(() => fn.call(context), {
+          scheduler,
+          phase: "effect",
+          scope
+        });
         cleanups.push(cleanup);
         return cleanup;
       },
@@ -1774,93 +1869,10 @@ const __componentModule = (() => {
 })();
 
 const __serverModule = (() => {
-  const { attachRegistryInspection, createRegistryStore } = __registryStoreModule;
   const serverEnvelopeKeys = new Set(["value", "signals", "boundary", "html", "redirect", "error"]);
   const appliedServerResult = Symbol.for("@async/framework.appliedServerResult");
   const appliedServerValues = new WeakSet();
 
-  function createServerRegistry(initialMap = {}, options = {}) {
-    const registryStore = options.registry ?? createRegistryStore();
-    const type = options.type ?? "server";
-    const entries = registryStore._map(type);
-    const defaults = {};
-
-    const registry = attachRegistryInspection({
-      register(id, fn) {
-        assertServerId(id);
-        if (typeof fn !== "function") {
-          throw new TypeError(`Server function "${id}" must be a function.`);
-        }
-        if (entries.has(id)) {
-          throw new Error(`Server function "${id}" is already registered.`);
-        }
-        entries.set(id, fn);
-        return id;
-      },
-
-      registerMany(map) {
-        for (const [id, fn] of Object.entries(map ?? {})) {
-          registry.register(id, fn);
-        }
-        return registry;
-      },
-
-      unregister(id) {
-        assertServerId(id);
-        return entries.delete(id);
-      },
-
-      resolve(id) {
-        assertServerId(id);
-        return entries.get(id);
-      },
-
-      async run(id, args = [], context = {}) {
-        assertServerId(id);
-        const fn = registry.resolve(id);
-        if (!fn) {
-          throw new Error(`Server function "${id}" is not registered.`);
-        }
-
-        let runContext;
-        const server = createServerNamespace((childId, childArgs, childContext = {}) => {
-          return registry.run(childId, childArgs, { ...runContext, ...childContext });
-        }, {}, () => runContext);
-
-        const mergedContext = {
-          ...defaults,
-          ...context,
-          cache: defaults.cache ?? context.cache
-        };
-
-        runContext = {
-          ...mergedContext,
-          id,
-          args,
-          input: mergedContext.input,
-          signals: createSignalReader(mergedContext.signals),
-          abort: mergedContext.abort,
-          cache: mergedContext.cache,
-          server
-        };
-
-        return fn.call(runContext, ...args);
-      },
-
-      _setContext(context = {}) {
-        Object.assign(defaults, context);
-        return registry;
-      },
-
-      _adoptMany() {
-        return registry;
-      }
-    }, registryStore, type);
-
-    registry.registerMany(initialMap);
-    return createServerNamespace((id, args, context) => registry.run(id, args, context), registry, () => defaults);
-  }
-
   function createServerProxy({
     endpoint = "/__async/server",
     fetch: fetchImpl = globalThis.fetch?.bind(globalThis),
@@ -1868,13 +1880,14 @@ const __serverModule = (() => {
     loader,
     router,
     cache,
+    scheduler,
     headers = {}
   } = {}) {
     if (typeof fetchImpl !== "function") {
       throw new TypeError("createServerProxy(...) requires fetch to be available.");
     }
 
-    const defaults = { signals, loader, router, cache };
+    const defaults = { signals, loader, router, cache, scheduler };
 
     async function run(id, args = [], context = {}) {
       assertServerId(id);
@@ -2213,7 +2226,7 @@ const __serverModule = (() => {
       throw new TypeError("Server function id must be a non-empty string.");
     }
   }
-  return { createServerRegistry, createServerProxy, resolveServerCommandArguments, applyServerResult, unwrapServerResult, defaultInput };
+  return { createServerProxy, resolveServerCommandArguments, applyServerResult, unwrapServerResult, defaultInput, createServerNamespace, createSignalReader, assertServerId };
 })();
 
 const __handlersModule = (() => {
@@ -2416,18 +2429,321 @@ const __handlersModule = (() => {
   return { createHandlerRegistry, parseHandlerRef, isHandlerToken };
 })();
 
+const __schedulerModule = (() => {
+  const defaultPhases = ["binding", "lifecycle", "effect", "async", "post"];
+
+  function createScheduler(options = {}) {
+    const phases = [...(options.phases ?? defaultPhases)];
+    const queues = new Map(phases.map((phase) => [phase, []]));
+    const keyedJobs = new Map();
+    const destroyedScopes = new Set();
+    const objectScopeIds = new WeakMap();
+    const onError = typeof options.onError === "function" ? options.onError : undefined;
+    const maxDepth = options.maxDepth ?? 100;
+    const strategy = options.strategy ?? "microtask";
+    let destroyed = false;
+    let flushing = false;
+    let scheduled = false;
+    let batchDepth = 0;
+    let jobCounter = 0;
+    let scopeCounter = 0;
+
+    const api = {
+      strategy,
+      phases,
+
+      batch(fn) {
+        if (typeof fn !== "function") {
+          throw new TypeError("scheduler.batch(fn) requires a function.");
+        }
+        assertActive();
+        batchDepth += 1;
+        let asyncBatch = false;
+        try {
+          const value = fn();
+          if (value && typeof value.then === "function") {
+            asyncBatch = true;
+            return value.finally(() => {
+              batchDepth -= 1;
+              requestFlush();
+            });
+          }
+          return value;
+        } finally {
+          if (!asyncBatch && batchDepth > 0) {
+            batchDepth -= 1;
+            requestFlush();
+          }
+        }
+      },
+
+      enqueue(phase, fn, options = {}) {
+        assertActive();
+        assertPhase(phase);
+        if (typeof fn !== "function") {
+          throw new TypeError("scheduler.enqueue(phase, fn) requires a function.");
+        }
+        const scope = options.scope;
+        if (scope !== undefined && destroyedScopes.has(scope)) {
+          return noop;
+        }
+
+        const dedupeKey = options.key === undefined ? undefined : `${phase}:${scopeKey(scope)}:${String(options.key)}`;
+        if (dedupeKey && keyedJobs.has(dedupeKey)) {
+          return keyedJobs.get(dedupeKey).cancel;
+        }
+
+        const job = {
+          id: ++jobCounter,
+          phase,
+          fn,
+          scope,
+          boundary: options.boundary,
+          key: dedupeKey,
+          canceled: false,
+          cancel() {
+            job.canceled = true;
+            if (job.key) {
+              keyedJobs.delete(job.key);
+            }
+          }
+        };
+        queues.get(phase).push(job);
+        if (job.key) {
+          keyedJobs.set(job.key, job);
+        }
+        requestFlush();
+        return job.cancel;
+      },
+
+      afterFlush(fn, options = {}) {
+        return api.enqueue("post", fn, options);
+      },
+
+      async flush() {
+        assertActive();
+        if (flushing) {
+          return;
+        }
+        scheduled = false;
+        flushing = true;
+        let depth = 0;
+        try {
+          while (hasJobs()) {
+            depth += 1;
+            if (depth > maxDepth) {
+              throw new Error(`Scheduler exceeded maxDepth ${maxDepth}.`);
+            }
+            for (const phase of phases) {
+              await flushPhase(phase);
+            }
+          }
+        } finally {
+          flushing = false;
+          if (hasJobs()) {
+            requestFlush();
+          }
+        }
+      },
+
+      async flushScope(scope) {
+        assertActive();
+        if (flushing) {
+          return;
+        }
+        scheduled = false;
+        flushing = true;
+        let depth = 0;
+        try {
+          while (hasJobsForScope(scope)) {
+            depth += 1;
+            if (depth > maxDepth) {
+              throw new Error(`Scheduler exceeded maxDepth ${maxDepth}.`);
+            }
+            for (const phase of phases) {
+              await flushPhase(phase, scope);
+            }
+          }
+        } finally {
+          flushing = false;
+          if (hasJobs()) {
+            requestFlush();
+          }
+        }
+      },
+
+      cancelScope(scope) {
+        if (scope === undefined) {
+          return api;
+        }
+        for (const queue of queues.values()) {
+          for (const job of queue) {
+            if (job.scope === scope) {
+              job.cancel();
+            }
+          }
+        }
+        return api;
+      },
+
+      markScopeDestroyed(scope) {
+        if (scope !== undefined) {
+          destroyedScopes.add(scope);
+          api.cancelScope(scope);
+        }
+        return api;
+      },
+
+      inspect() {
+        const counts = {};
+        for (const [phase, queue] of queues) {
+          counts[phase] = queue.filter((job) => !job.canceled).length;
+        }
+        return {
+          strategy,
+          phases: [...phases],
+          pending: counts,
+          scopesDestroyed: destroyedScopes.size,
+          flushing,
+          scheduled
+        };
+      },
+
+      destroy() {
+        destroyed = true;
+        for (const queue of queues.values()) {
+          for (const job of queue) {
+            job.cancel();
+          }
+          queue.length = 0;
+        }
+        keyedJobs.clear();
+        destroyedScopes.clear();
+      }
+    };
+
+    return api;
+
+    function requestFlush() {
+      if (strategy === "manual" || destroyed || flushing || batchDepth > 0 || scheduled) {
+        return;
+      }
+      scheduled = true;
+      scheduleMicrotask(() => {
+        if (!destroyed) {
+          void api.flush();
+        }
+      });
+    }
+
+    async function flushPhase(phase, scope) {
+      const queue = queues.get(phase);
+      const remaining = [];
+      const runnable = [];
+
+      for (const job of queue.splice(0)) {
+        if (job.canceled) {
+          continue;
+        }
+        if (scope !== undefined && job.scope !== scope) {
+          remaining.push(job);
+          continue;
+        }
+        runnable.push(job);
+      }
+
+      queue.push(...remaining);
+
+      for (const job of runnable) {
+        if (job.key) {
+          keyedJobs.delete(job.key);
+        }
+        if (job.canceled || (job.scope !== undefined && destroyedScopes.has(job.scope))) {
+          continue;
+        }
+        try {
+          await job.fn();
+        } catch (error) {
+          if (onError) {
+            onError(error, job);
+          } else {
+            throw error;
+          }
+        }
+      }
+    }
+
+    function hasJobs() {
+      for (const queue of queues.values()) {
+        if (queue.some((job) => !job.canceled)) {
+          return true;
+        }
+      }
+      return false;
+    }
+
+    function hasJobsForScope(scope) {
+      for (const queue of queues.values()) {
+        if (queue.some((job) => !job.canceled && job.scope === scope)) {
+          return true;
+        }
+      }
+      return false;
+    }
+
+    function assertActive() {
+      if (destroyed) {
+        throw new Error("Scheduler has been destroyed.");
+      }
+    }
+
+    function assertPhase(phase) {
+      if (!queues.has(phase)) {
+        throw new Error(`Unknown scheduler phase "${phase}".`);
+      }
+    }
+
+    function scopeKey(scope) {
+      if (scope === undefined) {
+        return "global";
+      }
+      if ((typeof scope === "object" && scope !== null) || typeof scope === "function") {
+        if (!objectScopeIds.has(scope)) {
+          objectScopeIds.set(scope, `scope:${++scopeCounter}`);
+        }
+        return objectScopeIds.get(scope);
+      }
+      return String(scope);
+    }
+  }
+
+  function scheduleMicrotask(fn) {
+    if (typeof queueMicrotask === "function") {
+      queueMicrotask(fn);
+      return;
+    }
+    Promise.resolve().then(fn);
+  }
+
+  function noop() {}
+  return { createScheduler };
+})();
+
 const __loaderModule = (() => {
   const { renderComponent } = __componentModule;
   const { createHandlerRegistry } = __handlersModule;
+  const { createScheduler } = __schedulerModule;
   const { createSignalRegistry, isSignalRef } = __signalsModule;
   const { matchAttribute, normalizeAttributeConfig, readAttribute } = __attributesModule;
   const inlineBindingPrefix = "__async:inline:";
 
-  function Loader({ root, signals, handlers, server, router, cache, attributes } = {}) {
+  function Loader({ root, signals, handlers, server, router, cache, attributes, scheduler } = {}) {
     const documentRef = root?.ownerDocument ?? root ?? globalThis.document;
     const rootNode = root ?? documentRef;
     const signalRegistry = signals ?? createSignalRegistry();
     const handlerRegistry = handlers ?? createHandlerRegistry();
+    const schedulerInstance = scheduler ?? createScheduler();
+    const ownsScheduler = !scheduler;
     const attributeConfig = normalizeAttributeConfig(attributes);
     const cleanups = new Set();
     const eventBindings = new WeakMap();
@@ -2448,6 +2764,7 @@ const __loaderModule = (() => {
       server,
       router,
       cache,
+      scheduler: schedulerInstance,
       attributes: attributeConfig,
 
       start() {
@@ -2487,6 +2804,7 @@ const __loaderModule = (() => {
           server: api.server,
           router: api.router,
           cache: api.cache,
+          scheduler: schedulerInstance,
           attributes: attributeConfig
         });
         cleanupChildren(target);
@@ -2507,6 +2825,9 @@ const __loaderModule = (() => {
           runCleanup(cleanup);
         }
         cleanups.clear();
+        if (ownsScheduler) {
+          schedulerInstance.destroy();
+        }
       },
 
       _observeVisible(target, fn) {
@@ -2524,13 +2845,14 @@ const __loaderModule = (() => {
       }
     };
 
-    signalRegistry._setContext?.({ server: api.server, router: api.router, loader: api, cache: api.cache });
+    signalRegistry._setContext?.({ server: api.server, router: api.router, loader: api, cache: api.cache, scheduler: schedulerInstance });
     api.server?._setContext?.({
       signals: signalRegistry,
       handlers: handlerRegistry,
       loader: api,
       router: api.router,
-      cache: api.cache
+      cache: api.cache,
+      scheduler: schedulerInstance
     });
 
     function bindEventAttributes(scope) {
@@ -2562,18 +2884,19 @@ const __loaderModule = (() => {
 
       const listener = async (event) => {
         try {
-          await handlerRegistry.run(ref, {
+          await schedulerInstance.batch(() => handlerRegistry.run(ref, {
             signals: signalRegistry,
             handlers: handlerRegistry,
             loader: api,
             server: api.server,
             router: api.router,
             cache: api.cache,
+            scheduler: schedulerInstance,
             event,
             element,
             el: element,
             root: rootNode
-          });
+          }));
         } catch (error) {
           dispatchAsyncError(element, error);
         }
@@ -2689,7 +3012,12 @@ const __loaderModule = (() => {
 
       const read = () => readBinding(path, options);
       apply(read());
-      addCleanup(subscribeBinding(path, () => apply(read())), element);
+      addCleanup(subscribeBinding(path, () => {
+        schedulerInstance.enqueue("binding", () => apply(read()), {
+          scope: element,
+          key
+        });
+      }), element);
     }
 
     function bindValueWriter(element, path) {
@@ -2750,7 +3078,12 @@ const __loaderModule = (() => {
           const state = {
             id,
             templates,
-            cleanup: signalRegistry.subscribe(`${id}.$status`, () => renderBoundary(boundary))
+            cleanup: signalRegistry.subscribe(`${id}.$status`, () => {
+              schedulerInstance.enqueue("binding", () => renderBoundary(boundary), {
+                scope: boundary,
+                key: `boundary:${id}`
+              });
+            })
           };
           boundaryState.set(boundary, state);
           addCleanup(state.cleanup, boundary);
@@ -2790,7 +3123,7 @@ const __loaderModule = (() => {
         }
         mountedElements.add(element);
         for (const ref of refs) {
-          runPseudo(element, ref);
+          scheduleLifecycle(element, () => runPseudo(element, ref), `attach:${ref}`);
         }
       }
 
@@ -2803,7 +3136,7 @@ const __loaderModule = (() => {
           continue;
         }
         visibleElements.add(element);
-        addCleanup(observeVisible(element, () => runPseudo(element, ref)), element);
+        addCleanup(observeVisible(element, () => scheduleLifecycle(element, () => runPseudo(element, ref), `visible:${ref}`)), element);
       }
     }
 
@@ -2827,6 +3160,7 @@ const __loaderModule = (() => {
           server: api.server,
           router: api.router,
           cache: api.cache,
+          scheduler: schedulerInstance,
           element,
           el: element,
           root: rootNode
@@ -2845,10 +3179,13 @@ const __loaderModule = (() => {
       const ownerWindow = target.ownerDocument?.defaultView ?? globalThis;
       const Observer = ownerWindow.IntersectionObserver ?? globalThis.IntersectionObserver;
       if (!Observer) {
-        queueMicrotask(() => {
+        schedulerInstance.enqueue("lifecycle", () => {
           if (!destroyed) {
             fn(target);
           }
+        }, {
+          scope: target,
+          key: "visible:fallback"
         });
         return () => {};
       }
@@ -2903,6 +3240,7 @@ const __loaderModule = (() => {
       }
       for (const element of elementsIn(node)) {
         runScopedCleanups(element);
+        schedulerInstance.markScopeDestroyed(element);
       }
     }
 
@@ -2926,6 +3264,13 @@ const __loaderModule = (() => {
       }
     }
 
+    function scheduleLifecycle(element, fn, key) {
+      schedulerInstance.enqueue("lifecycle", fn, {
+        scope: element,
+        key
+      });
+    }
+
     return api;
   }
 
@@ -3256,6 +3601,7 @@ const __partialsModule = (() => {
 const __routerModule = (() => {
   const { Loader } = __loaderModule;
   const { createHandlerRegistry } = __handlersModule;
+  const { createScheduler } = __schedulerModule;
   const { createSignalRegistry } = __signalsModule;
   const { applyServerResult } = __serverModule;
   const { createRegistryStore } = __registryStoreModule;
@@ -3376,12 +3722,15 @@ const __routerModule = (() => {
     partials,
     fetch: fetchImpl = globalThis.fetch?.bind(globalThis),
     routeEndpoint = "/__async/route",
-    attributes
+    attributes,
+    scheduler
   } = {}) {
     const documentRef = root?.ownerDocument ?? root ?? globalThis.document;
     const rootNode = root ?? documentRef;
     const signalRegistry = signals ?? loader?.signals ?? createSignalRegistry();
     const handlerRegistry = handlers ?? loader?.handlers ?? createHandlerRegistry();
+    const schedulerInstance = scheduler ?? loader?.scheduler ?? createScheduler();
+    const ownsScheduler = !scheduler && !loader?.scheduler;
     const attributeConfig = normalizeAttributeConfig(attributes ?? loader?.attributes);
     const loaderInstance =
       loader ??
@@ -3391,6 +3740,7 @@ const __routerModule = (() => {
         handlers: handlerRegistry,
         server,
         cache,
+        scheduler: schedulerInstance,
         attributes: attributeConfig
       });
     const ownsLoader = !loader;
@@ -3410,12 +3760,13 @@ const __routerModule = (() => {
       server,
       cache,
       partials,
+      scheduler: schedulerInstance,
       attributes: attributeConfig,
 
       start() {
         assertActive();
         loaderInstance.router = api;
-        signalRegistry._setContext?.({ router: api, loader: loaderInstance, server, cache });
+        signalRegistry._setContext?.({ router: api, loader: loaderInstance, server, cache, scheduler: schedulerInstance });
         if (ownsLoader) {
           loaderInstance.start();
         }
@@ -3479,6 +3830,9 @@ const __routerModule = (() => {
           cleanup();
         }
         cleanups.clear();
+        if (ownsScheduler) {
+          schedulerInstance.destroy();
+        }
       }
     };
 
@@ -3584,13 +3938,16 @@ const __routerModule = (() => {
         loader: loaderInstance,
         router: api,
         cache,
+        scheduler: schedulerInstance,
         abort: navigation?.abort
       });
+      await schedulerInstance.flush();
       if (!isActiveNavigation(navigation)) {
         return;
       }
       if (result?.html != null && !result.boundary && !result.redirect) {
         loaderInstance.swap(boundary, result.html);
+        await schedulerInstance.flush();
       }
       if (result?.redirect || options.history === false) {
         return;
@@ -3635,6 +3992,7 @@ const __routerModule = (() => {
         loader: loaderInstance,
         server,
         cache,
+        scheduler: schedulerInstance,
         abort: navigation?.abort
       };
     }
@@ -3821,15 +4179,17 @@ const __appModule = (() => {
   const { Loader } = __loaderModule;
   const { createPartialRegistry } = __partialsModule;
   const { createRouteRegistry, createRouter } = __routerModule;
-  const { createServerRegistry } = __serverModule;
+  const { createScheduler } = __schedulerModule;
+  const { createServerNamespace } = __serverModule;
   const { createSignal, createSignalRegistry } = __signalsModule;
   const { createRegistryStore } = __registryStoreModule;
   const { attributeName, normalizeAttributeConfig } = __attributesModule;
   const registryTypes = new Set(["signal", "handler", "server", "partial", "route", "component"]);
 
-  function defineApp(initial) {
+  function defineApp(initial, options = {}) {
     const registry = createRegistryStore(undefined, { target: "browser" });
     const runtimes = new Set();
+    const createRuntime = options.createRuntime ?? createApp;
 
     const app = {
       registry,
@@ -3848,7 +4208,7 @@ const __appModule = (() => {
       },
 
       start(options = {}) {
-        const runtime = createApp(app, options).start();
+        const runtime = createRuntime(app, options).start();
         app.runtime = runtime;
         return runtime;
       },
@@ -3873,13 +4233,18 @@ const __appModule = (() => {
   function createApp(appOrDefinition = Async, options = {}) {
     const app = isAppHub(appOrDefinition) ? appOrDefinition : defineApp(appOrDefinition ?? {});
     const target = options.target ?? "browser";
+    const scheduler = options.scheduler ?? options.loader?.scheduler ?? createScheduler({
+      strategy: target === "server" ? "manual" : "microtask"
+    });
+    const ownsScheduler = !options.scheduler && !options.loader?.scheduler;
     const attributes = normalizeAttributeConfig(options.attributes);
     const registry = options.registry ?? app.registry.view({ target });
     const signals = options.signals ?? createSignalRegistry(undefined, { registry, type: "signal" });
     const handlers = options.handlers ?? createHandlerRegistry(undefined, { registry, type: "handler" });
     const serverCache = createCacheRegistry(undefined, { registry, type: "cache.server" });
     const browserCache = createCacheRegistry(undefined, { registry, type: "cache.browser" });
-    const server = options.server ?? createServerRegistry(undefined, { registry, type: "server" });
+    const serverFactory = options.serverFactory ?? createServerReferenceRegistry;
+    const server = options.server ?? serverFactory(undefined, { registry, type: "server" });
     const partials = options.partials ?? createPartialRegistry(undefined, { registry, type: "partial" });
     const routes = options.routes ?? createRouteRegistry(undefined, { registry, type: "route" });
     const components = options.components ?? createComponentRegistry(undefined, { registry, type: "component" });
@@ -3907,6 +4272,7 @@ const __appModule = (() => {
       },
       loader,
       router,
+      scheduler,
       attributes,
 
       start() {
@@ -3923,12 +4289,13 @@ const __appModule = (() => {
             handlers,
             server,
             cache: browserCache,
+            scheduler,
             attributes
           });
           runtime.loader = loader;
 
           configureServerContext({ cache: browserCache });
-          signals._setContext?.({ server, loader, cache: browserCache });
+          signals._setContext?.({ server, loader, cache: browserCache, scheduler });
 
           loader.start();
 
@@ -3944,6 +4311,7 @@ const __appModule = (() => {
               server,
               cache: browserCache,
               partials,
+              scheduler,
               fetch: options.fetch,
               routeEndpoint: options.routeEndpoint,
               attributes
@@ -3955,7 +4323,7 @@ const __appModule = (() => {
           }
         } else {
           configureServerContext({ cache: serverCache });
-          signals._setContext?.({ server, cache: serverCache });
+          signals._setContext?.({ server, cache: serverCache, scheduler });
         }
 
         return runtime;
@@ -3969,9 +4337,10 @@ const __appModule = (() => {
       async render(url) {
         assertActive();
         configureServerContext({ cache: serverCache });
-        signals._setContext?.({ server, cache: serverCache });
+        signals._setContext?.({ server, cache: serverCache, scheduler });
         const matched = routes.match(url);
         if (!matched) {
+          await scheduler.flush();
           return {
             html: renderDocument("", { status: 404, signals, browserCache, boundary: options.boundary ?? "route", attributes }),
             status: 404,
@@ -3991,8 +4360,8 @@ const __appModule = (() => {
               cache: serverCache,
               browserCache,
               partials,
-              request: options.request,
-              locals: options.locals
+              scheduler,
+              ...currentRequestContext()
             })
           : { html: "" };
 
@@ -4005,6 +4374,8 @@ const __appModule = (() => {
           browserCache.restore(result.cache.browser);
         }
 
+        await scheduler.flush();
+
         const status = result.status ?? 200;
         return {
           html: renderDocument(result.html, { status, signals, browserCache, boundary: result.boundary ?? options.boundary ?? "route", attributes }),
@@ -4023,6 +4394,9 @@ const __appModule = (() => {
         router?.destroy?.();
         loader?.destroy?.();
         signals.destroy?.();
+        if (ownsScheduler) {
+          scheduler.destroy();
+        }
       },
 
       _applyUse(normalized) {
@@ -4043,11 +4417,23 @@ const __appModule = (() => {
         loader,
         router,
         cache,
-        request: options.request,
-        locals: options.locals
+        scheduler,
+        requestContext: options.requestContext,
+        ...currentRequestContext()
       });
     }
 
+    function currentRequestContext() {
+      const context = readRequestContextLike(options.requestContext);
+      return {
+        requestContext: context,
+        request: context.request ?? options.request,
+        headers: context.headers ?? options.headers,
+        cookies: context.cookies ?? options.cookies,
+        locals: context.locals ?? options.locals
+      };
+    }
+
     function assertActive() {
       if (destroyed) {
         throw new Error("Async app runtime has been destroyed.");
@@ -4201,6 +4587,77 @@ const __appModule = (() => {
     }
   }
 
+  function createServerReferenceRegistry(initialMap = {}, options = {}) {
+    const registry = options.registry ?? createRegistryStore();
+    const type = options.type ?? "server";
+    const defaults = {};
+
+    const reference = {
+      registry,
+
+      register(id, value) {
+        registry.register(type, id, value);
+        return id;
+      },
+
+      registerMany(map) {
+        for (const [id, value] of Object.entries(map ?? {})) {
+          reference.register(id, value);
+        }
+        return reference;
+      },
+
+      unregister(id) {
+        return registry.unregister(type, id);
+      },
+
+      resolve() {
+        return undefined;
+      },
+
+      async run(id) {
+        throw new Error(`Server command "${id}" cannot run without a server proxy or server registry.`);
+      },
+
+      keys() {
+        return registry.keys(type);
+      },
+
+      entries() {
+        return registry.entries(type);
+      },
+
+      inspect() {
+        return registry.entries(type);
+      },
+
+      _setContext(context = {}) {
+        Object.assign(defaults, context);
+        return reference;
+      },
+
+      _adoptMany() {
+        return reference;
+      }
+    };
+
+    reference.registerMany(initialMap);
+    return createServerNamespace((id, args, context) => reference.run(id, args, context), reference, () => defaults);
+  }
+
+  function readRequestContextLike(store) {
+    if (!store) {
+      return {};
+    }
+    if (typeof store.get === "function") {
+      return store.get() ?? {};
+    }
+    if (typeof store.getStore === "function") {
+      return store.getStore() ?? {};
+    }
+    return {};
+  }
+
   function normalizeEntries(type, entries = {}) {
     if (type !== "signal") {
       return { ...(entries ?? {}) };
@@ -4309,12 +4766,15 @@ const { createRouteRegistry: createRouteRegistry } = __routerModule;
 const { createRouter: createRouter } = __routerModule;
 const { defineRoute: defineRoute } = __routerModule;
 const { route: route } = __routerModule;
+const { createScheduler: createScheduler } = __schedulerModule;
+const { applyServerResult: applyServerResult } = __serverModule;
 const { createServerProxy: createServerProxy } = __serverModule;
-const { createServerRegistry: createServerRegistry } = __serverModule;
+const { resolveServerCommandArguments: resolveServerCommandArguments } = __serverModule;
+const { unwrapServerResult: unwrapServerResult } = __serverModule;
 const { computed: computed } = __signalsModule;
 const { createSignal: createSignal } = __signalsModule;
 const { createSignalRegistry: createSignalRegistry } = __signalsModule;
 const { effect: effect } = __signalsModule;
 const { signal: signal } = __signalsModule;
 
-export { asyncSignal, Async, createApp, defineApp, readSnapshot, attributeName, defineAttributeConfig, createCacheRegistry, defineCache, component, createComponentRegistry, defineComponent, delay, createHandlerRegistry, html, Loader, AsyncLoader, createPartialRegistry, createRegistryStore, createRouteRegistry, createRouter, defineRoute, route, createServerProxy, createServerRegistry, computed, createSignal, createSignalRegistry, effect, signal };
+export { asyncSignal, Async, createApp, defineApp, readSnapshot, attributeName, defineAttributeConfig, createCacheRegistry, defineCache, component, createComponentRegistry, defineComponent, delay, createHandlerRegistry, html, Loader, AsyncLoader, createPartialRegistry, createRegistryStore, createRouteRegistry, createRouter, defineRoute, route, createScheduler, applyServerResult, createServerProxy, resolveServerCommandArguments, unwrapServerResult, computed, createSignal, createSignalRegistry, effect, signal };