@moku-labs/web 2.4.14 → 2.4.16

package/dist/index.d.cts

@@ -914,9 +914,55 @@ type Api$4 = {
    */
   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$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 };
+  export { AnyVNode, ExtractApi$1 as 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). */
@@ -1024,6 +1070,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 {
@@ -1039,6 +1091,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:
@@ -1450,6 +1504,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 = {
@@ -3491,12 +3550,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;
 }

package/dist/index.d.mts

@@ -912,9 +912,55 @@ type Api$4 = {
    */
   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$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 };
+  export { AnyVNode, ExtractApi$1 as 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). */
@@ -1022,6 +1068,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 {
@@ -1037,6 +1089,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:
@@ -1448,6 +1502,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 = {
@@ -3489,12 +3548,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;
 }