@jskit-ai/kernel 0.1.86 → 0.1.88

package/client/asyncModuleRecovery.d.ts

@@ -0,0 +1,53 @@
+export type AsyncModuleRecoveryState = {
+  attempt: number;
+  error: any;
+  label: string;
+  message: string;
+  retry: (() => any) | null;
+  stale: boolean;
+  visible: boolean;
+};
+
+export function createAsyncModuleRecoveryState(options?: {
+  label?: string;
+  message?: string;
+  retry?: (() => any) | null;
+}): AsyncModuleRecoveryState;
+
+export function isDynamicImportError(error?: any): boolean;
+
+export function dynamicImportErrorMessage(error?: any, options?: {
+  label?: string;
+  stale?: boolean;
+}): string;
+
+export function notifyAsyncModuleLoadError(
+  state: AsyncModuleRecoveryState,
+  error?: any,
+  options?: {
+    label?: string;
+    message?: string;
+    retry?: (() => any) | null;
+    stale?: boolean;
+  }
+): AsyncModuleRecoveryState;
+
+export function dismissAsyncModuleRecovery(state: AsyncModuleRecoveryState): boolean;
+
+export function guardedReloadApp(options?: {
+  browserWindow?: any;
+  fetchFn?: ((input: string, init?: Record<string, any>) => Promise<any>) | null;
+  state?: AsyncModuleRecoveryState | null;
+  label?: string;
+  message?: string;
+}): Promise<boolean>;
+
+export function installAsyncModuleRecoveryHandlers(options?: {
+  router?: any;
+  state: AsyncModuleRecoveryState;
+  label?: string;
+  onNotify?: (state: AsyncModuleRecoveryState) => void;
+  windowObject?: any;
+}): Readonly<{
+  dispose: () => void;
+}>;

package/client/asyncModuleRecovery.js

