@moku-labs/web 2.2.2 → 2.3.1

package/dist/browser.d.mts

@@ -277,7 +277,7 @@ interface PathMatcher {
     };
   } | null;
 }
-declare namespace types_d_exports$3 {
+declare namespace types_d_exports$4 {
   export { Api$2 as Api, ClientRoute, CompileInput, CompiledRoute, Config$2 as Config, ExtractApi$1 as ExtractApi, ExtractRouteParams, ExtractSegmentParameter, GenerateContext, HeadConfig$1 as HeadConfig, LayoutContext, LoadContext, MatcherTable, Prettify, RouteBuilder, RouteContext, RouteDefinition, RouteHandlers, RouteMap, RouteRequire, RouteState, RouterApi, RouterConfig, RouterState, ScrollMode, State$2 as State, TransitionMode, TypedRoute, Urls };
 }
 /**
@@ -738,7 +738,7 @@ type Config$2 = RouterConfig;
 type State$2 = RouterState;
 /** Re-export under the canonical `Api` name for the plugin-types barrel. */
 type Api$2 = RouterApi;
-declare namespace types_d_exports$2 {
+declare namespace types_d_exports$3 {
   export { Api$1 as Api, ArticleMeta, Config$1 as Config, HeadConfig, HeadDefaults, HeadElement, ResolvedRoute, State$1 as State };
 }
 /**
@@ -913,7 +913,7 @@ type Api$1 = {
    */
   composeTitle(head: HeadConfig | undefined): string;
 };
-declare namespace types_d_exports$4 {
+declare namespace types_d_exports$5 {
   export { AnyVNode, ExtractApi, ISLAND_HOOK_NAMES, IslandContext, IslandDef, IslandEventHandler, IslandEvents, IslandHooks, IslandInstance, IslandRender, IslandRouteSlice, IslandSpec, IslandSpecExtras, IslandStateFactory, NavigateOptions, PageData, RenderResult, ResolvedSpaConfig, ScrollMode, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState, TransitionMode };
 }
 /** Per-navigation options for the programmatic navigators (`ctx.navigate` / `app.spa.navigate`). */
@@ -1925,7 +1925,7 @@ declare const spaPlugin: import("@moku-labs/core").PluginInstance<"spa", SpaConf
     el: Element;
   };
 }> & Record<never, never>;
