@async/framework 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 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

@@ -100,7 +100,7 @@ production:
 | `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.ts` | Bundled TypeScript source | TS-aware runtimes and higher-layer tooling |
 | `framework.d.ts` | Type declarations | TypeScript declarations for the public API |
 
 ```html
@@ -215,6 +215,7 @@ import {
   delay,
   effect,
   html,
+  readSnapshot,
   route,
   signal
 } from "@async/framework";
@@ -411,6 +412,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:
@@ -819,11 +824,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`

package/framework.d.ts

@@ -262,6 +262,7 @@ export interface PartialContext {
   cache?: CacheRegistry;
   browserCache?: CacheRegistry;
   partials: PartialRegistry;
+  abort?: AbortSignal;
   request?: Request;
   locals?: unknown;
   [key: string]: unknown;
@@ -506,6 +507,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;
@@ -537,6 +539,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;

package/framework.js

@@ -536,6 +536,7 @@ const __cacheModule = (() => {
     const registryStore = registry ?? createRegistryStore();
     const definitions = registryStore._map(type);
     const entries = registryStore._map(`${type}.entries`);
+    const pending = new Map();
 
     const registryApi = attachRegistryInspection({
       register(id, definition = defineCache()) {
@@ -597,19 +598,37 @@ const __cacheModule = (() => {
         if (cached !== undefined) {
           return cached;
         }
-        const value = await fn();
-        registryApi.set(key, value, options);
-        return value;
+        if (pending.has(key)) {
+          return pending.get(key);
+        }
+        let promise;
+        promise = Promise.resolve()
+          .then(fn)
+          .then((value) => {
+            if (pending.get(key) === promise) {
+              registryApi.set(key, value, options);
+            }
+            return value;
+          })
+          .finally(() => {
+            if (pending.get(key) === promise) {
+              pending.delete(key);
+            }
+          });
+        pending.set(key, promise);
+        return promise;
       },
 
       delete(key) {
         assertKey(key);
+        pending.delete(key);
         return entries.delete(key);
       },
 
       clear(prefix) {
         if (prefix === undefined) {
           entries.clear();
+          pending.clear();
           return registryApi;
         }
         for (const key of [...entries.keys()]) {
@@ -617,6 +636,11 @@ const __cacheModule = (() => {
             entries.delete(key);
           }
         }
+        for (const key of [...pending.keys()]) {
+          if (key.startsWith(prefix)) {
+            pending.delete(key);
+          }
+        }
         return registryApi;
       },
 
@@ -1752,6 +1776,8 @@ const __componentModule = (() => {
 const __serverModule = (() => {
   const { attachRegistryInspection, createRegistryStore } = __registryStoreModule;
   const serverEnvelopeKeys = new Set(["value", "signals", "boundary", "html", "redirect", "error"]);
+  const appliedServerResult = Symbol.for("@async/framework.appliedServerResult");
+  const appliedServerValues = new WeakSet();
 
   function createServerRegistry(initialMap = {}, options = {}) {
     const registryStore = options.registry ?? createRegistryStore();
@@ -1858,6 +1884,7 @@ const __serverModule = (() => {
         input: context.input ?? defaultInput(runContext),
         signals: context.signalValues ?? snapshotSignalPaths(context.signalPaths, runContext.signals)
       };
+      assertJsonTransportable(body);
 
       const response = await fetchImpl(joinEndpoint(endpoint, id), {
         method: "POST",
@@ -1875,7 +1902,7 @@ const __serverModule = (() => {
 
       const result = await readServerResponse(response);
       await applyServerResult(result, runContext);
-      return unwrapServerResult(result);
+      return markAppliedServerValue(unwrapServerResult(result));
     }
 
     return createServerNamespace(run, {
@@ -1910,6 +1937,9 @@ const __serverModule = (() => {
     if (!isServerEnvelope(result)) {
       return result;
     }
+    if (result[appliedServerResult] || appliedServerValues.has(result)) {
+      return result;
+    }
 
     if (result.signals && context.signals) {
       for (const [path, value] of Object.entries(result.signals)) {
@@ -1933,6 +1963,12 @@ const __serverModule = (() => {
       throw toError(result.error);
     }
 
+    Object.defineProperty(result, appliedServerResult, {
+      configurable: true,
+      enumerable: false,
+      value: true
+    });
+
     return result;
   }
 
@@ -1943,6 +1979,13 @@ const __serverModule = (() => {
     return result;
   }
 
+  function markAppliedServerValue(value) {
+    if (value && typeof value === "object") {
+      appliedServerValues.add(value);
+    }
+    return value;
+  }
+
   function defaultInput(context = {}) {
     const form = findForm(context);
     if (form) {
@@ -2120,6 +2163,30 @@ const __serverModule = (() => {
     return output;
   }
 
+  function assertJsonTransportable(value, seen = new Set()) {
+    if (value == null || typeof value !== "object") {
+      return;
+    }
+    if (seen.has(value)) {
+      return;
+    }
+    seen.add(value);
+
+    const tag = Object.prototype.toString.call(value);
+    if (tag === "[object File]" || tag === "[object Blob]" || tag === "[object FormData]") {
+      throw new Error("Server proxy JSON transport does not support File, Blob, or FormData values yet.");
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        assertJsonTransportable(item, seen);
+      }
+      return;
+    }
+    for (const item of Object.values(value)) {
+      assertJsonTransportable(item, seen);
+    }
+  }
+
   function joinEndpoint(endpoint, id) {
     return `${String(endpoint).replace(/\/$/, "")}/${encodeURIComponent(id)}`;
   }
@@ -3219,6 +3286,7 @@ const __routerModule = (() => {
         const nextRoute = normalizeRoute(pattern, definition);
         entries.set(pattern, nextRoute.definition);
         routes.push(nextRoute);
+        sortRoutes(routes);
         return nextRoute;
       },
 
@@ -3291,6 +3359,7 @@ const __routerModule = (() => {
       const nextRoute = normalizeRoute(pattern, definition);
       entries.set(pattern, nextRoute.definition);
       routes.push(nextRoute);
+      sortRoutes(routes);
     }
   }
 
@@ -3327,6 +3396,8 @@ const __routerModule = (() => {
     const ownsLoader = !loader;
     const cleanups = new Set();
     let destroyed = false;
+    let navigationVersion = 0;
+    let activeNavigation;
 
     const api = {
       mode,
@@ -3366,7 +3437,7 @@ const __routerModule = (() => {
       },
 
       match(url) {
-        return routes.match(url);
+        return routes.match(resolveUrl(url));
       },
 
       prefetch(url) {
@@ -3391,7 +3462,7 @@ const __routerModule = (() => {
           return null;
         }
 
-        const target = toUrl(url);
+        const target = resolveUrl(url);
         if (mode === "ssr-spa") {
           return fetchRoutePartial(target, options);
         }
@@ -3403,6 +3474,7 @@ const __routerModule = (() => {
           return;
         }
         destroyed = true;
+        activeNavigation?.controller.abort(new Error("Router has been destroyed."));
         for (const cleanup of cleanups) {
           cleanup();
         }
@@ -3442,24 +3514,37 @@ const __routerModule = (() => {
     async function renderLocalRoutePartial(target, options = {}) {
       const matched = api.match(target);
       if (!matched) {
+        beginNavigation(target, null);
         setNoRouteError(target);
         return null;
       }
 
+      const navigation = beginNavigation(target, matched);
       setMatchedRouterState(target, matched, { pending: true, error: null });
 
       try {
         if (!matched.route?.partial || !partials?.resolve?.(matched.route.partial)) {
           const error = new Error(`Route "${target.pathname}" does not have a registered partial.`);
-          setRouterState({ pending: false, error });
+          if (isActiveNavigation(navigation)) {
+            setRouterState({ pending: false, error });
+          }
           return null;
         }
 
-        const result = await partials.render(matched.route.partial, matched.params, contextFor(matched));
-        await applyNavigationResult(result, target, options);
+        const result = await partials.render(matched.route.partial, matched.params, contextFor(matched, navigation));
+        if (!isActiveNavigation(navigation)) {
+          return null;
+        }
+        await applyNavigationResult(result, target, options, navigation);
+        if (!isActiveNavigation(navigation)) {
+          return null;
+        }
         setRouterState({ pending: false, error: null });
         return result;
       } catch (error) {
+        if (!isActiveNavigation(navigation)) {
+          return null;
+        }
         setRouterState({ pending: false, error });
         throw error;
       }
@@ -3467,26 +3552,43 @@ const __routerModule = (() => {
 
     async function fetchRoutePartial(target, options = {}) {
       const matched = api.match(target);
+      const navigation = beginNavigation(target, matched);
       setMatchedRouterState(target, matched, { pending: true, error: null });
 
       try {
-        const result = await fetchRoute(target.href);
-        await applyNavigationResult(result, target, options);
+        const result = await fetchRoute(target.href, { signal: navigation.abort });
+        if (!isActiveNavigation(navigation)) {
+          return null;
+        }
+        await applyNavigationResult(result, target, options, navigation);
+        if (!isActiveNavigation(navigation)) {
+          return null;
+        }
         setRouterState({ pending: false, error: null });
         return result;
       } catch (error) {
+        if (!isActiveNavigation(navigation)) {
+          return null;
+        }
         setRouterState({ pending: false, error });
         throw error;
       }
     }
 
-    async function applyNavigationResult(result, target, options) {
+    async function applyNavigationResult(result, target, options, navigation) {
+      if (!isActiveNavigation(navigation)) {
+        return;
+      }
       await applyServerResult(result, {
         signals: signalRegistry,
         loader: loaderInstance,
         router: api,
-        cache
+        cache,
+        abort: navigation?.abort
       });
+      if (!isActiveNavigation(navigation)) {
+        return;
+      }
       if (result?.html != null && !result.boundary && !result.redirect) {
         loaderInstance.swap(boundary, result.html);
       }
@@ -3500,14 +3602,15 @@ const __routerModule = (() => {
       documentRef.defaultView?.history?.pushState?.({}, "", target.href);
     }
 
-    async function fetchRoute(url, { prefetch = false } = {}) {
+    async function fetchRoute(url, { prefetch = false, signal } = {}) {
       if (typeof fetchImpl !== "function") {
         throw new Error("Router navigation requires a partial registry or fetch.");
       }
       const response = await fetchImpl(`${routeEndpoint}?to=${encodeURIComponent(String(url))}`, {
         headers: {
           accept: "application/json, text/html"
-        }
+        },
+        signal
       });
       if (!response.ok) {
         throw new Error(`Route "${url}" failed with ${response.status}.`);
@@ -3522,7 +3625,7 @@ const __routerModule = (() => {
       return { boundary, html: await response.text() };
     }
 
-    function contextFor(matched) {
+    function contextFor(matched, navigation) {
       return {
         params: matched.params,
         route: matched.route,
@@ -3532,8 +3635,26 @@ const __routerModule = (() => {
         loader: loaderInstance,
         server,
         cache,
-        abort: undefined
+        abort: navigation?.abort
+      };
+    }
+
+    function beginNavigation(target, matched) {
+      activeNavigation?.controller.abort(new Error(`Router navigation superseded by ${target.pathname}${target.search}.`));
+      const controller = new AbortController();
+      const navigation = {
+        id: ++navigationVersion,
+        controller,
+        abort: controller.signal,
+        target,
+        matched
       };
+      activeNavigation = navigation;
+      return navigation;
+    }
+
+    function isActiveNavigation(navigation) {
+      return !destroyed && navigation && activeNavigation?.id === navigation.id && !navigation.abort.aborted;
     }
 
     function updateStateFromLocation() {
@@ -3570,7 +3691,14 @@ const __routerModule = (() => {
     }
 
     function currentUrl() {
-      return toUrl(documentRef.defaultView?.location?.href ?? "http://localhost/");
+      return resolveUrl(documentRef.defaultView?.location?.href ?? "http://localhost/");
+    }
+
+    function resolveUrl(url) {
+      if (url instanceof URL) {
+        return url;
+      }
+      return new URL(String(url), documentRef.defaultView?.location?.href ?? "http://localhost/");
     }
 
     function assertActive() {
@@ -3587,6 +3715,7 @@ const __routerModule = (() => {
       pattern,
       regex,
       keys,
+      score: routeScore(pattern),
       definition: normalized
     };
   }
@@ -3655,6 +3784,28 @@ const __routerModule = (() => {
     return String(value).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   }
 
+  function sortRoutes(routes) {
+    routes.sort((left, right) => right.score - left.score || right.pattern.length - left.pattern.length);
+  }
+
+  function routeScore(pattern) {
+    if (pattern === "*") {
+      return -1;
+    }
+    return pattern
+      .split("/")
+      .filter(Boolean)
+      .reduce((score, segment) => {
+        if (segment === "*") {
+          return score;
+        }
+        if (segment.startsWith(":")) {
+          return score + 2;
+        }
+        return score + 4;
+      }, pattern === "/" ? 3 : 0);
+  }
+
   function assertPattern(pattern) {
     if (typeof pattern !== "string" || (pattern !== "*" && !pattern.startsWith("/"))) {
       throw new TypeError("Route pattern must be a path string or \"*\".");
@@ -3738,7 +3889,7 @@ const __appModule = (() => {
     let started = false;
     let destroyed = false;
 
-    applySnapshot(signals, browserCache, options.snapshot);
+    applySnapshot(signals, browserCache, options.snapshot ?? (target === "browser" ? readSnapshot(options.root, { attributes }) : undefined));
     attachServerCache(server, serverCache);
 
     const runtime = {
@@ -3906,6 +4057,38 @@ const __appModule = (() => {
 
   const Async = defineApp();
 
+  function readSnapshot(root = globalThis.document, { attributes } = {}) {
+    const attributeConfig = normalizeAttributeConfig(attributes);
+    const snapshotAttr = attributeName(attributeConfig, "async", "snapshot");
+    const documentRef = root?.ownerDocument ?? root ?? globalThis.document;
+    const rootNode = root ?? documentRef;
+    if (!rootNode?.querySelectorAll && !documentRef?.querySelectorAll) {
+      return {};
+    }
+
+    for (const searchRoot of new Set([rootNode, documentRef])) {
+      if (!searchRoot?.querySelectorAll) {
+        continue;
+      }
+      for (const script of searchRoot.querySelectorAll("script[type='application/json'], script")) {
+        if (!script.hasAttribute?.(snapshotAttr)) {
+          continue;
+        }
+        const source = script.textContent?.trim() ?? "";
+        if (!source) {
+          return {};
+        }
+        try {
+          return JSON.parse(source);
+        } catch (cause) {
+          throw new Error(`Could not parse Async snapshot: ${cause instanceof Error ? cause.message : String(cause)}`);
+        }
+      }
+    }
+
+    return {};
+  }
+
   function applyUseToRuntime(runtime, normalized) {
     applyRegistryUse(runtime.signals, runtime.registry, normalized.signal);
     applyRegistryUse(runtime.handlers, runtime.registry, normalized.handler);
@@ -4066,7 +4249,7 @@ const __appModule = (() => {
   function escapeScriptJson(value) {
     return JSON.stringify(value).replaceAll("<", "\\u003c");
   }
-  return { defineApp, createApp, Async };
+  return { defineApp, createApp, readSnapshot, Async };
 })();
 
 const __delayModule = (() => {
@@ -4107,6 +4290,7 @@ const { asyncSignal: asyncSignal } = __asyncSignalModule;
 const { Async: Async } = __appModule;
 const { createApp: createApp } = __appModule;
 const { defineApp: defineApp } = __appModule;
+const { readSnapshot: readSnapshot } = __appModule;
 const { attributeName: attributeName } = __attributesModule;
 const { defineAttributeConfig: defineAttributeConfig } = __attributesModule;
 const { createCacheRegistry: createCacheRegistry } = __cacheModule;
@@ -4133,4 +4317,4 @@ const { createSignalRegistry: createSignalRegistry } = __signalsModule;
 const { effect: effect } = __signalsModule;
 const { signal: signal } = __signalsModule;
 
-export { asyncSignal, Async, createApp, defineApp, attributeName, defineAttributeConfig, createCacheRegistry, defineCache, component, createComponentRegistry, defineComponent, delay, createHandlerRegistry, html, Loader, AsyncLoader, createPartialRegistry, createRegistryStore, createRouteRegistry, createRouter, defineRoute, route, createServerProxy, createServerRegistry, computed, createSignal, createSignalRegistry, effect, signal };
+export { asyncSignal, Async, createApp, defineApp, readSnapshot, attributeName, defineAttributeConfig, createCacheRegistry, defineCache, component, createComponentRegistry, defineComponent, delay, createHandlerRegistry, html, Loader, AsyncLoader, createPartialRegistry, createRegistryStore, createRouteRegistry, createRouter, defineRoute, route, createServerProxy, createServerRegistry, computed, createSignal, createSignalRegistry, effect, signal };