@@ -0,0 +1,196 @@
+const DYNAMIC_IMPORT_ERROR_PATTERNS = Object.freeze([
+  /ChunkLoadError/iu,
+  /Failed to fetch dynamically imported module/iu,
+  /Importing a module script failed/iu,
+  /error loading dynamically imported module/iu,
+  /Loading chunk .+ failed/iu,
+  /Unable to preload CSS/iu
+]);
+
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+
+function errorText(error = null) {
+  return String(error?.message || error || "").trim();
+}
+
+function isDynamicImportError(error = null) {
+  const text = errorText(error);
+  return Boolean(text && DYNAMIC_IMPORT_ERROR_PATTERNS.some((pattern) => pattern.test(text)));
+}
+
+function dynamicImportErrorMessage(error = null, {
+  label = "App module",
+  stale = isDynamicImportError(error)
+} = {}) {
+  const moduleLabel = String(label || "App module").trim();
+  if (stale) {
+    return `${moduleLabel} did not download. The app may have been updated, or the network request failed.`;
+  }
+  return `${moduleLabel} could not load.`;
+}
+
+function createAsyncModuleRecoveryState({
+  label = "App module",
+  message = "",
+  retry = null
+} = {}) {
+  return {
+    attempt: 0,
+    error: null,
+    label: String(label || "App module").trim(),
+    message: String(message || "").trim(),
+    retry: typeof retry === "function" ? retry : null,
+    stale: false,
+    visible: false
+  };
+}
+
+function notifyAsyncModuleLoadError(state, error = null, {
+  label = "App module",
+  message = "",
+  retry = null,
+  stale = isDynamicImportError(error)
+} = {}) {
+  if (!isRecord(state)) {
+    throw new TypeError("notifyAsyncModuleLoadError requires a mutable recovery state object.");
+  }
+
+  const normalizedLabel = String(label || "App module").trim();
+  state.attempt = Number(state.attempt || 0) + 1;
+  state.error = error || null;
+  state.label = normalizedLabel;
+  state.message = String(message || "").trim() ||
+    dynamicImportErrorMessage(error, {
+      label: normalizedLabel,
+      stale
+    });
+  state.retry = typeof retry === "function" ? retry : null;
+  state.stale = Boolean(stale);
+  state.visible = true;
+  return state;
+}
+
+function dismissAsyncModuleRecovery(state) {
+  if (!isRecord(state)) {
+    return false;
+  }
+
+  state.visible = false;
+  return true;
+}
+
+async function guardedReloadApp({
+  browserWindow = typeof window !== "undefined" ? window : null,
+  fetchFn = typeof fetch === "function" ? fetch : null,
+  state = null,
+  label = "App",
+  message = "The app cannot reload because the app server is not reachable. Restart the server, then click Retry or Reload."
+} = {}) {
+  if (!browserWindow?.location) {
+    return false;
+  }
+  if (typeof fetchFn !== "function") {
+    browserWindow.location.reload();
+    return true;
+  }
+
+  try {
+    const response = await fetchFn(String(browserWindow.location.href || "/"), {
+      cache: "no-store",
+      credentials: "same-origin",
+      headers: {
+        Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
+      },
+      method: "GET"
+    });
+    if (!response?.ok) {
+      throw new Error(`Reload check failed with HTTP ${response?.status || 0}.`);
+    }
+    browserWindow.location.reload();
+    return true;
+  } catch (error) {
+    if (state) {
+      notifyAsyncModuleLoadError(state, error, {
+        label,
+        message,
+        retry: state.retry,
+        stale: false
+      });
+    }
+    return false;
+  }
+}
+
+function installAsyncModuleRecoveryHandlers({
+  router = null,
+  state,
+  label = "App module",
+  onNotify = null,
+  windowObject = typeof window !== "undefined" ? window : null
+} = {}) {
+  if (!isRecord(state)) {
+    throw new TypeError("installAsyncModuleRecoveryHandlers requires a mutable recovery state object.");
+  }
+
+  const disposers = [];
+  const notify = typeof onNotify === "function" ? onNotify : () => null;
+
+  if (router && typeof router.onError === "function") {
+    const removeRouterHandler = router.onError((error, to = {}) => {
+      if (!isDynamicImportError(error)) {
+        return;
+      }
+
+      const fullPath = String(to?.fullPath || "");
+      notifyAsyncModuleLoadError(state, error, {
+        label: "Page",
+        retry: fullPath && typeof router.replace === "function"
+          ? () => router.replace(fullPath)
+          : null,
+        stale: true
+      });
+      notify(state);
+    });
+    if (typeof removeRouterHandler === "function") {
+      disposers.push(removeRouterHandler);
+    }
+  }
+
+  if (windowObject && typeof windowObject.addEventListener === "function") {
+    const handler = (event) => {
+      const error = event?.reason;
+      if (!isDynamicImportError(error)) {
+        return;
+      }
+      notifyAsyncModuleLoadError(state, error, {
+        label,
+        stale: true
+      });
+      notify(state);
+    };
+    windowObject.addEventListener("unhandledrejection", handler);
+    disposers.push(() => {
+      windowObject.removeEventListener?.("unhandledrejection", handler);
+    });
+  }
+
+  return Object.freeze({
+    dispose() {
+      for (const dispose of disposers.splice(0)) {
+        dispose();
+      }
+    }
+  });
+}
+
+export {
+  createAsyncModuleRecoveryState,
+  dismissAsyncModuleRecovery,
+  dynamicImportErrorMessage,
+  guardedReloadApp,
+  installAsyncModuleRecoveryHandlers,
+  isDynamicImportError,
+  notifyAsyncModuleLoadError
+};

package/client/asyncModuleRecovery.test.js

