@jskit-ai/shell-web 0.1.85 → 0.1.87

package/package.descriptor.mjs

@@ -1,14 +1,15 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/shell-web",
-  version: "0.1.85",
+  version: "0.1.87",
   kind: "runtime",
   description: "Web shell layout runtime with outlet-based placement contributions.",
   dependsOn: [],
   capabilities: {
     provides: [
       "runtime.web-placement",
-      "runtime.web-error"
+      "runtime.web-error",
+      "runtime.web-async-module-recovery"
     ],
     requires: []
   },
@@ -54,6 +55,8 @@ export default Object.freeze({
         client: [
           "runtime.web-placement.client",
           "runtime.web-bootstrap.client",
+          "runtime.web-refresh.client",
+          "runtime.web-async-module-recovery.client",
           "runtime.web-error.client",
           "runtime.web-error.presentation-store.client"
         ]
@@ -291,7 +294,7 @@ export default Object.freeze({
     dependencies: {
       runtime: {
         "@mdi/js": "^7.4.47",
-        "@jskit-ai/kernel": "0.1.86"
+        "@jskit-ai/kernel": "0.1.88"
       },
       dev: {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/shell-web",
-  "version": "0.1.85",
+  "version": "0.1.87",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -9,6 +9,7 @@
     "./client": "./src/client/index.js",
     "./client/error": "./src/client/error/index.js",
     "./client/placement": "./src/client/placement/index.js",
+    "./client/asyncModuleRecovery": "./src/client/asyncModuleRecovery/index.js",
     "./client/bootstrap": "./src/client/bootstrap/index.js",
     "./server/support/localLinkItemScaffolds": "./src/server/support/localLinkItemScaffolds.js",
     "./client/navigation/linkResolver": "./src/client/navigation/linkResolver.js",
@@ -26,7 +27,7 @@
   },
   "dependencies": {
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/kernel": "0.1.86"
+    "@jskit-ai/kernel": "0.1.88"
   },
   "peerDependencies": {
     "pinia": "^3.0.4",

package/src/client/asyncModuleRecovery/index.js

@@ -0,0 +1,4 @@
+export {
+  SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY,
+  useShellAsyncModuleRecoveryRuntime
+} from "./inject.js";

package/src/client/asyncModuleRecovery/inject.js

@@ -0,0 +1,30 @@
+import {
+  hasInjectionContext,
+  inject
+} from "vue";
+
+const SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY =
+  "jskit.shell-web.runtime.web-async-module-recovery.client";
+
+function isShellAsyncModuleRecoveryRuntime(value) {
+  return Boolean(
+    value &&
+      typeof value.notify === "function" &&
+      typeof value.reload === "function"
+  );
+}
+
+function useShellAsyncModuleRecoveryRuntime() {
+  if (!hasInjectionContext()) {
+    return null;
+  }
+
+  const runtime = inject(SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY, null);
+  return isShellAsyncModuleRecoveryRuntime(runtime) ? runtime : null;
+}
+
+export {
+  SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY,
+  isShellAsyncModuleRecoveryRuntime,
+  useShellAsyncModuleRecoveryRuntime
+};

package/src/client/index.js

@@ -17,6 +17,10 @@ export { default as ShellTabLinkItem } from "./components/ShellTabLinkItem.vue";
 export { useShellLayoutState } from "./composables/useShellLayoutState.js";
 export { useShellLayoutStore } from "./stores/useShellLayoutStore.js";
 export { useShellErrorPresentationStore } from "./stores/useShellErrorPresentationStore.js";
+export {
+  SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY,
+  useShellAsyncModuleRecoveryRuntime
+} from "./asyncModuleRecovery/index.js";
 export {
   BOOTSTRAP_PAYLOAD_HANDLER_TAG,
   registerBootstrapPayloadHandler,

package/src/client/providers/ShellWebClientProvider.js

@@ -1,4 +1,18 @@
 import { getClientAppConfig } from "@jskit-ai/kernel/client";
+import {
+  createAsyncModuleRecoveryState,
+  guardedReloadApp,
+  installAsyncModuleRecoveryHandlers,
+  isDynamicImportError,
+  notifyAsyncModuleLoadError
+} from "@jskit-ai/kernel/client/asyncModuleRecovery";
+import {
+  isMissingDynamicModule,
+  notifyDynamicImportFailure
+} from "./appModuleLoadFailure.js";
+import {
+  SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY
+} from "../asyncModuleRecovery/inject.js";
 import {
   isRecord
 } from "@jskit-ai/kernel/shared/support";
@@ -29,18 +43,10 @@ import { resolveBootstrapErrorStatusCode } from "../bootstrap/bootstrapErrorStat
 const APP_PLACEMENT_MODULE_SPECIFIER = "/src/placement.js";
 const APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER = "/src/placementTopology.js";
 const APP_ERROR_MODULE_SPECIFIER = "/src/error.js";
+const ASYNC_MODULE_RELOAD_FAILURE_MESSAGE =
+  "The app cannot reload because the app server is not reachable. Restart the server, then click Reload.";
 
-function isMissingDynamicModule(error, moduleSpecifier) {
-  const message = String(error?.message || error || "");
-  return (
-    message.includes(moduleSpecifier) &&
-    (message.includes("Cannot find module") ||
-      message.includes("Failed to fetch dynamically imported module") ||
-      message.includes("ERR_MODULE_NOT_FOUND"))
-  );
-}
-
-async function loadAppPlacementDefinitions(logger) {
+async function loadAppPlacementDefinitions(logger, asyncModuleRecoveryRuntime = null) {
   try {
     const moduleNamespace = await import("/src/placement.js");
     const exported = moduleNamespace?.default;
@@ -60,6 +66,9 @@ async function loadAppPlacementDefinitions(logger) {
     if (isMissingDynamicModule(error, APP_PLACEMENT_MODULE_SPECIFIER)) {
       return [];
     }
+    notifyDynamicImportFailure(asyncModuleRecoveryRuntime, error, {
+      label: "Placement config"
+    });
 
     logger.warn(
       {
@@ -73,7 +82,7 @@ async function loadAppPlacementDefinitions(logger) {
   return [];
 }
 
-async function loadAppPlacementTopology(logger) {
+async function loadAppPlacementTopology(logger, asyncModuleRecoveryRuntime = null) {
   try {
     const moduleNamespace = await import("/src/placementTopology.js");
     const exported = moduleNamespace?.default;
@@ -82,6 +91,9 @@ async function loadAppPlacementTopology(logger) {
     if (isMissingDynamicModule(error, APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER)) {
       return [];
     }
+    notifyDynamicImportFailure(asyncModuleRecoveryRuntime, error, {
+      label: "Placement topology"
+    });
 
     logger.warn(
       {
@@ -127,7 +139,7 @@ function createErrorConfigToolkit(errorRuntime) {
   });
 }
 
-async function loadAppErrorConfig(logger, errorRuntime) {
+async function loadAppErrorConfig(logger, errorRuntime, asyncModuleRecoveryRuntime = null) {
   try {
     const moduleNamespace = await import("/src/error.js");
     const exported = moduleNamespace?.default;
@@ -149,6 +161,9 @@ async function loadAppErrorConfig(logger, errorRuntime) {
     if (isMissingDynamicModule(error, APP_ERROR_MODULE_SPECIFIER)) {
       return {};
     }
+    notifyDynamicImportFailure(asyncModuleRecoveryRuntime, error, {
+      label: "Error config"
+    });
 
     logger.warn(
       {
@@ -362,6 +377,10 @@ function installRouterErrorBridge(app, errorRuntime, logger) {
   }
 
   router.onError((error) => {
+    if (isDynamicImportError(error)) {
+      return;
+    }
+
     try {
       errorRuntime.report({
         source: "shell-web.router.on-error",
@@ -384,6 +403,121 @@ function installRouterErrorBridge(app, errorRuntime, logger) {
   });
 }
 
+function createShellAsyncModuleRecoveryRuntime({
+  app,
+  logger = null
+} = {}) {
+  if (!app || typeof app.has !== "function" || typeof app.make !== "function") {
+    throw new Error("createShellAsyncModuleRecoveryRuntime requires application has()/make().");
+  }
+
+  const runtimeLogger = logger || createSharedProviderLogger(app);
+  const state = createAsyncModuleRecoveryState();
+  let installedRecovery = null;
+
+  function errorRuntime() {
+    if (!app.has("runtime.web-error.client")) {
+      return null;
+    }
+    const runtime = app.make("runtime.web-error.client");
+    return runtime && typeof runtime.report === "function" ? runtime : null;
+  }
+
+  function report(nextState = state) {
+    const runtime = errorRuntime();
+    if (!runtime) {
+      runtimeLogger.warn(
+        {
+          label: String(nextState?.label || "")
+        },
+        "Async module recovery could not report because the shell error runtime is unavailable."
+      );
+      return null;
+    }
+
+    try {
+      return runtime.report({
+        source: "shell-web.async-module-recovery",
+        message: String(nextState?.message || "A required app module could not load."),
+        cause: nextState?.error || null,
+        intent: "app-recoverable",
+        severity: "warning",
+        dedupeKey: `shell-web.async-module-recovery.${Number(nextState?.attempt || 0)}`,
+        action: {
+          label: "Reload",
+          dismissOnRun: true,
+          handler() {
+            return reload();
+          }
+        }
+      });
+    } catch (error) {
+      runtimeLogger.error(
+        {
+          label: String(nextState?.label || ""),
+          error: String(error?.message || error || "unknown error")
+        },
+        "Async module recovery could not report through the shell error runtime."
+      );
+      return null;
+    }
+  }
+
+  async function reload() {
+    const reloaded = await guardedReloadApp({
+      state,
+      label: "App",
+      message: ASYNC_MODULE_RELOAD_FAILURE_MESSAGE
+    });
+    if (!reloaded) {
+      report(state);
+    }
+    return reloaded;
+  }
+
+  function notify(error = null, {
+    label = "App module",
+    message = "",
+    stale = isDynamicImportError(error)
+  } = {}) {
+    notifyAsyncModuleLoadError(state, error, {
+      label,
+      message,
+      retry: state.retry,
+      stale
+    });
+    return report(state);
+  }
+
+  function install() {
+    if (installedRecovery) {
+      return installedRecovery;
+    }
+
+    installedRecovery = installAsyncModuleRecoveryHandlers({
+      state,
+      label: "App module",
+      router: app.has("jskit.client.router") ? app.make("jskit.client.router") : null,
+      onNotify: report
+    });
+    return installedRecovery;
+  }
+
+  function dispose() {
+    installedRecovery?.dispose?.();
+    installedRecovery = null;
+  }
+
+  return Object.freeze({
+    dispose,
+    install,
+    notify,
+    reload,
+    report,
+    state
+  });
+}
+
 class ShellWebClientProvider {
   static id = "shell.web.client";
 
@@ -437,6 +571,12 @@ class ShellWebClientProvider {
         logger
       })
     );
+    app.singleton("runtime.web-async-module-recovery.client", (scope) =>
+      createShellAsyncModuleRecoveryRuntime({
+        app: scope,
+        logger
+      })
+    );
     app.singleton("runtime.web-error.presentation-store.client", () => createErrorPresentationStore());
     app.singleton("runtime.web-error.client", (scope) =>
       createErrorRuntime({
@@ -456,13 +596,17 @@ class ShellWebClientProvider {
     }
 
     const logger = createSharedProviderLogger(isRecord(app) ? app : null);
+    const errorRuntime = app.make("runtime.web-error.client");
+    const asyncModuleRecoveryRuntime = app.make("runtime.web-async-module-recovery.client");
+    asyncModuleRecoveryRuntime.install();
+
     const placementRuntime = app.make("runtime.web-placement.client");
     if (placementRuntime && typeof placementRuntime.replacePlacements === "function") {
-      const placementTopology = await loadAppPlacementTopology(logger);
+      const placementTopology = await loadAppPlacementTopology(logger, asyncModuleRecoveryRuntime);
       if (typeof placementRuntime.replacePlacementTopology === "function") {
         placementRuntime.replacePlacementTopology(placementTopology, { source: APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER });
       }
-      const placements = await loadAppPlacementDefinitions(logger);
+      const placements = await loadAppPlacementDefinitions(logger, asyncModuleRecoveryRuntime);
       placementRuntime.replacePlacements(placements, { source: APP_PLACEMENT_MODULE_SPECIFIER });
       const appConfig = getClientAppConfig();
       const surfaceRuntime = app.has("jskit.client.surface.runtime")
@@ -486,8 +630,7 @@ class ShellWebClientProvider {
       );
     }
 
-    const errorRuntime = app.make("runtime.web-error.client");
-    const errorConfig = await loadAppErrorConfig(logger, errorRuntime);
+    const errorConfig = await loadAppErrorConfig(logger, errorRuntime, asyncModuleRecoveryRuntime);
     applyAppErrorConfig(errorRuntime, errorConfig);
 
     const bootstrapRuntime = app.make("runtime.web-bootstrap.client");
@@ -514,6 +657,7 @@ class ShellWebClientProvider {
     vueApp.provide("jskit.shell-web.runtime.web-placement.client", placementRuntime);
     vueApp.provide("jskit.shell-web.runtime.web-refresh.client", refreshRuntime);
     vueApp.provide("jskit.shell-web.runtime.web-error.client", errorRuntime);
+    vueApp.provide(SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY, asyncModuleRecoveryRuntime);
     vueApp.provide(
       "jskit.shell-web.runtime.web-error.presentation-store.client",
       errorPresentationStore

package/src/client/providers/appModuleLoadFailure.js

@@ -0,0 +1,29 @@
+import {
+  isDynamicImportError
+} from "@jskit-ai/kernel/client/asyncModuleRecovery";
+
+function isMissingDynamicModule(error, moduleSpecifier) {
+  const message = String(error?.message || error || "");
+  return (
+    message.includes(moduleSpecifier) &&
+    (message.includes("Cannot find module") ||
+      message.includes("ERR_MODULE_NOT_FOUND"))
+  );
+}
+
+function notifyDynamicImportFailure(asyncModuleRecoveryRuntime, error, {
+  label = "App module"
+} = {}) {
+  if (!isDynamicImportError(error) || typeof asyncModuleRecoveryRuntime?.notify !== "function") {
+    return;
+  }
+
+  asyncModuleRecoveryRuntime.notify(error, {
+    label
+  });
+}
+
+export {
+  isMissingDynamicModule,
+  notifyDynamicImportFailure
+};

package/templates/expected-existing/src/pages/home/index.vue

@@ -19,7 +19,7 @@
 
 <style scoped>
 .generated-ui-screen {
-  --generated-ui-screen-title-size: clamp(1.5rem, 3vw, 2.5rem);
+  --generated-ui-screen-title-size: 2rem;
   --generated-ui-screen-panel-padding: 1rem;
 }
 
@@ -31,7 +31,7 @@
 .home-start-screen__title {
   font-size: var(--generated-ui-screen-title-size);
   font-weight: 700;
-  letter-spacing: -0.03em;
+  letter-spacing: 0;
   line-height: 1.08;
   margin: 0 0 0.45rem;
 }
@@ -39,4 +39,10 @@
 .home-start-screen__panel {
   padding: var(--generated-ui-screen-panel-padding);
 }
+
+@media (max-width: 640px) {
+  .generated-ui-screen {
+    --generated-ui-screen-title-size: 1.5rem;
+  }
+}
 </style>

package/templates/src/pages/home/index.vue

@@ -56,7 +56,7 @@ const health = computed(() => {
 
 <style scoped>
 .generated-ui-screen {
-  --generated-ui-screen-title-size: clamp(1.5rem, 2.5vw, 2.25rem);
+  --generated-ui-screen-title-size: 2rem;
   --generated-ui-screen-panel-padding: 1rem;
 }
 
@@ -70,7 +70,7 @@ const health = computed(() => {
 .home-surface-screen__title {
   font-size: var(--generated-ui-screen-title-size);
   font-weight: 700;
-  letter-spacing: -0.03em;
+  letter-spacing: 0;
   line-height: 1.1;
   margin: 0 0 0.4rem;
 }
@@ -90,6 +90,10 @@ const health = computed(() => {
 }
 
 @media (max-width: 640px) {
+  .generated-ui-screen {
+    --generated-ui-screen-title-size: 1.5rem;
+  }
+
   .home-surface-screen__header {
     flex-direction: column;
   }

package/templates/src/pages/home/settings.vue

@@ -29,14 +29,14 @@ import { RouterView } from "vue-router";
 
 <style scoped>
 .generated-ui-screen {
-  --generated-ui-screen-title-size: clamp(1.35rem, 2vw, 1.85rem);
+  --generated-ui-screen-title-size: 1.85rem;
   --generated-ui-screen-panel-padding: 1rem;
 }
 
 .settings-shell__title {
   font-size: var(--generated-ui-screen-title-size);
   font-weight: 650;
-  letter-spacing: -0.02em;
+  letter-spacing: 0;
   line-height: 1.15;
   margin: 0 0 0.35rem;
 }
@@ -81,6 +81,10 @@ import { RouterView } from "vue-router";
 }
 
 @media (max-width: 960px) {
+  .generated-ui-screen {
+    --generated-ui-screen-title-size: 1.35rem;
+  }
+
   .settings-shell__body {
     grid-template-columns: 1fr;
   }

package/test/asyncModuleRecoveryInject.test.js

@@ -0,0 +1,49 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createApp } from "vue";
+import {
+  SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY,
+  useShellAsyncModuleRecoveryRuntime
+} from "../src/client/asyncModuleRecovery/index.js";
+
+test("shell async module recovery runtime composable returns null outside Vue injection context", () => {
+  assert.equal(useShellAsyncModuleRecoveryRuntime(), null);
+});
+
+test("shell async module recovery runtime composable resolves the provided public runtime", async () => {
+  const runtime = {
+    notify(error, options) {
+      return { error, options };
+    },
+    async reload() {
+      return true;
+    }
+  };
+  const app = createApp({
+    render() {
+      return null;
+    }
+  });
+  app.provide(SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY, runtime);
+
+  assert.equal(
+    app.runWithContext(() => useShellAsyncModuleRecoveryRuntime()),
+    runtime
+  );
+});
+
+test("shell async module recovery runtime composable rejects incomplete runtimes", () => {
+  const app = createApp({
+    render() {
+      return null;
+    }
+  });
+  app.provide(SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY, {
+    notify() {}
+  });
+
+  assert.equal(
+    app.runWithContext(() => useShellAsyncModuleRecoveryRuntime()),
+    null
+  );
+});

package/test/bootstrapClaimContract.test.js

@@ -7,7 +7,7 @@ import descriptor from "../package.descriptor.mjs";
 
 const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_DIR = path.resolve(TEST_DIRECTORY, "..");
-const CREATE_APP_TEMPLATE_DIR = path.resolve(PACKAGE_DIR, "..", "..", "tooling", "create-app", "templates", "base-shell");
+const CREATE_APP_TEMPLATE_DIR = path.resolve(PACKAGE_DIR, "..", "..", "tooling", "create-app", "templates", "minimal-shell");
 
 function findFileMutation(id) {
   const files = descriptor?.mutations?.files;
@@ -48,7 +48,7 @@ test("shell-web claims starter shell files as app-owned scaffolds", () => {
   });
 });
 
-test("shell-web expected-existing starter files stay aligned with create-app base-shell", async () => {
+test("shell-web expected-existing starter files stay aligned with create-app minimal-shell", async () => {
   const comparedFiles = [
     "src/App.vue",
     "src/pages/home.vue",

package/test/provider.test.js

@@ -5,9 +5,31 @@ import {
   ShellWebClientProvider,
   resolveAppPlacementTopologyExport
 } from "../src/client/providers/ShellWebClientProvider.js";
+import {
+  isMissingDynamicModule
+} from "../src/client/providers/appModuleLoadFailure.js";
+import {
+  SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY
+} from "../src/client/asyncModuleRecovery/index.js";
 import { useShellErrorPresentationStore } from "../src/client/stores/useShellErrorPresentationStore.js";
 const CLIENT_APP_CONFIG_GLOBAL_KEY = "__JSKIT_CLIENT_APP_CONFIG__";
 
+async function withTemporaryGlobal(name, value, callback) {
+  const hadPrevious = Object.prototype.hasOwnProperty.call(globalThis, name);
+  const previousValue = globalThis[name];
+  globalThis[name] = value;
+
+  try {
+    return await callback();
+  } finally {
+    if (hadPrevious) {
+      globalThis[name] = previousValue;
+    } else {
+      delete globalThis[name];
+    }
+  }
+}
+
 function setClientAppConfig(source = {}) {
   const normalized =
     source && typeof source === "object" && !Array.isArray(source) ? Object.freeze({ ...source }) : Object.freeze({});
@@ -17,7 +39,7 @@ function setClientAppConfig(source = {}) {
   return normalized;
 }
 
-function createAppDouble({ surfaceRuntime = null, queryClient = null } = {}) {
+function createAppDouble({ surfaceRuntime = null, queryClient = null, router = null } = {}) {
   const singletons = new Map();
   const singletonInstances = new Map();
   const provided = [];
@@ -67,6 +89,9 @@ function createAppDouble({ surfaceRuntime = null, queryClient = null } = {}) {
       if (token === "jskit.client.query-client") {
         return Boolean(queryClient);
       }
+      if (token === "jskit.client.router") {
+        return Boolean(router);
+      }
       return singletons.has(token) || singletonInstances.has(token);
     },
     make(token) {
@@ -82,6 +107,9 @@ function createAppDouble({ surfaceRuntime = null, queryClient = null } = {}) {
       if (token === "jskit.client.query-client" && queryClient) {
         return queryClient;
       }
+      if (token === "jskit.client.router" && router) {
+        return router;
+      }
       if (singletonInstances.has(token)) {
         return singletonInstances.get(token);
       }
@@ -100,38 +128,45 @@ function createAppDouble({ surfaceRuntime = null, queryClient = null } = {}) {
 }
 
 async function withFetchStub(responsePayload, callback) {
-  const previousFetch = globalThis.fetch;
-  globalThis.fetch = async () => ({
+  return withFetchImplementation(async () => ({
     ok: true,
     async json() {
       return responsePayload;
     }
-  });
-
-  try {
-    return await callback();
-  } finally {
-    if (previousFetch === undefined) {
-      delete globalThis.fetch;
-    } else {
-      globalThis.fetch = previousFetch;
-    }
-  }
+  }), callback);
 }
 
 async function withFetchImplementation(fetchImplementation, callback) {
-  const previousFetch = globalThis.fetch;
-  globalThis.fetch = fetchImplementation;
+  return withTemporaryGlobal("fetch", fetchImplementation, callback);
+}
 
-  try {
-    return await callback();
-  } finally {
-    if (previousFetch === undefined) {
-      delete globalThis.fetch;
-    } else {
-      globalThis.fetch = previousFetch;
+async function withWindowDouble(windowObject, callback) {
+  return withTemporaryGlobal("window", windowObject, callback);
+}
+
+function createWindowDouble({ href = "https://example.test/home" } = {}) {
+  const listeners = new Map();
+  const reloadCalls = [];
+  const location = {
+    href,
+    reload() {
+      reloadCalls.push(location.href);
     }
-  }
+  };
+
+  return {
+    listeners,
+    reloadCalls,
+    location,
+    addEventListener(type, handler) {
+      listeners.set(type, handler);
+    },
+    removeEventListener(type, handler) {
+      if (listeners.get(type) === handler) {
+        listeners.delete(type);
+      }
+    }
+  };
 }
 
 test("shell web client provider preserves append-only placement topology object exports", () => {
@@ -160,6 +195,23 @@ test("shell web client provider preserves append-only placement topology object
   assert.deepEqual(warnings, []);
 });
 
+test("shell web boot import classifier does not swallow fetched dynamic module failures", () => {
+  assert.equal(
+    isMissingDynamicModule(
+      new Error("Cannot find module '/src/placement.js' imported from /src/main.js"),
+      "/src/placement.js"
+    ),
+    true
+  );
+  assert.equal(
+    isMissingDynamicModule(
+      new Error("Failed to fetch dynamically imported module: http://localhost:5173/src/placement.js?t=123"),
+      "/src/placement.js"
+    ),
+    false
+  );
+});
+
 test("shell web client provider binds runtime and injects it into Vue app", async () => {
   await withFetchStub({ surfaceAccess: {} }, async () => {
     const app = createAppDouble();
@@ -170,6 +222,7 @@ test("shell web client provider binds runtime and injects it into Vue app", asyn
     assert.equal(app.singletons.has("runtime.web-error.client"), true);
     assert.equal(app.singletons.has("runtime.web-error.presentation-store.client"), true);
     assert.equal(app.singletons.has("runtime.web-refresh.client"), true);
+    assert.equal(app.singletons.has("runtime.web-async-module-recovery.client"), true);
 
     await provider.boot(app);
     assert.equal(app.plugins.length, 0);
@@ -179,6 +232,7 @@ test("shell web client provider binds runtime and injects it into Vue app", asyn
     assert.equal(providedByKey.has("jskit.shell-web.runtime.web-placement.client"), true);
     assert.equal(providedByKey.has("jskit.shell-web.runtime.web-refresh.client"), true);
     assert.equal(providedByKey.has("jskit.shell-web.runtime.web-error.client"), true);
+    assert.equal(providedByKey.has(SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY), true);
     assert.equal(providedByKey.has("jskit.shell-web.runtime.web-error.presentation-store.client"), true);
 
     const placementRuntime = providedByKey.get("jskit.shell-web.runtime.web-placement.client");
@@ -194,6 +248,11 @@ test("shell web client provider binds runtime and injects it into Vue app", asyn
     const refreshRuntime = providedByKey.get("jskit.shell-web.runtime.web-refresh.client");
     assert.equal(typeof refreshRuntime.refresh, "function");
 
+    const asyncModuleRecoveryRuntime = providedByKey.get(SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY);
+    assert.equal(typeof asyncModuleRecoveryRuntime.install, "function");
+    assert.equal(typeof asyncModuleRecoveryRuntime.notify, "function");
+    assert.equal(typeof asyncModuleRecoveryRuntime.reload, "function");
+
     const errorStore = providedByKey.get("jskit.shell-web.runtime.web-error.presentation-store.client");
     assert.equal(typeof errorStore.getState, "function");
     assert.equal(typeof errorStore.present, "function");
@@ -260,6 +319,127 @@ test("shell refresh runtime reports recoverable retry errors as banners", async
   });
 });
 
+test("shell web client provider reports dynamic import failures through async module recovery", async () => {
+  await withFetchStub({ surfaceAccess: {} }, async () => {
+    const routerErrorHandlers = [];
+    const replacedPaths = [];
+    const router = {
+      onError(handler) {
+        routerErrorHandlers.push(handler);
+        return () => null;
+      },
+      replace(fullPath) {
+        replacedPaths.push(fullPath);
+      }
+    };
+    const app = createAppDouble({ router });
+    const provider = new ShellWebClientProvider();
+    provider.register(app);
+    await provider.boot(app);
+
+    assert.equal(routerErrorHandlers.length, 2);
+
+    const chunkError = new Error("Failed to fetch dynamically imported module: /assets/page.js");
+    for (const handler of routerErrorHandlers) {
+      handler(chunkError, {
+        fullPath: "/app/dashboard"
+      });
+    }
+
+    const errorStore = app.make("runtime.web-error.presentation-store.client");
+    const state = errorStore.getState();
+    assert.equal(state.channels.banner.length, 1);
+    assert.equal(
+      state.channels.banner[0].message,
+      "Page did not download. The app may have been updated, or the network request failed."
+    );
+    assert.equal(state.channels.banner[0].severity, "warning");
+    assert.equal(state.channels.banner[0].action.label, "Reload");
+    assert.deepEqual(replacedPaths, []);
+  });
+});
+
+test("shell web async module recovery reload action checks the document before reloading", async () => {
+  const windowObject = createWindowDouble();
+  await withWindowDouble(windowObject, async () => {
+    const fetchCalls = [];
+    await withFetchImplementation(async (input, init = {}) => {
+      fetchCalls.push({ input, init });
+      return {
+        ok: true,
+        status: 200,
+        async json() {
+          return { surfaceAccess: {} };
+        }
+      };
+    }, async () => {
+      const routerErrorHandlers = [];
+      const router = {
+        onError(handler) {
+          routerErrorHandlers.push(handler);
+          return () => null;
+        },
+        replace() {}
+      };
+      const app = createAppDouble({ router });
+      const provider = new ShellWebClientProvider();
+      provider.register(app);
+      await provider.boot(app);
+
+      const chunkError = new Error("Failed to fetch dynamically imported module: /assets/page.js");
+      routerErrorHandlers[0](chunkError, {
+        fullPath: "/home/settings"
+      });
+
+      const errorStore = app.make("runtime.web-error.presentation-store.client");
+      const banner = errorStore.getState().channels.banner[0];
+      await banner.action.handler();
+
+      assert.deepEqual(windowObject.reloadCalls, ["https://example.test/home"]);
+      const reloadFetch = fetchCalls.find((entry) => entry.input === "https://example.test/home");
+      assert.equal(reloadFetch?.init?.cache, "no-store");
+      assert.equal(reloadFetch?.init?.credentials, "same-origin");
+    });
+  });
+});
+
+test("shell web async module recovery keeps the page alive when reload check fails", async () => {
+  const windowObject = createWindowDouble();
+  await withWindowDouble(windowObject, async () => {
+    await withFetchImplementation(async (input) => {
+      if (input === "https://example.test/home") {
+        throw new TypeError("Failed to fetch");
+      }
+      return {
+        ok: true,
+        status: 200,
+        async json() {
+          return { surfaceAccess: {} };
+        }
+      };
+    }, async () => {
+      const app = createAppDouble();
+      const provider = new ShellWebClientProvider();
+      provider.register(app);
+      await provider.boot(app);
+
+      const recoveryRuntime = app.make("runtime.web-async-module-recovery.client");
+      const reloaded = await recoveryRuntime.reload();
+
+      assert.equal(reloaded, false);
+      assert.deepEqual(windowObject.reloadCalls, []);
+      const errorStore = app.make("runtime.web-error.presentation-store.client");
+      const state = errorStore.getState();
+      assert.equal(state.channels.banner.length, 1);
+      assert.equal(
+        state.channels.banner[0].message,
+        "The app cannot reload because the app server is not reachable. Restart the server, then click Reload."
+      );
+      assert.equal(state.channels.banner[0].action.label, "Reload");
+    });
+  });
+});
+
 test("shell web client provider resolves surface config from client app config", async () => {
   setClientAppConfig({
     tenancyMode: "workspaces",

package/test/settingsPlacementContract.test.js

@@ -38,6 +38,11 @@ function readTopology(id = "", owner = "") {
     : [];
 }
 
+function readClientContainerTokens() {
+  const tokens = descriptor?.metadata?.apiSummary?.containerTokens?.client;
+  return Array.isArray(tokens) ? tokens : [];
+}
+
 function findFileMutation(id) {
   const files = descriptor?.mutations?.files;
   return Array.isArray(files)
@@ -143,6 +148,29 @@ test("shell-web installs generated adaptive shell Playwright smoke coverage", as
   assert.equal(packageJson?.exports?.["./test/adaptiveShellSmoke"], "./src/test/adaptiveShellSmoke.js");
 });
 
+test("shell-web exports async module recovery runtime access as a public client API", async () => {
+  const packageJson = JSON.parse(await readFile(path.join(PACKAGE_DIR, "package.json"), "utf8"));
+  const clientIndex = await readFile(path.join(PACKAGE_DIR, "src", "client", "index.js"), "utf8");
+  const recoveryIndex = await readFile(
+    path.join(PACKAGE_DIR, "src", "client", "asyncModuleRecovery", "index.js"),
+    "utf8"
+  );
+  const providerSource = await readFile(
+    path.join(PACKAGE_DIR, "src", "client", "providers", "ShellWebClientProvider.js"),
+    "utf8"
+  );
+
+  assert.equal(
+    packageJson?.exports?.["./client/asyncModuleRecovery"],
+    "./src/client/asyncModuleRecovery/index.js"
+  );
+  assert.match(clientIndex, /useShellAsyncModuleRecoveryRuntime/);
+  assert.match(clientIndex, /SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY/);
+  assert.match(recoveryIndex, /useShellAsyncModuleRecoveryRuntime/);
+  assert.match(recoveryIndex, /SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY/);
+  assert.match(providerSource, /SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY/);
+});
+
 test("shell-web route transition keeps mobile route motion placement-driven", async () => {
   const source = await readFile(
     path.join(PACKAGE_DIR, "src", "client", "components", "ShellRouteTransition.vue"),
@@ -265,6 +293,15 @@ test("shell-web placement topology seeds global actions as a semantic shell plac
 });
 
 test("shell-web descriptor metadata advertises adaptive shell outlets, default links, and installs the scaffold page", () => {
+  assert.deepEqual(readClientContainerTokens(), [
+    "runtime.web-placement.client",
+    "runtime.web-bootstrap.client",
+    "runtime.web-refresh.client",
+    "runtime.web-async-module-recovery.client",
+    "runtime.web-error.client",
+    "runtime.web-error.presentation-store.client"
+  ]);
+
   assert.deepEqual(
     readOutlets("shell-layout:primary-bottom-nav"),
     [