@moku-labs/web 2.4.13 → 2.4.15

package/dist/browser.d.mts

@@ -1931,7 +1931,7 @@ declare const spaPlugin: import("@moku-labs/core").PluginInstance<"spa", SpaConf
   };
 }> & Record<never, never>;
 declare namespace types_d_exports$2 {
-  export { DataConfig, DataEntry, DataProvider, DataState, DataWriteSummary };
+  export { DataConfig, DataEntry, DataPreload, DataProvider, DataState, DataWriteSummary };
 }
 /**
  * @file data plugin — type definitions (Standard tier).
@@ -1951,6 +1951,12 @@ declare namespace types_d_exports$2 {
  * inside `write()`, so composing `data` in a browser app keeps the bundle free of
  * `node:*`.
  */
+/**
+ * How the browser loads page data. `"none"` fetches one page file per navigation
+ * (lazy). `"all"` also loads every page's data once, from one bundle file, after
+ * the app starts and the main thread is idle.
+ */
+type DataPreload = "none" | "all";
 /**
  * Configuration for {@link dataPlugin}. All fields have defaults (see `./config`).
  *
@@ -1971,6 +1977,13 @@ type DataConfig = {
    * path); keep them consistent (`"/" + trim(outputDir) + "/"`). Default `"/_data/"`.
    */
   baseUrl: string;
+  /**
+   * BOTH sides. `"all"`: the Node `write()` also writes one bundle file
+   * `<outputDir>/_all.json` (`{ "<page path>": data }`), and the browser fetches
+   * it once when idle and fills the `at()` cache. Set the same value in the Node
+   * app and the browser app. Default `"none"`: no bundle, lazy per-page fetches.
+   */
+  preload?: DataPreload;
 };
 /** One page's data to persist — `build` produces these from its route expansion. */
 interface DataEntry {
@@ -1987,6 +2000,11 @@ interface DataWriteSummary {
   bytes: number;
   /** The written file paths, relative to the build `outDir`. */
   files: string[];
+  /** The preload bundle, present only when `preload` is `"all"`. Not counted in `fileCount`/`bytes`. */
+  bundle?: {
+    file: string;
+    bytes: number;
+  };
 }
 /**
  * Internal data state. `lastWrite` records the most recent `write()` (Node);
@@ -2004,6 +2022,8 @@ interface DataState {
    * the fetch settles, on success and on failure, so a failure is never cached.
    */
   pending: Map<string, Promise<unknown | null>>;
+  /** Cancels the scheduled idle callback or aborts the bundle fetch. `null` when nothing is scheduled. */
+  cancelPreload: (() => void) | null;
 }
 /**
  * Public API mounted at `app.data` — the agnostic data provider. `write()` is the

package/dist/browser.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./chunk-D7D4PA-g.mjs";
-import { n as relativeDataFile, t as dataSuffix } from "./convention-Dp650o3y.mjs";
+import { n as dataSuffix, r as relativeDataFile, t as BUNDLE_FILE } from "./convention-BtVf429P.mjs";
 import { envPlugin as envPlugin$1, logPlugin as logPlugin$1 } from "@moku-labs/common";
 import { createCoreConfig } from "@moku-labs/core";
 import { browserEnv, browserEnv as browserEnv$1, envPlugin, logPlugin } from "@moku-labs/common/browser";
@@ -2393,7 +2393,7 @@ async function fetchAndCache(ctx, path) {
 /**
 * Builds the data provider — the agnostic bridge. `write()` is the Node persist
 * side; `at()` is the browser read side; `urlFor`/`fileFor` are the pure
-* convention. No `onStart`/`onStop` (holds no long-lived resource).
+* convention. The optional preload lives in `./preload` (started by `onStart`).
 *
 * @param ctx - The data plugin context.
 * @returns The {@link DataProvider} mounted at `app.data`.
@@ -2408,7 +2408,8 @@ function dataApi(ctx) {
 	return {
 		/**
 		* READ (browser) — fetch (and cache) the persisted data for a page path.
-		* Concurrent calls for one path share one in-flight request.
+		* Concurrent calls for one path share one in-flight request. It never waits
+		* for an in-flight preload bundle: an uncached path is fetched at once.
 		* Returns the raw JSON as `unknown`, which the route uses directly as `ctx.data`
 		* (no route `.parse()`); returns `null` if the fetch or JSON parse fails (so
 		* `spa` can fall back to HTML).
@@ -2443,7 +2444,7 @@ function dataApi(ctx) {
 		* ```
 		*/
 		async write(entries, options) {
-			const { writeData } = await import("./writer-CaoyORyZ.mjs");
+			const { writeData } = await import("./writer-Dwd02T9h.mjs");
 			return writeData(ctx, entries, options);
 		},
 		/**
@@ -2480,7 +2481,7 @@ function dataApi(ctx) {
 * Typed default data config (R6: no inline `as`). `outputDir` is the WRITE path
 * (filesystem, relative to the build `outDir`); `baseUrl` is the matching READ URL
 * (site-root-relative) the browser fetches from — the defaults agree
-* (`"_data"` ↔ `"/_data/"`).
+* (`"_data"` ↔ `"/_data/"`). `preload` is `"none"`: lazy per-page fetches only.
 *
 * @example
 * ```ts
@@ -2489,14 +2490,77 @@ function dataApi(ctx) {
 */
 const defaultDataConfig = {
 	outputDir: "_data",
-	baseUrl: "/_data/"
+	baseUrl: "/_data/",
+	preload: "none"
 };
 //#endregion