@@ -0,0 +1,185 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  createAsyncModuleRecoveryState,
+  dismissAsyncModuleRecovery,
+  dynamicImportErrorMessage,
+  guardedReloadApp,
+  installAsyncModuleRecoveryHandlers,
+  isDynamicImportError,
+  notifyAsyncModuleLoadError
+} from "./asyncModuleRecovery.js";
+
+function createWindowDouble() {
+  const listeners = new Map();
+  return {
+    listeners,
+    addEventListener(type, handler) {
+      listeners.set(type, handler);
+    },
+    removeEventListener(type, handler) {
+      if (listeners.get(type) === handler) {
+        listeners.delete(type);
+      }
+    }
+  };
+}
+
+test("async module recovery recognizes dynamic import failures only", () => {
+  assert.equal(
+    isDynamicImportError(new Error("Failed to fetch dynamically imported module: /assets/page.js")),
+    true
+  );
+  assert.equal(isDynamicImportError(new Error("Loading chunk dashboard failed")), true);
+  assert.equal(isDynamicImportError(new Error("Request failed.")), false);
+});
+
+test("async module recovery mutates state with an actionable retry", () => {
+  const retry = () => "retried";
+  const state = createAsyncModuleRecoveryState();
+  const error = new Error("Failed to fetch dynamically imported module: /assets/tool.js");
+
+  notifyAsyncModuleLoadError(state, error, {
+    label: "Tool",
+    retry
+  });
+
+  assert.equal(state.visible, true);
+  assert.equal(state.attempt, 1);
+  assert.equal(state.label, "Tool");
+  assert.equal(state.message, "Tool did not download. The app may have been updated, or the network request failed.");
+  assert.equal(state.retry, retry);
+  assert.equal(state.stale, true);
+
+  assert.equal(dismissAsyncModuleRecovery(state), true);
+  assert.equal(state.visible, false);
+});
+
+test("async module recovery message stays generic for non-stale failures", () => {
+  assert.equal(
+    dynamicImportErrorMessage(new Error("boom"), {
+      label: "Widget",
+      stale: false
+    }),
+    "Widget could not load."
+  );
+});
+
+test("async module recovery installs router and unhandled rejection handlers", async () => {
+  let routerHandler = null;
+  const replaced = [];
+  const notifications = [];
+  const windowObject = createWindowDouble();
+  const state = createAsyncModuleRecoveryState();
+  const disposable = installAsyncModuleRecoveryHandlers({
+    state,
+    label: "Runtime module",
+    onNotify(nextState) {
+      notifications.push({
+        attempt: nextState.attempt,
+        label: nextState.label
+      });
+    },
+    windowObject,
+    router: {
+      onError(handler) {
+        routerHandler = handler;
+        return () => {
+          routerHandler = null;
+        };
+      },
+      replace(fullPath) {
+        replaced.push(fullPath);
+      }
+    }
+  });
+
+  routerHandler(new Error("Failed to fetch dynamically imported module: /assets/page.js"), {
+    fullPath: "/app/home"
+  });
+
+  assert.equal(state.label, "Page");
+  assert.deepEqual(notifications[0], {
+    attempt: 1,
+    label: "Page"
+  });
+  assert.equal(typeof state.retry, "function");
+  await state.retry();
+  assert.deepEqual(replaced, ["/app/home"]);
+
+  windowObject.listeners.get("unhandledrejection")({
+    reason: new Error("Importing a module script failed.")
+  });
+  assert.equal(state.label, "Runtime module");
+  assert.deepEqual(notifications[1], {
+    attempt: 2,
+    label: "Runtime module"
+  });
+
+  disposable.dispose();
+  assert.equal(routerHandler, null);
+  assert.equal(windowObject.listeners.has("unhandledrejection"), false);
+});
+
+test("guarded reload navigates only after the current document is reachable", async () => {
+  const reloadCalls = [];
+  const fetchCalls = [];
+  const result = await guardedReloadApp({
+    browserWindow: {
+      location: {
+        href: "https://example.test/app",
+        reload() {
+          reloadCalls.push("reload");
+        }
+      }
+    },
+    async fetchFn(input, init) {
+      fetchCalls.push({ input, init });
+      return {
+        ok: true,
+        status: 200
+      };
+    }
+  });
+
+  assert.equal(result, true);
+  assert.deepEqual(reloadCalls, ["reload"]);
+  assert.equal(fetchCalls[0].input, "https://example.test/app");
+  assert.equal(fetchCalls[0].init.cache, "no-store");
+  assert.equal(fetchCalls[0].init.credentials, "same-origin");
+});
+
+test("guarded reload keeps the page alive when the server is unreachable", async () => {
+  const state = createAsyncModuleRecoveryState();
+  const retry = () => null;
+  notifyAsyncModuleLoadError(state, new Error("Failed to fetch dynamically imported module: /assets/tool.js"), {
+    label: "Tool",
+    retry
+  });
+
+  const reloadCalls = [];
+  const result = await guardedReloadApp({
+    state,
+    label: "App",
+    message: "App cannot reload yet.",
+    browserWindow: {
+      location: {
+        href: "https://example.test/app",
+        reload() {
+          reloadCalls.push("reload");
+        }
+      }
+    },
+    async fetchFn() {
+      throw new TypeError("Failed to fetch");
+    }
+  });
+
+  assert.equal(result, false);
+  assert.deepEqual(reloadCalls, []);
+  assert.equal(state.visible, true);
+  assert.equal(state.label, "App");
+  assert.equal(state.message, "App cannot reload yet.");
+  assert.equal(state.retry, retry);
+  assert.equal(state.stale, false);
+});

