@async/framework 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## Unreleased
 
+## 0.10.0 - 2026-06-17
+
+- Added rootless browser startup plus `attachRoot`, `detachRoot`,
+  `inspectRoots`, and streamed `applySnapshot(...)` support for advanced
+  build-step bootstrapping.
+- Added compact lazy registry descriptors with `_async` asset resolution,
+  inferred exports, and lazy handler, partial, component, and async-signal
+  materialization.
+- Added optional `async-container` and `async-suspense` custom elements while
+  preserving the existing `async:container`, `async:boundary`, and
+  `this.suspense(...)` Layer 1 APIs.
+
+## 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`,

package/README.md

@@ -187,6 +187,117 @@ You can also use an import map so app code imports `@async/framework` by name:
 </script>
 ```
 
+## Advanced Build-Step Runtime
+
+Layer 1 still works with no build step. A build step can optimize the same
+runtime by emitting SSR HTML plus compact registry descriptors. The browser can
+start in the document head, apply snapshots, and wait for a root to appear:
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "@async/framework": "https://unpkg.com/@async/framework@latest/browser.js"
+  }
+}
+</script>
+
+<script type="application/json" async:snapshot>
+{
+  "signal": {
+    "productId": "sku-1"
+  },
+  "handler": {
+    "cart.add": { "url": "cart.add.js" }
+  },
+  "component": {
+    "ProductCard": { "url": "ProductCard.js" }
+  },
+  "asyncSignal": {
+    "product.load": { "url": "product.load.js" }
+  }
+}
+</script>
+
+<script type="module">
+  import {
+    Async,
+    defineAsyncContainerElement,
+    defineAsyncSuspenseElement,
+    readSnapshot
+  } from "@async/framework";
+
+  Async.start({
+    snapshot: readSnapshot(document),
+    registryAssets: { baseUrl: "_async" }
+  });
+
+  defineAsyncContainerElement();
+  defineAsyncSuspenseElement();
+</script>
+```
+
+`Async.start()` defaults to rootless browser startup. It creates registries,
+applies snapshots, and prepares the scheduler/server proxy context without
+scanning DOM. Attach a root later with `Async.attachRoot(root)` or by using
+`<async-container>`:
+
+```html
+<async-container>
+  <button type="button" on:click="cart.add">Add</button>
+</async-container>
+```
+
+Descriptor URLs are relative to a type folder under `registryAssets.baseUrl`.
+The default is:
+
+```js
+{
+  baseUrl: "_async",
+  paths: {
+    component: "component",
+    handler: "handler",
+    asyncSignal: "asyncSignal",
+    partial: "partial",
+    route: "route"
+  }
+}
+```
+
+So this descriptor:
+
+```json
+{ "url": "ProductCard.js#ProductCard" }
+```
+
+resolves as:
+
+```txt
+/_async/component/ProductCard.js#ProductCard
+```
+
+If `#export` is omitted, Async tries the registry id leaf, then the file
+basename, then `default`.
+
+For declarative async boundaries, use `<async-suspense>` or keep using
+`this.suspense(...)` inside components:
+
+```html
+<async-suspense for="product.load">
+  <template loading>Loading...</template>
+  <template ready>
+    <h1 signal:text="product.load.title"></h1>
+  </template>
+  <template error>
+    <p signal:text="product.load.$error.message"></p>
+  </template>
+</async-suspense>
+```
+
+The build layer can hide `createBoundaryReceiver(...)` setup, but streaming is
+still explicit boundary patches: boundary id, sequence number, HTML, signal
+patches, and browser-cache patches. Async does not ship a component resume graph.
+
 ## Core API
 
 For npm consumers, `@async/framework` uses conditional exports: browser-aware
