@async/framework 0.9.0 → 0.10.1

package/server.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;
@@ -209,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[]>;
@@ -322,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>;
@@ -423,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;
 }
@@ -524,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>;
@@ -547,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;
@@ -604,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;
 }
@@ -614,6 +653,10 @@ 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;
@@ -622,6 +665,10 @@ export interface AsyncNamespace extends AppHub {
   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;
@@ -651,7 +698,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 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;
@@ -660,6 +707,10 @@ export declare function defineCache(options?: CacheDefinitionOptions): CacheDefi
 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;

package/src/app.js

@@ -9,8 +9,9 @@ import { createServerNamespace } from "./server.js";
 import { createSignal, createSignalRegistry } from "./signals.js";
 import { createRegistryStore } from "./registry-store.js";
 import { attributeName, normalizeAttributeConfig } from "./attributes.js";
+import { createLazyRegistry, defineRegistrySnapshot, sameRegistryValue } from "./lazy-registry.js";
 
-const registryTypes = new Set(["signal", "handler", "server", "partial", "route", "component"]);
+const registryTypes = new Set(["signal", "handler", "server", "partial", "route", "component", "asyncSignal"]);
 
 export function defineApp(initial, options = {}) {
   const registry = createRegistryStore(undefined, { target: "browser" });
@@ -39,6 +40,27 @@ export function defineApp(initial, options = {}) {
       return runtime;
     },
 
+    attachRoot(root) {
+      return ensureRuntime(app).attachRoot(root);
+    },
+
+    detachRoot(root) {
+      return app.runtime?.detachRoot(root) ?? app;
+    },
+
+    applySnapshot(snapshot, snapshotOptions = {}) {
+      if (app.runtime) {
+        app.runtime.applySnapshot(snapshot, snapshotOptions);
+        return app;
+      }
+      appendSnapshotDeclarations(registry, snapshot, snapshotOptions);
+      return app;
+    },
+
+    inspectRoots() {
+      return app.runtime?.inspectRoots() ?? { count: 0, roots: [] };
+    },
+
     _attach(runtime) {
       runtimes.add(runtime);
       return () => app._detach(runtime);
@@ -64,23 +86,32 @@ export function createApp(appOrDefinition = Async, options = {}) {
   });
   const ownsScheduler = !options.scheduler && !options.loader?.scheduler;
   const attributes = normalizeAttributeConfig(options.attributes);
+  const lazyRegistry = options.lazyRegistry ?? createLazyRegistry({
+    registryAssets: options.registryAssets,
+    importModule: options.importModule
+  });
   const registry = options.registry ?? app.registry.view({ target });
-  const signals = options.signals ?? createSignalRegistry(undefined, { registry, type: "signal" });
-  const handlers = options.handlers ?? createHandlerRegistry(undefined, { registry, type: "handler" });
+  const signals = options.signals ?? createSignalRegistry(undefined, { registry, type: "signal", lazyRegistry });
+  const handlers = options.handlers ?? createHandlerRegistry(undefined, { registry, type: "handler", lazyRegistry });
   const serverCache = createCacheRegistry(undefined, { registry, type: "cache.server" });
   const browserCache = createCacheRegistry(undefined, { registry, type: "cache.browser" });
   const serverFactory = options.serverFactory ?? createServerReferenceRegistry;
   const server = options.server ?? serverFactory(undefined, { registry, type: "server" });
-  const partials = options.partials ?? createPartialRegistry(undefined, { registry, type: "partial" });
+  const partials = options.partials ?? createPartialRegistry(undefined, { registry, type: "partial", lazyRegistry });
   const routes = options.routes ?? createRouteRegistry(undefined, { registry, type: "route" });
-  const components = options.components ?? createComponentRegistry(undefined, { registry, type: "component" });
+  const components = options.components ?? createComponentRegistry(undefined, { registry, type: "component", lazyRegistry });
+  const hasStartupRoot = options.loader || Object.hasOwn(options, "root");
+  const startupRoot = hasStartupRoot ? options.root : null;
   let loader = options.loader;
   let router = options.router;
+  let routerStarted = false;
   let detach = () => {};
   let started = false;
   let destroyed = false;
+  const rootLoaders = new Map();
 
-  applySnapshot(signals, browserCache, options.snapshot ?? (target === "browser" ? readSnapshot(options.root, { attributes }) : undefined));
+  const snapshotRoot = startupRoot ?? globalThis.document;
+  const initialSnapshot = options.snapshot ?? (target === "browser" ? readSnapshot(snapshotRoot, { attributes }) : undefined);
   attachServerCache(server, serverCache);
 
   const runtime = {
@@ -109,54 +140,112 @@ export function createApp(appOrDefinition = Async, options = {}) {
       started = true;
 
       if (target !== "server") {
-        loader = loader ?? Loader({
-          root: options.root,
-          signals,
-          handlers,
-          server,
-          cache: browserCache,
-          scheduler,
-          attributes
-        });
-        runtime.loader = loader;
-
         configureServerContext({ cache: browserCache });
         signals._setContext?.({ server, loader, cache: browserCache, scheduler });
 
-        loader.start();
+        if (loader) {
+          registerRootLoader(loader.root, loader);
+          loader.start();
+          startRouterFor(loader.root);
+        } else if (startupRoot != null) {
+          runtime.attachRoot(startupRoot);
+        }
+      } else {
+        configureServerContext({ cache: serverCache });
+        signals._setContext?.({ server, cache: serverCache, scheduler });
+      }
+
+      return runtime;
+    },
+
+    use(typeOrModule, entries) {
+      app.use(typeOrModule, entries);
+      return runtime;
+    },
+
+    attachRoot(root) {
+      assertActive();
+      if (target === "server") {
+        throw new Error("Server runtimes cannot attach DOM roots.");
+      }
+      if (!root) {
+        throw new TypeError("runtime.attachRoot(root) requires a root.");
+      }
+      if (rootLoaders.has(root)) {
+        return runtime;
+      }
 
-        if (router !== false && (router || shouldStartRouter(routes, options))) {
-          router = router ?? createRouter({
-            mode: options.mode ?? "ssr-spa",
-            root: options.root,
-            boundary: options.boundary ?? "route",
-            routes,
-            loader,
+      const rootLoader = rootLoaders.size === 0 && loader
+        ? loader
+        : Loader({
+            root,
             signals,
             handlers,
             server,
             cache: browserCache,
-            partials,
             scheduler,
-            fetch: options.fetch,
-            routeEndpoint: options.routeEndpoint,
             attributes
           });
-          runtime.router = router;
-          loader.router = router;
-          configureServerContext({ cache: browserCache, router });
-          router.start();
+      registerRootLoader(root, rootLoader);
+      rootLoader.start();
+      configureServerContext({ cache: browserCache });
+      signals._setContext?.({ server, loader: runtime.loader, cache: browserCache, scheduler });
+      startRouterFor(root);
+      return runtime;
+    },
+
+    detachRoot(root) {
+      assertActive();
+      if (target === "server") {
+        return runtime;
+      }
+      if (root == null) {
+        for (const rootLoader of new Set(rootLoaders.values())) {
+          rootLoader.destroy?.();
+        }
+        rootLoaders.clear();
+        router?.destroy?.();
+        router = undefined;
+        routerStarted = false;
+        loader = undefined;
+        runtime.loader = undefined;
+        runtime.router = undefined;
+        return runtime;
+      }
+      const rootLoader = rootLoaders.get(root);
+      if (!rootLoader) {
+        return runtime;
+      }
+      rootLoader.destroy?.();
+      rootLoaders.delete(root);
+      if (loader === rootLoader) {
+        router?.destroy?.();
+        router = undefined;
+        routerStarted = false;
+        const next = rootLoaders.values().next().value;
+        loader = next;
+        runtime.loader = next;
+        runtime.router = undefined;
+        if (next) {
+          startRouterFor(next.root);
         }
-      } else {
-        configureServerContext({ cache: serverCache });
-        signals._setContext?.({ server, cache: serverCache, scheduler });
       }
-
       return runtime;
     },
 
-    use(typeOrModule, entries) {
-      app.use(typeOrModule, entries);
+    inspectRoots() {
+      return {
+        count: rootLoaders.size,
+        roots: [...rootLoaders].map(([root, rootLoader]) => ({
+          root,
+          loader: rootLoader,
+          primary: rootLoader === loader
+        }))
+      };
+    },
+
+    applySnapshot(snapshot, snapshotOptions = {}) {
+      applySnapshotToRuntime(runtime, snapshot, snapshotOptions);
       return runtime;
     },
 
@@ -218,7 +307,14 @@ export function createApp(appOrDefinition = Async, options = {}) {
       destroyed = true;
       detach();
       router?.destroy?.();
-      loader?.destroy?.();
+      const destroyedLoaders = new Set(rootLoaders.values());
+      for (const rootLoader of destroyedLoaders) {
+        rootLoader.destroy?.();
+      }
+      rootLoaders.clear();
+      if (loader && !destroyedLoaders.has(loader)) {
+        loader?.destroy?.();
+      }
       signals.destroy?.();
       if (ownsScheduler) {
         scheduler.destroy();
@@ -232,10 +328,49 @@ export function createApp(appOrDefinition = Async, options = {}) {
 
   server.cache = serverCache;
   runtime.server.cache = serverCache;
+  runtime.applySnapshot(initialSnapshot, { strict: options.strictSnapshots ?? true });
   detach = app._attach(runtime);
 
   return runtime;
 
+  function registerRootLoader(root, rootLoader) {
+    rootLoaders.set(root, rootLoader);
+    if (!loader) {
+      loader = rootLoader;
+      runtime.loader = rootLoader;
+    }
+    rootLoader.server = server;
+    rootLoader.cache = browserCache;
+    rootLoader.scheduler = scheduler;
+  }
+
+  function startRouterFor(root) {
+    if (router === false || routerStarted || !(router || shouldStartRouter(routes, options)) || !runtime.loader) {
+      return;
+    }
+    router = router ?? createRouter({
+      mode: options.mode ?? "ssr-spa",
+      root,
+      boundary: options.boundary ?? "route",
+      routes,
+      loader: runtime.loader,
+      signals,
+      handlers,
+      server,
+      cache: browserCache,
+      partials,
+      scheduler,
+      fetch: options.fetch,
+      routeEndpoint: options.routeEndpoint,
+      attributes
+    });
+    runtime.router = router;
+    runtime.loader.router = router;
+    configureServerContext({ cache: browserCache, router });
+    router.start();
+    routerStarted = true;
+  }
+
   function configureServerContext(extra = {}) {
     const cache = isLocalServerRegistry(server) ? serverCache : extra.cache;
     server._setContext?.({
@@ -278,6 +413,7 @@ export function readSnapshot(root = globalThis.document, { attributes } = {}) {
     return {};
   }
 
+  const merged = {};
   for (const searchRoot of new Set([rootNode, documentRef])) {
     if (!searchRoot?.querySelectorAll) {
       continue;
@@ -288,17 +424,19 @@ export function readSnapshot(root = globalThis.document, { attributes } = {}) {
       }
       const source = script.textContent?.trim() ?? "";
       if (!source) {
-        return {};
+        continue;
       }
+      let parsed;
       try {
-        return JSON.parse(source);
+        parsed = JSON.parse(source);
       } catch (cause) {
         throw new Error(`Could not parse Async snapshot: ${cause instanceof Error ? cause.message : String(cause)}`);
       }
+      mergeSnapshot(merged, parsed, { strict: true });
     }
   }
 
-  return {};
+  return merged;
 }
 
 function applyUseToRuntime(runtime, normalized) {
@@ -308,10 +446,22 @@ function applyUseToRuntime(runtime, normalized) {
   applyRegistryUse(runtime.partials, runtime.registry, normalized.partial);
   applyRegistryUse(runtime.routes, runtime.registry, normalized.route);
   applyRegistryUse(runtime.components, runtime.registry, normalized.component);
+  applyRegistryStoreUse(runtime.registry, "asyncSignal", normalized.asyncSignal);
   applyRegistryUse(runtime.browser.cache, runtime.registry, normalized.cache.browser);
   applyRegistryUse(runtime.server.cache, runtime.registry, normalized.cache.server);
 }
 
+function applyRegistryStoreUse(registry, type, entries) {
+  if (!entries || Object.keys(entries).length === 0) {
+    return;
+  }
+  for (const [id, value] of Object.entries(entries)) {
+    if (!registry.has(type, id)) {
+      registry.register(type, id, value);
+    }
+  }
+}
+
 function applyRegistryUse(registry, runtimeRegistry, entries) {
   if (!entries || Object.keys(entries).length === 0) {
     return;
@@ -331,6 +481,7 @@ function emptyDeclarations() {
     partial: {},
     route: {},
     component: {},
+    asyncSignal: {},
     cache: {
       browser: {},
       server: {}
@@ -386,11 +537,128 @@ function isAppHub(value) {
   return Boolean(value && typeof value.use === "function" && typeof value.snapshot === "function" && value.registry);
 }
 
-function applySnapshot(signals, browserCache, snapshot = {}) {
-  for (const [path, value] of Object.entries(snapshot.signals ?? {})) {
-    setOrRegisterSignal(signals, path, value);
+function ensureRuntime(app) {
+  if (!app.runtime) {
+    app.start();
+  }
+  return app.runtime;
+}
+
+function applySnapshotToRuntime(runtime, snapshot = {}, options = {}) {
+  const normalized = normalizeSnapshot(snapshot);
+  for (const [path, value] of Object.entries(normalized.signal)) {
+    setOrRegisterSignal(runtime.signals, path, value);
+  }
+  runtime.browser.cache.restore(normalized.cache.browser);
+  mergeRegistryEntries(runtime, "handler", normalized.handler, runtime.handlers, options);
+  mergeRegistryEntries(runtime, "server", normalized.server, runtime.server, options);
+  mergeRegistryEntries(runtime, "partial", normalized.partial, runtime.partials, options);
+  mergeRegistryEntries(runtime, "route", normalized.route, runtime.routes, options);
+  mergeRegistryEntries(runtime, "component", normalized.component, runtime.components, options);
+  mergeRegistryEntries(runtime, "asyncSignal", normalized.asyncSignal, null, options);
+  return runtime;
+}
+
+function appendSnapshotDeclarations(registry, snapshot = {}, options = {}) {
+  const normalized = normalizeSnapshot(snapshot);
+  for (const [id, value] of Object.entries(normalized.signal)) {
+    registerSnapshotEntry(registry, "signal", id, createSignal(value), options);
+  }
+  for (const type of ["handler", "server", "partial", "route", "component", "asyncSignal"]) {
+    for (const [id, value] of Object.entries(normalized[type])) {
+      registerSnapshotEntry(registry, type, id, value, options);
+    }
+  }
+}
+
+function mergeRegistryEntries(runtime, type, entries, concreteRegistry, options = {}) {
+  if (!entries || Object.keys(entries).length === 0) {
+    return;
+  }
+  for (const [id, value] of Object.entries(entries)) {
+    registerSnapshotEntry(runtime.registry, type, id, value, options);
+  }
+  concreteRegistry?._adoptMany?.(entries);
+}
+
+function registerSnapshotEntry(registry, type, id, value, options = {}) {
+  const strict = options.strict ?? true;
+  const map = registry._map(type);
+  if (map.has(id)) {
+    if (sameRegistryValue(map.get(id), value) || sameSnapshotValue(map.get(id), value)) {
+      return;
+    }
+    if (strict) {
+      throw new Error(`${type} "${id}" is already registered with a different value.`);
+    }
+    return;
+  }
+  registry.set(type, id, value);
+}
+
+function normalizeSnapshot(snapshot = {}) {
+  const normalized = {
+    signal: {
+      ...(snapshot.signals ?? {}),
+      ...(snapshot.signal ?? {})
+    },
+    handler: { ...(snapshot.handler ?? {}) },
+    server: { ...(snapshot.server ?? {}) },
+    partial: { ...(snapshot.partial ?? {}) },
+    route: { ...(snapshot.route ?? {}) },
+    component: { ...(snapshot.component ?? {}) },
+    asyncSignal: { ...(snapshot.asyncSignal ?? {}) },
+    cache: {
+      browser: {
+        ...(snapshot.entries?.browser ?? {}),
+        ...(snapshot.cache?.browser ?? {})
+      }
+    }
+  };
+  return normalized;
+}
+
+function mergeSnapshot(target, source, options = {}) {
+  const normalized = normalizeSnapshot(defineRegistrySnapshot(source));
+  target.signal = {
+    ...(target.signal ?? target.signals ?? {}),
+    ...normalized.signal
+  };
+  target.signals = target.signal;
+  target.cache = {
+    ...(target.cache ?? {}),
+    browser: {
+      ...(target.cache?.browser ?? {}),
+      ...normalized.cache.browser
+    }
+  };
+  for (const type of ["handler", "server", "partial", "route", "component", "asyncSignal"]) {
+    target[type] = target[type] ?? {};
+    for (const [id, value] of Object.entries(normalized[type])) {
+      if (Object.hasOwn(target[type], id)) {
+        if (sameRegistryValue(target[type][id], value) || sameSnapshotValue(target[type][id], value)) {
+          continue;
+        }
+        if (options.strict ?? true) {
+          throw new Error(`${type} "${id}" is already declared with a different value.`);
+        }
+        continue;
+      }
+      target[type][id] = value;
+    }
+  }
+  return target;
+}
+
+function sameSnapshotValue(left, right) {
+  if (left === right) {
+    return true;
+  }
+  try {
+    return JSON.stringify(left) === JSON.stringify(right);
+  } catch {
+    return false;
   }
-  browserCache.restore(snapshot.cache?.browser);
 }
 
 function setOrRegisterSignal(signals, path, value) {

package/src/browser.js

@@ -5,8 +5,10 @@ export { createBoundaryReceiver } from "./boundary-receiver.js";
 export { createCacheRegistry, defineCache } from "./cache.js";
 export { component, createComponentRegistry, defineComponent } from "./component.js";
 export { delay } from "./delay.js";
+export { defineAsyncContainerElement, defineAsyncSuspenseElement } from "./elements.js";
 export { createHandlerRegistry } from "./handlers.js";
 export { html } from "./html.js";
+export { createLazyRegistry, defineRegistrySnapshot } from "./lazy-registry.js";
 export { Loader, AsyncLoader } from "./loader.js";
 export { createPartialRegistry } from "./partials.js";
 export { createRegistryStore } from "./registry-store.js";