@moku-labs/web 2.2.2 → 2.3.1

package/dist/index.mjs

@@ -1,10 +1,11 @@
 import { t as __exportAll } from "./chunk-D7D4PA-g.mjs";
 import { n as relativeDataFile, t as dataSuffix } from "./convention-Dp650o3y.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";
 import { appendFileSync, existsSync, readFileSync, readdirSync, realpathSync, statSync, watch } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
-import { cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { copyFile, cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { homedir, networkInterfaces, tmpdir } from "node:os";
 import minpath, { default as path } from "node:path";
 import { Feed } from "feed";
@@ -2558,9 +2559,70 @@ function substituteAssetPlaceholders(ctx, html) {
 	return html.replaceAll(ASSETS_PLACEHOLDER, buildAssetTags(ctx)).replaceAll(CSS_ASSETS_PLACEHOLDER, buildAssetTags(ctx, "css")).replaceAll(JS_ASSETS_PLACEHOLDER, buildAssetTags(ctx, "js"));
 }
 /**
-* Copies the configured `publicDir` (default `"public"`) verbatim into `outDir`,
-* preserving the nested directory structure. Skips silently (returns `null`) when
-* the source directory does not exist.
+* Test whether `destination` is already an up-to-date copy of the `src` file: same
+* size and at least as new (mtime). A missing destination — or any stat failure —
+* reports stale: when in doubt, copy.
+*
+* @param src - The source file path.
+* @param destination - The candidate destination file path.
+* @returns `true` when the destination can be skipped.
+* @example
+* ```ts
+* if (await isFreshCopy(src, destination)) return;
+* ```
+*/
+async function isFreshCopy(src, destination) {
+	try {
+		const [srcStat, destinationStat] = await Promise.all([stat(src), stat(destination)]);
+		return destinationStat.size === srcStat.size && destinationStat.mtimeMs >= srcStat.mtimeMs;
+	} catch {
+		return false;
+	}
+}
+/**
+* Recursively copy `from` into `to`, skipping every file whose destination is already
+* fresh. Skipping matters in dev rebuilds (which keep the previous outDir): re-copying
+* unchanged assets makes asset-watching dev servers (wrangler) reload on src-only
+* edits, and on macOS/APFS under Bun a large-file re-copy goes through clonefile(2),
+* whose FSEvents "ItemCloned" echo on the SOURCE path re-triggers `public/**` watchers
+* — a self-sustaining rebuild loop. Serial on purpose: public dirs can hold thousands
+* of assets and the skip path is stat-only, while an unbounded parallel copy risks fd
+* exhaustion.
+*
+* @param from - The source directory.
+* @param to - The destination directory (created when missing).
+* @returns The number of entries actually copied.
+* @example
+* ```ts
+* const copied = await copyDirIncremental("public", "dist");
+* ```
+*/
+async function copyDirIncremental(from, to) {
+	await mkdir(to, { recursive: true });
+	const entries = await readdir(from, { withFileTypes: true });
+	let copied = 0;
+	for (const entry of entries) {
+		const src = path.join(from, entry.name);
+		const destination = path.join(to, entry.name);
+		if (entry.isDirectory()) copied += await copyDirIncremental(src, destination);
+		else if (entry.isFile()) {
+			if (await isFreshCopy(src, destination)) continue;
+			await copyFile(src, destination);
+			copied += 1;
+		} else {
+			await cp(src, destination, { recursive: true });
+			copied += 1;
+		}
+	}
+	return copied;
+}
+/**
+* Copies the configured `publicDir` (default `"public"`) into `outDir`, preserving the
+* nested directory structure. The copy is incremental: a file whose destination already
+* exists with the same size and an mtime at least as new as the source is skipped. A
+* full build cleans outDir first, so every file misses the compare and the output is
+* identical to a verbatim copy; a dev rebuild (`skipClean`) rewrites only what changed.
+* Skips silently (returns `null`) when the source directory does not exist.
 *
 * @param ctx - Plugin context (provides `config`, `log`).
 * @returns The copy result, or `null` when the public directory is absent.
@@ -2578,14 +2640,15 @@ async function copyPublic(ctx) {
 		});
 		return null;
 	}
-	await cp(from, ctx.config.outDir, { recursive: true });
+	const copied = await copyDirIncremental(from, ctx.config.outDir);
 	ctx.log.debug("build:public", {
 		from,
-		dest: ctx.config.outDir
+		dest: ctx.config.outDir,
+		copied
 	});
 	return {
 		from: path.normalize(from),
-		copied: 1
+		copied
 	};
 }
 //#endregion
@@ -4531,7 +4594,7 @@ function createDataState(_ctx) {
 * isInvalidBaseUrl("_data"); // true
 * ```
 */
-function isInvalidBaseUrl(baseUrl) {
+function isInvalidBaseUrl$1(baseUrl) {
 	return typeof baseUrl !== "string" || !baseUrl.startsWith("/");
 }
 /**
@@ -4546,7 +4609,7 @@ 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/").`);
+	if (isInvalidBaseUrl$1(config.baseUrl)) throw new Error(`[web] data.baseUrl: must be a site-root-relative URL path starting with "/" (e.g. "/_data/").`);
 }
 //#endregion
 //#region src/plugins/data/index.ts
@@ -9168,6 +9231,252 @@ const cliPlugin = createPlugin$1("cli", {
 	api: createApi$1
 });
 //#endregion
+//#region src/plugins/collection/read.ts
+/**
+* @file `loadCollectionShard` — the collection plugin's standalone BROWSER read
+* primitive. Internal to the `collection` plugin AND exported for standalone
+* consumers: `collection.at(...)` wraps it, and a room-layer consumer can import it
+* directly from `@moku-labs/web/browser`.
+*
+* Unlike the `data` plugin's isomorphic `loadJson`, this uses the `fetch` global
+* DIRECTLY (no `node:fs` branch). Consumers — and tests — rely on `fetch` even
+* under Node test environments, so there is no document sniffing here: a shard is
+* always fetched over HTTP from the build-authored URL. This keeps the module
+* fully node-free.
+*/
+/**
+* Fetch + parse a build-authored collection shard over HTTP. Builds the shard URL
+* via {@link collectionUrl}, fetches it, and throws on a non-OK response so the
+* caller (`collection.at`) can decide whether to fall back.
+*
+* @template T - The expected shape of the parsed shard JSON.
+* @param baseUrl - The site-root URL prefix (ends with `/`, e.g. `"/"`).
+* @param collection - The collection name (e.g. `"bank"`).
+* @param shard - The shard key within the collection (e.g. `"en/animals"`).
+* @returns The parsed shard JSON, typed as `T`.
+* @throws {Error} If the fetch is not OK.
+* @example
+* ```ts
+* const animals = await loadCollectionShard<Animal[]>("/", "bank", "en/animals");
+* ```
+*/
+async function loadCollectionShard(baseUrl, collection, shard) {
+	const url = collectionUrl(baseUrl, collection, shard);
+	const response = await fetch(url);
+	if (!response.ok) throw new Error(`[web] collection: failed to fetch ${url} (${String(response.status)}).`);
+	return response.json();
+}
+//#endregion
+//#region src/plugins/collection/api.ts
+/**
+* @file collection plugin — API factory (the collection provider surface).
+*
+* Node-free by construction: this module statically imports only types + the pure
+* convention + the node-free `read` primitive. The Node write side (`write()`)
+* reaches its `node:fs` writer through a lazy `await import("./writer")` at call
+* time, so a browser bundle that composes `collection` for the read side never
+* pulls `node:*`. The read side (`at()`) uses only the `fetch`-based
+* `loadCollectionShard`.
+*/
+/**
+* Builds the collection provider — the static-data 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).
+*
+* @param ctx - The collection plugin context.
+* @returns The {@link CollectionProvider} mounted at `app.collection`.
+* @example
+* ```ts
+* const api = collectionApi(ctx);
+* await api.write([{ collection: "bank", shard: "en/animals", data }]); // Node build
+* await api.at("bank", "en/animals");                                   // browser
+* ```
+*/
+function collectionApi(ctx) {
+	return {
+		/**
+		* READ (browser) — fetch (and cache) the persisted data for a `(collection,
+		* shard)` key. Returns the raw JSON as `unknown`; returns `null` if the fetch
+		* or JSON parse fails (so the consumer can fall back). Wraps the throwing
+		* {@link loadCollectionShard} reader into a soft null-returning app read.
+		*
+		* @param collection - The collection name (e.g. `"bank"`).
+		* @param shard - The shard key within the collection (e.g. `"en/animals"`).
+		* @returns The shard's raw data, or `null` on failure.
+		* @example
+		* ```ts
+		* const raw = await api.at("bank", "en/animals");
+		* ```
+		*/
+		async at(collection, shard) {
+			const key = `${collection}/${shard}`;
+			if (ctx.state.cache.has(key)) return ctx.state.cache.get(key);
+			try {
+				const data = await loadCollectionShard(ctx.config.baseUrl, collection, shard);
+				ctx.state.cache.set(key, data);
+				return data;
+			} catch {
+				return null;
+			}
+		},
+		/**
+		* WRITE (Node) — persist one JSON file per entry, keyed by `(collection,
+		* shard)`. Called by the build after it authors the shards. Lazily loads its
+		* `node:fs` writer (keeping a browser bundle node-free).
+		*
+		* @param entries - The per-shard data to persist.
+		* @param options - Optional `{ outDir }` override (defaults to `./dist`).
+		* @param options.outDir - Build output directory the write happens under.
+		* @returns A summary of the written files.
+		* @example
+		* ```ts
+		* await api.write([{ collection: "bank", shard: "ru", data }], { outDir: "dist" });
+		* ```
+		*/
+		async write(entries, options) {
+			const { writeCollection } = await import("./writer-C9BfpPio.mjs");
+			return writeCollection(ctx, entries, options);
+		},
+		/**
+		* PURE — the browser fetch URL for a `(collection, shard)` key.
+		*
+		* @param collection - The collection name.
+		* @param shard - The shard key within the collection.
+		* @returns The site-root-relative shard URL.
+		* @example
+		* ```ts
+		* api.urlFor("bank", "en/animals"); // "/bank/en/animals.json"
+		* ```
+		*/
+		urlFor(collection, shard) {
+			return collectionUrl(ctx.config.baseUrl, collection, shard);
+		},
+		/**
+		* PURE — the `outDir`-relative file path for a `(collection, shard)` key.
+		*
+		* @param collection - The collection name.
+		* @param shard - The shard key within the collection.
+		* @returns The output-relative file path.
+		* @example
+		* ```ts
+		* api.fileFor("bank", "en/animals"); // "bank/en/animals.json"
+		* ```
+		*/
+		fileFor(collection, shard) {
+			return relativeShardFile(collection, shard);
+		}
+	};
+}
+//#endregion
+//#region src/plugins/collection/config.ts
+/**
+* Typed default collection config (R6: no inline `as`). `baseUrl` is the READ-side
+* site-root URL prefix the browser fetches shards from; the collection name is the
+* top directory under it. The default `"/"` serves shards straight from the site
+* root (e.g. `/bank/en/animals.json`).
+*
+* @example
+* ```ts
+* createPlugin("collection", { config: defaultCollectionConfig });
+* ```
+*/
+const defaultCollectionConfig = { baseUrl: "/" };
+//#endregion
+//#region src/plugins/collection/state.ts
+/**
+* Creates initial collection state: a null `lastWrite` slot (populated by the Node
+* `write()` side) and an empty `cache` (populated lazily by the browser
+* `at(collection, shard)` side on first fetch).
+*
+* @param _ctx - Minimal context with global and config.
+* @param _ctx.global - Global framework configuration.
+* @param _ctx.config - Resolved plugin configuration.
+* @returns Fresh collection state with no recorded write and an empty per-shard cache.
+* @example
+* ```ts
+* const state = createCollectionState({ global: {}, config });
+* ```
+*/
+function createCollectionState(_ctx) {
+	return {
+		lastWrite: null,
+		cache: /* @__PURE__ */ new Map()
+	};
+}
+//#endregion
+//#region src/plugins/collection/validate.ts
+/**
+* Reports whether a `baseUrl` value is invalid: it must be a string that ends with
+* a `"/"` so the collection name appends cleanly (`baseUrl + collection + "/" + …`).
+*
+* @param baseUrl - The candidate `baseUrl` value to check.
+* @returns `true` when `baseUrl` is not a string or does not end with "/".
+* @example
+* ```ts
+* isInvalidBaseUrl("/"); // false
+* isInvalidBaseUrl("/cdn"); // true
+* ```
+*/
+function isInvalidBaseUrl(baseUrl) {
+	return typeof baseUrl !== "string" || !baseUrl.endsWith("/");
+}
+/**
+* Validates the resolved collection config: the browser `baseUrl` must be a string
+* ending with `"/"` so the collection name appends cleanly.
+*
+* @param config - The resolved plugin configuration.
+* @throws {Error} If `baseUrl` is not a string ending with "/".
+* @example
+* ```ts
+* validateCollectionConfig({ baseUrl: "/" });
+* ```
+*/
+function validateCollectionConfig(config) {
+	if (isInvalidBaseUrl(config.baseUrl)) throw new Error(`[web] collection.baseUrl: must be a URL prefix ending with "/" (e.g. "/" or "/cdn/").`);
+}
+//#endregion
+//#region src/plugins/collection/index.ts
+/**
+* @file collection — Standard tier plugin (wiring-only). The static-data
+* COLLECTION provider — the collection-keyed sibling of the page-path-keyed `data`
+* plugin.
+*
+* Owns ONE contract — `(collection, shard) → persisted JSON file` — and nothing
+* about what the data is: `write(entries)` persists per-shard JSON on Node (the
+* build supplies the shards it already authored); `at(collection, shard)` fetches +
+* caches it in the browser as `unknown`, read on demand by the consumer. NOT a
+* framework default — the consumer composes it where needed (Node build AND/OR
+* browser app).
+*
+* **No hard `depends`** — fully browser-composable; the `node:fs` writer is behind
+* a lazy `import()` inside `write()`. Build ordering is a call-site contract: the
+* build writes shards during/after its pages phase, via `app.collection.write`.
+* No `onStart`/`onStop`.
+* @see README.md
+*/
+/**
+* Collection plugin — the static-data collection provider. Mounts
+* `write(entries)` (Node persist), `at(collection, shard)` (browser read), and the
+* pure `urlFor`/`fileFor` convention at `app.collection`.
+*
+* @example
+* ```ts
+* // Node build: write build-authored shards during/after the build's pages phase.
+* const app = createApp({ plugins: [collectionPlugin, buildPlugin] });
+* await app.build.run();
+* await app.collection.write([{ collection: "bank", shard: "en/animals", data }]);
+*
+* // Browser app: compose `collectionPlugin` too; fetch a shard on demand.
+* const raw = await app.collection.at("bank", "en/animals"); // unknown | null
+* ```
+*/
+const collectionPlugin = createPlugin$1("collection", {
+	config: defaultCollectionConfig,
+	createState: createCollectionState,
+	onInit: (ctx) => validateCollectionConfig(ctx.config),
+	api: collectionApi
+});
+//#endregion
 //#region src/plugins/spa/api.ts
 /**
 * Creates the spa plugin API surface (registration / control). All methods
@@ -9333,7 +9642,7 @@ function syncHead(_head, doc) {
 }
 //#endregion
 //#region src/plugins/spa/types.ts
-var types_exports$7 = /* @__PURE__ */ __exportAll({ ISLAND_HOOK_NAMES: () => ISLAND_HOOK_NAMES });
+var types_exports$8 = /* @__PURE__ */ __exportAll({ ISLAND_HOOK_NAMES: () => ISLAND_HOOK_NAMES });
 /** Allowed hook names — single source of truth for fail-fast validation. */
 const ISLAND_HOOK_NAMES = [
 	"onCreate",
@@ -11471,21 +11780,24 @@ var types_exports = /* @__PURE__ */ __exportAll({});
 //#region src/plugins/cli/types.ts
 var types_exports$1 = /* @__PURE__ */ __exportAll({});
 //#endregion
-//#region src/plugins/content/types.ts
+//#region src/plugins/collection/types.ts
 var types_exports$2 = /* @__PURE__ */ __exportAll({});
 //#endregion
-//#region src/plugins/data/types.ts
+//#region src/plugins/content/types.ts
 var types_exports$3 = /* @__PURE__ */ __exportAll({});
 //#endregion
-//#region src/plugins/deploy/types.ts
+//#region src/plugins/data/types.ts
 var types_exports$4 = /* @__PURE__ */ __exportAll({});
 //#endregion
-//#region src/plugins/head/types.ts
+//#region src/plugins/deploy/types.ts
 var types_exports$5 = /* @__PURE__ */ __exportAll({});
 //#endregion
-//#region src/plugins/router/types.ts
+//#region src/plugins/head/types.ts
 var types_exports$6 = /* @__PURE__ */ __exportAll({});
 //#endregion
+//#region src/plugins/router/types.ts
+var types_exports$7 = /* @__PURE__ */ __exportAll({});
+//#endregion
 //#region node_modules/unist-util-stringify-position/lib/index.js
 /**
 * @typedef {import('unist').Node} Node
@@ -13684,4 +13996,4 @@ const createApp = core.createApp;
 */
 const createPlugin = core.createPlugin;
 //#endregion
-export { types_exports as Build, types_exports$1 as Cli, types_exports$2 as Content, types_exports$3 as Data, types_exports$4 as Deploy, EmbedFacadeButton, GalleryTrack, types_exports$5 as Head, types_exports$6 as Router, types_exports$7 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, hardNavigate, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, navigate, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_exports as Build, types_exports$1 as Cli, types_exports$2 as Collection, types_exports$3 as Content, types_exports$4 as Data, types_exports$5 as Deploy, EmbedFacadeButton, GalleryTrack, types_exports$6 as Head, types_exports$7 as Router, types_exports$8 as Spa, browserEnv, buildArticleHead, buildPlugin, canonical, cliPlugin, cloudflareBindings, collectionPlugin, collectionUrl, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, deployPlugin, dotenv, envPlugin, feedLink, fileSystemContent, hardNavigate, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, loadCollectionShard, logPlugin, meta, navigate, og, processEnv, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/dist/writer-BBtgz9wt.cjs

@@ -0,0 +1,90 @@
+const require_convention = require("./convention-CsJw7CML.cjs");
+const require_index = require("./index.cjs");
+let node_fs_promises = require("node:fs/promises");
+let node_path = require("node:path");
+node_path = require_index.__toESM(node_path, 1);
+let p_limit = require("p-limit");
+p_limit = require_index.__toESM(p_limit, 1);
+//#region src/plugins/collection/writer.ts
+/**
+* @file collection plugin — Node write side of the provider (`write()`).
+*
+* This is the ONLY module in the `collection` plugin that touches `node:*`. It is
+* reached exclusively through a lazy `await import("./writer")` inside `api.ts`'s
+* `write()`, so a browser bundle that composes `collection` for the read side never
+* statically pulls `node:fs` (see `__tests__/unit/isolation.test.ts`).
+*
+* It is domain-agnostic: it persists whatever `data` each {@link CollectionShard}
+* carries (the build authored these), one JSON file per shard, at the path
+* {@link relativeShardFile} derives from `(collection, shard)`. No domain knowledge,
+* no expansion (build already authored the shards).
+*/
+/** Default build output root, matching build's default `outDir` ("./dist", build/api.ts). */
+const DEFAULT_OUT_DIR = "./dist";
+/** Concurrency bound for per-shard JSON writes. */
+const WRITE_CONCURRENCY = 8;
+/**
+* Persist one shard's data as JSON under `<outDir>/<relativeShardFile>` and return
+* the written `{ relative, bytes }`.
+*
+* @param entry - The shard entry to persist.
+* @param outDir - The build output root.
+* @returns The written file's `outDir`-relative path and byte length.
+* @example
+* ```ts
+* await writeEntry({ collection: "bank", shard: "en/animals", data }, "./dist");
+* ```
+*/
+async function writeEntry(entry, outDir) {
+	const relative = require_convention.relativeShardFile(entry.collection, entry.shard);
+	const filePath = node_path.default.join(outDir, relative);
+	await (0, node_fs_promises.mkdir)(node_path.default.dirname(filePath), { recursive: true });
+	const body = JSON.stringify(entry.data);
+	await (0, node_fs_promises.writeFile)(filePath, body, "utf8");
+	return {
+		relative,
+		bytes: Buffer.byteLength(body, "utf8")
+	};
+}
+/**
+* Roll up the per-file write records into the public {@link CollectionWriteSummary}:
+* file count, total byte length, and the `outDir`-relative paths in write order.
+*
+* @param written - The per-file `{ relative, bytes }` records from {@link writeEntry}.
+* @returns The aggregated write summary.
+* @example
+* ```ts
+* compileSummary([{ relative: "bank/en/animals.json", bytes: 12 }]);
+* ```
+*/
+function compileSummary(written) {
+	return {
+		fileCount: written.length,
+		bytes: written.reduce((total, file) => total + file.bytes, 0),
+		files: written.map((file) => file.relative)
+	};
+}
+/**
+* The Node write side of the provider. Persists one JSON file per shard (bounded
+* by `p-limit`) — domain-agnostic, no expansion (`build` already authored the
+* shards). Records the summary in `ctx.state.lastWrite`.
+*
+* @param ctx - The collection plugin context (state, config).
+* @param entries - The per-shard data to persist.
+* @param options - Optional overrides.
+* @param options.outDir - Build output directory to write under (default `./dist`).
+* @returns A summary of the written files.
+* @example
+* ```ts
+* const summary = await writeCollection(ctx, [{ collection: "bank", shard: "ru", data }]);
+* ```
+*/
+async function writeCollection(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.state.lastWrite = summary;
+	return summary;
+}
+//#endregion
+exports.writeCollection = writeCollection;

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

@@ -1,9 +1,10 @@
-const require_convention = require("./convention-BpDfzX7e.cjs");
+const require_convention = require("./convention-CLIDd9k-.cjs");
+const require_index = require("./index.cjs");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
-node_path = require_convention.__toESM(node_path, 1);
+node_path = require_index.__toESM(node_path, 1);
 let p_limit = require("p-limit");
-p_limit = require_convention.__toESM(p_limit, 1);
+p_limit = require_index.__toESM(p_limit, 1);
 //#region src/plugins/data/writer.ts
 /**
 * @file data plugin — Node write side of the agnostic provider (`write()`).

package/dist/writer-C9BfpPio.mjs

@@ -0,0 +1,87 @@
+import { n as relativeShardFile } from "./convention-Bs8SrQS9.mjs";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import pLimit from "p-limit";
+//#region src/plugins/collection/writer.ts
+/**
+* @file collection plugin — Node write side of the provider (`write()`).
+*
+* This is the ONLY module in the `collection` plugin that touches `node:*`. It is
+* reached exclusively through a lazy `await import("./writer")` inside `api.ts`'s
+* `write()`, so a browser bundle that composes `collection` for the read side never
+* statically pulls `node:fs` (see `__tests__/unit/isolation.test.ts`).
+*
+* It is domain-agnostic: it persists whatever `data` each {@link CollectionShard}
+* carries (the build authored these), one JSON file per shard, at the path
+* {@link relativeShardFile} derives from `(collection, shard)`. No domain knowledge,
+* no expansion (build already authored the shards).
+*/
+/** Default build output root, matching build's default `outDir` ("./dist", build/api.ts). */
+const DEFAULT_OUT_DIR = "./dist";
+/** Concurrency bound for per-shard JSON writes. */
+const WRITE_CONCURRENCY = 8;
+/**
+* Persist one shard's data as JSON under `<outDir>/<relativeShardFile>` and return
+* the written `{ relative, bytes }`.
+*
+* @param entry - The shard entry to persist.
+* @param outDir - The build output root.
+* @returns The written file's `outDir`-relative path and byte length.
+* @example
+* ```ts
+* await writeEntry({ collection: "bank", shard: "en/animals", data }, "./dist");
+* ```
+*/
+async function writeEntry(entry, outDir) {
+	const relative = relativeShardFile(entry.collection, entry.shard);
+	const filePath = path.join(outDir, relative);
+	await mkdir(path.dirname(filePath), { recursive: true });
+	const body = JSON.stringify(entry.data);
+	await writeFile(filePath, body, "utf8");
+	return {
+		relative,
+		bytes: Buffer.byteLength(body, "utf8")
+	};
+}
+/**
+* Roll up the per-file write records into the public {@link CollectionWriteSummary}:
+* file count, total byte length, and the `outDir`-relative paths in write order.
+*
+* @param written - The per-file `{ relative, bytes }` records from {@link writeEntry}.
+* @returns The aggregated write summary.
+* @example
+* ```ts
+* compileSummary([{ relative: "bank/en/animals.json", bytes: 12 }]);
+* ```
+*/
+function compileSummary(written) {
+	return {
+		fileCount: written.length,
+		bytes: written.reduce((total, file) => total + file.bytes, 0),
+		files: written.map((file) => file.relative)
+	};
+}
+/**
+* The Node write side of the provider. Persists one JSON file per shard (bounded
+* by `p-limit`) — domain-agnostic, no expansion (`build` already authored the
+* shards). Records the summary in `ctx.state.lastWrite`.
+*
+* @param ctx - The collection plugin context (state, config).
+* @param entries - The per-shard data to persist.
+* @param options - Optional overrides.
+* @param options.outDir - Build output directory to write under (default `./dist`).
+* @returns A summary of the written files.
+* @example
+* ```ts
+* const summary = await writeCollection(ctx, [{ collection: "bank", shard: "ru", data }]);
+* ```
+*/
+async function writeCollection(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.state.lastWrite = summary;
+	return summary;
+}
+//#endregion
+export { writeCollection };

package/package.json

@@ -132,5 +132,5 @@
     "test:build-e2e": "bun test src/plugins/build/__tests__/e2e/",
     "test:coverage": "vitest run --project unit --project integration --coverage"
   },
-  "version": "2.2.2"
+  "version": "2.3.1"
 }