@async/framework 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## Unreleased
+
+## 0.9.0 - 2026-06-17
+
+- Added `createBoundaryReceiver(...)` for optional out-of-order boundary patch
+  delivery with per-boundary sequence checks, signal/cache effect ordering,
+  scheduler flushing, redirects, and destroyed parent-scope filtering.
+
+## 0.8.0 - 2026-06-17
+
+- Split browser and server entrypoints with `@async/framework/browser`,
+  `@async/framework/server`, browser-only CDN bundles, and server-only local
+  function registry exports.
+- Added `createRequestContextStore(...)` for Node request-scoped server
+  function context using `AsyncLocalStorage`.
+- Added the Layer 1.5 scheduler for deterministic signal binding, lifecycle,
+  effect, async, and post-flush phases.
+- Added browser microtask scheduling by default and manual scheduler flushing for
+  server render paths.
+- Threaded `this.scheduler` through loader, handler, component, async signal,
+  server, router, and partial contexts.
+
 ## 0.7.0 - 2026-06-17
 
 - Added router navigation abort/version guards so stale route partials cannot

package/README.md

@@ -53,6 +53,8 @@ primitives. It keeps the runtime small and explicit:
 - Handlers live in a registry and run through delegated DOM events.
 - Async signals use native `AbortSignal` cancellation and suppress stale async
   completions.
+- A small scheduler batches signal-driven DOM bindings, lifecycle callbacks,
+  effects, and async refreshes without adding a render loop.
 - Browser and server cache declarations are structurally split.
 - Boundaries can be swapped out of order and rescanned, which keeps server
   streaming and partial HTML replacement simple.
@@ -68,7 +70,7 @@ next level on every app.
 
 | Layer | Name | Requirement | Purpose |
 | --- | --- | --- | --- |
-| 1 | Runtime bootloader | No build. CDN or direct ESM import. | Signals, async signals, handlers, command events, lifecycle pseudo-events, scoped fragments, and boundary swaps. |
+| 1 | Runtime bootloader | No build. CDN or direct ESM import. | Signals, async signals, scheduler, handlers, command events, lifecycle pseudo-events, scoped fragments, and boundary swaps. |
 | 2 | App/server layer | Light server integration. No app compiler required. | `Async.use(...)`, router modes, server function proxy, partial registry, SSR output, browser activation, and split browser/server cache. |
 | 3 | Authoring build | Build step required. | JSX, ESM, and TypeScript authoring that lowers into Layer 1 HTML attributes and Layer 2 registries. |
 | 4 | Chunk and resumability metadata | Build metadata required. | Lazy module manifests, visibility/prefetch hints, resource graphs, and resumability records that the bootloader can consume. |
@@ -90,18 +92,18 @@ and package lifecycle tooling. Browser consumers import ESM directly.
 
 ## CDN
 
-The package ships root CDN artifacts for UNPKG and can be loaded without a
+The package ships browser CDN artifacts for UNPKG and can be loaded without a
 build step. Use `@latest` for quick prototypes, and pin an exact version in
 production:
 
 | File | Format | Use |
 | --- | --- | --- |
-| `framework.js` | ESM | Readable browser module bundle |
-| `framework.min.js` | ESM | Compact browser module bundle |
-| `framework.umd.js` | UMD | Readable script-tag/CommonJS-style bundle |
-| `framework.umd.min.js` | UMD | Compact script-tag/CommonJS-style bundle and default CDN file |
-| `framework.ts` | Bundled TypeScript source | TS-aware runtimes and higher-layer tooling |
-| `framework.d.ts` | Type declarations | TypeScript declarations for the public API |
+| `browser.js` | ESM | Readable browser module bundle |
+| `browser.min.js` | ESM | Compact browser module bundle |
+| `browser.umd.js` | UMD | Readable script-tag/CommonJS-style bundle |
+| `browser.umd.min.js` | UMD | Compact script-tag/CommonJS-style bundle and default CDN file |
+| `browser.ts` | Bundled TypeScript source | TS-aware runtimes and higher-layer tooling |
+| `browser.d.ts` | Type declarations | TypeScript declarations for the browser API |
 
 ```html
 <main async:container>
@@ -113,7 +115,7 @@ production:
   import {
     Async,
     createSignal
-  } from "https://unpkg.com/@async/framework@latest/framework.js";
+  } from "https://unpkg.com/@async/framework@latest/browser.js";
 
   Async.use({
     signal: {
@@ -136,7 +138,7 @@ For a plain script tag, use the UMD bundle. In this UMD-only global form,
 call `Async.Loader(...)` directly.
 
 ```html
