@jskit-ai/shell-web 0.1.84 → 0.1.86

package/package.descriptor.mjs

@@ -1,14 +1,15 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/shell-web",
-  version: "0.1.84",
+  version: "0.1.86",
   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.85"
+        "@jskit-ai/kernel": "0.1.87"
       },
       dev: {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/shell-web",
-  "version": "0.1.84",
+  "version": "0.1.86",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/kernel": "0.1.85"
+    "@jskit-ai/kernel": "0.1.87"
   },
   "peerDependencies": {
     "pinia": "^3.0.4",

package/src/client/components/ShellRouteTransition.vue

@@ -24,6 +24,7 @@ import {
   normalizeMenuLinkPathname,
   resolveMenuLinkTarget
 } from "../support/menuLinkTarget.js";
+import { resolveShellRouteTransitionKey } from "../support/routeTransitionKey.js";
 
 const props = defineProps({
   enabled: {
@@ -232,7 +233,16 @@ const routeTransitionName = computed(() => {
   return "";
 });
 
-const routeTransitionKey = computed(() => normalizeComparablePathname(route?.path || route?.fullPath || "/") || "/");
+const routeTransitionKey = computed(() => {
+  const routePathKey = routeTransitionName.value
+    ? normalizeComparablePathname(route?.path || route?.fullPath || "/")
+    : "";
+  return resolveShellRouteTransitionKey({
+    routePathKey,
+    routeTransitionName: routeTransitionName.value,
+    surfaceId: currentSurfaceId.value
+  });
+});
 
 const swipeNavigationEnabled = computed(() =>
   Boolean(
@@ -409,7 +419,12 @@ function isSwipeIgnoredTarget(target) {
 <style scoped>
 .shell-route-transition {
   --shell-route-transition-distance: 100%;
+  align-items: stretch;
   --shell-route-transition-opacity: 1;
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  min-height: 0;
   overflow-x: clip;
   position: relative;
 }
@@ -420,6 +435,10 @@ function isSwipeIgnoredTarget(target) {
 
 .shell-route-transition__pane {
   background: rgb(var(--v-theme-background));
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  min-height: 0;
   width: 100%;
 }
 

package/src/client/providers/ShellWebClientProvider.js

@@ -1,4 +1,15 @@
 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 {
   isRecord
 } from "@jskit-ai/kernel/shared/support";
@@ -29,18 +40,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 +63,9 @@ async function loadAppPlacementDefinitions(logger) {
     if (isMissingDynamicModule(error, APP_PLACEMENT_MODULE_SPECIFIER)) {
       return [];
     }
+    notifyDynamicImportFailure(asyncModuleRecoveryRuntime, error, {
+      label: "Placement config"
+    });
 
     logger.warn(
       {
@@ -73,7 +79,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 +88,9 @@ async function loadAppPlacementTopology(logger) {
     if (isMissingDynamicModule(error, APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER)) {
       return [];
     }
+    notifyDynamicImportFailure(asyncModuleRecoveryRuntime, error, {
+      label: "Placement topology"
+    });
 
     logger.warn(
       {
@@ -127,7 +136,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 +158,9 @@ async function loadAppErrorConfig(logger, errorRuntime) {
     if (isMissingDynamicModule(error, APP_ERROR_MODULE_SPECIFIER)) {
       return {};
     }
+    notifyDynamicImportFailure(asyncModuleRecoveryRuntime, error, {
+      label: "Error config"
+    });
 
     logger.warn(
       {
@@ -362,6 +374,10 @@ function installRouterErrorBridge(app, errorRuntime, logger) {
   }
 
   router.onError((error) => {
+    if (isDynamicImportError(error)) {
+      return;
+    }
+
     try {
       errorRuntime.report({
         source: "shell-web.router.on-error",
@@ -384,6 +400,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 +568,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 +593,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 +627,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 +654,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("jskit.shell-web.runtime.web-async-module-recovery.client", 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/src/client/support/routeTransitionKey.js

@@ -0,0 +1,22 @@
+function normalizeText(value = "") {
+  return String(value || "").trim();
+}
+
+function resolveShellRouteTransitionKey({
+  routePathKey = "",
+  routeTransitionName = "",
+  surfaceId = ""
+} = {}) {
+  if (normalizeText(routeTransitionName)) {
+    return normalizeText(routePathKey) || "/";
+  }
+
+  const surfaceKey = normalizeText(surfaceId);
+  if (surfaceKey && surfaceKey !== "*") {
+    return `surface:${surfaceKey}`;
+  }
+
+  return "stable";
+}
+
+export { resolveShellRouteTransitionKey };

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

@@ -14,7 +14,7 @@ import { RouterView } from "vue-router";
     <v-sheet rounded="lg" border class="settings-shell__panel">
       <div class="settings-shell__body">
         <nav class="settings-shell__nav" aria-label="Home settings sections">
-          <v-list nav density="comfortable" rounded="lg" border>
+          <v-list nav density="compact" rounded="lg">
             <ShellOutlet target="home-settings:primary-menu" />
           </v-list>
         </nav>
@@ -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;
 }
@@ -53,10 +53,38 @@ import { RouterView } from "vue-router";
 }
 
 .settings-shell__content {
+  border-left: 1px solid rgba(var(--v-theme-on-surface), 0.18);
   min-width: 0;
+  padding-left: 1rem;
+}
+
+.settings-shell__nav :deep(.v-list) {
+  padding: 0.35rem;
+}
+
+.settings-shell__nav :deep(.v-list-item) {
+  min-height: 48px;
+  padding-inline: 0.6rem 0.7rem;
+}
+
+.settings-shell__nav :deep(.v-list-item__prepend) {
+  margin-inline-end: 0;
+}
+
+.settings-shell__nav :deep(.v-list-item__spacer) {
+  min-width: 0.5rem;
+  width: 0.5rem;
+}
+
+.settings-shell__nav :deep(.v-list-item-title) {
+  line-height: 1.2;
 }
 
 @media (max-width: 960px) {
+  .generated-ui-screen {
+    --generated-ui-screen-title-size: 1.35rem;
+  }
+
   .settings-shell__body {
     grid-template-columns: 1fr;
   }
@@ -72,5 +100,10 @@ import { RouterView } from "vue-router";
     flex: 0 0 auto;
     min-height: 48px;
   }
+
+  .settings-shell__content {
+    border-left: 0;
+    padding-left: 0;
+  }
 }
 </style>

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/menuIcons.test.js

@@ -4,6 +4,7 @@ import test from "node:test";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import {
+  mdiAccountKeyOutline,
   mdiCogOutline,
   mdiConsoleNetworkOutline,
   mdiViewListOutline
@@ -29,6 +30,10 @@ test("shell-web leaves unknown explicit mdi metadata icons unchanged", () => {
   assert.equal(resolveMenuLinkIcon({ icon: "mdi-not-a-real-supported-icon" }), "mdi-not-a-real-supported-icon");
 });
 
+test("shell-web accepts imported @mdi/js path constants as explicit menu icons", () => {
+  assert.equal(resolveMenuLinkIcon({ icon: mdiAccountKeyOutline }), mdiAccountKeyOutline);
+});
+
 test("shell-web menu icon resolution does not import the full mdi namespace", async () => {
   const source = await readFile(path.join(PACKAGE_DIR, "src", "client", "lib", "menuIcons.js"), "utf8");
 

package/test/provider.test.js

@@ -5,9 +5,28 @@ import {
   ShellWebClientProvider,
   resolveAppPlacementTopologyExport
 } from "../src/client/providers/ShellWebClientProvider.js";
+import {
+  isMissingDynamicModule
+} from "../src/client/providers/appModuleLoadFailure.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 +36,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 +86,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 +104,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 +125,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 +192,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 +219,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 +229,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("jskit.shell-web.runtime.web-async-module-recovery.client"), 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 +245,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("jskit.shell-web.runtime.web-async-module-recovery.client");
+    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 +316,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

@@ -5,6 +5,7 @@ import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { assertGeneratedUiSourceContract } from "@jskit-ai/kernel/shared/support/generatedUiContract";
 import descriptor from "../package.descriptor.mjs";
+import { resolveShellRouteTransitionKey } from "../src/client/support/routeTransitionKey.js";
 
 const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_DIR = path.resolve(TEST_DIRECTORY, "..");
@@ -37,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)
@@ -159,10 +165,54 @@ test("shell-web route transition keeps mobile route motion placement-driven", as
   assert.match(source, /router\.push\(nextEntry\.href\)/);
   assert.match(source, /isSwipeIgnoredTarget/);
   assert.match(source, /touch-action:\s*pan-y/);
+  assert.match(source, /\.shell-route-transition\s*\{[\s\S]*display:\s*flex/);
+  assert.match(source, /\.shell-route-transition\s*\{[\s\S]*min-height:\s*0/);
+  assert.match(source, /\.shell-route-transition__pane\s*\{[\s\S]*flex:\s*1 1 auto/);
+  assert.match(source, /\.shell-route-transition__pane\s*\{[\s\S]*min-height:\s*0/);
   assert.match(source, /transitionDirection\.value = nextIndex > previousIndex \? "forward" : "reverse"/);
+  assert.match(
+    source,
+    /const routeTransitionKey = computed\(\(\) => \{[\s\S]*const routePathKey = routeTransitionName\.value[\s\S]*normalizeComparablePathname\(route\?\.path \|\| route\?\.fullPath \|\| "\/"\)[\s\S]*resolveShellRouteTransitionKey\(\{[\s\S]*routeTransitionName: routeTransitionName\.value,[\s\S]*surfaceId: currentSurfaceId\.value[\s\S]*\}\);[\s\S]*\}\);/
+  );
   assert.match(source, /prefers-reduced-motion:\s*reduce/);
 });
 
+test("shell-web route transition key preserves no-motion surfaces and animated path transitions", () => {
+  const previewSurfaceKey = "surface:vibe64-preview";
+  assert.equal(
+    resolveShellRouteTransitionKey({
+      routeTransitionName: "",
+      routePathKey: "/preview",
+      surfaceId: "vibe64-preview"
+    }),
+    previewSurfaceKey
+  );
+  assert.equal(
+    resolveShellRouteTransitionKey({
+      routeTransitionName: "",
+      routePathKey: "/preview/dashboard",
+      surfaceId: "vibe64-preview"
+    }),
+    previewSurfaceKey
+  );
+  assert.equal(
+    resolveShellRouteTransitionKey({
+      routeTransitionName: "shell-route-slide-forward",
+      routePathKey: "/dashboard",
+      surfaceId: "home"
+    }),
+    "/dashboard"
+  );
+  assert.equal(
+    resolveShellRouteTransitionKey({
+      routeTransitionName: "",
+      routePathKey: "/dashboard",
+      surfaceId: "*"
+    }),
+    "stable"
+  );
+});
+
 test("shell-web settings landing page redirects to the starter child page", async () => {
   const source = await readFile(path.join(PACKAGE_DIR, "templates", "src", "pages", "home", "settings", "index.vue"), "utf8");
 
@@ -220,6 +270,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"),
     [