npm - @async/framework - Versions diffs - 0.1.0 → 0.2.0 - Mend

@async/framework 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/CHANGELOG.md +5 -0
package/README.md +65 -18
package/examples/router/index.html +2 -5
package/examples/router/main.js +1 -1
package/package.json +1 -1
package/src/router.js +104 -45

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,10 @@
 # Changelog
+## 0.2.0 - 2026-06-17
+- Added `csr` router mode for client-side first route rendering plus local SPA
+  navigation through route partial boundary swaps.
 ## 0.1.0 - 2026-06-17
 - Reset `@async/framework` to Layer 1 AsyncLoader.

package/README.md CHANGED Viewed

@@ -375,34 +375,81 @@ const partials = createPartialRegistry({
 });
 ```
-The router swaps route partials into a boundary:
+The router swaps route partials into a boundary. `csr` starts from an empty
+route boundary, renders the current route partial locally, then keeps future
+navigation local too:
 ```js
-const router = createRouter({
-  mode: "ssr-spa",
-  root: document,
-  boundary: "route",
-  routes: createRouteRegistry({
+Async.use({
+  partial: {
+    home() {
+      return html`<h1>Home</h1>`;
+    },
+    "product.page"({ id }) {
+      return html`<h1>Product ${id}</h1>`;
+    }
+  },
+  route: {
     "/": defineRoute("home"),
     "/products/:id": defineRoute("product.page")
-  }),
-  loader,
-  signals,
-  server,
-  partials
-}).start();
+  }
+});
+Async.start({
+  mode: "csr",
+  boundary: "route",
+  root: document
+});
 ```
 `route(...)` remains a compatibility alias for `defineRoute(...)`.
 Router modes:
-| Mode | Behavior |
+| Mode | Initial route | Later navigation |
 | --- | --- |
-| `spa` | Intercepts same-origin links and GET forms, then swaps route HTML |
-| `ssr-spa` | Starts from server HTML, then uses SPA navigation |
-| `mpa` | Does not intercept navigation |
-| `ssr` | Leaves navigation to the server document flow |
+| `csr` | Client renders local partial into boundary | Client renders local partial and swaps |
+| `spa` | Existing HTML may already contain route | Client renders local partial and swaps |
+| `ssr` | Server rendered document | Browser navigates normally |
+| `ssr-spa` | Server rendered document/route boundary | Fetch route partial, apply effects, swap |
+| `mpa` | Any document source | Browser navigates normally |
+CSR startup can use an empty route boundary:
+```html
+<main data-async-container>
+  <nav>
+    <a href="/">Home</a>
+    <a href="/products/sku-1">Product</a>
+  </nav>
+  <section data-async-boundary="route"></section>
+</main>
+```
+Router state lives under `router.*` signals:
+```txt
+router.url
+router.path
+router.params
+router.query
+router.route
+router.pending
+router.error
+```
+Register a wildcard route for an explicit fallback page:
+```js
+Async.use({
+  route: {
+    "/": defineRoute("home.page"),
+    "/products/:id": defineRoute("product.page"),
+    "*": defineRoute("notFound.page")
+  }
+});
+```
 ### Cache
@@ -569,7 +616,7 @@ rescans the inserted fragment.
 | [`examples/components`](./examples/components) | Scoped fragment components and lifecycle hooks |
 | [`examples/streaming`](./examples/streaming) | Boundary swaps with rescanned handlers |
 | [`examples/server-call`](./examples/server-call) | Command events calling server functions |
-| [`examples/router`](./examples/router) | SSR-SPA route boundary swaps |
+| [`examples/router`](./examples/router) | CSR first render and local route boundary swaps |
 | [`examples/partials`](./examples/partials) | Server-rendered partial fragments |
 | [`examples/cache`](./examples/cache) | Browser/server cache declarations |
 | [`examples/ssr`](./examples/ssr) | Server render output and browser activation snapshot |

package/examples/router/index.html CHANGED Viewed

@@ -3,7 +3,7 @@
   <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
-    <title>AsyncLoader Router</title>
+    <title>AsyncLoader CSR Router</title>
   </head>
   <body>
     <main data-async-container>
@@ -11,10 +11,7 @@
         <a href="/">Home</a>
         <a href="/products/sku-1">Product</a>
       </nav>
-      <section data-async-boundary="route">
-        <h1>Home</h1>
-        <p>Cart: <strong data-async-text="routerDemo.cartCount"></strong></p>
-      </section>
+      <section data-async-boundary="route"></section>
     </main>
     <script type="module" src="./main.js"></script>
   </body>

package/examples/router/main.js CHANGED Viewed

@@ -46,7 +46,7 @@ Async.use({
 });
 Async.start({
-  mode: "ssr-spa",
+  mode: "csr",
   root: document,
   boundary: "route"
 });

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@async/framework",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "No-build AsyncLoader app runtime with signals, command events, server calls, route partials, cache split, SSR activation, and streaming boundaries.",
   "type": "module",
   "packageManager": "pnpm@11.1.0",

package/src/router.js CHANGED Viewed

@@ -63,7 +63,7 @@ export function createRouteRegistry(initialMap = {}) {
 }
 export function createRouter({
-  mode = "spa",
+  mode = "ssr-spa",
   root,
   boundary = "route",
   routes = createRouteRegistry(),
@@ -89,6 +89,7 @@ export function createRouter({
       server,
       cache
     });
+  const ownsLoader = !loader;
   const cleanups = new Set();
   let destroyed = false;
@@ -108,10 +109,23 @@ export function createRouter({
       assertActive();
       loaderInstance.router = api;
       signalRegistry._setContext?.({ router: api, loader: loaderInstance, server, cache });
-      ensureRouterState(currentUrl());
-      if (mode === "spa" || mode === "ssr-spa") {
-        bindNavigation();
+      if (ownsLoader) {
+        loaderInstance.start();
       }
+      if (mode === "mpa" || mode === "ssr") {
+        updateStateFromLocation();
+        return api;
+      }
+      bindNavigation();
+      if (mode === "csr") {
+        void api.navigate(currentUrl(), {
+          replace: true,
+          initial: true,
+          source: "client"
+        }).catch(() => {});
+        return api;
+      }
+      updateStateFromLocation();
       return api;
     },
@@ -121,6 +135,9 @@ export function createRouter({
     prefetch(url) {
       assertActive();
+      if (mode === "ssr-spa" && typeof fetchImpl === "function") {
+        return fetchRoute(url, { prefetch: true });
+      }
       const matched = api.match(url);
       if (matched?.route?.partial && partials?.resolve?.(matched.route.partial)) {
         return partials.render(matched.route.partial, matched.params, contextFor(matched));
@@ -133,43 +150,16 @@ export function createRouter({
     async navigate(url, options = {}) {
       assertActive();
-      if (mode === "mpa") {
+      if (mode === "mpa" || mode === "ssr") {
         documentRef.defaultView?.location?.assign?.(url);
         return null;
       }
       const target = toUrl(url);
-      const matched = api.match(target);
-      setRouterState({
-        url: target.href,
-        path: target.pathname,
-        query: queryObject(target),
-        params: matched?.params ?? {},
-        route: matched?.pattern ?? null,
-        pending: true,
-        error: null
-      });
-      try {
-        const result = await resolveNavigation(target, matched);
-        await applyServerResult(result, {
-          signals: signalRegistry,
-          loader: loaderInstance,
-          router: api,
-          cache
-        });
-        if (result?.html != null && !result.boundary && !result.redirect) {
-          loaderInstance.swap(boundary, result.html);
-        }
-        if (options.history !== false) {
-          documentRef.defaultView?.history?.pushState?.({}, "", target.href);
-        }
-        setRouterState({ pending: false, error: null });
-        return result;
-      } catch (error) {
-        setRouterState({ pending: false, error });
-        throw error;
+      if (mode === "ssr-spa") {
+        return fetchRoutePartial(target, options);
       }
+      return renderLocalRoutePartial(target, options);
     },
     destroy() {
@@ -213,11 +203,65 @@ export function createRouter({
     cleanups.add(() => documentRef.defaultView?.removeEventListener?.("popstate", popstate));
   }
-  async function resolveNavigation(target, matched) {
-    if (matched?.route?.partial && partials?.resolve?.(matched.route.partial)) {
-      return partials.render(matched.route.partial, matched.params, contextFor(matched));
+  async function renderLocalRoutePartial(target, options = {}) {
+    const matched = api.match(target);
+    if (!matched) {
+      setNoRouteError(target);
+      return null;
+    }
+    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 });
+        return null;
+      }
+      const result = await partials.render(matched.route.partial, matched.params, contextFor(matched));
+      await applyNavigationResult(result, target, options);
+      setRouterState({ pending: false, error: null });
+      return result;
+    } catch (error) {
+      setRouterState({ pending: false, error });
+      throw error;
+    }
+  }
+  async function fetchRoutePartial(target, options = {}) {
+    const matched = api.match(target);
+    setMatchedRouterState(target, matched, { pending: true, error: null });
+    try {
+      const result = await fetchRoute(target.href);
+      await applyNavigationResult(result, target, options);
+      setRouterState({ pending: false, error: null });
+      return result;
+    } catch (error) {
+      setRouterState({ pending: false, error });
+      throw error;
     }
-    return fetchRoute(target.href);
+  }
+  async function applyNavigationResult(result, target, options) {
+    await applyServerResult(result, {
+      signals: signalRegistry,
+      loader: loaderInstance,
+      router: api,
+      cache
+    });
+    if (result?.html != null && !result.boundary && !result.redirect) {
+      loaderInstance.swap(boundary, result.html);
+    }
+    if (result?.redirect || options.history === false) {
+      return;
+    }
+    if (options.replace) {
+      documentRef.defaultView?.history?.replaceState?.({}, "", target.href);
+      return;
+    }
+    documentRef.defaultView?.history?.pushState?.({}, "", target.href);
   }
   async function fetchRoute(url, { prefetch = false } = {}) {
@@ -256,17 +300,29 @@ export function createRouter({
     };
   }
-  function ensureRouterState(url) {
-    signalRegistry.ensure("router", {});
+  function updateStateFromLocation() {
+    const url = currentUrl();
     const matched = api.match(url);
+    setMatchedRouterState(url, matched, { pending: false, error: null });
+  }
+  function setMatchedRouterState(url, matched, patch = {}) {
+    signalRegistry.ensure("router", {});
     setRouterState({
       url: url.href,
       path: url.pathname,
       query: queryObject(url),
       params: matched?.params ?? {},
-      route: matched?.pattern ?? null,
+      route: matched?.route ?? null,
+      ...patch
+    });
+  }
+  function setNoRouteError(url) {
+    const error = new Error(`No route matched ${url.pathname}${url.search}`);
+    setMatchedRouterState(url, null, {
       pending: false,
-      error: null
+      error
     });
   }
@@ -301,6 +357,9 @@ function normalizeRoute(pattern, definition) {
 function compilePattern(pattern) {
   const keys = [];
+  if (pattern === "*") {
+    return { regex: /^.*$/, keys };
+  }
   if (pattern === "/") {
     return { regex: /^\/$/, keys };
   }
@@ -361,7 +420,7 @@ function escapeRegExp(value) {
 }
 function assertPattern(pattern) {
-  if (typeof pattern !== "string" || !pattern.startsWith("/")) {
-    throw new TypeError("Route pattern must be a path string.");
+  if (typeof pattern !== "string" || (pattern !== "*" && !pattern.startsWith("/"))) {
+    throw new TypeError("Route pattern must be a path string or \"*\".");
   }
 }