-<script src="https://unpkg.com/@async/framework@latest/framework.umd.min.js"></script>
+<script src="https://unpkg.com/@async/framework@latest/browser.umd.min.js"></script>
 <script>
   Async.use({
     signal: {
@@ -159,7 +161,7 @@ You can also use an import map so app code imports `@async/framework` by name:
 <script type="importmap">
 {
   "imports": {
-    "@async/framework": "https://unpkg.com/@async/framework@latest/framework.js"
+    "@async/framework": "https://unpkg.com/@async/framework@latest/browser.js"
   }
 }
 </script>
@@ -187,6 +189,10 @@ You can also use an import map so app code imports `@async/framework` by name:
 
 ## Core API
 
+For npm consumers, `@async/framework` uses conditional exports: browser-aware
+tooling receives the browser entry, while Node receives the server-capable
+entry. Use explicit subpaths when the target matters.
+
 ```js
 import {
   Async,
@@ -204,8 +210,8 @@ import {
   createRegistryStore,
   createRouteRegistry,
   createRouter,
+  createScheduler,
   createServerProxy,
-  createServerRegistry,
   createSignalRegistry,
   defineAttributeConfig,
   defineApp,
@@ -218,7 +224,16 @@ import {
   readSnapshot,
   route,
   signal
-} from "@async/framework";
+} from "@async/framework/browser";
+```
+
+Server-only APIs live behind the server entry:
+
+```js
+import {
+  createRequestContextStore,
+  createServerRegistry
+} from "@async/framework/server";
 ```
 
 `Loader` is the canonical loader factory. `AsyncLoader` remains as a
@@ -373,6 +388,49 @@ signals.set("product.title", "Headphones");
 
 `signal(...)` remains a compatibility alias for `createSignal(...)`.
 
+### Scheduler
+
+The scheduler is the Layer 1.5 ordering engine. Signal writes are still
+synchronous:
+
+```js
+signals.set("count", 3);
+signals.get("count");
+// 3
+```
+
+DOM bindings, component lifecycle callbacks, component effects, and async signal
+refreshes are scheduled through deterministic phases:
+
+```txt
+binding -> lifecycle -> effect -> async -> post
+```
+
+Browser runtimes use a microtask scheduler by default. Server runtimes use a
+manual scheduler and drain it during `runtime.render(...)`.
+
+```js
+import {
+  createScheduler
+} from "@async/framework";
+
+const scheduler = createScheduler({
+  strategy: "manual"
+});
+
+const runtime = Async.start({
+  root: document,
+  scheduler
+});
+
+signals.set("count", 1);
+await scheduler.flush();
+```
+
+Most apps do not need to call the scheduler directly. It is exposed for tests,
+custom runtimes, streaming receivers, and higher layers that need explicit flush
+boundaries.
+
 ### Async Signals
 
 Async signals add loading state, error state, versions, refresh, and cancel to a
@@ -401,6 +459,7 @@ The async function context includes:
 | `this.id` | Current async signal id |
 | `this.version` | Run version |
 | `this.abort` | Native `AbortSignal` with non-enumerable `cancel(reason?)` |
+| `this.scheduler` | Current runtime scheduler |
 | `this.refresh()` | Start a new run |
 
 `this.abort` can be passed directly to `fetch` or to `delay`:
@@ -619,6 +678,10 @@ Server registries run locally on the server and proxies call an HTTP endpoint
 from the browser. Both expose the same dotted call shape.
 
 ```js
+import {
+  createServerRegistry
+} from "@async/framework/server";
+
 const server = createServerRegistry({
   "cart.add"(productId, quantity) {
     return {
@@ -634,6 +697,10 @@ const server = createServerRegistry({
 Client proxy:
 
 ```js
+import {
+  createServerProxy
+} from "@async/framework/browser";
+
 const server = createServerProxy({
   endpoint: "/__async/server",
   signals,
@@ -983,6 +1050,47 @@ loader.swap(
 `swap(boundaryId, fragmentOrTemplate)` replaces the boundary contents and
 rescans the inserted fragment.
 
+When boundary patches can arrive independently, use `createBoundaryReceiver`.
+It keeps per-boundary sequence state, applies signal/cache effects before the
+HTML swap, flushes scheduled bindings, and ignores stale child patches after a
+parent scope is destroyed.
+
+```js
+import { createBoundaryReceiver } from "@async/framework/browser";
+
+const receiver = createBoundaryReceiver({
+  loader: runtime.loader,
+  signals: runtime.signals,
+  cache: runtime.browser.cache,
+  scheduler: runtime.scheduler,
+  router: runtime.router
+});
+
+await receiver.apply({
+  boundary: "product",
+  seq: 1,
+  signals: {
+    product: { title: "Keyboard" }
+  },
+  cache: {
+    browser: {
+      "product:sku-1": { title: "Keyboard" }
+    }
+  },
+  html: `
+    <article>
+      <h1 signal:text="product.title"></h1>
+      <button type="button" on:click="server.cart.add(productId)">Add</button>
+    </article>
+  `
+});
+```
+
+Sequence numbers are tracked per boundary: `hero` patch `10` can apply before
+`reviews` patch `2`, while a later `hero` patch `9` is ignored. The receiver
+does not add transport management, a transaction log, hydration, or component
+rerendering.
+
 ## Examples
 
 | Example | Shows |
@@ -1022,7 +1130,7 @@ pnpm run release:check
 such as signals, handlers, server functions, partials, routes, and components.
 It writes `.async/registry-manifest.json` plus a per-file cache at
 `.async/registry-lint-cache.json`, skips generated root bundles such as
-`framework.umd.min.js`, and fails only when the same registry type and id are
+`browser.umd.min.js`, and fails only when the same registry type and id are
 declared with different normalized content. Duplicate declarations with the
 same content are reported as dedupe candidates, not errors.
 

package/{framework.d.ts → browser.d.ts}

@@ -1,5 +1,5 @@
 // Generated by scripts/build-framework-bundle.js. Do not edit by hand.
-// Public type declarations for @async/framework.
+// Browser type declarations for @async/framework/browser.
 
 export type RuntimeTarget = "browser" | "server";
 export type RouterMode = "csr" | "spa" | "ssr" | "ssr-spa" | "mpa";
@@ -40,6 +40,52 @@ export interface TemplateResult {
   readonly values: readonly unknown[];
 }
 
+export type SchedulerStrategy = "microtask" | "manual";
+export type SchedulerPhase = "binding" | "lifecycle" | "effect" | "async" | "post" | string;
+export interface SchedulerJob {
+  id: number;
+  phase: SchedulerPhase;
+  scope?: unknown;
+  boundary?: string;
+  key?: string;
+  canceled: boolean;
+  cancel(): void;
+}
+export interface SchedulerOptions {
+  strategy?: SchedulerStrategy;
+  phases?: SchedulerPhase[];
+  maxDepth?: number;
+  onError?(error: unknown, job: SchedulerJob): void;
+}
+export interface SchedulerInspection {
+  strategy: SchedulerStrategy;
+  phases: SchedulerPhase[];
+  pending: Record<string, number>;
+  scopesDestroyed: number;
+  flushing: boolean;
+  scheduled: boolean;
+}
+export interface Scheduler {
+  strategy: SchedulerStrategy;
+  phases: SchedulerPhase[];
+  batch<T>(fn: () => T): T;
+  enqueue(phase: SchedulerPhase, job: () => MaybePromise<unknown>, options?: { scope?: unknown; boundary?: string; key?: string }): Cleanup;
+  flush(): Promise<void>;
+  flushScope(scope: unknown): Promise<void>;
+  afterFlush(job: () => MaybePromise<unknown>, options?: { scope?: unknown; boundary?: string; key?: string }): Cleanup;
+  cancelScope(scope: unknown): this;
+  markScopeDestroyed(scope: unknown): this;
+  isScopeDestroyed(scope: unknown): boolean;
+  destroy(): void;
+  inspect(): SchedulerInspection;
+}
+
+export interface RequestContextStore {
+  run<T>(context: Record<string, unknown> | undefined, fn: () => T): T;
+  get(): Record<string, unknown> | undefined;
+  snapshot(): Record<string, unknown>;
+}
+
 export interface Signal<T = unknown> {
   readonly kind: "signal";
   value: T;
@@ -113,6 +159,7 @@ export interface AsyncSignalContext {
   router?: Router;
   loader?: LoaderInstance;
   cache?: CacheRegistry;
+  scheduler?: Scheduler;
   refresh(): Promise<unknown>;
 }
 
@@ -149,6 +196,7 @@ export interface HandlerContext {
   loader?: LoaderInstance;
   router?: Router;
   cache?: CacheRegistry;
+  scheduler?: Scheduler;
   event?: Event;
   element?: Element;
   el?: Element;
@@ -192,6 +240,7 @@ export interface ServerContext {
   locals?: unknown;
   abort?: AbortSignal;
   cache?: CacheRegistry;
+  scheduler?: Scheduler;
   server: ServerNamespace;
   [key: string]: unknown;
 }
@@ -216,6 +265,7 @@ export interface ServerProxyOptions {
   loader?: LoaderInstance;
   router?: Router;
   cache?: CacheRegistry;
+  scheduler?: Scheduler;
   headers?: Record<string, string>;
 }
 
@@ -263,6 +313,7 @@ export interface PartialContext {
   browserCache?: CacheRegistry;
   partials: PartialRegistry;
   abort?: AbortSignal;
+  scheduler?: Scheduler;
   request?: Request;
   locals?: unknown;
   [key: string]: unknown;
@@ -315,6 +366,7 @@ export interface RouterOptions {
   fetch?: typeof fetch;
   routeEndpoint?: string;
   attributes?: AttributeConfig;
+  scheduler?: Scheduler;
 }
 
 export interface Router {
@@ -328,6 +380,7 @@ export interface Router {
   server?: ServerNamespace;
   cache?: CacheRegistry;
   partials?: PartialRegistry;
+  scheduler: Scheduler;
   attributes: NormalizedAttributeConfig;
   start(): this;
   match(url: string | URL): RouteMatch | null;
@@ -346,6 +399,7 @@ export interface ComponentContext {
   server?: ServerNamespace;
   router?: Router;
   cache?: CacheRegistry;
+  scheduler?: Scheduler;
   signal<T = unknown>(initial: T): SignalRef<T>;
   signal<T = unknown>(name: string, initial: T): SignalRef<T>;
   computed<T = unknown>(name: string, fn: (this: ComponentContext) => T): SignalRef<T>;
@@ -382,6 +436,7 @@ export interface LoaderOptions {
   server?: ServerNamespace;
   router?: Router;
   cache?: CacheRegistry;
+  scheduler?: Scheduler;
   attributes?: AttributeConfig;
 }
 
@@ -392,6 +447,7 @@ export interface LoaderInstance {
   server?: ServerNamespace;
   router?: Router;
   cache?: CacheRegistry;
+  scheduler: Scheduler;
   attributes: NormalizedAttributeConfig;
   start(): this;
   scan(rootOrFragment?: Document | Element | DocumentFragment): this;
@@ -403,6 +459,53 @@ export interface LoaderInstance {
 export type AsyncLoaderOptions = LoaderOptions;
 export type AsyncLoaderInstance = LoaderInstance;
 
+export interface BoundaryPatch {
+  boundary: string;
+  seq: number;
+  html?: TemplateLike;
+  signals?: Record<string, unknown>;
+  cache?: { browser?: Record<string, unknown> };
+  redirect?: string;
+  error?: unknown;
+  parentScope?: string;
+  scope?: string;
+  meta?: Record<string, unknown>;
+}
+
+export type BoundaryApplyResult =
+  | { status: "applied"; boundary: string; seq: number }
+  | { status: "ignored-stale"; boundary: string; seq: number; lastSeq: number }
+  | { status: "ignored-destroyed"; boundary: string; seq: number; parentScope?: string }
+  | { status: "redirected"; boundary: string; seq: number; redirect: string }
+  | { status: "errored"; boundary: string; seq: number; error: Error };
+
+export interface BoundaryReceiverInspection {
+  destroyed: boolean;
+  boundaries: Record<string, { lastSeq: number; applied: number; ignored: number; errored?: number; lastStatus?: BoundaryApplyResult["status"] }>;
+  recent: Array<{ boundary: string; seq: number; status: BoundaryApplyResult["status"]; lastSeq?: number; parentScope?: string; redirect?: string }>;
+}
+
+export interface BoundaryReceiverOptions {
+  loader: LoaderInstance;
+  signals?: SignalRegistry;
+  cache?: CacheRegistry;
+  scheduler?: Scheduler;
+  router?: Router;
+  onApply?(result: BoundaryApplyResult, patch: BoundaryPatch): void;
+  onIgnore?(result: BoundaryApplyResult, patch: BoundaryPatch): void;
+  onError?(error: Error, result: BoundaryApplyResult, patch: BoundaryPatch): void;
+  throwOnError?: boolean;
+  recentLimit?: number;
+  isScopeDestroyed?(scope: string): boolean;
+}
+
+export interface BoundaryReceiver {
+  apply(patch: BoundaryPatch): Promise<BoundaryApplyResult>;
+  inspect(): BoundaryReceiverInspection;
+  reset(boundary?: string): this;
+  destroy(): void;
+}
+
 export interface RegistryStore {
   target: RuntimeTarget;
   register(type: RegistryType, id: string, value: unknown): string;
@@ -473,6 +576,8 @@ export interface CreateAppOptions extends LoaderOptions {
   routeEndpoint?: string;
   request?: Request;
   locals?: unknown;
+  requestContext?: RequestContextStore;
+  scheduler?: Scheduler;
 }
 
 export interface RenderResult {
@@ -495,6 +600,7 @@ export interface AppRuntime {
   browser: { cache: CacheRegistry };
   loader?: LoaderInstance;
   router?: Router;
+  scheduler: Scheduler;
   attributes: NormalizedAttributeConfig;
   start(): this;
   use(type: Parameters<AppHub["use"]>[0], entries?: unknown): this;
@@ -510,6 +616,7 @@ export interface AsyncNamespace extends AppHub {
   readSnapshot: typeof readSnapshot;
   attributeName: typeof attributeName;
   defineAttributeConfig: typeof defineAttributeConfig;
+  createBoundaryReceiver: typeof createBoundaryReceiver;
   createCacheRegistry: typeof createCacheRegistry;
   defineCache: typeof defineCache;
   component: typeof component;
@@ -524,10 +631,13 @@ export interface AsyncNamespace extends AppHub {
   createRegistryStore: typeof createRegistryStore;
   createRouteRegistry: typeof createRouteRegistry;
   createRouter: typeof createRouter;
+  createScheduler: typeof createScheduler;
   defineRoute: typeof defineRoute;
   route: typeof route;
+  applyServerResult: typeof applyServerResult;
   createServerProxy: typeof createServerProxy;
-  createServerRegistry: typeof createServerRegistry;
+  resolveServerCommandArguments: typeof resolveServerCommandArguments;
+  unwrapServerResult: typeof unwrapServerResult;
   computed: typeof computed;
   createSignal: typeof createSignal;
   createSignalRegistry: typeof createSignalRegistry;
@@ -542,6 +652,7 @@ export declare function defineApp(initial?: AppDefinition): AppHub;
 export declare function readSnapshot(root?: Document | Element, options?: { attributes?: AttributeConfig }): { signals?: Record<string, unknown>; cache?: { browser?: Record<string, unknown> } };
 export declare function attributeName(attributes: AttributeConfig | undefined, type: keyof NormalizedAttributeConfig, name: string): string;
 export declare function defineAttributeConfig(config?: AttributeConfig): NormalizedAttributeConfig;
+export declare function createBoundaryReceiver(options: BoundaryReceiverOptions): BoundaryReceiver;
 export declare function createCacheRegistry(initialMap?: Record<string, CacheDefinition | CacheDefinitionOptions>, options?: { now?: () => number; registry?: RegistryStore; type?: "cache.browser" | "cache.server" }): CacheRegistry;
 export declare function defineCache(options?: CacheDefinitionOptions): CacheDefinition;
 export declare function component<TProps extends Record<string, unknown> = Record<string, unknown>>(fn: ComponentFunction<TProps>): ComponentFunction<TProps>;
@@ -556,11 +667,14 @@ export declare function createPartialRegistry(initialMap?: Record<string, Partia
 export declare function createRegistryStore(initial?: AppDefinition, options?: { target?: RuntimeTarget; backing?: unknown }): RegistryStore;
 export declare function createRouteRegistry(initialMap?: Record<string, RouteDefinition | string>, options?: { registry?: RegistryStore; type?: "route" }): RouteRegistry;
 export declare function createRouter(options?: RouterOptions): Router;
+export declare function createScheduler(options?: SchedulerOptions): Scheduler;
 export declare function defineRoute(partial: string, options?: Omit<RouteDefinition, "partial">): RouteDefinition;
 export declare const route: typeof defineRoute;
+export declare function applyServerResult(result: unknown, context?: Record<string, unknown>): Promise<unknown>;
 export declare function createServerProxy(options?: ServerProxyOptions): ServerNamespace;
-export declare function createServerRegistry(initialMap?: Record<string, ServerFunction>, options?: { registry?: RegistryStore; type?: "server" }): ServerNamespace;
-export declare function computed<T = unknown>(fn: (this: { signals: SignalRegistry; id: string; server?: ServerNamespace; router?: Router; loader?: LoaderInstance; cache?: CacheRegistry }) => T): ComputedSignal<T>;
+export declare function resolveServerCommandArguments(args: Array<{ type: "local"; name: string } | { type: "signal"; path: string }>, context?: Record<string, unknown>): { args: unknown[]; signalValues: Record<string, unknown>; signalPaths: string[] };
+export declare function unwrapServerResult<T = unknown>(result: ServerResult<T>): T | ServerResult<T>;
+export declare function computed<T = unknown>(fn: (this: { signals: SignalRegistry; id: string; server?: ServerNamespace; router?: Router; loader?: LoaderInstance; cache?: CacheRegistry; scheduler?: Scheduler }) => T): ComputedSignal<T>;
 export declare function createSignal<T = unknown>(initial: T): Signal<T>;
 export declare function createSignalRegistry(initialMap?: SignalMap, options?: { registry?: RegistryStore; type?: "signal" }): SignalRegistry;
 export declare function effect(fn: () => unknown): EffectDefinition;