fix(framework): report automatic scheduler flush errors

Author: PatrickJS

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.11.10 - 2026-06-18
+
+- Routed automatic microtask scheduler flush failures through an explicit error
+  channel so failed jobs no longer surface as unhandled promise rejections.
+- Reported automatic flush failures to configured `onError` handlers or
+  `globalThis.reportError`, with scheduler metadata for phase, scope, and key,
+  while preserving manual `scheduler.flush()` rejection behavior.
+- Added regression coverage for automatic `onError` reporting, `reportError`
+  delivery without unhandled rejections, and manual flush rejection metadata.
+- Bundle size from bundled TypeScript source: `browser.ts` 184,238 B raw /
+  34,642 B gzip -> `browser.min.js` 78,267 B raw / 23,232 B gzip
+  (-105,971 B raw, -11,410 B gzip).
+
 ## 0.11.9 - 2026-06-18
 
 - Normalized scheduler batch thenables with `Promise.resolve(value)` before

browser.js

@@ -3240,7 +3240,7 @@ const __schedulerModule = (() => {
       scheduled = true;
       scheduleMicrotask(() => {
         if (!destroyed) {
-          void api.flush();
+          void api.flush().catch(reportAutomaticFlushError);
         }
       });
     }
@@ -3276,12 +3276,22 @@ const __schedulerModule = (() => {
           if (onError) {
             onError(error, job);
           } else {
-            throw error;
+            throw annotateSchedulerError(error, job);
           }
         }
       }
     }
 
+    function reportAutomaticFlushError(error) {
+      if (typeof globalThis.reportError === "function") {
+        globalThis.reportError(error);
+        return;
+      }
+      setTimeout(() => {
+        throw error;
+      }, 0);
+    }
+
     function hasJobs() {
       for (const queue of queues.values()) {
         if (queue.some((job) => !job.canceled)) {
@@ -3340,6 +3350,25 @@ const __schedulerModule = (() => {
     return (typeof scope === "object" && scope !== null) || typeof scope === "function";
   }
 
+  function annotateSchedulerError(error, job) {
+    if (!error || (typeof error !== "object" && typeof error !== "function")) {
+      return error;
+    }
+    try {
+      Object.defineProperty(error, "scheduler", {
+        configurable: true,
+        value: {
+          phase: job.phase,
+          scope: job.scope,
+          key: job.key
+        }
+      });
+    } catch {
+      // Non-extensible thrown values still need to propagate through the chosen error channel.
+    }
+    return error;
+  }
+
   function scheduleMicrotask(fn) {
     if (typeof queueMicrotask === "function") {
       queueMicrotask(fn);

browser.min.js

@@ -3242,7 +3242,7 @@ const __schedulerModule = (() => {
       scheduled = true;
       scheduleMicrotask(() => {
         if (!destroyed) {
-          void api.flush();
+          void api.flush().catch(reportAutomaticFlushError);
         }
       });
     }
@@ -3278,12 +3278,22 @@ const __schedulerModule = (() => {
           if (onError) {
             onError(error, job);
           } else {
-            throw error;
+            throw annotateSchedulerError(error, job);
           }
         }
       }
     }
 
+    function reportAutomaticFlushError(error) {
+      if (typeof globalThis.reportError === "function") {
+        globalThis.reportError(error);
+        return;
+      }
+      setTimeout(() => {
+        throw error;
+      }, 0);
+    }
+
     function hasJobs() {
       for (const queue of queues.values()) {
         if (queue.some((job) => !job.canceled)) {
@@ -3342,6 +3352,25 @@ const __schedulerModule = (() => {
     return (typeof scope === "object" && scope !== null) || typeof scope === "function";
   }
 
+  function annotateSchedulerError(error, job) {
+    if (!error || (typeof error !== "object" && typeof error !== "function")) {
+      return error;
+    }
+    try {
+      Object.defineProperty(error, "scheduler", {
+        configurable: true,
+        value: {
+          phase: job.phase,
+          scope: job.scope,
+          key: job.key
+        }
+      });
+    } catch {
+      // Non-extensible thrown values still need to propagate through the chosen error channel.
+    }
+    return error;
+  }
+
   function scheduleMicrotask(fn) {
     if (typeof queueMicrotask === "function") {
       queueMicrotask(fn);

browser.ts

@@ -1,6 +1,6 @@
 {
   "name": "@async/framework",
-  "version": "0.11.9",
+  "version": "0.11.10",
   "description": "No-build Loader app runtime with browser and server entrypoints, signals, command events, route partials, cache split, SSR activation, and streaming boundaries.",
   "type": "module",
   "main": "./server.js",

browser.umd.js

@@ -219,7 +219,7 @@ export function createScheduler(options = {}) {
     scheduled = true;
     scheduleMicrotask(() => {
       if (!destroyed) {
-        void api.flush();
+        void api.flush().catch(reportAutomaticFlushError);
       }
     });
   }
@@ -255,12 +255,22 @@ export function createScheduler(options = {}) {
         if (onError) {
           onError(error, job);
         } else {
-          throw error;
+          throw annotateSchedulerError(error, job);
         }
       }
     }
   }
 
+  function reportAutomaticFlushError(error) {
+    if (typeof globalThis.reportError === "function") {
+      globalThis.reportError(error);
+      return;
+    }
+    setTimeout(() => {
+      throw error;
+    }, 0);
+  }
+
   function hasJobs() {
     for (const queue of queues.values()) {
       if (queue.some((job) => !job.canceled)) {
@@ -319,6 +329,25 @@ function isObjectScope(scope) {
   return (typeof scope === "object" && scope !== null) || typeof scope === "function";
 }
 
+function annotateSchedulerError(error, job) {
+  if (!error || (typeof error !== "object" && typeof error !== "function")) {
+    return error;
+  }
+  try {
+    Object.defineProperty(error, "scheduler", {
+      configurable: true,
+      value: {
+        phase: job.phase,
+        scope: job.scope,
+        key: job.key
+      }
+    });
+  } catch {
+    // Non-extensible thrown values still need to propagate through the chosen error channel.
+  }
+  return error;
+}
+
 function scheduleMicrotask(fn) {
   if (typeof queueMicrotask === "function") {
     queueMicrotask(fn);