@opentf/web 0.7.0 → 0.8.0

package/core/signals.js

@@ -15,6 +15,8 @@ import { reportError } from "./errors.js";
 
 /** The consumer (effect or computed) currently executing, if any. */
 let activeConsumer = null;
+/** Disposer collector of the innermost `scope()` currently building, if any. */
+let activeScope = null;
 /** Depth of nested `batch()` calls; effects flush when this returns to 0. */
 let batchDepth = 0;
 /** Re-entrancy guard for the flush loop. */
@@ -149,6 +151,36 @@ export function computed(fn) {
   };
 }
 
+/**
+ * Collect ownership of the effects created while `fn` runs. Returns
+ * `{ result, dispose }`: `dispose()` stops every effect `fn` created (including
+ * ones created in nested calls, unless an inner `scope()` claimed them first).
+ *
+ * This is how dynamic regions own their bindings: a keyed-list item, a
+ * conditional branch, or a mounted page builds its DOM inside a scope, and
+ * evicting/swapping/unmounting disposes the scope — otherwise the bindings'
+ * effects would stay subscribed to their signals forever (a leak that also
+ * makes every later write pay for dead subscribers).
+ */
+export function scope(fn) {
+  const disposers = [];
+  const prev = activeScope;
+  activeScope = disposers;
+  let result;
+  try {
+    result = fn();
+  } finally {
+    activeScope = prev;
+  }
+  return {
+    result,
+    dispose() {
+      for (const d of disposers) d();
+      disposers.length = 0;
+    },
+  };
+}
+
 /**
  * Run `fn` immediately, tracking the signals it reads, and re-run it whenever
  * any of them change. `fn` may return a cleanup function, which runs before the
@@ -166,22 +198,31 @@ export function effect(fn) {
       runCleanup(node);
       clearSources(node);
       const prev = activeConsumer;
+      const prevScope = activeScope;
+      // Effects created during a run belong to whoever the run's body says they
+      // do (an explicit inner scope()), never to whatever scope happens to be
+      // ambient — a flush-time re-run must not donate its children to an
+      // unrelated scope that was open when the write occurred.
       activeConsumer = node;
+      activeScope = null;
       try {
         const result = node.fn();
         if (typeof result === "function") node.cleanup = result;
       } finally {
         activeConsumer = prev;
+        activeScope = prevScope;
       }
     },
   };
   node.run();
-  return function dispose() {
+  const dispose = function dispose() {
     if (node.disposed) return;
     node.disposed = true;
     runCleanup(node);
     clearSources(node);
   };
+  if (activeScope) activeScope.push(dispose);
+  return dispose;
 }
 
 function runCleanup(node) {

package/package.json

@@ -1,13 +1,20 @@
 {
   "name": "@opentf/web",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The native-first OTF Web runtime — signal-based reactivity and zero-VDOM DOM operations, paired with the IR-based compiler.",
   "type": "module",
   "exports": {
     ".": "./index.js",
     "./signals": "./core/signals.js",
     "./runtime": "./runtime/index.js",
-    "./server": "./server/index.js"
+    "./server": {
+      "types": "./server/index.d.ts",
+      "default": "./server/index.js"
+    },
+    "./server/adapters/node": {
+      "types": "./server/adapters/node.d.ts",
+      "default": "./server/adapters/node.js"
+    }
   },
   "files": [
     "index.js",

package/runtime/dom.js

@@ -2,7 +2,7 @@
 // also back runtime-driven updates (reactive text/attributes). No virtual DOM,
 // no diffing — just direct, fine-grained DOM writes wired to signals.
 
-import { effect, signal } from "../core/signals.js";
+import { effect, scope, signal } from "../core/signals.js";
 import { claimRegionEnd, claimRegionStart } from "./hydrate.js";
 
 // Attribute names that must be assigned as JS properties (not setAttribute) for
@@ -269,32 +269,47 @@ export function bindChild(anchor, fn) {
  */
 export function hydrateChild(cur, adoptFn, buildFn) {
   claimRegionStart(cur);
-  const adopted = toNodes(adoptFn(cur));
+  // Adopt inside a scope so the adopted branch owns its bindings' effects; the
+  // region disposes it when a reactive change swaps the branch out.
+  const adoptedScope = scope(() => toNodes(adoptFn(cur)));
   const anchor = claimRegionEnd(cur);
   // Seed with the adopted nodes and skip the first effect run's DOM write: the branch is
   // already in place. The first run still evaluates `buildFn` to subscribe to its reactive
   // deps (the built nodes are discarded); from the second run on it swaps normally.
-  return childEffect(anchor, buildFn, adopted, true);
+  return childEffect(anchor, buildFn, adoptedScope.result, true, adoptedScope);
 }
 
 /** The child-region effect shared by {@link bindChild} (empty seed, no skip) and
  * {@link hydrateChild} (seeded with adopted nodes, first DOM write skipped). On each run
- * the previous nodes are replaced with the new ones, inserted before `anchor`. */
-function childEffect(anchor, fn, current, skipFirst) {
+ * the previous nodes are replaced with the new ones, inserted before `anchor`; the
+ * previous branch's scope is disposed so its bindings' effects don't outlive it. */
+function childEffect(anchor, fn, current, skipFirst, currentScope = null) {
   let first = skipFirst;
-  return effect(() => {
-    const next = toNodes(fn());
+  const disposeEffect = effect(() => {
+    // Build in a scope: the branch's nested bindings (text/attr/list effects)
+    // belong to this run and are disposed when the branch is replaced.
+    const built = scope(() => toNodes(fn()));
     if (first) {
       first = false;
-      return; // hydration: keep the adopted DOM on first paint (subscribe only)
+      // Hydration first run subscribes the region effect only; the discarded
+      // build's own effects must not stay live alongside the adopted branch.
+      built.dispose();
+      return; // keep the adopted DOM on first paint
     }
+    const next = built.result;
     const host = anchor.parentNode;
     for (const n of current) {
       if (n.parentNode === host) host.removeChild(n);
     }
     if (host) for (const n of next) host.insertBefore(n, anchor);
+    if (currentScope) currentScope.dispose();
+    currentScope = built;
     current = next;
   });
+  return () => {
+    disposeEffect();
+    if (currentScope) currentScope.dispose();
+  };
 }
 
 /**
@@ -333,8 +348,10 @@ export function hydrateList(cur, sourceFn, adoptItem, renderItem, keyFn) {
     const item = items[index];
     const key = keyFn ? keyFn(item, index) : index;
     const sig = signal(item);
-    const node = adoptItem(cur, sig, index); // claims one item subtree off `cur`
-    cache.set(key, { sig, node });
+    // Adopt inside a scope so the item owns its bindings' effects; eviction
+    // disposes them (same ownership as CSR-built items in reconcileList).
+    const s = scope(() => adoptItem(cur, sig, index)); // claims one item subtree off `cur`
+    cache.set(key, { sig, node: s.result, dispose: s.dispose });
     prevKeys.push(key);
   }
   const anchor = claimRegionEnd(cur);
@@ -350,7 +367,7 @@ export function hydrateList(cur, sourceFn, adoptItem, renderItem, keyFn) {
  * order) carry reconciliation state across runs. Returns the effect disposer.
  */
 function reconcileList(anchor, sourceFn, renderItem, keyFn, cache, prevKeys) {
-  return effect(() => {
+  const disposeEffect = effect(() => {
     const data = sourceFn();
     const items = Array.isArray(data) ? data : [];
     const next = new Map();
@@ -373,7 +390,12 @@ function reconcileList(anchor, sourceFn, renderItem, keyFn, cache, prevKeys) {
         prevIndex[index] = prevPos.has(key) ? prevPos.get(key) : -1;
       } else {
         const sig = signal(item);
-        entry = { sig, node: renderItem(sig, index) };
+        // Build inside a scope: the item owns its bindings' effects, so
+        // evicting it detaches them from shared signals (e.g. a selection
+        // signal every row's class reads). Without this every discarded row
+        // leaves a zombie effect that all later writes keep re-running.
+        const s = scope(() => renderItem(sig, index));
+        entry = { sig, node: s.result, dispose: s.dispose };
         prevIndex[index] = -1;
       }
       next.set(key, entry);
@@ -381,8 +403,9 @@ function reconcileList(anchor, sourceFn, renderItem, keyFn, cache, prevKeys) {
       nodes[index] = entry.node;
     }
 
-    // Remove nodes whose keys disappeared.
+    // Remove nodes whose keys disappeared, and dispose their bindings.
     for (const entry of cache.values()) {
+      if (entry.dispose) entry.dispose();
       if (entry.node.parentNode) entry.node.parentNode.removeChild(entry.node);
     }
     cache = next;
@@ -403,6 +426,13 @@ function reconcileList(anchor, sourceFn, renderItem, keyFn, cache, prevKeys) {
       if (nodes[i].nextSibling !== ref) host.insertBefore(nodes[i], ref);
     }
   });
+  return () => {
+    disposeEffect();
+    for (const entry of cache.values()) {
+      if (entry.dispose) entry.dispose();
+    }
+    cache.clear();
+  };
 }
 
 /**

package/runtime/index.js

@@ -14,6 +14,8 @@ export * from "./mount.js";
 export * from "./hydrate.js";
 export * from "./lifecycle.js";
 export * from "./router.js";
+export * from "./route-data.js";
+export * from "./resource.js";
 export * from "./context.js";
 export * from "./error-boundary.js";
 export * from "./portal.js";

package/runtime/mount.js

@@ -2,6 +2,7 @@
 // SPEC §2.2). Components compile to Custom Elements and mount via the DOM.
 
 import { reportError } from "../core/errors.js";
+import { scope } from "../core/signals.js";
 
 /**
  * Mount a view into `target`. `view` is either a factory function returning a
@@ -11,9 +12,21 @@ import { reportError } from "../core/errors.js";
  * built from `onMount`/`onCleanup`. After insertion we run the `onMount` callbacks,
  * collecting any returned disposer into `cleanups` so a caller (e.g. the router)
  * can tear the page down on navigation.
+ *
+ * A factory build runs inside a reactive `scope`, and the scope's disposer joins
+ * the cleanups: teardown (router navigation) stops every binding effect the page
+ * created, so a replaced page's subscriptions don't outlive it.
  */
 export function mount(view, target) {
-  const node = typeof view === "function" ? view() : view;
+  let node;
+  if (typeof view === "function") {
+    const s = scope(view);
+    node = s.result;
+    const lc = (node.__lifecycle ??= { mounts: [], cleanups: [] });
+    lc.cleanups.push(s.dispose);
+  } else {
+    node = view;
+  }
   target.appendChild(node);
   runMount(node);
   return node;

package/runtime/resource.js

@@ -0,0 +1,139 @@
+// `resource()` — the client-side async-data primitive (SPEC §7.4, docs/DATA.md).
+// Components are strictly synchronous (SPEC §5.5), so async data lives *next to*
+// the view: a resource wraps a fetcher in signals and the view renders its
+// reactive `loading` / `error` / `data` states:
+//
+//   const users = resource(() => fetch("/api/users").then((r) => r.json()));
+//   // in JSX: {users.loading ? <Spinner /> : users.data.map(...)}
+//
+// With a reactive source, the fetch re-runs whenever the source changes, and a
+// `null`/`false` source pauses it (conditional fetching):
+//
+//   const user = resource(() => router.params.id, (id, { signal }) =>
+//     fetch(`/api/users/${id}`, { signal }).then((r) => r.json()));
+//
+// Staleness: each run bumps a token and aborts the previous run's AbortController
+// (passed to the fetcher as `{ signal }`), so an out-of-order resolution can never
+// overwrite newer data — even for fetchers that ignore the signal.
+//
+// Server (SSG/SSR): no effect is created and nothing is fetched — `loading` stays
+// `true`, so the prerendered HTML shows the loading branch. That is exactly what
+// the client's first paint renders before its own fetch resolves, keeping
+// hydration adoption aligned.
+
+import { batch, effect, signal, untracked } from "../core/signals.js";
+
+// Test override: bun tests run under happy-dom (a `document` always exists), so
+// server behavior is opted into explicitly.
+let serverOverride = null;
+
+/** Force server (true) / client (false) behavior for new resources — tests only. */
+export function __setResourceServer(v) {
+  serverOverride = v;
+}
+
+const isServer = () => serverOverride ?? typeof document === "undefined";
+
+/**
+ * Create a resource. Two call shapes:
+ *
+ *   resource(fetcher, options?)          — fetch once (and on refetch())
+ *   resource(source, fetcher, options?)  — re-fetch when the reactive `source`
+ *                                          changes; `null`/`false` pauses
+ *
+ * @param {Function} source  reactive source read inside the tracking effect; its
+ *        value is passed to the fetcher.
+ * @param {Function} fetcher  `(sourceValue, { signal }) => data | Promise<data>`.
+ * @param {{ initial?: unknown }} [options]  `initial` seeds `data` before the
+ *        first resolution.
+ * @returns {{ data: unknown, loading: boolean, error: unknown,
+ *             refetch: () => Promise<unknown> | undefined }}  reactive getters —
+ *        read them inside bindings/effects to subscribe.
+ */
+export function resource(source, fetcher, options = {}) {
+  if (typeof fetcher !== "function") {
+    options = fetcher ?? {};
+    fetcher = source;
+    source = null;
+  }
+  const src = typeof source === "function" ? source : () => true;
+  const data = signal(options.initial);
+  const error = signal(undefined);
+  const loading = signal(true); // a fetch is intended; the server leaves it true
+  let token = 0;
+  let controller = null;
+
+  function run(value) {
+    controller?.abort();
+    // Captured per-run: by the time a superseded run's promise settles, the
+    // module-level `controller` already belongs to a newer run.
+    const c = (controller = typeof AbortController !== "undefined" ? new AbortController() : null);
+    const t = ++token;
+    batch(() => {
+      loading.value = true;
+      error.value = undefined;
+    });
+    // The async IIFE starts the fetcher *synchronously* (no wasted microtask)
+    // while converting a synchronous throw into a rejection.
+    return (async () => fetcher(value, { signal: c?.signal }))()
+      .then(
+        (v) => {
+          if (t !== token) return; // superseded — a newer run owns the signals
+          batch(() => {
+            data.value = v;
+            loading.value = false;
+          });
+          return v;
+        },
+        (e) => {
+          if (t !== token) return;
+          // Keep the last good `data` (stale-while-error); only `error` flips.
+          batch(() => {
+            error.value = e;
+            loading.value = false;
+          });
+        },
+      );
+  }
+
+  if (!isServer()) {
+    effect(() => {
+      const value = src(); // the effect's ONLY tracked read
+      if (value == null || value === false) {
+        // Paused: cancel anything in flight and settle as "not loading".
+        untracked(() => {
+          token++;
+          controller?.abort();
+          controller = null;
+          loading.value = false;
+        });
+        return;
+      }
+      untracked(() => run(value));
+      // Before a re-run (source changed) and on scope dispose: invalidate + abort,
+      // so a torn-down region's fetch can neither land nor leak a connection.
+      return () => {
+        token++;
+        controller?.abort();
+      };
+    });
+  }
+
+  return {
+    get data() {
+      return data.value;
+    },
+    get loading() {
+      return loading.value;
+    },
+    get error() {
+      return error.value;
+    },
+    /** Re-run the fetcher with the current source value (no-op while paused). */
+    refetch() {
+      const value = untracked(src);
+      if (value == null || value === false) return undefined;
+      return run(value);
+    },
+  };
+}

package/runtime/route-data.js

@@ -0,0 +1,64 @@
+// Route-loader data on the client (docs/DATA.md). A page with a sibling
+// `loader.{js,ts}` gets its data three ways, all converging on `router.data`:
+//
+//   • first paint over server HTML — the payload is inlined as
+//     `<script type="application/json" id="__otfw_data">` and read here;
+//   • SPA navigation — fetched from `<path>/__data.json` (the same URL a static
+//     host serves as a literal file written at SSG time, and the serve/dev
+//     servers answer dynamically);
+//   • dev/CSR first load — the same fetch, since there is no server markup.
+//
+// The endpoint returns the raw loader JSON (no envelope): 404 means "no data for
+// this route" (no loader, or the loader called `notFound()`) and maps to
+// `undefined` so the page renders its empty state.
+
+/** The reserved per-route data filename/URL suffix (`/todos` → `/todos/__data.json`). */
+export const DATA_FILE = "__data.json";
+
+// Match the router's path normalization (a trailing slash must hit the same URL).
+const normalize = (p) => (p || "/").replace(/(.)\/+$/, "$1");
+
+/** The data-endpoint URL for a page path: `"/"` → `/__data.json`,
+ *  `"/todos"` → `/todos/__data.json`, preserving the query string. */
+export function dataUrlFor(pathname, search = "") {
+  const path = normalize(pathname);
+  return (path === "/" ? `/${DATA_FILE}` : `${path}/${DATA_FILE}`) + (search || "");
+}
+
+/**
+ * Fetch a route's loader data. 200 → the parsed JSON; 404 → `undefined` (no
+ * loader / `notFound()`); anything else throws (the router reports it and
+ * commits the navigation with no data).
+ */
+export async function fetchRouteData(pathname, search = "") {
+  const res = await fetch(dataUrlFor(pathname, search));
+  if (res.status === 404) return undefined;
+  if (!res.ok) throw new Error(`route data request for ${pathname} failed (${res.status})`);
+  return res.json();
+}
+
+// The inline first-paint payload, read once and cached (mirrors the island-props
+// payload reader in hydrate.js). `undefined` data serializes to *no script at all*
+// (the toolchain skips injection), so a missing element simply reads as undefined.
+let _read = false;
+let _value;
+
+/** The loader data inlined by the server for the current document, or `undefined`. */
+export function readInlineRouteData() {
+  if (!_read) {
+    _read = true;
+    const el = typeof document !== "undefined" ? document.getElementById("__otfw_data") : null;
+    try {
+      _value = el ? JSON.parse(el.textContent || "null") : undefined;
+    } catch {
+      _value = undefined;
+    }
+  }
+  return _value;
+}
+
+/** Reset the cached inline payload (tests only — a fresh document between cases). */
+export function __resetInlineRouteData() {
+  _read = false;
+  _value = undefined;
+}

package/runtime/router.js

@@ -11,12 +11,14 @@
 // NOTE: passing route params to a page via its `props` argument
 // (`function Page(props) { props.params.id }`) and layout `props.children`
 // composition both require signal-free page props, which the compiler does not
-// emit yet — for now pages read params via the reactive `router.params`.
+// emit yet — for now pages read params via the reactive `router.params`, and a
+// route loader's data via the reactive `router.data` (docs/DATA.md).
 
 import { clearError, reportError } from "../core/errors.js";
 import { signal } from "../core/signals.js";
 import { beginHydration, cursor, endHydration } from "./hydrate.js";
 import { runCleanup, runMount } from "./mount.js";
+import { fetchRouteData, readInlineRouteData } from "./route-data.js";
 
 const isBrowser = typeof window !== "undefined";
 
@@ -34,9 +36,10 @@ const state = {
   searchParams: signal(new URLSearchParams(isBrowser ? window.location.search : "")),
   params: signal({}),
   locale: signal(null),
+  data: signal(undefined),
 };
 
-export const routes = { pages: {}, layouts: {}, notFound: null };
+export const routes = { pages: {}, layouts: {}, notFound: null, loaderRoutes: new Set() };
 let guard = null;
 let rootEl = null;
 
@@ -135,14 +138,19 @@ export const router = {
   get locale() {
     return state.locale.value;
   },
+  get data() {
+    return state.data.value;
+  },
   push: (path) => navigate(path),
   replace: (path) => navigate(path, true),
 };
 
-/** Derive the route ("/counter", "/") from a `.../app/<route>/page.jsx` path. */
+/** Derive the route ("/counter", "/") from a `.../app/<route>/page.jsx` path. The
+ *  lookahead pins `/app` to a complete path segment, so a route folder that merely
+ *  starts with "app" (`/appointments`) isn't clipped. */
 function routeFromPath(filePath) {
   const r = filePath
-    .replace(/^.*\/app/, "")
+    .replace(/^.*\/app(?=\/)/, "")
     .replace(/\/(page|layout|404)\.(jsx|tsx|mdx|md)$/, "");
   return r === "" ? "/" : r;
 }
@@ -162,6 +170,22 @@ export function registerRoutes(modules) {
   }
 }
 
+/**
+ * Register which route *patterns* (`"/todos"`, `"/items/[id]"`) have a server
+ * loader (docs/DATA.md) — the toolchain discovers `loader.{js,ts}` files and
+ * passes the list via `mountApp({ loaders })`. `navigate` only fetches
+ * `<path>/__data.json` for routes in this set; `matchRoute` returns the same
+ * pattern string, so membership is a plain Set lookup.
+ */
+export function registerLoaderRoutes(paths) {
+  routes.loaderRoutes = new Set(paths || []);
+}
+
+/** Set the reactive `router.data` directly (server render and tests). */
+export function setRouteData(data) {
+  state.data.value = data;
+}
+
 /** Layout entries that wrap `route`, outermost (root) first. */
 export function layoutChain(route) {
   const chain = [];
@@ -255,11 +279,14 @@ async function resolveModule(entry) {
  * so a page reading `router.pathname`/`params`/`query` resolves to the route being
  * pre-rendered. The client uses `navigate` instead.
  */
-export function setRouteState({ pathname = "/", search = "", params = {}, locale } = {}) {
+export function setRouteState({ pathname = "/", search = "", params = {}, locale, data } = {}) {
   state.pathname.value = normalizePath(pathname);
   state.searchParams.value = new URLSearchParams(search);
   state.params.value = params;
   state.locale.value = locale !== undefined ? locale : resolveLocale(pathname).locale;
+  // Always assigned (even when the caller passed none) so a loader-less render
+  // never shows a previous route's stale data.
+  state.data.value = data;
 }
 
 /**
@@ -270,9 +297,16 @@ export function setRouteState({ pathname = "/", search = "", params = {}, locale
 export function matchRoute(pathname) {
   pathname = resolveLocale(pathname).path;
   for (const route in routes.pages) {
+    // `[param]` / `[...rest]` become named groups; literal parts are regex-escaped
+    // (a `v1.0` folder must not match `v1X0`).
     const pattern = route
-      .replace(/\[\.\.\.([^\]]+)\]/g, "(?<$1>.+)")
-      .replace(/\[([^\]]+)\]/g, "(?<$1>[^/]+)");
+      .split(/(\[\.\.\.[^\]]+\]|\[[^\]]+\])/)
+      .map((part) => {
+        if (part.startsWith("[...")) return `(?<${part.slice(4, -1)}>.+)`;
+        if (part.startsWith("[")) return `(?<${part.slice(1, -1)}>[^/]+)`;
+        return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      })
+      .join("");
     const m = pathname.match(new RegExp(`^${pattern}/?$`));
     if (m) {
       const params = { ...(m.groups || {}) };
@@ -285,12 +319,20 @@ export function matchRoute(pathname) {
   return null;
 }
 
+// Monotonic navigation sequence: a navigation that awaited its loader-data fetch
+// commits only if no newer navigation started meanwhile (stale data must never
+// win over a later click).
+let navSeq = 0;
+
 /**
- * Navigate to `path`. Runs an optional route guard, swaps the rendered page
- * (tearing down the previous one's lifecycle), and updates window.history.
+ * Navigate to `path`. Runs an optional route guard, fetches the route's loader
+ * data when it has any (docs/DATA.md — fetch *then* commit, like the guard),
+ * swaps the rendered page (tearing down the previous one's lifecycle), and
+ * updates window.history.
  */
 export async function navigate(path, replace = false, isPop = false, hydrate = false) {
   if (!path || !rootEl) return;
+  const seq = ++navSeq;
   const url = new URL(path, window.location.origin);
 
   if (guard) {
@@ -323,10 +365,30 @@ export async function navigate(path, replace = false, isPop = false, hydrate = f
     matchRoute(url.pathname) ||
     (routes.notFound ? { entry: routes.notFound, params: {}, route: null } : null);
 
+  // Loader data (docs/DATA.md): resolved before any state write / history push /
+  // DOM swap, mirroring the guard's "settle before commit" flow. First paint over
+  // server HTML reads the inlined payload; every other navigation (SPA nav, dev/CSR
+  // first load, popstate) fetches the `<path>/__data.json` endpoint. A failed fetch
+  // is reported and the navigation commits with `data === undefined`.
+  let data;
+  if (match && match.route && routes.loaderRoutes.has(match.route)) {
+    if (hydrate) {
+      data = readInlineRouteData();
+    } else {
+      try {
+        data = await fetchRouteData(url.pathname, url.search);
+      } catch (e) {
+        reportError(e, { phase: "data", path: url.pathname });
+      }
+      if (seq !== navSeq) return; // a newer navigation superseded this one
+    }
+  }
+
   state.pathname.value = normalizePath(url.pathname);
   state.searchParams.value = url.searchParams;
   state.params.value = match ? match.params : {};
   state.locale.value = resolveLocale(url.pathname).locale;
+  state.data.value = data;
 
   if (!isPop) {
     if (replace) window.history.replaceState({}, "", path);
@@ -412,12 +474,15 @@ export async function navigate(path, replace = false, isPop = false, hydrate = f
  * @param {Function} [opts.guard]  optional `(to, tools) => …` route guard.
  * @param {"spa"|"mpa"} [opts.nav]  navigation mode (default "spa"); "mpa" disables
  *   client-side link interception so every navigation is a full page load.
+ * @param {string[]} [opts.loaders]  route patterns that have a server loader
+ *   (docs/DATA.md) — navigation fetches `<path>/__data.json` for these.
  */
-export function mountApp({ pages, target, guard: g, i18n, nav } = {}) {
+export function mountApp({ pages, target, guard: g, i18n, nav, loaders } = {}) {
   rootEl = target || (isBrowser ? document.getElementById("app") : null);
   navMode = nav === "mpa" ? "mpa" : "spa";
   if (i18n) configureI18n(i18n);
   if (pages) registerRoutes(pages);
+  if (loaders) registerLoaderRoutes(loaders);
   guard = g || null;
   // In MPA mode the browser owns navigation (full loads push real history entries),
   // so there is no client-side history to react to — only wire popstate for SPA.