-declare namespace types_d_exports$1 {
+declare namespace types_d_exports$2 {
   export { DataConfig, DataEntry, DataProvider, DataState, DataWriteSummary };
 }
 /**
@@ -2072,7 +2072,43 @@ type DataProvider = {
  * ```
  */
 declare const dataPlugin: import("@moku-labs/core").PluginInstance<"data", DataConfig, DataState, DataProvider, {}> & Record<never, never>;
-declare namespace types_d_exports {
+//#endregion
+//#region src/plugins/collection/convention.d.ts
+/**
+ * Compute the browser fetch URL for a `(collection, shard)` key: the `baseUrl`
+ * prefix joined with the {@link shardSuffix}. Exported so standalone consumers can
+ * derive the same URL without composing the plugin.
+ *
+ * @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 site-root-relative shard URL (e.g. `/bank/en/animals.json`).
+ * @example
+ * ```ts
+ * collectionUrl("/", "bank", "en/animals"); // "/bank/en/animals.json"
+ * ```
+ */
+declare function collectionUrl(baseUrl: string, collection: string, shard: string): string;
+//#endregion
+//#region src/plugins/collection/read.d.ts
+/**
+ * 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");
+ * ```
+ */
+declare function loadCollectionShard<T>(baseUrl: string, collection: string, shard: string): Promise<T>;
+declare namespace types_d_exports$1 {
   export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, EmbedFacade, EmbedFacadeProps, EmbedOptions, FileSystemContentOptions, Frontmatter, GalleryComponent, GalleryOptions, GalleryProps, GallerySlide, GalleryTransformOptions, LoadAllOptions, MermaidDiagramOptions, State };
 }
 /**
@@ -2571,6 +2607,140 @@ declare const contentPlugin: import("@moku-labs/core").PluginInstance<"content",
     paths: readonly string[];
   };
 }> & Record<never, never>;
+declare namespace types_d_exports {
+  export { CollectionConfig, CollectionProvider, CollectionShard, CollectionState, CollectionWriteSummary };
+}
+/**
+ * @file collection plugin — type definitions (Standard tier).
+ *
+ * The `collection` plugin is the **static-data collection provider** — the
+ * collection-keyed sibling of the page-path-keyed `data` plugin. It owns ONE
+ * thing: the contract `(collection, shard) → persisted JSON file`. It knows
+ * NOTHING about what the data *is* — no domain types appear here. A consumer
+ * decides its own shard shape (`at`'s `T`).
+ *
+ *  - **Node (build):** `write(entries)` persists one JSON file per shard, keyed by
+ *    `(collection, shard)` via {@link CollectionProvider.fileFor}. The build
+ *    supplies the entries (it already authored the shards), so there is no
+ *    expansion here.
+ *  - **Browser (runtime):** `at(collection, shard)` fetches + caches that file as
+ *    `unknown`, which the consumer reads on demand.
+ *
+ * The Node-only file-writing code (`node:fs`) is isolated behind a lazy `import()`
+ * inside `write()`, so composing `collection` in a browser app keeps the bundle
+ * free of `node:*`.
+ */
+/**
+ * Configuration for {@link collectionPlugin}. All fields have defaults (see
+ * `./config`).
+ *
+ * @example
+ * ```ts
+ * const cfg: CollectionConfig = { baseUrl: "/" };
+ * ```
+ */
+type CollectionConfig = {
+  /**
+   * READ side (browser): site-root URL prefix the client fetches the per-shard
+   * JSON from. The collection name is the top directory under it, so the fetched
+   * URL is `baseUrl + collection + "/" + shard + ".json"`. Default `"/"`.
+   */
+  baseUrl: string;
+};
+/** One build-authored shard to persist — the build produces these. */
+interface CollectionShard {
+  /** The collection name — the top directory (e.g. `"bank"`). */
+  collection: string;
+  /**
+   * The shard key WITHIN the collection (e.g. `"en/animals"`); may contain `/`,
+   * which is preserved as a nested path. Maps to a file via
+   * {@link CollectionProvider.fileFor}.
+   */
+  shard: string;
+  /** The serializable data for this shard. */
+  data: unknown;
+}
+/** Summary returned by {@link CollectionProvider.write} and cached in state. */
+interface CollectionWriteSummary {
+  /** Number of per-shard JSON files written. */
+  fileCount: number;
+  /** Total bytes written across all files. */
+  bytes: number;
+  /** The written file paths, relative to the build `outDir`. */
+  files: string[];
+}
+/**
+ * Internal collection state. `lastWrite` records the most recent `write()` (Node);
+ * `cache` memoizes fetched per-`(collection, shard)` data (browser, lazy). Both
+ * empty until their respective side first runs.
+ */
+interface CollectionState {
+  /** Result of the last `write()`, or `null` if it has not run yet (Node). */
+  lastWrite: CollectionWriteSummary | null;
+  /** Per-`(collection, shard)` fetched data, cached after the first `at()` (browser). */
+  cache: Map<string, unknown>;
+}
+/**
+ * Public API mounted at `app.collection` — the static-data collection provider.
+ * `write()` is the Node persist side; `at()` is the browser read side;
+ * `urlFor`/`fileFor` are the pure URL convention shared by both so the written
+ * file and fetched URL can never drift.
+ *
+ * @example
+ * ```ts
+ * // Node build (build supplies the shards it already authored):
+ * await app.collection.write([{ collection: "bank", shard: "en/animals", data }]);
+ *
+ * // Browser: fetch a shard on demand, read by the consumer:
+ * const raw = await app.collection.at("bank", "en/animals"); // unknown | null (null on failure)
+ * ```
+ */
+type CollectionProvider = {
+  /**
+   * READ (browser) — fetch (and cache) the persisted data for a `(collection,
+   * shard)` key from `config.baseUrl`. Returns the raw parsed JSON as `unknown`;
+   * returns `null` if the fetch or JSON parse fails.
+   *
+   * @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.
+   */
+  at(collection: string, shard: string): Promise<unknown | null>;
+  /**
+   * WRITE (Node) — persist one JSON file per entry, keyed by `(collection, shard)`
+   * via {@link CollectionProvider.fileFor}. Called by the build after it authors
+   * the shards. Lazily loads its `node:fs` writer, so it never contaminates a
+   * browser bundle.
+   *
+   * @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.
+   */
+  write(entries: readonly CollectionShard[], options?: {
+    outDir?: string;
+  }): Promise<CollectionWriteSummary>;
+  /**
+   * PURE — the browser fetch URL for a `(collection, shard)` key (e.g.
+   * `("bank", "en/animals")` → `/bank/en/animals.json`). Shared with
+   * {@link CollectionProvider.fileFor}.
+   *
+   * @param collection - The collection name.
+   * @param shard - The shard key within the collection.
+   * @returns The site-root-relative shard URL.
+   */
+  urlFor(collection: string, shard: string): string;
+  /**
+   * PURE — the `outDir`-relative file path for a `(collection, shard)` key (e.g.
+   * `("bank", "en/animals")` → `bank/en/animals.json`). Shared with
+   * {@link CollectionProvider.urlFor}.
+   *
+   * @param collection - The collection name.
+   * @param shard - The shard key within the collection.
+   * @returns The output-relative file path.
+   */
+  fileFor(collection: string, shard: string): string;
+};
 //#endregion
 //#region src/browser.d.ts
 /**
@@ -2674,4 +2844,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$5, Events, import("@moku-labs/core").CoreApisFromTuple<[import("@moku-labs/core").CorePluginInstance<"log", import("@moku-labs/common").LogConfig, import("@moku-labs/common").LogState, import("@moku-labs/common").LogApi>, import("@moku-labs/core").CorePluginInstance<"env", import("@moku-labs/common").EnvConfig, import("@moku-labs/common").EnvState, import("@moku-labs/common").EnvApi>]>>;
 //#endregion
-export { type Channel, type ChannelKeepAlive, type ChannelOptions, type ChannelReconnect, types_d_exports as Content, types_d_exports$1 as Data, type Env, types_d_exports$2 as Head, type Log, types_d_exports$3 as Router, types_d_exports$4 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, hardNavigate, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, navigate, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { type Channel, type ChannelKeepAlive, type ChannelOptions, type ChannelReconnect, types_d_exports as Collection, types_d_exports$1 as Content, types_d_exports$2 as Data, type Env, types_d_exports$3 as Head, type Log, types_d_exports$4 as Router, types_d_exports$5 as Spa, browserEnv, buildArticleHead, canonical, collectionUrl, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, hardNavigate, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, loadCollectionShard, logPlugin, meta, navigate, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/dist/browser.mjs

@@ -2640,7 +2640,7 @@ function syncHead(_head, doc) {
 }
 //#endregion
 //#region src/plugins/spa/types.ts
-var types_exports$4 = /* @__PURE__ */ __exportAll({ ISLAND_HOOK_NAMES: () => ISLAND_HOOK_NAMES });
+var types_exports$5 = /* @__PURE__ */ __exportAll({ ISLAND_HOOK_NAMES: () => ISLAND_HOOK_NAMES });
 /** Allowed hook names — single source of truth for fail-fast validation. */
 const ISLAND_HOOK_NAMES = [
 	"onCreate",
@@ -4772,6 +4772,112 @@ const spaPlugin = createPlugin$1("spa", {
 	onStop: disposeSpa
 });
 //#endregion
+//#region src/plugins/collection/convention.ts
+/**
+* @file collection plugin — the pure URL/file convention (no `node:*`, no DOM).
+*
+* ONE function maps a `(collection, shard)` key to its shard suffix, so the browser
+* fetch URL (`baseUrl + suffix`) and the on-disk file (`outDir + "/" + suffix`) are
+* derived from the same source and cannot drift. The collection name is the top
+* directory and the shard becomes a `.json` file beneath it (its INTERNAL slashes
+* are kept as nested dirs):
+*   ("bank", "en/animals") → "bank/en/animals.json"
+*   ("bank", "ru")         → "bank/ru.json"
+*   ("/bank/", "/en/")     → "bank/en.json"  (outer slashes trimmed)
+*
+* Encoding split: the FETCH suffix ({@link shardSuffix}) keeps the key's
+* percent-encoding (the browser requests the encoded path); the FILE path
+* ({@link relativeShardFile}) decodes it so the on-disk name is literal.
+*/
+/**
+* Strip leading/trailing slashes from `collection` and `shard` (keeping the
+* shard's INTERNAL slashes as nested path segments), then join them as
+* `` `${collection}/${shard}.json` `` — the suffix shared by the fetch URL and the
+* on-disk file.
+*
+* @param collection - The collection name (e.g. `"bank"`).
+* @param shard - The shard key within the collection (e.g. `"en/animals"`).
+* @returns The shard suffix (e.g. `"bank/en/animals.json"`).
+* @example
+* ```ts
+* shardSuffix("bank", "en/animals"); // "bank/en/animals.json"
+* shardSuffix("/bank/", "/ru/");     // "bank/ru.json"
+* ```
+*/
+function shardSuffix(collection, shard) {
+	return `${trimSlashes(collection)}/${trimSlashes(shard)}.json`;
+}
+/**
+* Strip any leading and trailing slashes from a path segment, leaving its internal
+* slashes intact.
+*
+* @param segment - The raw `collection` or `shard` value.
+* @returns The segment without outer slashes.
+* @example
+* ```ts
+* trimSlashes("/en/animals/"); // "en/animals"
+* ```
+*/
+function trimSlashes(segment) {
+	let trimmed = segment;
+	while (trimmed.startsWith("/")) trimmed = trimmed.slice(1);
+	while (trimmed.endsWith("/")) trimmed = trimmed.slice(0, -1);
+	return trimmed;
+}
+/**
+* Compute the browser fetch URL for a `(collection, shard)` key: the `baseUrl`
+* prefix joined with the {@link shardSuffix}. Exported so standalone consumers can
+* derive the same URL without composing the plugin.
+*
+* @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 site-root-relative shard URL (e.g. `/bank/en/animals.json`).
+* @example
+* ```ts
+* collectionUrl("/", "bank", "en/animals"); // "/bank/en/animals.json"
+* ```
+*/
+function collectionUrl(baseUrl, collection, shard) {
+	return `${baseUrl}${shardSuffix(collection, shard)}`;
+}
+//#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/content/api.ts
 /** Actionable error when the content plugin is composed without any provider. */
 const NO_PROVIDER = "[web] content: no provider composed.\n  Add fileSystemContent(...) to pluginConfigs.content.providers.";
@@ -5325,18 +5431,21 @@ const contentPlugin = createPlugin$1("content", {
 	api: contentApi
 });
 //#endregion
-//#region src/plugins/content/types.ts
+//#region src/plugins/collection/types.ts
 var types_exports = /* @__PURE__ */ __exportAll({});
 //#endregion
-//#region src/plugins/data/types.ts
+//#region src/plugins/content/types.ts
 var types_exports$1 = /* @__PURE__ */ __exportAll({});
 //#endregion
-//#region src/plugins/head/types.ts
+//#region src/plugins/data/types.ts
 var types_exports$2 = /* @__PURE__ */ __exportAll({});
 //#endregion
-//#region src/plugins/router/types.ts
+//#region src/plugins/head/types.ts
 var types_exports$3 = /* @__PURE__ */ __exportAll({});
 //#endregion
+//#region src/plugins/router/types.ts
+var types_exports$4 = /* @__PURE__ */ __exportAll({});
+//#endregion
 //#region src/browser.ts
 /**
 * @file `@moku-labs/web/browser` — the browser-safe entry point.
@@ -5411,4 +5520,4 @@ const createApp = core.createApp;
 */
 const createPlugin = core.createPlugin;
 //#endregion
-export { types_exports as Content, types_exports$1 as Data, types_exports$2 as Head, types_exports$3 as Router, types_exports$4 as Spa, browserEnv, buildArticleHead, canonical, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, hardNavigate, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, logPlugin, meta, navigate, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };
+export { types_exports as Collection, types_exports$1 as Content, types_exports$2 as Data, types_exports$3 as Head, types_exports$4 as Router, types_exports$5 as Spa, browserEnv, buildArticleHead, canonical, collectionUrl, contentPlugin, createApp, createChannel, createIsland, createPlugin, createUrls, dataPlugin, defineRoutes, envPlugin, feedLink, hardNavigate, headPlugin, hreflang, i18nPlugin, jsonLd, lazyEmbed, loadCollectionShard, logPlugin, meta, navigate, og, route, routerPlugin, sitePlugin, spaPlugin, twitter };

package/dist/convention-Bs8SrQS9.mjs

@@ -0,0 +1,109 @@
+//#region src/plugins/collection/convention.ts
+/**
+* @file collection plugin — the pure URL/file convention (no `node:*`, no DOM).
+*
+* ONE function maps a `(collection, shard)` key to its shard suffix, so the browser
+* fetch URL (`baseUrl + suffix`) and the on-disk file (`outDir + "/" + suffix`) are
+* derived from the same source and cannot drift. The collection name is the top
+* directory and the shard becomes a `.json` file beneath it (its INTERNAL slashes
+* are kept as nested dirs):
+*   ("bank", "en/animals") → "bank/en/animals.json"
+*   ("bank", "ru")         → "bank/ru.json"
+*   ("/bank/", "/en/")     → "bank/en.json"  (outer slashes trimmed)
+*
+* Encoding split: the FETCH suffix ({@link shardSuffix}) keeps the key's
+* percent-encoding (the browser requests the encoded path); the FILE path
+* ({@link relativeShardFile}) decodes it so the on-disk name is literal.
+*/
+/**
+* Strip leading/trailing slashes from `collection` and `shard` (keeping the
+* shard's INTERNAL slashes as nested path segments), then join them as
+* `` `${collection}/${shard}.json` `` — the suffix shared by the fetch URL and the
+* on-disk file.
+*
+* @param collection - The collection name (e.g. `"bank"`).
+* @param shard - The shard key within the collection (e.g. `"en/animals"`).
+* @returns The shard suffix (e.g. `"bank/en/animals.json"`).
+* @example
+* ```ts
+* shardSuffix("bank", "en/animals"); // "bank/en/animals.json"
+* shardSuffix("/bank/", "/ru/");     // "bank/ru.json"
+* ```
+*/
+function shardSuffix(collection, shard) {
+	return `${trimSlashes(collection)}/${trimSlashes(shard)}.json`;
+}
+/**
+* Strip any leading and trailing slashes from a path segment, leaving its internal
+* slashes intact.
+*
+* @param segment - The raw `collection` or `shard` value.
+* @returns The segment without outer slashes.
+* @example
+* ```ts
+* trimSlashes("/en/animals/"); // "en/animals"
+* ```
+*/
+function trimSlashes(segment) {
+	let trimmed = segment;
+	while (trimmed.startsWith("/")) trimmed = trimmed.slice(1);
+	while (trimmed.endsWith("/")) trimmed = trimmed.slice(0, -1);
+	return trimmed;
+}
+/**
+* Compute the browser fetch URL for a `(collection, shard)` key: the `baseUrl`
+* prefix joined with the {@link shardSuffix}. Exported so standalone consumers can
+* derive the same URL without composing the plugin.
+*
+* @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 site-root-relative shard URL (e.g. `/bank/en/animals.json`).
+* @example
+* ```ts
+* collectionUrl("/", "bank", "en/animals"); // "/bank/en/animals.json"
+* ```
+*/
+function collectionUrl(baseUrl, collection, shard) {
+	return `${baseUrl}${shardSuffix(collection, shard)}`;
+}
+/**
+* Decode a shard suffix's percent-escapes so the on-disk file carries the literal
+* name (servers decode the encoded fetch URL before filesystem lookup). Falls back
+* to the raw suffix on malformed escapes.
+*
+* @param suffix - The computed shard suffix (possibly percent-encoded).
+* @returns The decoded suffix, or the raw suffix on malformed escapes.
+* @example
+* ```ts
+* decodeSuffix("bank/en/a%20%26%20b.json"); // "bank/en/a & b.json"
+* ```
+*/
+function decodeSuffix(suffix) {
+	try {
+		return decodeURIComponent(suffix);
+	} catch {
+		return suffix;
+	}
+}
+/**
+* Compute the `outDir`-relative shard file for a `(collection, shard)` key — the
+* DECODED {@link shardSuffix} (servers resolve the decoded request path against
+* literal file names). The collection name IS the top directory, so there is no
+* extra output-dir wrapper. Shared by the Node writer and the pure `fileFor`
+* accessor so the written file and the reported path never drift.
+*
+* @param collection - The collection name (e.g. `"bank"`).
+* @param shard - The shard key within the collection (e.g. `"en/animals"`).
+* @returns The `outDir`-relative file path (e.g. `bank/en/animals.json`).
+* @example
+* ```ts
+* relativeShardFile("bank", "en/animals"); // "bank/en/animals.json"
+* relativeShardFile("bank", "a%20%26%20b"); // "bank/a & b.json"
+* ```
+*/
+function relativeShardFile(collection, shard) {
+	return decodeSuffix(shardSuffix(collection, shard));
+}
+//#endregion
+export { relativeShardFile as n, collectionUrl as t };

package/dist/{convention-BpDfzX7e.cjs → convention-CLIDd9k-.cjs}

@@ -1,34 +1,3 @@
-//#region \0rolldown/runtime.js
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __exportAll = (all, no_symbols) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
-	return target;
-};
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-		});
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-//#endregion
 //#region src/plugins/data/convention.ts
 /**
 * @file data plugin — the pure URL/file convention (no `node:*`, no DOM).
@@ -102,18 +71,6 @@ function relativeDataFile(outputDir, path) {
 	return `${outputDir.endsWith("/") ? outputDir.slice(0, -1) : outputDir}/${decodeSuffix(dataSuffix(path))}`;
 }
 //#endregion
-Object.defineProperty(exports, "__exportAll", {
-	enumerable: true,
-	get: function() {
-		return __exportAll;
-	}
-});
-Object.defineProperty(exports, "__toESM", {
-	enumerable: true,
-	get: function() {
-		return __toESM;
-	}
-});
 Object.defineProperty(exports, "dataSuffix", {
 	enumerable: true,
 	get: function() {

package/dist/convention-CsJw7CML.cjs

@@ -0,0 +1,120 @@
+//#region src/plugins/collection/convention.ts
+/**
+* @file collection plugin — the pure URL/file convention (no `node:*`, no DOM).
+*
+* ONE function maps a `(collection, shard)` key to its shard suffix, so the browser
+* fetch URL (`baseUrl + suffix`) and the on-disk file (`outDir + "/" + suffix`) are
+* derived from the same source and cannot drift. The collection name is the top
+* directory and the shard becomes a `.json` file beneath it (its INTERNAL slashes
+* are kept as nested dirs):
+*   ("bank", "en/animals") → "bank/en/animals.json"
+*   ("bank", "ru")         → "bank/ru.json"
+*   ("/bank/", "/en/")     → "bank/en.json"  (outer slashes trimmed)
+*
+* Encoding split: the FETCH suffix ({@link shardSuffix}) keeps the key's
+* percent-encoding (the browser requests the encoded path); the FILE path
+* ({@link relativeShardFile}) decodes it so the on-disk name is literal.
+*/
+/**
+* Strip leading/trailing slashes from `collection` and `shard` (keeping the
+* shard's INTERNAL slashes as nested path segments), then join them as
+* `` `${collection}/${shard}.json` `` — the suffix shared by the fetch URL and the
+* on-disk file.
+*
+* @param collection - The collection name (e.g. `"bank"`).
+* @param shard - The shard key within the collection (e.g. `"en/animals"`).
+* @returns The shard suffix (e.g. `"bank/en/animals.json"`).
+* @example
+* ```ts
+* shardSuffix("bank", "en/animals"); // "bank/en/animals.json"
+* shardSuffix("/bank/", "/ru/");     // "bank/ru.json"
+* ```
+*/
+function shardSuffix(collection, shard) {
+	return `${trimSlashes(collection)}/${trimSlashes(shard)}.json`;
+}
+/**
+* Strip any leading and trailing slashes from a path segment, leaving its internal
+* slashes intact.
+*
+* @param segment - The raw `collection` or `shard` value.
+* @returns The segment without outer slashes.
+* @example
+* ```ts
+* trimSlashes("/en/animals/"); // "en/animals"
+* ```
+*/
+function trimSlashes(segment) {
+	let trimmed = segment;
+	while (trimmed.startsWith("/")) trimmed = trimmed.slice(1);
+	while (trimmed.endsWith("/")) trimmed = trimmed.slice(0, -1);
+	return trimmed;
+}
+/**
+* Compute the browser fetch URL for a `(collection, shard)` key: the `baseUrl`
+* prefix joined with the {@link shardSuffix}. Exported so standalone consumers can
+* derive the same URL without composing the plugin.
+*
+* @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 site-root-relative shard URL (e.g. `/bank/en/animals.json`).
+* @example
+* ```ts
+* collectionUrl("/", "bank", "en/animals"); // "/bank/en/animals.json"
+* ```
+*/
+function collectionUrl(baseUrl, collection, shard) {
+	return `${baseUrl}${shardSuffix(collection, shard)}`;
+}
+/**
+* Decode a shard suffix's percent-escapes so the on-disk file carries the literal
+* name (servers decode the encoded fetch URL before filesystem lookup). Falls back
+* to the raw suffix on malformed escapes.
+*
+* @param suffix - The computed shard suffix (possibly percent-encoded).
+* @returns The decoded suffix, or the raw suffix on malformed escapes.
+* @example
+* ```ts
+* decodeSuffix("bank/en/a%20%26%20b.json"); // "bank/en/a & b.json"
+* ```
+*/
+function decodeSuffix(suffix) {
+	try {
+		return decodeURIComponent(suffix);
+	} catch {
+		return suffix;
+	}
+}
+/**
+* Compute the `outDir`-relative shard file for a `(collection, shard)` key — the
+* DECODED {@link shardSuffix} (servers resolve the decoded request path against
+* literal file names). The collection name IS the top directory, so there is no
+* extra output-dir wrapper. Shared by the Node writer and the pure `fileFor`
+* accessor so the written file and the reported path never drift.
+*
+* @param collection - The collection name (e.g. `"bank"`).
+* @param shard - The shard key within the collection (e.g. `"en/animals"`).
+* @returns The `outDir`-relative file path (e.g. `bank/en/animals.json`).
+* @example
+* ```ts
+* relativeShardFile("bank", "en/animals"); // "bank/en/animals.json"
+* relativeShardFile("bank", "a%20%26%20b"); // "bank/a & b.json"
+* ```
+*/
+function relativeShardFile(collection, shard) {
+	return decodeSuffix(shardSuffix(collection, shard));
+}
+//#endregion
+Object.defineProperty(exports, "collectionUrl", {
+	enumerable: true,
+	get: function() {
+		return collectionUrl;
+	}
+});
+Object.defineProperty(exports, "relativeShardFile", {
+	enumerable: true,
+	get: function() {
+		return relativeShardFile;
+	}
+});