@jskit-ai/agent-docs 0.1.48 → 0.1.50

package/guide/agent/app-setup/a-more-interesting-shell.md

@@ -554,6 +554,52 @@ The default error policy is intent-based. Runtime code reports what kind of erro
 - `app-recoverable` uses `banner`; shell refresh and recoverable navigation failures stay visible without blocking the app.
 - `blocking` uses `dialog`; unexpected UI failures and other blocking errors require explicit attention.
 
+When app code catches a dynamic import failure itself, report it through the shell async module recovery runtime so it uses the same reload banner as router chunk failures:
+
+```js
+import { useShellAsyncModuleRecoveryRuntime } from "@jskit-ai/shell-web/client/asyncModuleRecovery";
+
+const asyncModuleRecovery = useShellAsyncModuleRecoveryRuntime();
+
+try {
+  await import("@xterm/xterm");
+} catch (error) {
+  asyncModuleRecovery?.notify(error, {
+    label: "Terminal"
+  });
+}
+```
+
+`useShellAsyncModuleRecoveryRuntime()` returns `null` when the shell runtime is not available in the current Vue context. That lets app-owned components use optional chaining instead of duplicating shell-web's internal injection token.
+
+Use the narrow `@jskit-ai/shell-web/client/asyncModuleRecovery` subpath for this runtime, especially from modules that are imported by Node-mode Vitest suites. The aggregate `@jskit-ai/shell-web/client` barrel also exports the composable for normal Vite app code, but that barrel includes `.vue` component exports and can require Vue SFC handling in tests.
+
+Request connectivity failures use a separate shell recovery path. Generated apps already configure TanStack Query to retry transient failures with capped backoff. `shell-web` then observes the app's `jskit.client.query-client` and, when an active query finishes in a transport failure such as `Network request failed.` or `Failed to fetch`, reports an `app-recoverable` banner with a `Retry` action that refetches that exact query. Normal HTTP validation and application errors stay local to the screen.
+
+Imperative app code only needs the public runtime when it catches a request failure outside the standard query/resource composables:
+
+```js
+import { useShellRequestRecoveryRuntime } from "@jskit-ai/shell-web/client/requestRecovery";
+
+const requestRecovery = useShellRequestRecoveryRuntime();
+
+async function loadProjectAccess() {
+  try {
+    return await fetch("/api/project-access");
+  } catch (error) {
+    requestRecovery?.report(error, {
+      label: "Project access",
+      retry: loadProjectAccess
+    });
+    throw error;
+  }
+}
+```
+
+`useShellRequestRecoveryRuntime()` returns `null` when the shell runtime is not available in the current Vue context. Use the narrow `@jskit-ai/shell-web/client/requestRecovery` subpath for the same reason as async module recovery: it avoids pulling `.vue` component exports into Node-mode test suites.
+
+For query-backed screens, the default is automatic. Set `meta: { jskit: { requestRecovery: false } }` only when a query deliberately owns its entire connectivity recovery UI. Set `meta: { jskit: { requestRecoveryLabel: "Project access" } }` when the default `Request` label is too generic.
+
 ### The home page talks to the backend
 
 `src/pages/home/index.vue` uses Vue Query to fetch `/api/health` and display the result in the UI.

package/guide/agent/app-setup/initial-scaffolding.md

