@async/framework 0.7.0 → 0.8.0

package/{framework.umd.js → browser.umd.js}

@@ -105,7 +105,8 @@
                   router: context.router,
                   loader: context.loader,
                   cache: context.cache,
-                  abort: activeAbort
+                  abort: activeAbort,
+                  scheduler: context.scheduler
                 });
               }
               return server;
@@ -119,6 +120,9 @@
             get cache() {
               return registry._context?.().cache;
             },
+            get scheduler() {
+              return registry._context?.().scheduler;
+            },
             get version() {
               return runVersion;
             },
@@ -195,11 +199,20 @@
         _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() {
@@ -235,11 +248,26 @@
         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);
@@ -876,7 +904,8 @@
               server: registry._context?.().server,
               router: registry._context?.().router,
               loader: registry._context?.().loader,
-              cache: registry._context?.().cache
+              cache: registry._context?.().cache,
+              scheduler: registry._context?.().scheduler
             }));
           });
         }
@@ -904,6 +933,8 @@
       const registryCleanups = new Map();
       const runtimeContext = {};
       const boundEntries = new Set();
+      let subscriptionCounter = 0;
+      let effectCounter = 0;
 
       const registry = attachRegistryInspection({
         register(id, signalLike) {
@@ -979,17 +1010,21 @@
           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}`
             });
           });
         },
@@ -1007,10 +1042,12 @@
           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) {
@@ -1029,10 +1066,22 @@
               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();
@@ -1109,6 +1158,17 @@
           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) {
@@ -1575,10 +1635,15 @@
         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) {
@@ -1586,7 +1651,17 @@
         },
         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);
             }
@@ -1596,6 +1671,7 @@
           while (destroyHooks.length > 0) {
             destroyHooks.pop()?.();
           }
+          runtime.scheduler?.markScopeDestroyed(scope);
           while (cleanups.length > 0) {
             cleanups.pop()?.();
           }
@@ -1604,10 +1680,24 @@
           }
         }
       };
+
+      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;
@@ -1619,6 +1709,7 @@
         server,
         router,
         cache,
+        scheduler,
 
         signal(name, initial) {
           if (arguments.length === 1) {
@@ -1663,7 +1754,11 @@
         },
 
         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;
         },
@@ -1785,93 +1880,10 @@
   })();
 
   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),
@@ -1879,13 +1891,14 @@
       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);
@@ -2224,7 +2237,7 @@
         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 = (() => {
@@ -2427,18 +2440,321 @@
     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();
@@ -2459,6 +2775,7 @@
         server,
         router,
         cache,
+        scheduler: schedulerInstance,
         attributes: attributeConfig,
 
         start() {
@@ -2498,6 +2815,7 @@
             server: api.server,
             router: api.router,
             cache: api.cache,
+            scheduler: schedulerInstance,
             attributes: attributeConfig
           });
           cleanupChildren(target);
@@ -2518,6 +2836,9 @@
             runCleanup(cleanup);
           }
           cleanups.clear();
+          if (ownsScheduler) {
+            schedulerInstance.destroy();
+          }
         },
 
         _observeVisible(target, fn) {
@@ -2535,13 +2856,14 @@
         }
       };
 
-      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) {
@@ -2573,18 +2895,19 @@
 
         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);
           }
@@ -2700,7 +3023,12 @@
 
         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) {
@@ -2761,7 +3089,12 @@
             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);
@@ -2801,7 +3134,7 @@
           }
           mountedElements.add(element);
           for (const ref of refs) {
-            runPseudo(element, ref);
+            scheduleLifecycle(element, () => runPseudo(element, ref), `attach:${ref}`);
           }
         }
 
@@ -2814,7 +3147,7 @@
             continue;
           }
           visibleElements.add(element);
-          addCleanup(observeVisible(element, () => runPseudo(element, ref)), element);
+          addCleanup(observeVisible(element, () => scheduleLifecycle(element, () => runPseudo(element, ref), `visible:${ref}`)), element);
         }
       }
 
@@ -2838,6 +3171,7 @@
             server: api.server,
             router: api.router,
             cache: api.cache,
+            scheduler: schedulerInstance,
             element,
             el: element,
             root: rootNode
@@ -2856,10 +3190,13 @@
         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 () => {};
         }
@@ -2914,6 +3251,7 @@
         }
         for (const element of elementsIn(node)) {
           runScopedCleanups(element);
+          schedulerInstance.markScopeDestroyed(element);
         }
       }
 
@@ -2937,6 +3275,13 @@
         }
       }
 
+      function scheduleLifecycle(element, fn, key) {
+        schedulerInstance.enqueue("lifecycle", fn, {
+          scope: element,
+          key
+        });
+      }
+
       return api;
     }
 
@@ -3267,6 +3612,7 @@
   const __routerModule = (() => {
     const { Loader } = __loaderModule;
     const { createHandlerRegistry } = __handlersModule;
+    const { createScheduler } = __schedulerModule;
     const { createSignalRegistry } = __signalsModule;
     const { applyServerResult } = __serverModule;
     const { createRegistryStore } = __registryStoreModule;
@@ -3387,12 +3733,15 @@
       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 ??
@@ -3402,6 +3751,7 @@
           handlers: handlerRegistry,
           server,
           cache,
+          scheduler: schedulerInstance,
           attributes: attributeConfig
         });
       const ownsLoader = !loader;
@@ -3421,12 +3771,13 @@
         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();
           }
@@ -3490,6 +3841,9 @@
             cleanup();
           }
           cleanups.clear();
+          if (ownsScheduler) {
+            schedulerInstance.destroy();
+          }
         }
       };
 
@@ -3595,13 +3949,16 @@
           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;
@@ -3646,6 +4003,7 @@
           loader: loaderInstance,
           server,
           cache,
+          scheduler: schedulerInstance,
           abort: navigation?.abort
         };
       }
@@ -3832,15 +4190,17 @@
     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,
@@ -3859,7 +4219,7 @@
         },
 
         start(options = {}) {
-          const runtime = createApp(app, options).start();
+          const runtime = createRuntime(app, options).start();
           app.runtime = runtime;
           return runtime;
         },
@@ -3884,13 +4244,18 @@
     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" });
@@ -3918,6 +4283,7 @@
         },
         loader,
         router,
+        scheduler,
         attributes,
 
         start() {
@@ -3934,12 +4300,13 @@
               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();
 
@@ -3955,6 +4322,7 @@
                 server,
                 cache: browserCache,
                 partials,
+                scheduler,
                 fetch: options.fetch,
                 routeEndpoint: options.routeEndpoint,
                 attributes
@@ -3966,7 +4334,7 @@
             }
           } else {
             configureServerContext({ cache: serverCache });
-            signals._setContext?.({ server, cache: serverCache });
+            signals._setContext?.({ server, cache: serverCache, scheduler });
           }
 
           return runtime;
@@ -3980,9 +4348,10 @@
         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,
@@ -4002,8 +4371,8 @@
                 cache: serverCache,
                 browserCache,
                 partials,
-                request: options.request,
-                locals: options.locals
+                scheduler,
+                ...currentRequestContext()
               })
             : { html: "" };
 
@@ -4016,6 +4385,8 @@
             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 }),
@@ -4034,6 +4405,9 @@
           router?.destroy?.();
           loader?.destroy?.();
           signals.destroy?.();
+          if (ownsScheduler) {
+            scheduler.destroy();
+          }
         },
 
         _applyUse(normalized) {
@@ -4054,11 +4428,23 @@
           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.");
@@ -4212,6 +4598,77 @@
       }
     }
 
+    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 ?? {}) };
@@ -4320,14 +4777,17 @@
   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;
-  const api = { 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 };
+  const api = { 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 };
   assertNoUmdNamespaceConflicts(api, Async);
   Object.assign(Async, api);
   Async.Async = Async;