feat(scheduler): commit loader swaps in frame phase

Author: PatrickJS

CHANGELOG.md

@@ -2,11 +2,15 @@
 
 ## Unreleased
 
+- Added scheduler commit-phase ordering for app-level loader swaps and streamed
+  boundary patches, including frame-backed commits and deterministic
+  non-browser fallbacks.
+
 ## 0.14.0 - 2026-06-26
 
 - Updated the Flow bridge to consume `@async/flow` 0.10.0 through the
   scheduler-free integration subpaths and shared protocol brands.
-- Bundle size from bundled TypeScript source: `browser.ts` raw 228,465 B (228.5 KB / 0.228 MB), gzip 42,518 B (42.5 KB / 0.043 MB), br 35,193 B (35.2 KB / 0.035 MB) -> `browser.min.js` raw 96,205 B (96.2 KB / 0.096 MB), gzip 27,993 B (28.0 KB / 0.028 MB), br 24,820 B (24.8 KB / 0.025 MB); delta raw -132,260 B (-132.3 KB / -0.132 MB), gzip -14,525 B (-14.5 KB / -0.015 MB), br -10,373 B (-10.4 KB / -0.010 MB).
+- Bundle size from bundled TypeScript source: `browser.ts` raw 236,170 B (236.2 KB / 0.236 MB), gzip 44,028 B (44.0 KB / 0.044 MB), br 36,421 B (36.4 KB / 0.036 MB) -> `browser.min.js` raw 99,320 B (99.3 KB / 0.099 MB), gzip 29,136 B (29.1 KB / 0.029 MB), br 25,662 B (25.7 KB / 0.026 MB); delta raw -136,850 B (-136.9 KB / -0.137 MB), gzip -14,892 B (-14.9 KB / -0.015 MB), br -10,759 B (-10.8 KB / -0.011 MB).
 
 ## 0.13.0 - 2026-06-26
 

specs/framework.md

@@ -125,3 +125,6 @@ tree or hidden hydration model.
 - [12-composition-patterns.md](./framework/12-composition-patterns.md) -
   composition pattern guidance for children, regions, templates, presenters,
   outlets, boundaries, and anti-patterns.
+- [13-scheduler-and-commit-phase.md](./framework/13-scheduler-and-commit-phase.md)
+  - scheduler timing, visual commit phase, background work, and
+  `Async.loader.swap(...)` completion semantics.

specs/framework/02-runtime-kernel.md

@@ -49,8 +49,10 @@ returned from `Async.start(...)` / `createApp(...).start()`.
 
 - The kernel owns registry materialization and runtime lifecycle.
 - The loader owns DOM scanning once a root is attached.
-- The app-level loader facade owns only bootstrap ordering. The concrete
-  runtime loader keeps synchronous DOM semantics.
+- The app-level loader facade owns bootstrap ordering and promise completion for
+  scheduled commit work. The concrete runtime loader keeps synchronous
+  validation and return shapes while DOM mutation runs through the scheduler
+  commit phase.
 - The router owns navigation once started for a root.
 - The scheduler owns queued work ordering.
 - Signal and cache registries own mutable data state.

specs/framework/04-dom-protocol.md

@@ -37,9 +37,11 @@ Default protocol attributes include:
 - `intersect:*`
 
 `Loader({ root, ... }).start()` scans a root. `loader.scan(fragment)` scans
-newly inserted content. `loader.swap(boundary, html, options?)` replaces a
-boundary and rescans inserted element roots by default. `strategy: "morph"` is
-an opt-in boundary update strategy for stable shell markup: it preserves
+newly inserted content. `loader.swap(boundary, html, options?)` validates and
+targets a boundary synchronously, then schedules replacement or morph work in
+the scheduler commit phase and rescans inserted element roots by default.
+`strategy: "morph"` is an opt-in boundary update strategy for stable shell
+markup: it preserves
 matching nodes by `async:key`, `data-key`, `id`, or sibling order and tag name,
 then cleans up removed or replaced nodes. `scan: "full"` scans the boundary
 element and its subtree, while `scan: "none"` leaves inserted content inert
@@ -61,9 +63,10 @@ do not become refresh dependencies unless the render function reads the signal
 itself or the path is listed in `deps`.
 
 `Async.loader.scan(...)`, `Async.loader.swap(...)`, `Async.loader.refresh(...)`,
-and `Async.loader.mount(...)` are promise-returning app-level facade methods. They
-queue until a concrete runtime loader exists, then delegate to the same
-synchronous loader operations.
+and `Async.loader.mount(...)` are promise-returning app-level facade methods.
+They queue until a concrete runtime loader exists. `Async.loader.swap(...)` and
+refresh calls that perform swaps resolve only after the scheduled commit,
+inserted-DOM scan and binding, and post-commit flush complete.
 
 ## Subsystem Boundaries
 
@@ -73,8 +76,9 @@ synchronous loader operations.
 - The signal registry reads and writes state.
 - The component system may emit protocol attributes in rendered fragments.
 - The boundary receiver and router call loader swaps for replacement.