+//#region src/plugins/data/preload.ts
+/**
+* Fetches the bundle and caches every path not already cached. Never rejects:
+* a failed fetch leaves lazy `at()` working. Clears `cancelPreload` when done.
+*
+* @param ctx - The data plugin context.
+* @param signal - Aborts the fetch on stop.
+* @returns Resolves when the fill is done or failed.
+* @example
+* ```ts
+* await fill(ctx, signal);
+* ```
+*/
+async function fill(ctx, signal) {
+	try {
+		const response = await fetch(`${ctx.config.baseUrl}${BUNDLE_FILE}`, { signal });
+		const bundle = response.ok ? await response.json() : {};
+		for (const [path, data] of Object.entries(bundle)) if (!signal.aborted && !ctx.state.cache.has(path)) ctx.state.cache.set(path, data);
+	} catch {} finally {
+		ctx.state.cancelPreload = null;
+	}
+}
+/**
+* From `onStart`: when idle, fetch `<baseUrl>_all.json` once and fill the cache.
+* No-op on Node, with `preload: "none"`, with save-data on, or if already scheduled.
+*
+* @param ctx - The data plugin context.
+* @example
+* ```ts
+* startPreload(ctx);
+* ```
+*/
+function startPreload(ctx) {
+	const nav = globalThis.navigator;
+	if (ctx.config.preload !== "all" || typeof document === "undefined" || ctx.state.cancelPreload !== null || nav?.connection?.saveData === true) return;
+	const controller = new AbortController();
+	const run = () => {
+		fill(ctx, controller.signal);
+	};
+	const idle = typeof requestIdleCallback === "function";
+	const handle = idle ? requestIdleCallback(run, { timeout: 2e3 }) : setTimeout(run, 0);
+	ctx.state.cancelPreload = () => {
+		if (idle) cancelIdleCallback(handle);
+		else clearTimeout(handle);
+		controller.abort();
+	};
+}
+/**
+* From `onStop`: cancel the idle callback or abort the bundle fetch.
+*
+* @param ctx - The data plugin context.
+* @example
+* ```ts
+* stopPreload(ctx);
+* ```
+*/
+function stopPreload(ctx) {
+	ctx.state.cancelPreload?.();
+	ctx.state.cancelPreload = null;
+}
+//#endregion
 //#region src/plugins/data/state.ts
 /**
 * Creates initial data state: a null `lastWrite` slot (populated by the Node
 * `write()` side), an empty `cache` (populated lazily by the browser `at(path)`
-* side on first fetch) and an empty `pending` map of in-flight fetches.
+* side on first fetch), an empty `pending` map of in-flight fetches, and no
+* preload scheduled.
 *
 * @param _ctx - Minimal context with global and config.
 * @param _ctx.global - Global framework configuration.
@@ -2511,7 +2575,8 @@ function createDataState(_ctx) {
 	return {
 		lastWrite: null,
 		cache: /* @__PURE__ */ new Map(),
-		pending: /* @__PURE__ */ new Map()
+		pending: /* @__PURE__ */ new Map(),
+		cancelPreload: null
 	};
 }
 //#endregion
@@ -2533,10 +2598,10 @@ function isInvalidBaseUrl(baseUrl) {
 }
 /**
 * Validates the resolved data config: the browser `baseUrl` must be a non-empty,
-* site-root-relative URL path.
+* site-root-relative URL path, and `preload` must be `"none"` or `"all"`.
 *
 * @param config - The resolved plugin configuration.
-* @throws {Error} If `baseUrl` is empty or not a rooted URL path.
+* @throws {Error} If `baseUrl` is empty or not a rooted URL path, or `preload` is unknown.
 * @example
 * ```ts
 * validateDataConfig({ outputDir: "_data", baseUrl: "/_data/" });
@@ -2544,6 +2609,8 @@ function isInvalidBaseUrl(baseUrl) {
 */
 function validateDataConfig(config) {
 	if (isInvalidBaseUrl(config.baseUrl)) throw new Error(`[web] data.baseUrl: must be a site-root-relative URL path starting with "/" (e.g. "/_data/").`);
+	const { preload } = config;
+	if (preload !== void 0 && preload !== "none" && preload !== "all") throw new Error(`[web] data.preload: must be "none" or "all".\n  Set it to "all" in both apps, or remove it.`);
 }
 //#endregion
 //#region src/plugins/data/index.ts