@@ -358,7 +358,7 @@ void bootstrapClientShellApp({
 });
 ```
 
-The flow is simple once you read it in order: config in, runtime in memory, router built from that runtime, app-owned Vue plugins created once, app bootstrapped. Pinia, Vue Query, the router, and Vuetify are owned by the base app bootstrap so runtime packages share the same instances instead of carrying independent copies.
+The flow is simple once you read it in order: config in, runtime in memory, router built from that runtime, app-owned Vue plugins created once, app bootstrapped. Pinia, Vue Query, the router, and Vuetify are owned by the base app bootstrap so runtime packages share the same instances instead of carrying independent copies. Passing the same `queryClient` into `bootstrapClientShellApp(...)` also gives `shell-web` the QueryClient it observes for automatic request recovery when transport failures exhaust their normal retries.
 
 <DocsInDepth title="In depth" preview-height="15rem">
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.48",
+  "version": "0.1.50",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/client-requests.md

@@ -68,6 +68,9 @@ Error presentation rules:
 
 - Resource load failures should stay local to the screen with the runtime's `loadError` state and a retry action.
 - Do not force global banners for ordinary list/view/add-edit load failures; the shell error policy treats `resource-load` as `silent` by default.
+- Transport/connectivity failures are different from ordinary resource-load errors. `shell-web` observes the app QueryClient and reports active query failures such as `Network request failed.` or `Failed to fetch` through request recovery with a `Retry` action.
+- For imperative app-caught request failures outside the standard query/resource composables, use `useShellRequestRecoveryRuntime()` from `@jskit-ai/shell-web/client/requestRecovery` and pass a retry callback.
+- Use query meta `jskit.requestRecovery = false` only when a query owns its full connectivity recovery UI, and `jskit.requestRecoveryLabel` when the recovery banner needs a better label.
 - Use `useUiFeedback()` or `useCommand()` for user-triggered action feedback. Those flows report `action-feedback`, and the app-owned shell error policy decides the channel.
 - Use explicit shell error intents only for exceptional app-level cases: `app-recoverable` for recoverable shell/runtime failures and `blocking` for failures that require user attention.
 

package/reference/autogen/packages/shell-web.md

@@ -14,6 +14,17 @@ Use this on demand; do not load the full index at startup.
 
 ### src
 
+### `src/client/asyncModuleRecovery/index.js`
+Exports
+- `SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY`
+- `useShellAsyncModuleRecoveryRuntime`
+
+### `src/client/asyncModuleRecovery/inject.js`
+Exports
+- `SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY`
+- `isShellAsyncModuleRecoveryRuntime(value)`
+- `useShellAsyncModuleRecoveryRuntime()`
+
 ### `src/client/bootstrap/bootstrapErrorStatus.js`
 Exports
 - `resolveBootstrapErrorStatusCode(error)`
@@ -194,6 +205,12 @@ Exports
 - `useShellLayoutState`
 - `useShellLayoutStore`
 - `useShellErrorPresentationStore`
+- `SHELL_ASYNC_MODULE_RECOVERY_RUNTIME_KEY`
+- `useShellAsyncModuleRecoveryRuntime`
+- `SHELL_REQUEST_RECOVERY_RUNTIME_KEY`
+- `isRecoverableRequestError`
+- `requestRecoveryMessage`
+- `useShellRequestRecoveryRuntime`
 - `BOOTSTRAP_PAYLOAD_HANDLER_TAG`
 - `registerBootstrapPayloadHandler`
 - `resolveBootstrapPayloadHandlers`
@@ -329,6 +346,40 @@ Local functions
 - `installRouterErrorBridge(app, errorRuntime, logger)`
 - `createShellAsyncModuleRecoveryRuntime({ app, logger = null } = {})`
 
+### `src/client/requestRecovery/index.js`
+Exports
+- `SHELL_REQUEST_RECOVERY_RUNTIME_KEY`
+- `useShellRequestRecoveryRuntime`
+- `isRecoverableRequestError`
+- `requestRecoveryMessage`
+
+### `src/client/requestRecovery/inject.js`
+Exports
+- `SHELL_REQUEST_RECOVERY_RUNTIME_KEY`
+- `isShellRequestRecoveryRuntime(value)`
+- `useShellRequestRecoveryRuntime()`
+
+### `src/client/requestRecovery/runtime.js`
+Exports
+- `createShellRequestRecoveryRuntime({ app, logger = null } = {})`
+- `isRecoverableRequestError(error = null)`
+- `requestRecoveryMessage(error = null, { label = "Request", message = "" } = {})`
+Local functions
+- `normalizeText(value, fallback = "")`
+- `errorMessage(error = null)`
+- `errorCode(error = null)`
+- `errorName(error = null)`
+- `normalizeRequestErrorStatus(error = null)`
+- `isCanceledRequestError(error = null)`
+- `resolveQueryMeta(query = null)`
+- `isRequestRecoveryDisabled(query = null)`
+- `resolveQueryRecoveryLabel(query = null)`
+- `isActiveQuery(query = null)`
+- `recoverableQueryError(query = null)`
+- `createQueryRetry(queryClient, query = null)`
+- `resolveQueryHash(query = null)`
+- `installRecoverableQueryObserver({ app, runtime, logger } = {})`
+
 ### `src/client/runtime/bootstrapRuntime.js`
 Exports
 - `createShellBootstrapRuntime({ app, logger = null, fetchImplementation = globalThis.fetch, bootstrapPath = DEFAULT_BOOTSTRAP_PATH } = {})`