-- The app-level loader facade may buffer work before bootstrap, but it does not
-  change boundary replacement semantics once a concrete loader exists.
+- The app-level loader facade may buffer work before bootstrap, but it delegates
+  replacement to the concrete loader and waits for commit completion when it
+  returns a promise to app code.
 
 ## Protocol Contract
 

specs/framework/08-resume-and-streaming.md

@@ -80,8 +80,8 @@ Patch effects apply in this order:
 
 1. Signal patches.
 2. Browser cache restore.
-3. Boundary HTML swap and rescan.
-4. Scheduler flush for affected work.
+3. Boundary HTML swap scheduled through the commit phase, with rescan.
+4. Scheduler flush for affected work, including post-commit completion.
 5. Redirect.
 
 ## Resume Contract
@@ -93,7 +93,8 @@ Resume must preserve document continuity:
 - Boundary swaps must clean removed scopes before inserted HTML is scanned.
 - Child patches with destroyed parent scopes are ignored.
 - Same-boundary patches are serialized so later sequence numbers cannot commit
-  before earlier in-flight patches finish.
+  before earlier in-flight patches finish their scheduled DOM commit and
+  post-commit flush.
 
 ## Invariants
 
@@ -117,8 +118,10 @@ Resume must preserve document continuity:
 
 - Browser activation restores signal and cache snapshots and binds existing
   DOM.
-- A boundary patch applies signal and cache effects before replacing HTML.
-- Inserted HTML is rescanned so delegated handlers and signal bindings work.
+- A boundary patch applies signal and cache effects before scheduling HTML
+  replacement.
+- Inserted HTML is rescanned during commit so delegated handlers and signal
+  bindings work before the patch reports success.
 - Stale same-boundary patches are ignored while independent boundary patches can
   apply out of order.
 - Failed DOM, scheduler, redirect, or capability errors can be retried with the

specs/framework/13-scheduler-and-commit-phase.md

@@ -0,0 +1,131 @@
+# Scheduler And Commit Phase
+
+Reference file for [Async Framework](../framework.md). This file owns
+scheduler timing, visual commit ordering, background work, and
+`Async.loader.swap(...)` promise completion.
+
+## Purpose
+
+Async needs deterministic ordering for signal effects, lifecycle callbacks,
+route partials, and streamed boundary patches without turning the runtime into a
+component renderer. The scheduler orders explicit work that the protocol
+already names. It is not React Fiber, a virtual DOM reconciler, or a hidden
+renderer loop.
+
+## Responsibilities
+
+- Keep registration and validation synchronous.
+- Resolve signal effects, async-signal state, and lifecycle work in microtasks.
+- Commit visual DOM replacement and morph work in the commit phase.
+- Resolve post-commit promises only after inserted DOM has been scanned and the
+  post flush has completed.
+- Run non-critical background work only after required visible work is done.
+- Provide deterministic fallbacks for server, command-line, and test runtimes
+  that do not expose browser frame or idle callbacks.
+
+## Timing Model
+
+Scheduler timing is phase based:
+
+1. Sync and registration: `Async.use(...)`, registry adoption, option
+   validation, boundary lookup, signal reads, signal writes, and direct handler
+   invocation remain ordinary synchronous JavaScript.
+2. Microtask resolve and effects: binding updates, lifecycle callbacks, signal
+   effects, and async-signal work flush from the microtask scheduler unless a
+   manual scheduler is supplied.
+3. Animation-frame commit: visual boundary replacement, morph work, route
+   partial DOM commits, and streamed HTML swaps run in the commit phase. Browser
+   runtimes use `requestAnimationFrame` for this phase when it is available.
+4. Post flush: post callbacks and completion promises settle after commit work
+   has run, inserted DOM has been scanned and bound, and earlier phase work
+   created by that scan has drained.
+5. Idle and background: optional non-critical work runs after the post flush.
+   Browser runtimes may use `requestIdleCallback` for this phase.
+
+`requestAnimationFrame` is only for visual commit work. `requestIdleCallback` is
+only for non-critical background work. Neither callback is required to run
+registration, signal writes, event dispatch, server result parsing, or ordinary
+effect scheduling.
+
+## Public Contract
+
+`createScheduler(...)` exposes a small deterministic scheduler with named
+phases, `enqueue(...)`, `afterFlush(...)`, `commit(...)`, `flush(...)`,
+`flushScope(...)`, scope cancellation, and inspection.
+
+`Async.loader.swap(...)` is the app-level promise-returning swap API. It queues
+until a concrete browser loader exists, schedules DOM mutation in the scheduler
+commit phase, and resolves only after:
+
+- the target boundary has been replaced or morphed
+- inserted protocol attributes have been scanned
+- signal, class, event, component, and lifecycle bindings created by that scan
+  have had their required flush opportunity
+- post-commit scheduler callbacks have completed
+
+The concrete runtime loader still validates synchronously, returns the same
+boundary, boundary array, or cleanup function shape as before, and is used by
+routers, server-result application, and streaming receivers. Integrations that
+need completion semantics must wait for the scheduled commit before reporting
+success, redirecting, or resolving app-level promises.
+
+## Fallbacks
+
+When `requestAnimationFrame` is unavailable, the commit phase falls back to a
+synchronous deterministic commit. This keeps server and test runtimes stable
+while preserving the same post-flush promise boundary.
+
+When `requestIdleCallback` is unavailable, background work remains a normal
+scheduler phase after post flush. It must not be required for visible DOM
+correctness.
+
+Manual schedulers do not auto-flush. Tests and custom runtimes that choose a
+manual scheduler must call `flush(...)` or `flushScope(...)` to advance queued
+work.
+
+## Subsystem Boundaries
+
+- The scheduler orders work; it does not discover DOM, diff components, own a
+  render tree, or decide what HTML should exist.
+- The loader owns boundary lookup, cleanup, replacement, morphing, scanning,
+  and binding.
+- The router owns navigation state and route partial selection, then waits for
+  loader commit completion before finishing DOM-changing navigation.
+- The boundary receiver owns patch sequence and retry state, then waits for
+  loader commit completion before consuming a successful sequence number.
+- Server-result application owns envelope effect ordering, then waits for
+  loader commit completion before following redirects that depend on committed
+  HTML.
+
+## Invariants
+
+- Sync validation errors surface before commit scheduling.
+- Commit jobs for the same boundary serialize when frame-backed commits are
+  deferred.
+- Independent boundaries may prepare or commit independently unless a caller
+  explicitly batches them.
+- Post callbacks do not resolve before earlier phase work created by a commit
+  has had a chance to drain.
+- Background work never gates boundary correctness.
+
+## Failure Modes
+
+- A missing boundary fails before a swap is scheduled.
+- A scan or binding failure during commit rejects the app-level swap promise and
+  lets streaming receivers retry the same sequence number.
+- Destroyed scopes cancel their pending scheduler work.
+- A destroyed runtime rejects queued loader work and prevents later commit
+  attempts from targeting detached roots.
+
+## Acceptance Criteria
+
+- A frame-backed app-level `Async.loader.swap(...)` does not mutate the DOM
+  before the animation-frame commit.
+- The same promise resolves only after replacement, scan, inserted bindings,
+  lifecycle flush, and post flush complete.
+- Non-browser runtimes without `requestAnimationFrame` keep deterministic
+  synchronous commit fallback behavior.
+- Same-boundary frame commits serialize so a later swap cannot commit before an
+  earlier in-flight swap finishes.
+- Streamed boundary patches report success only after the scheduled loader
+  commit finishes.

