@moku-labs/web 2.4.14 → 2.4.16

package/README.md

@@ -225,6 +225,8 @@ Importing `@moku-labs/web/browser` can **never** drag node/native code into a cl
 bun run check:bundle   # asserts: zero static node/native imports + under the gzip budget
 ```
 
+The shipped `browser.mjs` has no JSDoc comments. This keeps it under the budget. `browser.d.mts` keeps them, so your editor still shows the docs.
+
 ## The route is the contract
 
 A route is a fluent builder. Each step is optional except `render`, and every type flows from it:

package/dist/browser.d.mts

@@ -913,9 +913,55 @@ type Api$1 = {
    */
   composeTitle(head: HeadConfig | undefined): string;
 };
+//#endregion
+//#region src/plugins/spa/prefetch.d.ts
+/** The live preloader the kernel keeps on `state.prefetch`. */
+interface Prefetcher {
+  /**
+   * Take the preload for `path` and remove it: one use only. Undefined on a miss or an
+   * entry older than 30 s.
+   *
+   * @param path - The page path (pathname + search).
+   * @returns The pending or settled page HTML, or `undefined`.
+   * @example
+   * // A navigation to /en/about/ right after a pointerdown on its link:
+   * state.prefetch?.take("/en/about/"); // Promise<string>; a second take returns undefined
+   */
+  take(path: string): Promise<string> | undefined;
+  /**
+   * Re-observe every eligible `a[href]` in the document. `"visible"` only; a no-op for
+   * `"intent"`. The kernel calls it at boot and after every swap.
+   *
+   * @example
+   * // After a swap mounted the new page's islands, watch the new page's links:
+   * state.prefetch?.observe();
+   */
+  observe(): void;
+  /**
+   * Remove the listeners, disconnect the observer, clear timers and idle callbacks, abort
+   * in-flight preloads, empty the map. Idempotent.
+   *
+   * @example
+   * // kernel.dispose() on app.stop(): no preload listener stays on document
+   * state.prefetch?.dispose();
+   * state.prefetch = null;
+   */
+  dispose(): void;
+}
 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 };
+  export { AnyVNode, ExtractApi, ISLAND_HOOK_NAMES, IslandContext, IslandDef, IslandEventHandler, IslandEvents, IslandHooks, IslandInstance, IslandRender, IslandRouteSlice, IslandSpec, IslandSpecExtras, IslandStateFactory, NavigateOptions, PageData, PrefetchMode, RenderResult, ResolvedSpaConfig, ScrollMode, SpaApi, SpaConfig, SpaContext, SpaDataReader, SpaEmitFunction, SpaEvents, SpaKernel, SpaKernelDeps, SpaRequire, SpaState, TransitionMode };
 }
+/**
+ * When the spa preloads a linked page's HTML before the tap (`spa.prefetch`):
+ * - `false` — never; the page is fetched on click, as without the option;
+ * - `"intent"` — on `pointerdown` / `touchstart` at once, or after 65 ms of mouse hover;
+ * - `"visible"` — as `"intent"`, plus every link that enters the viewport, drained in idle
+ *   time with at most 2 preloads in flight.
+ *
+ * @example
+ * createApp({ pluginConfigs: { spa: { prefetch: "visible" } } });
+ */
+type PrefetchMode = false | "intent" | "visible";
 /** Per-navigation options for the programmatic navigators (`ctx.navigate` / `app.spa.navigate`). */
 interface NavigateOptions {
   /** Override the scroll behaviour for this single navigation (else the route/app default). */
@@ -1023,6 +1069,12 @@ type SpaConfig = {
    * Defaults to an empty array.
    */
   islands?: IslandDef[];
+  /**
+   * Preload a linked page's HTML before the tap, so the swap does not wait for the network.
+   * A preload is used once, lives 30 s, and is skipped with save-data on, on a 2G connection,
+   * and for a route the client DATA path renders. Defaults to `false` (fetch on click only).
+   */
+  prefetch?: PrefetchMode;
 };
 /** Resolved SPA config after defaults are applied. */
 interface ResolvedSpaConfig {
@@ -1038,6 +1090,8 @@ interface ResolvedSpaConfig {
   progressBar: boolean;
   /** Pre-registered islands. */
   islands: IslandDef[];
+  /** The validated preload mode (`false` ⇒ no preload listeners at all). */
+  prefetch: PrefetchMode;
 }
 /**
  * What a island's `render` may return:
@@ -1449,6 +1503,11 @@ interface SpaState {
   navigate: ((path: string, options?: NavigateOptions) => void) | null;
   /** The single shared SPA kernel instance (null until onInit builds it). */
   kernel: SpaKernel | null;
+  /**
+   * The live HTML preloader, built by `kernel.boot()` when `spa.prefetch` is not `false`.
+   * Null before boot, after stop or `hardNavigate`, and when the mode is `false`.
+   */
+  prefetch: Prefetcher | null;
 }
 /** Public API of the spa plugin (registration / control surface). */
 type SpaApi = {
@@ -2022,12 +2081,6 @@ interface DataState {
    * the fetch settles, on success and on failure, so a failure is never cached.
    */
   pending: Map<string, Promise<unknown | null>>;
-  /**
-   * The preload bundle fetch while it is in flight (browser, `preload: "all"`).
-   * `at()` awaits it before fetching a single file. Never rejects. `null` when no
-   * bundle fetch is running.
-   */
-  bundle: Promise<void> | null;
   /** Cancels the scheduled idle callback or aborts the bundle fetch. `null` when nothing is scheduled. */
   cancelPreload: (() => void) | null;
 }