@async/framework 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## Unreleased
+
+## 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
+  clobber newer navigations, and route partial contexts receive `this.abort`.
+- Added ranked route matching so static and dynamic routes win over wildcard
+  fallbacks regardless of registration order.
+- Added `readSnapshot(...)` and automatic browser activation from SSR snapshot
+  scripts.
+- Fixed repeated server result application when proxy/server envelopes pass
+  through namespace or handler callers.
+- Added in-flight `cache.getOrSet(...)` deduplication and clear proxy errors for
+  `File`, `Blob`, and `FormData` values that the JSON transport cannot send.
+- Changed `framework.ts` from a source facade to a bundled TypeScript source
+  entrypoint.
+
 ## 0.6.0 - 2026-06-17
 
 - Added `Loader` as the canonical public loader factory, including

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` | TypeScript source facade | 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,
@@ -215,9 +221,19 @@ import {
   delay,
   effect,
   html,
+  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
@@ -372,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
@@ -400,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`:
@@ -411,6 +471,10 @@ await delay(250, this.abort);
 If a dependency read through `this.signals.get(...)` changes, the async signal
 reruns and the previous run is aborted.
 
+Dependency reads are captured while the async signal function starts running.
+Read signal dependencies before the first `await`; reads that happen later are
+ordinary reads and do not create refresh subscriptions.
+
 ## HTML Protocol
 
 Loader scans regular HTML attributes:
@@ -614,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 {
@@ -629,6 +697,10 @@ const server = createServerRegistry({
 Client proxy:
 
 ```js
+import {
+  createServerProxy
+} from "@async/framework/browser";
+
 const server = createServerProxy({
   endpoint: "/__async/server",
   signals,
@@ -819,11 +891,17 @@ hydrate, diff, patch, or rerender:
 ```js
 createApp(browserApp, {
   root: document,
-  snapshot,
   server: createServerProxy({ endpoint: "/__async/server" })
 }).start();
 ```
 
+If an `async:snapshot` script is present under the root or document,
+`createApp(...)` reads it automatically. You can also inspect it directly:
+
+```js
+const snapshot = readSnapshot(document);
+```
+
 ## Components
 
 Components are scoped fragment functions. They return strings or `html`
@@ -1011,7 +1089,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,51 @@ 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;
+  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 +158,7 @@ export interface AsyncSignalContext {
   router?: Router;
   loader?: LoaderInstance;
   cache?: CacheRegistry;
+  scheduler?: Scheduler;
   refresh(): Promise<unknown>;
 }
 
@@ -149,6 +195,7 @@ export interface HandlerContext {
   loader?: LoaderInstance;
   router?: Router;
   cache?: CacheRegistry;
+  scheduler?: Scheduler;
   event?: Event;
   element?: Element;
   el?: Element;
@@ -192,6 +239,7 @@ export interface ServerContext {
   locals?: unknown;
   abort?: AbortSignal;
   cache?: CacheRegistry;
+  scheduler?: Scheduler;
   server: ServerNamespace;
   [key: string]: unknown;
 }
@@ -216,6 +264,7 @@ export interface ServerProxyOptions {
   loader?: LoaderInstance;
   router?: Router;
   cache?: CacheRegistry;
+  scheduler?: Scheduler;
   headers?: Record<string, string>;
 }
 
@@ -262,6 +311,8 @@ export interface PartialContext {
   cache?: CacheRegistry;
   browserCache?: CacheRegistry;
   partials: PartialRegistry;
+  abort?: AbortSignal;
+  scheduler?: Scheduler;
   request?: Request;
   locals?: unknown;
   [key: string]: unknown;
@@ -314,6 +365,7 @@ export interface RouterOptions {
   fetch?: typeof fetch;
   routeEndpoint?: string;
   attributes?: AttributeConfig;
+  scheduler?: Scheduler;
 }
 
 export interface Router {
@@ -327,6 +379,7 @@ export interface Router {
   server?: ServerNamespace;
   cache?: CacheRegistry;
   partials?: PartialRegistry;
+  scheduler: Scheduler;
   attributes: NormalizedAttributeConfig;
   start(): this;
   match(url: string | URL): RouteMatch | null;
@@ -345,6 +398,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>;
@@ -381,6 +435,7 @@ export interface LoaderOptions {
   server?: ServerNamespace;
   router?: Router;
   cache?: CacheRegistry;
+  scheduler?: Scheduler;
   attributes?: AttributeConfig;
 }
 
@@ -391,6 +446,7 @@ export interface LoaderInstance {
   server?: ServerNamespace;
   router?: Router;
   cache?: CacheRegistry;
+  scheduler: Scheduler;
   attributes: NormalizedAttributeConfig;
   start(): this;
   scan(rootOrFragment?: Document | Element | DocumentFragment): this;
@@ -472,6 +528,8 @@ export interface CreateAppOptions extends LoaderOptions {
   routeEndpoint?: string;
   request?: Request;
   locals?: unknown;
+  requestContext?: RequestContextStore;
+  scheduler?: Scheduler;
 }
 
 export interface RenderResult {
@@ -494,6 +552,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;
@@ -506,6 +565,7 @@ export interface AsyncNamespace extends AppHub {
   asyncSignal: typeof asyncSignal;
   createApp: typeof createApp;
   defineApp: typeof defineApp;
+  readSnapshot: typeof readSnapshot;
   attributeName: typeof attributeName;
   defineAttributeConfig: typeof defineAttributeConfig;
   createCacheRegistry: typeof createCacheRegistry;
@@ -522,10 +582,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;
@@ -537,6 +600,7 @@ export declare function asyncSignal<T = unknown>(id: string, fn: AsyncSignalFunc
 export declare const Async: AppHub;
 export declare function createApp(appOrDefinition?: AppHub | AppDefinition, options?: CreateAppOptions): AppRuntime;
 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 createCacheRegistry(initialMap?: Record<string, CacheDefinition | CacheDefinitionOptions>, options?: { now?: () => number; registry?: RegistryStore; type?: "cache.browser" | "cache.server" }): CacheRegistry;
@@ -553,11 +617,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;