src/app.js

@@ -608,7 +608,11 @@ function createLoaderFacade() {
   }
 
   async function invoke(loader, method, args) {
-    return loader[method](...args);
+    const result = loader[method](...args);
+    if (method === "swap" || method === "refresh") {
+      await loader._whenCommitted?.(result);
+    }
+    return result;
   }
 }
 
@@ -809,7 +813,11 @@ function createRouterLoaderFacade(getRouter) {
   }
 
   async function invoke(loader, method, args) {
-    return loader[method](...args);
+    const result = loader[method](...args);
+    if (method === "swap" || method === "refresh") {
+      await loader._whenCommitted?.(result);
+    }
+    return result;
   }
 }
 

src/boundary-receiver.js

@@ -215,10 +215,11 @@ export function createBoundaryReceiver(options = {}) {
     let replacementCount = 0;
     if (normalized.html != null) {
       boundaryElement = loader.swap(normalized.boundary, normalized.html);
+      await waitForLoaderCommit(loader, boundaryElement);
     }
     if (normalized.replace) {
       boundaryElement ??= findBoundaryElement(loader.root, normalized.boundary, attributes);
-      replacementCount = applyReplacements(boundaryElement, normalized.replace);
+      replacementCount = await applyReplacements(boundaryElement, normalized.replace);
     }
 
     let attrs;
@@ -276,15 +277,16 @@ export function createBoundaryReceiver(options = {}) {
     }
   }
 
-  function applyReplacements(boundaryElement, replacements) {
+  async function applyReplacements(boundaryElement, replacements) {
     let applied = 0;
     for (const replacement of replacements) {
       if (replacement.mode === "boundary") {
         const target = findBoundaryElement(loader.root, replacement.target, attributes);
         if (!containsOrEquals(boundaryElement, target)) {
           throw new Error(`Boundary replacement target "${replacement.target}" is outside boundary "${boundaryIdFor(boundaryElement, attributes)}".`);
         }
-        loader.swap(replacement.target, replacement.html);
+        const swapped = loader.swap(replacement.target, replacement.html);
+        await waitForLoaderCommit(loader, swapped);
         applied += 1;
         continue;
       }
@@ -794,6 +796,12 @@ async function flushScheduler(scheduler, scope) {
   }
 }
 
+async function waitForLoaderCommit(loader, result) {
+  if (typeof loader?._whenCommitted === "function") {
+    await loader._whenCommitted(result);
+  }
+}
+
 async function followRedirect(redirect, router, loader) {
   if (router && typeof router.navigate === "function") {
     await router.navigate(redirect);