@jskit-ai/shell-web 0.1.87 → 0.1.89

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/shell-web",
-  version: "0.1.87",
+  version: "0.1.89",
   kind: "runtime",
   description: "Web shell layout runtime with outlet-based placement contributions.",
   dependsOn: [],
@@ -9,7 +9,8 @@ export default Object.freeze({
     provides: [
       "runtime.web-placement",
       "runtime.web-error",
-      "runtime.web-async-module-recovery"
+      "runtime.web-async-module-recovery",
+      "runtime.web-request-recovery"
     ],
     requires: []
   },
@@ -41,6 +42,10 @@ export default Object.freeze({
           subpath: "./client/error",
           summary: "Exports default error policy and runtime error reporter hook."
         },
+        {
+          subpath: "./client/requestRecovery",
+          summary: "Exports request connectivity recovery classification and runtime access for app-caught request failures."
+        },
         {
           subpath: "./client/bootstrap",
           summary: "Exports the shared client bootstrap handler registry used to extend /api/bootstrap handling."
@@ -57,6 +62,7 @@ export default Object.freeze({
           "runtime.web-bootstrap.client",
           "runtime.web-refresh.client",
           "runtime.web-async-module-recovery.client",
+          "runtime.web-request-recovery.client",
           "runtime.web-error.client",
           "runtime.web-error.presentation-store.client"
         ]
@@ -294,7 +300,7 @@ export default Object.freeze({
     dependencies: {
       runtime: {
         "@mdi/js": "^7.4.47",
-        "@jskit-ai/kernel": "0.1.88"
+        "@jskit-ai/kernel": "0.1.90"
       },
       dev: {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/shell-web",
-  "version": "0.1.87",
+  "version": "0.1.89",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -10,6 +10,7 @@
     "./client/error": "./src/client/error/index.js",
     "./client/placement": "./src/client/placement/index.js",
     "./client/asyncModuleRecovery": "./src/client/asyncModuleRecovery/index.js",
+    "./client/requestRecovery": "./src/client/requestRecovery/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",
@@ -27,7 +28,7 @@
   },
   "dependencies": {
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/kernel": "0.1.88"
+    "@jskit-ai/kernel": "0.1.90"
   },
   "peerDependencies": {
     "pinia": "^3.0.4",

package/src/client/index.js

@@ -21,6 +21,12 @@ export {
   SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY,
   useShellAsyncModuleRecoveryRuntime
 } from "./asyncModuleRecovery/index.js";
+export {
+  SHELL_REQUEST_RECOVERY_RUNTIME_KEY,
+  isRecoverableRequestError,
+  requestRecoveryMessage,
+  useShellRequestRecoveryRuntime
+} from "./requestRecovery/index.js";
 export {
   BOOTSTRAP_PAYLOAD_HANDLER_TAG,
   registerBootstrapPayloadHandler,

package/src/client/providers/ShellWebClientProvider.js

@@ -13,6 +13,12 @@ import {
 import {
   SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY
 } from "../asyncModuleRecovery/inject.js";
+import {
+  SHELL_REQUEST_RECOVERY_RUNTIME_KEY
+} from "../requestRecovery/inject.js";
+import {
+  createShellRequestRecoveryRuntime
+} from "../requestRecovery/runtime.js";
 import {
   isRecord
 } from "@jskit-ai/kernel/shared/support";
@@ -577,6 +583,12 @@ class ShellWebClientProvider {
         logger
       })
     );
+    app.singleton("runtime.web-request-recovery.client", (scope) =>
+      createShellRequestRecoveryRuntime({
+        app: scope,
+        logger
+      })
+    );
     app.singleton("runtime.web-error.presentation-store.client", () => createErrorPresentationStore());
     app.singleton("runtime.web-error.client", (scope) =>
       createErrorRuntime({
@@ -598,6 +610,7 @@ 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");
+    const requestRecoveryRuntime = app.make("runtime.web-request-recovery.client");
     asyncModuleRecoveryRuntime.install();
 
     const placementRuntime = app.make("runtime.web-placement.client");
@@ -632,6 +645,7 @@ class ShellWebClientProvider {
 
     const errorConfig = await loadAppErrorConfig(logger, errorRuntime, asyncModuleRecoveryRuntime);
     applyAppErrorConfig(errorRuntime, errorConfig);
+    requestRecoveryRuntime.install();
 
     const bootstrapRuntime = app.make("runtime.web-bootstrap.client");
     if (bootstrapRuntime && typeof bootstrapRuntime.initialize === "function") {
@@ -658,6 +672,7 @@ class ShellWebClientProvider {
     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(SHELL_REQUEST_RECOVERY_RUNTIME_KEY, requestRecoveryRuntime);
     vueApp.provide(
       "jskit.shell-web.runtime.web-error.presentation-store.client",
       errorPresentationStore

package/src/client/requestRecovery/index.js

@@ -0,0 +1,8 @@
+export {
+  SHELL_REQUEST_RECOVERY_RUNTIME_KEY,
+  useShellRequestRecoveryRuntime
+} from "./inject.js";
+export {
+  isRecoverableRequestError,
+  requestRecoveryMessage
+} from "./runtime.js";

package/src/client/requestRecovery/inject.js

@@ -0,0 +1,30 @@
+import {
+  hasInjectionContext,
+  inject
+} from "vue";
+
+const SHELL_REQUEST_RECOVERY_RUNTIME_KEY =
+  "jskit.shell-web.runtime.web-request-recovery.client";
+
+function isShellRequestRecoveryRuntime(value) {
+  return Boolean(
+    value &&
+      typeof value.report === "function" &&
+      typeof value.reload === "function"
+  );
+}
+
+function useShellRequestRecoveryRuntime() {
+  if (!hasInjectionContext()) {
+    return null;
+  }
+
+  const runtime = inject(SHELL_REQUEST_RECOVERY_RUNTIME_KEY, null);
+  return isShellRequestRecoveryRuntime(runtime) ? runtime : null;
+}
+
+export {
+  SHELL_REQUEST_RECOVERY_RUNTIME_KEY,
+  isShellRequestRecoveryRuntime,
+  useShellRequestRecoveryRuntime
+};

package/src/client/requestRecovery/runtime.js

@@ -0,0 +1,446 @@
+import { guardedReloadApp } from "@jskit-ai/kernel/client/asyncModuleRecovery";
+import { isRecord } from "@jskit-ai/kernel/shared/support";
+import { createProviderLogger as createSharedProviderLogger } from "@jskit-ai/kernel/shared/support/providerLogger";
+
+const REQUEST_RECOVERY_RELOAD_FAILURE_MESSAGE =
+  "The app cannot reload because the app server is not reachable. Restart the server, then click Reload.";
+
+const RECOVERABLE_REQUEST_ERROR_MESSAGES = Object.freeze([
+  /Failed to fetch/iu,
+  /Load failed/iu,
+  /Network request failed/iu,
+  /NetworkError when attempting to fetch resource/iu,
+  /The Internet connection appears to be offline/iu
+]);
+
+const RECOVERABLE_REQUEST_ERROR_CODES = Object.freeze(new Set([
+  "EAI_AGAIN",
+  "ECONNABORTED",
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "ENETDOWN",
+  "ENETUNREACH",
+  "ENOTFOUND",
+  "ERR_NETWORK",
+  "ETIMEDOUT"
+]));
+
+const CANCELED_REQUEST_ERROR_CODES = Object.freeze(new Set([
+  "ABORT_ERR",
+  "ERR_ABORTED",
+  "ERR_CANCELED"
+]));
+
+function normalizeText(value, fallback = "") {
+  const normalized = String(value || "").trim();
+  return normalized || String(fallback || "").trim();
+}
+
+function errorMessage(error = null) {
+  return normalizeText(error?.message || error?.cause?.message || error);
+}
+
+function errorCode(error = null) {
+  return normalizeText(error?.code || error?.cause?.code).toUpperCase();
+}
+
+function errorName(error = null) {
+  return normalizeText(error?.name || error?.cause?.name);
+}
+
+function normalizeRequestErrorStatus(error = null) {
+  if (!isRecord(error)) {
+    return null;
+  }
+
+  const hasStatus = Object.prototype.hasOwnProperty.call(error, "status");
+  const hasStatusCode = Object.prototype.hasOwnProperty.call(error, "statusCode");
+  if (!hasStatus && !hasStatusCode) {
+    return null;
+  }
+
+  const status = Number(hasStatus ? error.status : error.statusCode);
+  return Number.isInteger(status) ? status : null;
+}
+
+function isCanceledRequestError(error = null) {
+  const name = errorName(error).toLowerCase();
+  if (name === "aborterror" || name === "cancelederror") {
+    return true;
+  }
+  return CANCELED_REQUEST_ERROR_CODES.has(errorCode(error));
+}
+
+function isRecoverableRequestError(error = null) {
+  if (!error || isCanceledRequestError(error)) {
+    return false;
+  }
+
+  const status = normalizeRequestErrorStatus(error);
+  if (status === 0) {
+    return true;
+  }
+
+  if (RECOVERABLE_REQUEST_ERROR_CODES.has(errorCode(error))) {
+    return true;
+  }
+
+  const message = errorMessage(error);
+  return Boolean(
+    message &&
+      RECOVERABLE_REQUEST_ERROR_MESSAGES.some((pattern) => pattern.test(message))
+  );
+}
+
+function requestRecoveryMessage(error = null, {
+  label = "Request",
+  message = ""
+} = {}) {
+  const explicitMessage = normalizeText(message);
+  if (explicitMessage) {
+    return explicitMessage;
+  }
+
+  const requestLabel = normalizeText(label, "Request");
+  if (requestLabel === "Request") {
+    return "The app could not reach the server or network. Check the connection and try again.";
+  }
+  return `${requestLabel} could not reach the server or network. Check the connection and try again.`;
+}
+
+function resolveQueryMeta(query = null) {
+  if (isRecord(query?.meta)) {
+    return query.meta;
+  }
+  if (isRecord(query?.options?.meta)) {
+    return query.options.meta;
+  }
+  return {};
+}
+
+function isRequestRecoveryDisabled(query = null) {
+  const meta = resolveQueryMeta(query);
+  if (meta.jskitRequestRecovery === false || meta.requestRecovery === false) {
+    return true;
+  }
+
+  const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
+  return jskitMeta.requestRecovery === false;
+}
+
+function resolveQueryRecoveryLabel(query = null) {
+  const meta = resolveQueryMeta(query);
+  const jskitMeta = isRecord(meta.jskit) ? meta.jskit : {};
+
+  return normalizeText(
+    jskitMeta.requestRecoveryLabel ||
+      jskitMeta.label ||
+      meta.jskitRequestRecoveryLabel ||
+      meta.requestRecoveryLabel ||
+      meta.label,
+    "Request"
+  );
+}
+
+function isActiveQuery(query = null) {
+  if (typeof query?.isActive === "function") {
+    return Boolean(query.isActive());
+  }
+  if (typeof query?.getObserversCount === "function") {
+    return Number(query.getObserversCount()) > 0;
+  }
+  return true;
+}
+
+function recoverableQueryError(query = null) {
+  const state = isRecord(query?.state) ? query.state : {};
+  if (state.status !== "error" || state.fetchStatus !== "idle") {
+    return null;
+  }
+
+  const error = state.error || state.fetchFailureReason || null;
+  return isRecoverableRequestError(error) ? error : null;
+}
+
+function createQueryRetry(queryClient, query = null) {
+  if (!queryClient || typeof queryClient.refetchQueries !== "function") {
+    return null;
+  }
+
+  const queryKey = query?.queryKey;
+  if (!Array.isArray(queryKey)) {
+    return null;
+  }
+
+  return () =>
+    queryClient.refetchQueries(
+      {
+        queryKey,
+        exact: true,
+        type: "active"
+      },
+      {
+        throwOnError: false
+      }
+    );
+}
+
+function resolveQueryHash(query = null) {
+  const explicitHash = normalizeText(query?.queryHash);
+  if (explicitHash) {
+    return explicitHash;
+  }
+
+  try {
+    return normalizeText(JSON.stringify(query?.queryKey || []));
+  } catch {
+    return normalizeText(String(query?.queryKey || ""));
+  }
+}
+
+function installRecoverableQueryObserver({
+  app,
+  runtime,
+  logger
+} = {}) {
+  if (!app?.has?.("jskit.client.query-client")) {
+    return Object.freeze({
+      dispose() {}
+    });
+  }
+
+  const queryClient = app.make("jskit.client.query-client");
+  const queryCache =
+    queryClient && typeof queryClient.getQueryCache === "function"
+      ? queryClient.getQueryCache()
+      : null;
+  if (!queryCache || typeof queryCache.subscribe !== "function") {
+    return Object.freeze({
+      dispose() {}
+    });
+  }
+
+  const reportedErrorUpdateByQueryHash = new Map();
+
+  function inspectQuery(query = null) {
+    if (!query || isRequestRecoveryDisabled(query) || !isActiveQuery(query)) {
+      return;
+    }
+
+    const error = recoverableQueryError(query);
+    const queryHash = resolveQueryHash(query);
+    if (!error || !queryHash) {
+      reportedErrorUpdateByQueryHash.delete(queryHash);
+      return;
+    }
+
+    const errorUpdateCount = Number(query?.state?.errorUpdateCount || 0);
+    const reportKey = `${errorUpdateCount}:${errorMessage(error)}`;
+    if (reportedErrorUpdateByQueryHash.get(queryHash) === reportKey) {
+      return;
+    }
+    reportedErrorUpdateByQueryHash.set(queryHash, reportKey);
+
+    runtime.report(error, {
+      label: resolveQueryRecoveryLabel(query),
+      retry: createQueryRetry(queryClient, query),
+      source: "shell-web.request-recovery.query",
+      stale: query?.state?.data !== undefined,
+      dedupeKey: `shell-web.request-recovery.query.${queryHash}.${errorUpdateCount}`
+    });
+  }
+
+  try {
+    if (typeof queryCache.getAll === "function") {
+      for (const query of queryCache.getAll()) {
+        inspectQuery(query);
+      }
+    }
+  } catch (error) {
+    logger.warn(
+      {
+        error: errorMessage(error) || "unknown error"
+      },
+      "Shell request recovery could not inspect existing queries."
+    );
+  }
+
+  const unsubscribe = queryCache.subscribe((event = {}) => {
+    try {
+      inspectQuery(event?.query);
+    } catch (error) {
+      logger.warn(
+        {
+          error: errorMessage(error) || "unknown error"
+        },
+        "Shell request recovery query observer failed."
+      );
+    }
+  });
+
+  return Object.freeze({
+    dispose() {
+      reportedErrorUpdateByQueryHash.clear();
+      if (typeof unsubscribe === "function") {
+        unsubscribe();
+      }
+    }
+  });
+}
+
+function createShellRequestRecoveryRuntime({
+  app,
+  logger = null
+} = {}) {
+  if (!app || typeof app.has !== "function" || typeof app.make !== "function") {
+    throw new Error("createShellRequestRecoveryRuntime requires application has()/make().");
+  }
+
+  const runtimeLogger = logger || createSharedProviderLogger(app);
+  let installedQueryObserver = null;
+  let reloadAttempt = 0;
+
+  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;
+  }
+
+  async function reload({
+    label = "App",
+    message = REQUEST_RECOVERY_RELOAD_FAILURE_MESSAGE
+  } = {}) {
+    const reloaded = await guardedReloadApp({
+      label,
+      message
+    });
+    if (!reloaded) {
+      reloadAttempt += 1;
+      report(new Error("Network request failed."), {
+        label,
+        message,
+        reload: true,
+        force: true,
+        source: "shell-web.request-recovery.reload",
+        dedupeKey: `shell-web.request-recovery.reload.${reloadAttempt}`
+      });
+    }
+    return reloaded;
+  }
+
+  function retryAction(error, options, retry) {
+    return {
+      label: normalizeText(options.actionLabel, "Retry"),
+      dismissOnRun: true,
+      async handler() {
+        try {
+          return await retry();
+        } catch (retryError) {
+          if (isRecoverableRequestError(retryError)) {
+            return report(retryError, options);
+          }
+          throw retryError;
+        }
+      }
+    };
+  }
+
+  function reloadAction(options) {
+    return {
+      label: normalizeText(options.actionLabel, "Reload"),
+      dismissOnRun: true,
+      handler() {
+        return reload({
+          label: options.label,
+          message: options.reloadFailureMessage || REQUEST_RECOVERY_RELOAD_FAILURE_MESSAGE
+        });
+      }
+    };
+  }
+
+  function report(error = null, options = {}) {
+    if (!isRecoverableRequestError(error) && options.force !== true) {
+      return null;
+    }
+
+    const runtime = errorRuntime();
+    const source = normalizeText(options.source, "shell-web.request-recovery");
+    if (!runtime) {
+      runtimeLogger.warn(
+        {
+          source,
+          error: errorMessage(error) || "unknown error"
+        },
+        "Shell request recovery could not report because the shell error runtime is unavailable."
+      );
+      return null;
+    }
+
+    const retry = typeof options.retry === "function" ? options.retry : null;
+    const action = retry
+      ? retryAction(error, options, retry)
+      : options.reload === true
+        ? reloadAction(options)
+        : null;
+
+    try {
+      return runtime.report({
+        source,
+        message: requestRecoveryMessage(error, options),
+        cause: error || null,
+        intent: "app-recoverable",
+        severity: normalizeText(options.severity, options.stale ? "warning" : "error"),
+        dedupeKey: normalizeText(options.dedupeKey),
+        dedupeWindowMs: Number.isFinite(Number(options.dedupeWindowMs))
+          ? Math.max(0, Number(options.dedupeWindowMs))
+          : 2000,
+        action
+      });
+    } catch (reportError) {
+      runtimeLogger.error(
+        {
+          source,
+          error: errorMessage(reportError) || "unknown error"
+        },
+        "Shell request recovery could not report through the shell error runtime."
+      );
+      return null;
+    }
+  }
+
+  function install() {
+    if (installedQueryObserver) {
+      return installedQueryObserver;
+    }
+
+    installedQueryObserver = installRecoverableQueryObserver({
+      app,
+      runtime: api,
+      logger: runtimeLogger
+    });
+    return installedQueryObserver;
+  }
+
+  function dispose() {
+    installedQueryObserver?.dispose?.();
+    installedQueryObserver = null;
+  }
+
+  const api = Object.freeze({
+    dispose,
+    install,
+    isRecoverableRequestError,
+    reload,
+    report
+  });
+
+  return api;
+}
+
+export {
+  createShellRequestRecoveryRuntime,
+  isRecoverableRequestError,
+  requestRecoveryMessage
+};

package/src/client/runtime/bootstrapRuntime.js

@@ -50,6 +50,14 @@ function createShellBootstrapRuntime({
   let initialized = false;
   let refreshQueue = Promise.resolve();
 
+  function requestRecoveryRuntime() {
+    if (!app.has("runtime.web-request-recovery.client")) {
+      return null;
+    }
+    const runtime = app.make("runtime.web-request-recovery.client");
+    return runtime && typeof runtime.report === "function" ? runtime : null;
+  }
+
   async function resolveBootstrapRequest(reason = "manual") {
     const handlers = resolveBootstrapPayloadHandlers(app);
     let request = {
@@ -162,6 +170,12 @@ function createShellBootstrapRuntime({
       return applyBootstrapPayload(payload, reason, request);
     } catch (error) {
       await applyBootstrapError(error, reason, request);
+      requestRecoveryRuntime()?.report?.(error, {
+        label: "App data",
+        retry: () => refresh(reason),
+        source: "shell-web.bootstrap",
+        dedupeKey: `shell-web.bootstrap.${String(reason || "manual").trim() || "manual"}.request-failed`
+      });
       runtimeLogger.warn(
         {
           reason,

package/test/provider.test.js

@@ -11,6 +11,9 @@ import {
 import {
   SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY
 } from "../src/client/asyncModuleRecovery/index.js";
+import {
+  SHELL_REQUEST_RECOVERY_RUNTIME_KEY
+} from "../src/client/requestRecovery/index.js";
 import { useShellErrorPresentationStore } from "../src/client/stores/useShellErrorPresentationStore.js";
 const CLIENT_APP_CONFIG_GLOBAL_KEY = "__JSKIT_CLIENT_APP_CONFIG__";
 
@@ -169,6 +172,32 @@ function createWindowDouble({ href = "https://example.test/home" } = {}) {
   };
 }
 
+function createQueryCacheDouble(initialQueries = []) {
+  const listeners = [];
+  const queries = [...initialQueries];
+
+  return {
+    queries,
+    getAll() {
+      return queries;
+    },
+    subscribe(listener) {
+      listeners.push(listener);
+      return () => {
+        const index = listeners.indexOf(listener);
+        if (index >= 0) {
+          listeners.splice(index, 1);
+        }
+      };
+    },
+    emit(event) {
+      for (const listener of [...listeners]) {
+        listener(event);
+      }
+    }
+  };
+}
+
 test("shell web client provider preserves append-only placement topology object exports", () => {
   const warnings = [];
   const topology = {
@@ -223,6 +252,7 @@ test("shell web client provider binds runtime and injects it into Vue app", asyn
     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);
+    assert.equal(app.singletons.has("runtime.web-request-recovery.client"), true);
 
     await provider.boot(app);
     assert.equal(app.plugins.length, 0);
@@ -233,6 +263,7 @@ test("shell web client provider binds runtime and injects it into Vue app", asyn
     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(SHELL_REQUEST_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");
@@ -253,6 +284,11 @@ test("shell web client provider binds runtime and injects it into Vue app", asyn
     assert.equal(typeof asyncModuleRecoveryRuntime.notify, "function");
     assert.equal(typeof asyncModuleRecoveryRuntime.reload, "function");
 
+    const requestRecoveryRuntime = providedByKey.get(SHELL_REQUEST_RECOVERY_RUNTIME_KEY);
+    assert.equal(typeof requestRecoveryRuntime.install, "function");
+    assert.equal(typeof requestRecoveryRuntime.report, "function");
+    assert.equal(typeof requestRecoveryRuntime.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");
@@ -319,6 +355,132 @@ test("shell refresh runtime reports recoverable retry errors as banners", async
   });
 });
 
+test("shell request recovery reports active query transport failures with retry actions", async () => {
+  await withFetchStub({ surfaceAccess: {} }, async () => {
+    const refetchCalls = [];
+    const queryCache = createQueryCacheDouble();
+    const queryClient = {
+      getQueryCache() {
+        return queryCache;
+      },
+      async refetchQueries(filters = {}, options = {}) {
+        refetchCalls.push({ filters, options });
+      }
+    };
+    const app = createAppDouble({ queryClient });
+    const provider = new ShellWebClientProvider();
+    provider.register(app);
+    await provider.boot(app);
+
+    const failedQuery = {
+      queryHash: "[\"project-access\"]",
+      queryKey: ["project-access"],
+      meta: {
+        jskit: {
+          requestRecoveryLabel: "Project access"
+        }
+      },
+      state: {
+        status: "error",
+        fetchStatus: "idle",
+        error: {
+          status: 0,
+          message: "Network request failed."
+        },
+        errorUpdateCount: 1
+      },
+      isActive() {
+        return true;
+      }
+    };
+    queryCache.emit({ type: "updated", query: failedQuery });
+
+    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,
+      "Project access could not reach the server or network. Check the connection and try again."
+    );
+    assert.equal(state.channels.banner[0].action.label, "Retry");
+
+    await state.channels.banner[0].action.handler();
+    assert.equal(refetchCalls.length, 1);
+    assert.deepEqual(refetchCalls[0].filters, {
+      queryKey: ["project-access"],
+      exact: true,
+      type: "active"
+    });
+    assert.deepEqual(refetchCalls[0].options, {
+      throwOnError: false
+    });
+  });
+});
+
+test("shell request recovery ignores ordinary active query validation failures", async () => {
+  await withFetchStub({ surfaceAccess: {} }, async () => {
+    const queryCache = createQueryCacheDouble();
+    const queryClient = {
+      getQueryCache() {
+        return queryCache;
+      },
+      async refetchQueries() {}
+    };
+    const app = createAppDouble({ queryClient });
+    const provider = new ShellWebClientProvider();
+    provider.register(app);
+    await provider.boot(app);
+
+    queryCache.emit({
+      type: "updated",
+      query: {
+        queryHash: "[\"project-access\"]",
+        queryKey: ["project-access"],
+        state: {
+          status: "error",
+          fetchStatus: "idle",
+          error: {
+            status: 422,
+            message: "Invalid input."
+          },
+          errorUpdateCount: 1
+        },
+        isActive() {
+          return true;
+        }
+      }
+    });
+
+    const errorStore = app.make("runtime.web-error.presentation-store.client");
+    assert.equal(errorStore.getState().channels.banner.length, 0);
+  });
+});
+
+test("shell bootstrap transport failures report through request recovery", async () => {
+  let fetchCalls = 0;
+  await withFetchImplementation(async () => {
+    fetchCalls += 1;
+    throw new TypeError("Failed to fetch");
+  }, async () => {
+    const app = createAppDouble();
+    const provider = new ShellWebClientProvider();
+    provider.register(app);
+    await provider.boot(app);
+
+    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,
+      "App data could not reach the server or network. Check the connection and try again."
+    );
+    assert.equal(state.channels.banner[0].action.label, "Retry");
+
+    await state.channels.banner[0].action.handler();
+    assert.equal(fetchCalls, 2);
+  });
+});
+
 test("shell web client provider reports dynamic import failures through async module recovery", async () => {
   await withFetchStub({ surfaceAccess: {} }, async () => {
     const routerErrorHandlers = [];

package/test/requestRecovery.test.js

@@ -0,0 +1,72 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createApp } from "vue";
+import {
+  SHELL_REQUEST_RECOVERY_RUNTIME_KEY,
+  isRecoverableRequestError,
+  requestRecoveryMessage,
+  useShellRequestRecoveryRuntime
+} from "../src/client/requestRecovery/index.js";
+
+test("shell request recovery classifier accepts transport failures only", () => {
+  assert.equal(isRecoverableRequestError({ status: 0, message: "Network request failed." }), true);
+  assert.equal(isRecoverableRequestError(new TypeError("Failed to fetch")), true);
+  assert.equal(isRecoverableRequestError({ code: "ECONNREFUSED", message: "fetch failed" }), true);
+  assert.equal(isRecoverableRequestError({ status: 422, message: "Invalid input." }), false);
+  assert.equal(isRecoverableRequestError(new Error("Business rule failed.")), false);
+  assert.equal(isRecoverableRequestError({ name: "AbortError", message: "The operation was aborted." }), false);
+  assert.equal(isRecoverableRequestError({ code: "ERR_CANCELED", message: "canceled" }), false);
+});
+
+test("shell request recovery message uses app-facing labels", () => {
+  assert.equal(
+    requestRecoveryMessage(null, { label: "Project access" }),
+    "Project access could not reach the server or network. Check the connection and try again."
+  );
+  assert.equal(
+    requestRecoveryMessage(null, { message: "Custom recovery copy." }),
+    "Custom recovery copy."
+  );
+});
+
+test("shell request recovery runtime composable returns null outside Vue injection context", () => {
+  assert.equal(useShellRequestRecoveryRuntime(), null);
+});
+
+test("shell request recovery runtime composable resolves the provided public runtime", () => {
+  const runtime = {
+    report(error, options) {
+      return { error, options };
+    },
+    async reload() {
+      return true;
+    }
+  };
+  const app = createApp({
+    render() {
+      return null;
+    }
+  });
+  app.provide(SHELL_REQUEST_RECOVERY_RUNTIME_KEY, runtime);
+
+  assert.equal(
+    app.runWithContext(() => useShellRequestRecoveryRuntime()),
+    runtime
+  );
+});
+
+test("shell request recovery runtime composable rejects incomplete runtimes", () => {
+  const app = createApp({
+    render() {
+      return null;
+    }
+  });
+  app.provide(SHELL_REQUEST_RECOVERY_RUNTIME_KEY, {
+    report() {}
+  });
+
+  assert.equal(
+    app.runWithContext(() => useShellRequestRecoveryRuntime()),
+    null
+  );
+});

package/test/settingsPlacementContract.test.js

@@ -171,6 +171,29 @@ test("shell-web exports async module recovery runtime access as a public client
   assert.match(providerSource, /SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY/);
 });
 
+test("shell-web exports request 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", "requestRecovery", "index.js"),
+    "utf8"
+  );
+  const providerSource = await readFile(
+    path.join(PACKAGE_DIR, "src", "client", "providers", "ShellWebClientProvider.js"),
+    "utf8"
+  );
+
+  assert.equal(
+    packageJson?.exports?.["./client/requestRecovery"],
+    "./src/client/requestRecovery/index.js"
+  );
+  assert.match(clientIndex, /useShellRequestRecoveryRuntime/);
+  assert.match(clientIndex, /SHELL_REQUEST_RECOVERY_RUNTIME_KEY/);
+  assert.match(recoveryIndex, /useShellRequestRecoveryRuntime/);
+  assert.match(recoveryIndex, /SHELL_REQUEST_RECOVERY_RUNTIME_KEY/);
+  assert.match(providerSource, /SHELL_REQUEST_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"),
@@ -298,6 +321,7 @@ test("shell-web descriptor metadata advertises adaptive shell outlets, default l
     "runtime.web-bootstrap.client",
     "runtime.web-refresh.client",
     "runtime.web-async-module-recovery.client",
+    "runtime.web-request-recovery.client",
     "runtime.web-error.client",
     "runtime.web-error.presentation-store.client"
   ]);