@@ -202,6 +313,7 @@ import {
   createApp,
   createCacheRegistry,
   createComponentRegistry,
+  createLazyRegistry,
   component,
   computed,
   createSignal,
@@ -213,10 +325,13 @@ import {
   createScheduler,
   createServerProxy,
   createSignalRegistry,
+  defineAsyncContainerElement,
+  defineAsyncSuspenseElement,
   defineAttributeConfig,
   defineApp,
   defineCache,
   defineComponent,
+  defineRegistrySnapshot,
   defineRoute,
   delay,
   effect,
@@ -1050,6 +1165,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 |

package/browser.d.ts

@@ -13,6 +13,7 @@ export type RegistryType =
   | "partial"
   | "route"
   | "component"
+  | "asyncSignal"
   | "cache.browser"
   | "cache.server"
   | "cache.browser.entries"
@@ -34,6 +35,20 @@ export interface NormalizedAttributeConfig {
 
 export type TemplatePrimitive = string | number | boolean | null | undefined;
 export type TemplateLike = TemplateResult | TemplatePrimitive | Node | TemplateLike[];
+export interface LazyDescriptor {
+  url: string;
+  [key: string]: unknown;
+}
+export interface RegistryAssetsConfig {
+  baseUrl?: string;
+  paths?: Partial<Record<"component" | "handler" | "asyncSignal" | "partial" | "route", string>>;
+}
+export interface LazyRegistry {
+  registryAssets: Required<Pick<RegistryAssetsConfig, "baseUrl">> & { paths: Record<string, string> };
+  resolveUrl(type: "component" | "handler" | "asyncSignal" | "partial" | "route", id: string, descriptor: LazyDescriptor): { moduleUrl: string; exportNames: string[]; url: string };
+  resolve<T = unknown>(type: "component" | "handler" | "asyncSignal" | "partial" | "route", id: string, descriptor: LazyDescriptor): Promise<T>;
+  inspect(): { registryAssets: unknown; modules: string[]; exports: string[] };
+}
 
 export interface TemplateResult {
   readonly strings: TemplateStringsArray;
@@ -75,6 +90,7 @@ export interface Scheduler {
   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;
 }
@@ -208,8 +224,8 @@ export interface HandlerContext {
 export type HandlerFunction = (this: HandlerContext, context: HandlerContext) => MaybePromise<unknown>;
 
 export interface HandlerRegistry extends RegistryInspection<HandlerFunction> {
-  register(id: string, fn: HandlerFunction): string;
-  registerMany(map?: Record<string, HandlerFunction>): this;
+  register(id: string, fn: HandlerFunction | LazyDescriptor): string;
+  registerMany(map?: Record<string, HandlerFunction | LazyDescriptor>): this;
   unregister(id: string): boolean;
   resolve(id: string): HandlerFunction | undefined;
   run(ref: string, context?: Partial<HandlerContext>): Promise<unknown[]>;
@@ -321,8 +337,8 @@ export interface PartialContext {
 export type PartialFunction = (this: PartialContext, props: Record<string, unknown>) => MaybePromise<TemplateLike | ServerEnvelope>;
 
 export interface PartialRegistry extends RegistryInspection<PartialFunction> {
-  register(id: string, fn: PartialFunction): string;
-  registerMany(map?: Record<string, PartialFunction>): this;
+  register(id: string, fn: PartialFunction | LazyDescriptor): string;
+  registerMany(map?: Record<string, PartialFunction | LazyDescriptor>): this;
   unregister(id: string): boolean;
   resolve(id: string): PartialFunction | undefined;
   render(id: string, props?: Record<string, unknown>, context?: Partial<PartialContext>): Promise<ServerEnvelope>;
@@ -422,8 +438,8 @@ export interface SuspenseViews {
 }
 
 export interface ComponentRegistry extends RegistryInspection<ComponentFunction> {
-  register(id: string, Component: ComponentFunction): string;
-  registerMany(map?: Record<string, ComponentFunction>): this;
+  register(id: string, Component: ComponentFunction | LazyDescriptor): string;
+  registerMany(map?: Record<string, ComponentFunction | LazyDescriptor>): this;
   unregister(id: string): boolean;
   resolve(id: string): ComponentFunction | undefined;
 }
@@ -458,6 +474,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;
@@ -476,22 +539,24 @@ export interface RegistryStore {
 
 export interface RegistrySnapshot {
   signal: Record<string, unknown>;
-  handler: Record<string, { id: string; kind: "handler" }>;
-  server: Record<string, { id: string; kind: "server" }>;
-  partial: Record<string, { id: string; kind: "partial" }>;
+  handler: Record<string, { id?: string } | LazyDescriptor>;
+  server: Record<string, { id?: string } | LazyDescriptor>;
+  partial: Record<string, { id?: string } | LazyDescriptor>;
   route: Record<string, RouteDefinition>;
-  component: Record<string, { id: string; kind: "component" }>;
+  component: Record<string, { id?: string } | LazyDescriptor>;
+  asyncSignal: Record<string, { id?: string } | LazyDescriptor>;
   cache: { browser: Record<string, CacheDefinition>; server: Record<string, CacheDefinition> };
   entries: { browser: Record<string, unknown>; server: Record<string, unknown> };
 }
 
 export interface AppDefinition {
   signal?: SignalMap;
-  handler?: Record<string, HandlerFunction>;
+  handler?: Record<string, HandlerFunction | LazyDescriptor>;
   server?: Record<string, ServerFunction>;
-  partial?: Record<string, PartialFunction>;
+  partial?: Record<string, PartialFunction | LazyDescriptor>;
   route?: Record<string, RouteDefinition | string>;
-  component?: Record<string, ComponentFunction>;
+  component?: Record<string, ComponentFunction | LazyDescriptor>;
+  asyncSignal?: Record<string, AsyncSignalFunction | LazyDescriptor>;
   cache?: {
     browser?: Record<string, CacheDefinition | CacheDefinitionOptions>;
     server?: Record<string, CacheDefinition | CacheDefinitionOptions>;
@@ -499,25 +564,43 @@ export interface AppDefinition {
   entries?: { browser?: Record<string, unknown>; server?: Record<string, unknown> };
 }
 
+export interface RegistryRuntimeSnapshot extends AppDefinition {
+  signals?: Record<string, unknown>;
+}
+
+export interface RootInspection {
+  count: number;
+  roots: Array<{ root: Document | Element | DocumentFragment; loader: LoaderInstance; primary: boolean }>;
+}
+
 export interface AppHub {
   registry: RegistryStore;
   runtime?: AppRuntime;
   use(type: "signal", entries: SignalMap): this;
-  use(type: "handler", entries: Record<string, HandlerFunction>): this;
+  use(type: "handler", entries: Record<string, HandlerFunction | LazyDescriptor>): this;
   use(type: "server", entries: Record<string, ServerFunction>): this;
-  use(type: "partial", entries: Record<string, PartialFunction>): this;
+  use(type: "partial", entries: Record<string, PartialFunction | LazyDescriptor>): this;
   use(type: "route", entries: Record<string, RouteDefinition | string>): this;
-  use(type: "component", entries: Record<string, ComponentFunction>): this;
+  use(type: "component", entries: Record<string, ComponentFunction | LazyDescriptor>): this;
+  use(type: "asyncSignal", entries: Record<string, AsyncSignalFunction | LazyDescriptor>): this;
   use(moduleObject: AppDefinition): this;
   snapshot(): AppDefinition;
   start(options?: CreateAppOptions): AppRuntime;
+  attachRoot(root: Document | Element | DocumentFragment): AppRuntime;
+  detachRoot(root?: Document | Element | DocumentFragment): this;
+  applySnapshot(snapshot: RegistryRuntimeSnapshot, options?: { strict?: boolean }): this;
+  inspectRoots(): RootInspection;
 }
 
 export interface CreateAppOptions extends LoaderOptions {
   target?: RuntimeTarget;
   mode?: RouterMode;
   boundary?: string;
-  snapshot?: { signals?: Record<string, unknown>; cache?: { browser?: Record<string, unknown> } };
+  snapshot?: RegistryRuntimeSnapshot;
+  registryAssets?: RegistryAssetsConfig;
+  importModule?: (url: string) => MaybePromise<Record<string, unknown>>;
+  lazyRegistry?: LazyRegistry;
+  strictSnapshots?: boolean;
   registry?: RegistryStore;
   loader?: LoaderInstance;
   router?: Router | false;
@@ -556,6 +639,10 @@ export interface AppRuntime {
   attributes: NormalizedAttributeConfig;
   start(): this;
   use(type: Parameters<AppHub["use"]>[0], entries?: unknown): this;
+  attachRoot(root: Document | Element | DocumentFragment): this;
+  detachRoot(root?: Document | Element | DocumentFragment): this;
+  applySnapshot(snapshot: RegistryRuntimeSnapshot, options?: { strict?: boolean }): this;
+  inspectRoots(): RootInspection;
   render(url: string | URL): Promise<RenderResult>;
   destroy(): void;
 }
@@ -566,13 +653,22 @@ export interface AsyncNamespace extends AppHub {
   createApp: typeof createApp;
   defineApp: typeof defineApp;
   readSnapshot: typeof readSnapshot;
+  attachRoot: AppHub["attachRoot"];
+  detachRoot: AppHub["detachRoot"];
+  applySnapshot: AppHub["applySnapshot"];
+  inspectRoots: AppHub["inspectRoots"];
   attributeName: typeof attributeName;
   defineAttributeConfig: typeof defineAttributeConfig;
+  createBoundaryReceiver: typeof createBoundaryReceiver;
   createCacheRegistry: typeof createCacheRegistry;
   defineCache: typeof defineCache;
   component: typeof component;
   createComponentRegistry: typeof createComponentRegistry;
   defineComponent: typeof defineComponent;
+  defineAsyncContainerElement: typeof defineAsyncContainerElement;
+  defineAsyncSuspenseElement: typeof defineAsyncSuspenseElement;
+  defineRegistrySnapshot: typeof defineRegistrySnapshot;
+  createLazyRegistry: typeof createLazyRegistry;
   delay: typeof delay;
   createHandlerRegistry: typeof createHandlerRegistry;
   html: typeof html;
@@ -600,14 +696,19 @@ 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 readSnapshot(root?: Document | Element, options?: { attributes?: AttributeConfig }): RegistryRuntimeSnapshot;
 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>;
 export declare function createComponentRegistry(initialMap?: Record<string, ComponentFunction>, options?: { registry?: RegistryStore; type?: "component" }): ComponentRegistry;
 export declare function defineComponent<TProps extends Record<string, unknown> = Record<string, unknown>>(fn: ComponentFunction<TProps>): ComponentFunction<TProps>;
+export declare function defineAsyncContainerElement(options?: { tagName?: string; app?: AppHub; Async?: AppHub; customElements?: CustomElementRegistry; HTMLElement?: typeof HTMLElement; window?: Window }): CustomElementConstructor;
+export declare function defineAsyncSuspenseElement(options?: { tagName?: string; customElements?: CustomElementRegistry; HTMLElement?: typeof HTMLElement; window?: Window }): CustomElementConstructor;
+export declare function defineRegistrySnapshot<T extends RegistryRuntimeSnapshot>(snapshot?: T): T;
+export declare function createLazyRegistry(options?: { registryAssets?: RegistryAssetsConfig; assets?: RegistryAssetsConfig; importModule?: (url: string) => MaybePromise<Record<string, unknown>> }): LazyRegistry;
 export declare function delay(ms: number, signal?: AbortSignal): Promise<void>;
 export declare function createHandlerRegistry(initialMap?: Record<string, HandlerFunction>, options?: { registry?: RegistryStore; type?: "handler" }): HandlerRegistry;
 export declare function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;