package/client/index.d.ts

@@ -6,6 +6,60 @@ export type ClientLogger = {
   isDebugEnabled?: boolean;
 };
 
+export type AsyncModuleRecoveryState = {
+  attempt: number;
+  error: any;
+  label: string;
+  message: string;
+  retry: (() => any) | null;
+  stale: boolean;
+  visible: boolean;
+};
+
+export function createAsyncModuleRecoveryState(options?: {
+  label?: string;
+  message?: string;
+  retry?: (() => any) | null;
+}): AsyncModuleRecoveryState;
+
+export function isDynamicImportError(error?: any): boolean;
+
+export function dynamicImportErrorMessage(error?: any, options?: {
+  label?: string;
+  stale?: boolean;
+}): string;
+
+export function notifyAsyncModuleLoadError(
+  state: AsyncModuleRecoveryState,
+  error?: any,
+  options?: {
+    label?: string;
+    message?: string;
+    retry?: (() => any) | null;
+    stale?: boolean;
+  }
+): AsyncModuleRecoveryState;
+
+export function dismissAsyncModuleRecovery(state: AsyncModuleRecoveryState): boolean;
+
+export function guardedReloadApp(options?: {
+  browserWindow?: any;
+  fetchFn?: ((input: string, init?: Record<string, any>) => Promise<any>) | null;
+  state?: AsyncModuleRecoveryState | null;
+  label?: string;
+  message?: string;
+}): Promise<boolean>;
+
+export function installAsyncModuleRecoveryHandlers(options?: {
+  router?: any;
+  state: AsyncModuleRecoveryState;
+  label?: string;
+  onNotify?: (state: AsyncModuleRecoveryState) => void;
+  windowObject?: any;
+}): Readonly<{
+  dispose: () => void;
+}>;
+
 export function getClientAppConfig(): Readonly<Record<string, any>>;
 export function resolveMobileConfig(appConfig?: Record<string, any>): Readonly<Record<string, any>>;
 export function resolveClientAssetMode(appConfig?: Record<string, any>): string;

package/client/index.js

@@ -1,4 +1,13 @@
 export { getClientAppConfig, resolveMobileConfig, resolveClientAssetMode } from "./appConfig.js";
+export {
+  createAsyncModuleRecoveryState,
+  dismissAsyncModuleRecovery,
+  dynamicImportErrorMessage,
+  guardedReloadApp,
+  installAsyncModuleRecoveryHandlers,
+  isDynamicImportError,
+  notifyAsyncModuleLoadError
+} from "./asyncModuleRecovery.js";
 export { normalizeIncomingAppUrl, registerMobileLaunchRouting } from "./mobileLaunchRouting.js";
 export { resolveClientBootstrapDebugEnabled, createSurfaceShellRouter as createShellRouter, bootstrapClientShellApp } from "./shellBootstrap.js";
 export { createComponentInteractionEmitter } from "./componentInteraction.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.86",
+  "version": "0.1.88",
   "type": "module",
   "dependencies": {
     "json-rest-schema": "1.x.x"
@@ -14,6 +14,10 @@
       "types": "./client/index.d.ts",
       "default": "./client/index.js"
     },
+    "./client/asyncModuleRecovery": {
+      "types": "./client/asyncModuleRecovery.d.ts",
+      "default": "./client/asyncModuleRecovery.js"
+    },
     "./client/pageRedirects": {
       "types": "./client/pageRedirects.d.ts",
       "default": "./client/pageRedirects.js"

package/test/barrelExposure.test.js

@@ -82,10 +82,17 @@ const BARREL_EXPECTATIONS = Object.freeze([
     expectedExports: Object.freeze([
       "bootstrapClientShellApp",
       "createComponentInteractionEmitter",
+      "createAsyncModuleRecoveryState",
       "createShellRouter",
+      "dismissAsyncModuleRecovery",
+      "dynamicImportErrorMessage",
       "resolveClientAssetMode",
+      "guardedReloadApp",
       "getClientAppConfig",
+      "installAsyncModuleRecoveryHandlers",
+      "isDynamicImportError",
       "normalizeIncomingAppUrl",
+      "notifyAsyncModuleLoadError",
       "registerMobileLaunchRouting",
       "resolveMobileConfig",
       "resolveClientBootstrapDebugEnabled"