@@ -2560,7 +2627,8 @@ function validateDataConfig(config) {
 * **No hard `depends`** — fully browser-composable; the `node:fs` writer is behind
 * a lazy `import()` inside `write()`. Build ordering is a call-site contract: build
 * writes data during its pages phase (after its Phase-0 clean), via `app.data.write`.
-* No `onStart`/`onStop`.
+* `onStart` schedules the optional `preload: "all"` bundle fetch (browser, idle);
+* `onStop` cancels it.
 * @see README.md
 */
 /**
@@ -2586,7 +2654,9 @@ const dataPlugin = createPlugin$1("data", {
 	config: defaultDataConfig,
 	createState: createDataState,
 	onInit: (ctx) => validateDataConfig(ctx.config),
-	api: dataApi
+	api: dataApi,
+	onStart: (ctx) => startPreload(ctx),
+	onStop: (ctx) => stopPreload(ctx)
 });
 //#endregion
 //#region src/plugins/spa/head.ts

package/dist/{convention-CLIDd9k-.cjs → convention-BO-VoFLO.cjs}

@@ -70,7 +70,15 @@ function decodeSuffix(suffix) {
 function relativeDataFile(outputDir, path) {
 	return `${outputDir.endsWith("/") ? outputDir.slice(0, -1) : outputDir}/${decodeSuffix(dataSuffix(path))}`;
 }
+/** Preload bundle file name. Page files end in `/index.json`, so it never collides. */
+const BUNDLE_FILE = "_all.json";
 //#endregion
+Object.defineProperty(exports, "BUNDLE_FILE", {
+	enumerable: true,
+	get: function() {
+		return BUNDLE_FILE;
+	}
+});
 Object.defineProperty(exports, "dataSuffix", {
 	enumerable: true,
 	get: function() {

package/dist/{convention-Dp650o3y.mjs → convention-BtVf429P.mjs}

@@ -70,5 +70,7 @@ function decodeSuffix(suffix) {
 function relativeDataFile(outputDir, path) {
 	return `${outputDir.endsWith("/") ? outputDir.slice(0, -1) : outputDir}/${decodeSuffix(dataSuffix(path))}`;
 }
+/** Preload bundle file name. Page files end in `/index.json`, so it never collides. */
+const BUNDLE_FILE = "_all.json";
 //#endregion
-export { relativeDataFile as n, dataSuffix as t };
+export { dataSuffix as n, relativeDataFile as r, BUNDLE_FILE as t };

package/dist/index.cjs

@@ -30,7 +30,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_convention = require("./convention-CLIDd9k-.cjs");
+const require_convention = require("./convention-BO-VoFLO.cjs");
 const require_convention$1 = require("./convention-CsJw7CML.cjs");
 let _moku_labs_common = require("@moku-labs/common");
 let _moku_labs_core = require("@moku-labs/core");
@@ -4651,7 +4651,7 @@ async function fetchAndCache(ctx, path) {
 /**
 * Builds the data provider — the agnostic bridge. `write()` is the Node persist
 * side; `at()` is the browser read side; `urlFor`/`fileFor` are the pure
-* convention. No `onStart`/`onStop` (holds no long-lived resource).
+* convention. The optional preload lives in `./preload` (started by `onStart`).
 *
 * @param ctx - The data plugin context.
 * @returns The {@link DataProvider} mounted at `app.data`.
@@ -4666,7 +4666,8 @@ function dataApi(ctx) {
 	return {
 		/**
 		* READ (browser) — fetch (and cache) the persisted data for a page path.
-		* Concurrent calls for one path share one in-flight request.
+		* Concurrent calls for one path share one in-flight request. It never waits
+		* for an in-flight preload bundle: an uncached path is fetched at once.
 		* Returns the raw JSON as `unknown`, which the route uses directly as `ctx.data`
 		* (no route `.parse()`); returns `null` if the fetch or JSON parse fails (so
 		* `spa` can fall back to HTML).
@@ -4701,7 +4702,7 @@ function dataApi(ctx) {
 		* ```
 		*/
 		async write(entries, options) {
-			const { writeData } = await Promise.resolve().then(() => require("./writer-BEM-Pbgb.cjs"));
+			const { writeData } = await Promise.resolve().then(() => require("./writer-ryba09yV.cjs"));
 			return writeData(ctx, entries, options);
 		},
 		/**
@@ -4738,7 +4739,7 @@ function dataApi(ctx) {
 * Typed default data config (R6: no inline `as`). `outputDir` is the WRITE path
 * (filesystem, relative to the build `outDir`); `baseUrl` is the matching READ URL
 * (site-root-relative) the browser fetches from — the defaults agree
-* (`"_data"` ↔ `"/_data/"`).
+* (`"_data"` ↔ `"/_data/"`). `preload` is `"none"`: lazy per-page fetches only.
 *
 * @example
 * ```ts
@@ -4747,14 +4748,77 @@ function dataApi(ctx) {
 */
 const defaultDataConfig = {
 	outputDir: "_data",
-	baseUrl: "/_data/"
+	baseUrl: "/_data/",
+	preload: "none"
 };
 //#endregion
+//#region src/plugins/data/preload.ts
+/**
+* Fetches the bundle and caches every path not already cached. Never rejects:
+* a failed fetch leaves lazy `at()` working. Clears `cancelPreload` when done.
+*
+* @param ctx - The data plugin context.
+* @param signal - Aborts the fetch on stop.
+* @returns Resolves when the fill is done or failed.
+* @example
+* ```ts
+* await fill(ctx, signal);
+* ```
+*/
+async function fill(ctx, signal) {
+	try {
+		const response = await fetch(`${ctx.config.baseUrl}${require_convention.BUNDLE_FILE}`, { signal });
+		const bundle = response.ok ? await response.json() : {};
+		for (const [path, data] of Object.entries(bundle)) if (!signal.aborted && !ctx.state.cache.has(path)) ctx.state.cache.set(path, data);
+	} catch {} finally {
+		ctx.state.cancelPreload = null;
+	}
+}
+/**
+* From `onStart`: when idle, fetch `<baseUrl>_all.json` once and fill the cache.
+* No-op on Node, with `preload: "none"`, with save-data on, or if already scheduled.
+*
+* @param ctx - The data plugin context.
+* @example
+* ```ts
+* startPreload(ctx);
+* ```
+*/
+function startPreload(ctx) {
+	const nav = globalThis.navigator;
+	if (ctx.config.preload !== "all" || typeof document === "undefined" || ctx.state.cancelPreload !== null || nav?.connection?.saveData === true) return;
+	const controller = new AbortController();
+	const run = () => {
+		fill(ctx, controller.signal);
+	};
+	const idle = typeof requestIdleCallback === "function";
+	const handle = idle ? requestIdleCallback(run, { timeout: 2e3 }) : setTimeout(run, 0);
+	ctx.state.cancelPreload = () => {
+		if (idle) cancelIdleCallback(handle);
+		else clearTimeout(handle);
+		controller.abort();
+	};
+}
+/**
+* From `onStop`: cancel the idle callback or abort the bundle fetch.
+*
+* @param ctx - The data plugin context.
+* @example
+* ```ts
+* stopPreload(ctx);
+* ```
+*/
+function stopPreload(ctx) {
+	ctx.state.cancelPreload?.();
+	ctx.state.cancelPreload = null;
+}
+//#endregion
 //#region src/plugins/data/state.ts
 /**
 * Creates initial data state: a null `lastWrite` slot (populated by the Node
 * `write()` side), an empty `cache` (populated lazily by the browser `at(path)`
-* side on first fetch) and an empty `pending` map of in-flight fetches.
+* side on first fetch), an empty `pending` map of in-flight fetches, and no
+* preload scheduled.
 *
 * @param _ctx - Minimal context with global and config.
 * @param _ctx.global - Global framework configuration.
@@ -4769,7 +4833,8 @@ function createDataState(_ctx) {
 	return {
 		lastWrite: null,
 		cache: /* @__PURE__ */ new Map(),
-		pending: /* @__PURE__ */ new Map()
+		pending: /* @__PURE__ */ new Map(),
+		cancelPreload: null
 	};
 }
 //#endregion
@@ -4791,10 +4856,10 @@ function isInvalidBaseUrl$1(baseUrl) {
 }
 /**
 * Validates the resolved data config: the browser `baseUrl` must be a non-empty,
-* site-root-relative URL path.
+* site-root-relative URL path, and `preload` must be `"none"` or `"all"`.
 *
 * @param config - The resolved plugin configuration.
-* @throws {Error} If `baseUrl` is empty or not a rooted URL path.
+* @throws {Error} If `baseUrl` is empty or not a rooted URL path, or `preload` is unknown.
 * @example
 * ```ts
 * validateDataConfig({ outputDir: "_data", baseUrl: "/_data/" });
@@ -4802,6 +4867,8 @@ function isInvalidBaseUrl$1(baseUrl) {
 */
 function validateDataConfig(config) {
 	if (isInvalidBaseUrl$1(config.baseUrl)) throw new Error(`[web] data.baseUrl: must be a site-root-relative URL path starting with "/" (e.g. "/_data/").`);
+	const { preload } = config;
+	if (preload !== void 0 && preload !== "none" && preload !== "all") throw new Error(`[web] data.preload: must be "none" or "all".\n  Set it to "all" in both apps, or remove it.`);
 }
 //#endregion
 //#region src/plugins/data/index.ts
@@ -4818,7 +4885,8 @@ function validateDataConfig(config) {
 * **No hard `depends`** — fully browser-composable; the `node:fs` writer is behind
 * a lazy `import()` inside `write()`. Build ordering is a call-site contract: build
 * writes data during its pages phase (after its Phase-0 clean), via `app.data.write`.
-* No `onStart`/`onStop`.
+* `onStart` schedules the optional `preload: "all"` bundle fetch (browser, idle);
+* `onStop` cancels it.
 * @see README.md
 */
 /**
@@ -4844,7 +4912,9 @@ const dataPlugin = createPlugin$1("data", {
 	config: defaultDataConfig,
 	createState: createDataState,
 	onInit: (ctx) => validateDataConfig(ctx.config),
-	api: dataApi
+	api: dataApi,
+	onStart: (ctx) => startPreload(ctx),
+	onStop: (ctx) => stopPreload(ctx)
 });
 //#endregion
 //#region src/plugins/build/phases/pages.tsx

package/dist/index.d.cts

@@ -3400,7 +3400,7 @@ declare const contentPlugin: import("@moku-labs/core").PluginInstance<"content",
   };
 }> & Record<never, never>;
 declare namespace types_d_exports$4 {
-  export { DataConfig, DataEntry, DataProvider, DataState, DataWriteSummary };
+  export { DataConfig, DataEntry, DataPreload, DataProvider, DataState, DataWriteSummary };
 }
 /**
  * @file data plugin — type definitions (Standard tier).
@@ -3420,6 +3420,12 @@ declare namespace types_d_exports$4 {
  * inside `write()`, so composing `data` in a browser app keeps the bundle free of
  * `node:*`.
  */
+/**
+ * How the browser loads page data. `"none"` fetches one page file per navigation
+ * (lazy). `"all"` also loads every page's data once, from one bundle file, after
+ * the app starts and the main thread is idle.
+ */
+type DataPreload = "none" | "all";
 /**
  * Configuration for {@link dataPlugin}. All fields have defaults (see `./config`).
  *
@@ -3440,6 +3446,13 @@ type DataConfig = {
    * path); keep them consistent (`"/" + trim(outputDir) + "/"`). Default `"/_data/"`.
    */
   baseUrl: string;
+  /**
+   * BOTH sides. `"all"`: the Node `write()` also writes one bundle file
+   * `<outputDir>/_all.json` (`{ "<page path>": data }`), and the browser fetches
+   * it once when idle and fills the `at()` cache. Set the same value in the Node
+   * app and the browser app. Default `"none"`: no bundle, lazy per-page fetches.
+   */
+  preload?: DataPreload;
 };
 /** One page's data to persist — `build` produces these from its route expansion. */
 interface DataEntry {
@@ -3456,6 +3469,11 @@ interface DataWriteSummary {
   bytes: number;
   /** The written file paths, relative to the build `outDir`. */
   files: string[];
+  /** The preload bundle, present only when `preload` is `"all"`. Not counted in `fileCount`/`bytes`. */
+  bundle?: {
+    file: string;
+    bytes: number;
+  };
 }
 /**
  * Internal data state. `lastWrite` records the most recent `write()` (Node);
@@ -3473,6 +3491,8 @@ interface DataState {
    * the fetch settles, on success and on failure, so a failure is never cached.
    */
   pending: Map<string, Promise<unknown | null>>;
+  /** Cancels the scheduled idle callback or aborts the bundle fetch. `null` when nothing is scheduled. */
+  cancelPreload: (() => void) | null;
 }
 /**
  * Public API mounted at `app.data` — the agnostic data provider. `write()` is the

package/dist/index.d.mts

@@ -3398,7 +3398,7 @@ declare const contentPlugin: import("@moku-labs/core").PluginInstance<"content",
   };
 }> & Record<never, never>;
 declare namespace types_d_exports$4 {
-  export { DataConfig, DataEntry, DataProvider, DataState, DataWriteSummary };
+  export { DataConfig, DataEntry, DataPreload, DataProvider, DataState, DataWriteSummary };
 }
 /**
  * @file data plugin — type definitions (Standard tier).
@@ -3418,6 +3418,12 @@ declare namespace types_d_exports$4 {
  * inside `write()`, so composing `data` in a browser app keeps the bundle free of
  * `node:*`.
  */
+/**
+ * How the browser loads page data. `"none"` fetches one page file per navigation
+ * (lazy). `"all"` also loads every page's data once, from one bundle file, after
+ * the app starts and the main thread is idle.
+ */
+type DataPreload = "none" | "all";
 /**
  * Configuration for {@link dataPlugin}. All fields have defaults (see `./config`).
  *
@@ -3438,6 +3444,13 @@ type DataConfig = {
    * path); keep them consistent (`"/" + trim(outputDir) + "/"`). Default `"/_data/"`.
    */
   baseUrl: string;
+  /**
+   * BOTH sides. `"all"`: the Node `write()` also writes one bundle file
+   * `<outputDir>/_all.json` (`{ "<page path>": data }`), and the browser fetches
+   * it once when idle and fills the `at()` cache. Set the same value in the Node
+   * app and the browser app. Default `"none"`: no bundle, lazy per-page fetches.
+   */
+  preload?: DataPreload;
 };
 /** One page's data to persist — `build` produces these from its route expansion. */
 interface DataEntry {
@@ -3454,6 +3467,11 @@ interface DataWriteSummary {
   bytes: number;
   /** The written file paths, relative to the build `outDir`. */
   files: string[];
+  /** The preload bundle, present only when `preload` is `"all"`. Not counted in `fileCount`/`bytes`. */
+  bundle?: {
+    file: string;
+    bytes: number;
+  };
 }
 /**
  * Internal data state. `lastWrite` records the most recent `write()` (Node);
@@ -3471,6 +3489,8 @@ interface DataState {
    * the fetch settles, on success and on failure, so a failure is never cached.
    */
   pending: Map<string, Promise<unknown | null>>;
+  /** Cancels the scheduled idle callback or aborts the bundle fetch. `null` when nothing is scheduled. */
+  cancelPreload: (() => void) | null;
 }
 /**
  * Public API mounted at `app.data` — the agnostic data provider. `write()` is the

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { t as __exportAll } from "./chunk-D7D4PA-g.mjs";
-import { n as relativeDataFile, t as dataSuffix } from "./convention-Dp650o3y.mjs";
+import { n as dataSuffix, r as relativeDataFile, t as BUNDLE_FILE } from "./convention-BtVf429P.mjs";
 import { n as relativeShardFile, t as collectionUrl } from "./convention-Bs8SrQS9.mjs";
 import { browserEnv, cloudflareBindings, dotenv, envPlugin, envPlugin as envPlugin$1, logPlugin, logPlugin as logPlugin$1, processEnv } from "@moku-labs/common";
 import { createCoreConfig } from "@moku-labs/core";
@@ -4607,7 +4607,7 @@ async function fetchAndCache(ctx, path) {
 /**
 * Builds the data provider — the agnostic bridge. `write()` is the Node persist
 * side; `at()` is the browser read side; `urlFor`/`fileFor` are the pure
-* convention. No `onStart`/`onStop` (holds no long-lived resource).
+* convention. The optional preload lives in `./preload` (started by `onStart`).
 *
 * @param ctx - The data plugin context.
 * @returns The {@link DataProvider} mounted at `app.data`.
@@ -4622,7 +4622,8 @@ function dataApi(ctx) {
 	return {
 		/**
 		* READ (browser) — fetch (and cache) the persisted data for a page path.
-		* Concurrent calls for one path share one in-flight request.
+		* Concurrent calls for one path share one in-flight request. It never waits
+		* for an in-flight preload bundle: an uncached path is fetched at once.
 		* Returns the raw JSON as `unknown`, which the route uses directly as `ctx.data`
 		* (no route `.parse()`); returns `null` if the fetch or JSON parse fails (so
 		* `spa` can fall back to HTML).
@@ -4657,7 +4658,7 @@ function dataApi(ctx) {
 		* ```
 		*/
 		async write(entries, options) {
-			const { writeData } = await import("./writer-CaoyORyZ.mjs");
+			const { writeData } = await import("./writer-Dwd02T9h.mjs");
 			return writeData(ctx, entries, options);
 		},
 		/**
@@ -4694,7 +4695,7 @@ function dataApi(ctx) {
 * Typed default data config (R6: no inline `as`). `outputDir` is the WRITE path
 * (filesystem, relative to the build `outDir`); `baseUrl` is the matching READ URL
 * (site-root-relative) the browser fetches from — the defaults agree
-* (`"_data"` ↔ `"/_data/"`).
+* (`"_data"` ↔ `"/_data/"`). `preload` is `"none"`: lazy per-page fetches only.
 *
 * @example
 * ```ts
@@ -4703,14 +4704,77 @@ function dataApi(ctx) {
 */
 const defaultDataConfig = {
 	outputDir: "_data",
-	baseUrl: "/_data/"
+	baseUrl: "/_data/",
+	preload: "none"
 };
 //#endregion
+//#region src/plugins/data/preload.ts
+/**
+* Fetches the bundle and caches every path not already cached. Never rejects:
+* a failed fetch leaves lazy `at()` working. Clears `cancelPreload` when done.
+*
+* @param ctx - The data plugin context.
+* @param signal - Aborts the fetch on stop.
+* @returns Resolves when the fill is done or failed.
+* @example
+* ```ts
+* await fill(ctx, signal);
+* ```
+*/
+async function fill(ctx, signal) {
+	try {
+		const response = await fetch(`${ctx.config.baseUrl}${BUNDLE_FILE}`, { signal });
+		const bundle = response.ok ? await response.json() : {};
+		for (const [path, data] of Object.entries(bundle)) if (!signal.aborted && !ctx.state.cache.has(path)) ctx.state.cache.set(path, data);
+	} catch {} finally {
+		ctx.state.cancelPreload = null;
+	}
+}
+/**
+* From `onStart`: when idle, fetch `<baseUrl>_all.json` once and fill the cache.
+* No-op on Node, with `preload: "none"`, with save-data on, or if already scheduled.
+*
+* @param ctx - The data plugin context.
+* @example
+* ```ts
+* startPreload(ctx);
+* ```
+*/
+function startPreload(ctx) {
+	const nav = globalThis.navigator;
+	if (ctx.config.preload !== "all" || typeof document === "undefined" || ctx.state.cancelPreload !== null || nav?.connection?.saveData === true) return;
+	const controller = new AbortController();
+	const run = () => {
+		fill(ctx, controller.signal);
+	};
+	const idle = typeof requestIdleCallback === "function";
+	const handle = idle ? requestIdleCallback(run, { timeout: 2e3 }) : setTimeout(run, 0);
+	ctx.state.cancelPreload = () => {
+		if (idle) cancelIdleCallback(handle);
+		else clearTimeout(handle);
+		controller.abort();
+	};
+}
+/**
+* From `onStop`: cancel the idle callback or abort the bundle fetch.
+*
+* @param ctx - The data plugin context.
+* @example
+* ```ts
+* stopPreload(ctx);
+* ```
+*/
+function stopPreload(ctx) {
+	ctx.state.cancelPreload?.();
+	ctx.state.cancelPreload = null;
+}
+//#endregion
 //#region src/plugins/data/state.ts
 /**
 * Creates initial data state: a null `lastWrite` slot (populated by the Node
 * `write()` side), an empty `cache` (populated lazily by the browser `at(path)`
-* side on first fetch) and an empty `pending` map of in-flight fetches.
+* side on first fetch), an empty `pending` map of in-flight fetches, and no
+* preload scheduled.
 *
 * @param _ctx - Minimal context with global and config.
 * @param _ctx.global - Global framework configuration.
@@ -4725,7 +4789,8 @@ function createDataState(_ctx) {
 	return {
 		lastWrite: null,
 		cache: /* @__PURE__ */ new Map(),
-		pending: /* @__PURE__ */ new Map()
+		pending: /* @__PURE__ */ new Map(),
+		cancelPreload: null
 	};
 }
 //#endregion
@@ -4747,10 +4812,10 @@ function isInvalidBaseUrl$1(baseUrl) {
 }
 /**
 * Validates the resolved data config: the browser `baseUrl` must be a non-empty,
-* site-root-relative URL path.
+* site-root-relative URL path, and `preload` must be `"none"` or `"all"`.
 *
 * @param config - The resolved plugin configuration.
-* @throws {Error} If `baseUrl` is empty or not a rooted URL path.
+* @throws {Error} If `baseUrl` is empty or not a rooted URL path, or `preload` is unknown.
 * @example
 * ```ts
 * validateDataConfig({ outputDir: "_data", baseUrl: "/_data/" });
@@ -4758,6 +4823,8 @@ function isInvalidBaseUrl$1(baseUrl) {
 */
 function validateDataConfig(config) {
 	if (isInvalidBaseUrl$1(config.baseUrl)) throw new Error(`[web] data.baseUrl: must be a site-root-relative URL path starting with "/" (e.g. "/_data/").`);
+	const { preload } = config;
+	if (preload !== void 0 && preload !== "none" && preload !== "all") throw new Error(`[web] data.preload: must be "none" or "all".\n  Set it to "all" in both apps, or remove it.`);
 }
 //#endregion
 //#region src/plugins/data/index.ts
@@ -4774,7 +4841,8 @@ function validateDataConfig(config) {
 * **No hard `depends`** — fully browser-composable; the `node:fs` writer is behind
 * a lazy `import()` inside `write()`. Build ordering is a call-site contract: build
 * writes data during its pages phase (after its Phase-0 clean), via `app.data.write`.
-* No `onStart`/`onStop`.
+* `onStart` schedules the optional `preload: "all"` bundle fetch (browser, idle);
+* `onStop` cancels it.
 * @see README.md
 */
 /**
@@ -4800,7 +4868,9 @@ const dataPlugin = createPlugin$1("data", {
 	config: defaultDataConfig,
 	createState: createDataState,
 	onInit: (ctx) => validateDataConfig(ctx.config),
-	api: dataApi
+	api: dataApi,
+	onStart: (ctx) => startPreload(ctx),
+	onStop: (ctx) => stopPreload(ctx)
 });
 //#endregion
 //#region src/plugins/build/phases/pages.tsx

package/dist/{writer-CaoyORyZ.mjs → writer-Dwd02T9h.mjs}

@@ -1,4 +1,4 @@
-import { n as relativeDataFile } from "./convention-Dp650o3y.mjs";
+import { r as relativeDataFile, t as BUNDLE_FILE } from "./convention-BtVf429P.mjs";
 import { mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import pLimit from "p-limit";
@@ -63,8 +63,36 @@ function compileSummary(written) {
 	};
 }
 /**
+* Persist the preload bundle: one JSON object `{ "<page path>": data }` keyed by
+* each entry's `path`, exactly the key `at(path)` caches under. A later entry for
+* the same path wins, like the per-page file it overwrites.
+*
+* @param entries - The per-page data to bundle.
+* @param outDir - The build output root.
+* @param outputDir - The configured data output subdir.
+* @returns The written bundle's `outDir`-relative path and byte length.
+* @example
+* ```ts
+* await writeBundle([{ path: "/en/hello/", data }], "./dist", "_data");
+* ```
+*/
+async function writeBundle(entries, outDir, outputDir) {
+	const bundle = {};
+	for (const entry of entries) bundle[entry.path] = entry.data;
+	const file = `${outputDir.endsWith("/") ? outputDir.slice(0, -1) : outputDir}/${BUNDLE_FILE}`;
+	const filePath = path.join(outDir, file);
+	await mkdir(path.dirname(filePath), { recursive: true });
+	const body = JSON.stringify(bundle);
+	await writeFile(filePath, body, "utf8");
+	return {
+		file,
+		bytes: Buffer.byteLength(body, "utf8")
+	};
+}
+/**
 * The Node write side of the provider. Persists one JSON file per entry (bounded
 * by `p-limit`) — domain-agnostic, no route expansion (`build` already did that).
+* With `preload: "all"` it also writes the bundle file (see {@link writeBundle}).
 * Records the summary in `ctx.state.lastWrite`.
 *
 * @param ctx - The data plugin context (state, config).
@@ -81,6 +109,7 @@ async function writeData(ctx, entries, options) {
 	const outDir = options?.outDir ?? DEFAULT_OUT_DIR;
 	const limit = pLimit(WRITE_CONCURRENCY);
 	const summary = compileSummary(await Promise.all(entries.map((entry) => limit(() => writeEntry(entry, outDir, ctx.config.outputDir)))));
+	if (ctx.config.preload === "all") summary.bundle = await writeBundle(entries, outDir, ctx.config.outputDir);
 	ctx.state.lastWrite = summary;
 	return summary;
 }

package/dist/{writer-BEM-Pbgb.cjs → writer-ryba09yV.cjs}

@@ -1,4 +1,4 @@
-const require_convention = require("./convention-CLIDd9k-.cjs");
+const require_convention = require("./convention-BO-VoFLO.cjs");
 const require_index = require("./index.cjs");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
@@ -66,8 +66,36 @@ function compileSummary(written) {
 	};
 }
 /**
+* Persist the preload bundle: one JSON object `{ "<page path>": data }` keyed by
+* each entry's `path`, exactly the key `at(path)` caches under. A later entry for
+* the same path wins, like the per-page file it overwrites.
+*
+* @param entries - The per-page data to bundle.
+* @param outDir - The build output root.
+* @param outputDir - The configured data output subdir.
+* @returns The written bundle's `outDir`-relative path and byte length.
+* @example
+* ```ts
+* await writeBundle([{ path: "/en/hello/", data }], "./dist", "_data");
+* ```
+*/
+async function writeBundle(entries, outDir, outputDir) {
+	const bundle = {};
+	for (const entry of entries) bundle[entry.path] = entry.data;
+	const file = `${outputDir.endsWith("/") ? outputDir.slice(0, -1) : outputDir}/${require_convention.BUNDLE_FILE}`;
+	const filePath = node_path.default.join(outDir, file);
+	await (0, node_fs_promises.mkdir)(node_path.default.dirname(filePath), { recursive: true });
+	const body = JSON.stringify(bundle);
+	await (0, node_fs_promises.writeFile)(filePath, body, "utf8");
+	return {
+		file,
+		bytes: Buffer.byteLength(body, "utf8")
+	};
+}
+/**
 * The Node write side of the provider. Persists one JSON file per entry (bounded
 * by `p-limit`) — domain-agnostic, no route expansion (`build` already did that).
+* With `preload: "all"` it also writes the bundle file (see {@link writeBundle}).
 * Records the summary in `ctx.state.lastWrite`.
 *
 * @param ctx - The data plugin context (state, config).
@@ -84,6 +112,7 @@ async function writeData(ctx, entries, options) {
 	const outDir = options?.outDir ?? DEFAULT_OUT_DIR;
 	const limit = (0, p_limit.default)(WRITE_CONCURRENCY);
 	const summary = compileSummary(await Promise.all(entries.map((entry) => limit(() => writeEntry(entry, outDir, ctx.config.outputDir)))));
+	if (ctx.config.preload === "all") summary.bundle = await writeBundle(entries, outDir, ctx.config.outputDir);
 	ctx.state.lastWrite = summary;
 	return summary;
 }

package/package.json

@@ -139,5 +139,5 @@
     "typescript-eslint": "8.58.0",
     "vitest": "4.0.18"
   },
-  "version": "2.4.13"
+  "version": "2.4.15"
 }