@moku-labs/web 2.2.2 → 2.3.0

package/dist/index.d.cts

@@ -278,7 +278,7 @@ interface PathMatcher {
     };
   } | null;
 }
-declare namespace types_d_exports$6 {
+declare namespace types_d_exports$7 {
   export { Api$5 as Api, ClientRoute, CompileInput, CompiledRoute, Config$5 as Config, ExtractApi$2 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$5 as State, TransitionMode, TypedRoute, Urls };
 }
 /**
@@ -739,7 +739,7 @@ type Config$5 = RouterConfig;
 type State$5 = RouterState;
 /** Re-export under the canonical `Api` name for the plugin-types barrel. */
 type Api$5 = RouterApi;
-declare namespace types_d_exports$5 {
+declare namespace types_d_exports$6 {
   export { Api$4 as Api, ArticleMeta, Config$4 as Config, HeadConfig, HeadDefaults, HeadElement, ResolvedRoute, State$4 as State };
 }
 /**
@@ -914,7 +914,7 @@ type Api$4 = {
    */
   composeTitle(head: HeadConfig | undefined): string;
 };
-declare namespace types_d_exports$7 {
+declare namespace types_d_exports$8 {
   export { AnyVNode, ExtractApi$1 as 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`). */
@@ -1956,7 +1956,7 @@ declare const buildPlugin: import("@moku-labs/core").PluginInstance<"build", Con
  * const trigger: WorkflowTrigger = "versioned-tag";
  */
 type WorkflowTrigger = "auto" | "versioned-tag" | "dispatch";
-declare namespace types_d_exports$4 {
+declare namespace types_d_exports$5 {
   export { Api$2 as Api, Config$2 as Config, CreateProjectResult, DeployErrorCode, DeployInitOptions, DeployResult, DeployRunOptions, InitResult, SpawnFunction, SpawnOptions, SpawnedProcess, State$2 as State, WorkflowTrigger, WranglerErrorKind };
 }
 /**
@@ -2736,6 +2736,159 @@ type Api$1 = {
  */
 declare const cliPlugin: import("@moku-labs/core").PluginInstance<"cli", Config$1, State$1, Api$1, {}> & Record<never, never>;
 declare namespace types_d_exports$2 {
+  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/plugins/collection/index.d.ts
+/**
+ * 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
+ * ```
+ */
+declare const collectionPlugin: import("@moku-labs/core").PluginInstance<"collection", CollectionConfig, CollectionState, CollectionProvider, {}> & Record<never, never>;
+declare namespace types_d_exports$3 {
   export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, EmbedFacade, EmbedFacadeProps, EmbedOptions, FileSystemContentOptions, Frontmatter, GalleryComponent, GalleryOptions, GalleryProps, GallerySlide, GalleryTransformOptions, LoadAllOptions, MermaidDiagramOptions, State };
 }
 /**
@@ -3234,7 +3387,7 @@ declare const contentPlugin: import("@moku-labs/core").PluginInstance<"content",
     paths: readonly string[];
   };
 }> & Record<never, never>;
-declare namespace types_d_exports$3 {
+declare namespace types_d_exports$4 {
   export { DataConfig, DataEntry, DataProvider, DataState, DataWriteSummary };
 }
 /**
@@ -3900,6 +4053,42 @@ declare function EmbedFacadeButton(props: EmbedFacadeProps): VNode;
  */
 declare function GalleryTrack(props: GalleryProps): VNode;
 //#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>;
+//#endregion
 //#region src/index.d.ts
 /**
  * Create and initialize a `@moku-labs/web` application — the Layer-3 entry point.
@@ -4006,4 +4195,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$8, 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 { types_d_exports as Build, type Channel, type ChannelKeepAlive, type ChannelOptions, type ChannelReconnect, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, type EmbedFacade, EmbedFacadeButton, type EmbedFacadeProps, type EmbedOptions, type Env, type GalleryComponent, type GalleryOptions, type GalleryProps, type GallerySlide, GalleryTrack, types_d_exports$5 as Head, type Log, types_d_exports$6 as Router, types_d_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_d_exports as Build, type Channel, type ChannelKeepAlive, type ChannelOptions, type ChannelReconnect, types_d_exports$1 as Cli, types_d_exports$2 as Collection, types_d_exports$3 as Content, types_d_exports$4 as Data, types_d_exports$5 as Deploy, type EmbedFacade, EmbedFacadeButton, type EmbedFacadeProps, type EmbedOptions, type Env, type GalleryComponent, type GalleryOptions, type GalleryProps, type GallerySlide, GalleryTrack, types_d_exports$6 as Head, type Log, types_d_exports$7 as Router, types_d_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/index.d.mts

@@ -276,7 +276,7 @@ interface PathMatcher {
     };
   } | null;
 }
-declare namespace types_d_exports$6 {
+declare namespace types_d_exports$7 {
   export { Api$5 as Api, ClientRoute, CompileInput, CompiledRoute, Config$5 as Config, ExtractApi$2 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$5 as State, TransitionMode, TypedRoute, Urls };
 }
 /**
@@ -737,7 +737,7 @@ type Config$5 = RouterConfig;
 type State$5 = RouterState;
 /** Re-export under the canonical `Api` name for the plugin-types barrel. */
 type Api$5 = RouterApi;
-declare namespace types_d_exports$5 {
+declare namespace types_d_exports$6 {
   export { Api$4 as Api, ArticleMeta, Config$4 as Config, HeadConfig, HeadDefaults, HeadElement, ResolvedRoute, State$4 as State };
 }
 /**
@@ -912,7 +912,7 @@ type Api$4 = {
    */
   composeTitle(head: HeadConfig | undefined): string;
 };
-declare namespace types_d_exports$7 {
+declare namespace types_d_exports$8 {
   export { AnyVNode, ExtractApi$1 as 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`). */
@@ -1954,7 +1954,7 @@ declare const buildPlugin: import("@moku-labs/core").PluginInstance<"build", Con
  * const trigger: WorkflowTrigger = "versioned-tag";
  */
 type WorkflowTrigger = "auto" | "versioned-tag" | "dispatch";
-declare namespace types_d_exports$4 {
+declare namespace types_d_exports$5 {
   export { Api$2 as Api, Config$2 as Config, CreateProjectResult, DeployErrorCode, DeployInitOptions, DeployResult, DeployRunOptions, InitResult, SpawnFunction, SpawnOptions, SpawnedProcess, State$2 as State, WorkflowTrigger, WranglerErrorKind };
 }
 /**
@@ -2734,6 +2734,159 @@ type Api$1 = {
  */
 declare const cliPlugin: import("@moku-labs/core").PluginInstance<"cli", Config$1, State$1, Api$1, {}> & Record<never, never>;
 declare namespace types_d_exports$2 {
+  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/plugins/collection/index.d.ts
+/**
+ * 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
+ * ```
+ */
+declare const collectionPlugin: import("@moku-labs/core").PluginInstance<"collection", CollectionConfig, CollectionState, CollectionProvider, {}> & Record<never, never>;
+declare namespace types_d_exports$3 {
   export { Api, Article, ArticleCard, ComputedFields, Config, ContentApiContext, ContentEvents, ContentProvider, ContentProviderState, EmbedFacade, EmbedFacadeProps, EmbedOptions, FileSystemContentOptions, Frontmatter, GalleryComponent, GalleryOptions, GalleryProps, GallerySlide, GalleryTransformOptions, LoadAllOptions, MermaidDiagramOptions, State };
 }
 /**
@@ -3232,7 +3385,7 @@ declare const contentPlugin: import("@moku-labs/core").PluginInstance<"content",
     paths: readonly string[];
   };
 }> & Record<never, never>;
-declare namespace types_d_exports$3 {
+declare namespace types_d_exports$4 {
   export { DataConfig, DataEntry, DataProvider, DataState, DataWriteSummary };
 }
 /**
@@ -3898,6 +4051,42 @@ declare function EmbedFacadeButton(props: EmbedFacadeProps): VNode;
  */
 declare function GalleryTrack(props: GalleryProps): VNode;
 //#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>;
+//#endregion
 //#region src/index.d.ts
 /**
  * Create and initialize a `@moku-labs/web` application — the Layer-3 entry point.
@@ -4004,4 +4193,4 @@ declare const createApp: <const ExtraPlugins extends readonly import("@moku-labs
  */
 declare const createPlugin: import("@moku-labs/core").BoundCreatePluginFunction<Config$8, 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 { types_d_exports as Build, type Channel, type ChannelKeepAlive, type ChannelOptions, type ChannelReconnect, types_d_exports$1 as Cli, types_d_exports$2 as Content, types_d_exports$3 as Data, types_d_exports$4 as Deploy, type EmbedFacade, EmbedFacadeButton, type EmbedFacadeProps, type EmbedOptions, type Env, type GalleryComponent, type GalleryOptions, type GalleryProps, type GallerySlide, GalleryTrack, types_d_exports$5 as Head, type Log, types_d_exports$6 as Router, types_d_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_d_exports as Build, type Channel, type ChannelKeepAlive, type ChannelOptions, type ChannelReconnect, types_d_exports$1 as Cli, types_d_exports$2 as Collection, types_d_exports$3 as Content, types_d_exports$4 as Data, types_d_exports$5 as Deploy, type EmbedFacade, EmbedFacadeButton, type EmbedFacadeProps, type EmbedOptions, type Env, type GalleryComponent, type GalleryOptions, type GalleryProps, type GallerySlide, GalleryTrack, types_d_exports$6 as Head, type Log, types_d_exports$7 as Router, types_d_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 };