@jskit-ai/agent-docs 0.1.131 → 0.1.132

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

@@ -2,834 +2,63 @@
 
 # A more interesting shell
 
-In the first chapter, the app started with `shell-web` already installed. That is the normal JSKIT starting point: a real layout, navigation outlets, a first settings area, and a proper app-level error host.
-
-This still is not authentication, not database work, and not multi-surface routing. The app remains small. But it starts to look and behave like something you could actually grow.
-
-## Running the shell
-
-From inside `exampleapp`, run:
-
-```bash
-npm run dev
-npm run server
-```
-
-You want both processes running. The starter home page fetches `/api/health`, so the browser-facing dev server on port `5173` expects the backend on port `3000` to be alive as well.
-
-**Minimal: Adding `shell-web` To A Bare Scaffold**
-
-The normal `create-app` template already has `shell-web`. If you deliberately created the bare scaffold with `--minimal` or `--template minimal-shell`, install the shell before you personalize the files it claims:
-
-```bash
-npx jskit add package shell-web
-```
-
-That package addition is intentionally strict: `shell-web` only takes over scaffold files if they are still **exactly** the same as the files that `create-app --minimal` originally wrote. If you have already edited those starter files, `shell-web` refuses to claim them instead of overwriting your work.
-
-Open `http://localhost:5173/` in the browser. The app lands in the `home` surface inside a real shell with an app bar, a navigation drawer, and a settings route at `/home/settings`.
-
-Two shell pieces are worth noticing first.
-
-- Navigation lives in the drawer itself. `Home` and `Settings` are real shell menu entries from the start.
-- `Settings` is already a real nested section. Opening `/home/settings` redirects to `/home/settings/general`, and the left-side menu already contains a starter `General` entry.
-
-Open `http://localhost:5173/home/settings` in the browser to see that nested settings shell immediately:
-
-## Module features
-
-The most important idea in `shell-web` is that the app has _specific, named places_ where UI can be inserted later. JSKIT calls those places _placements_. In practice, this means later packages or generators do not have to rewrite the whole shell every time they want to add a menu entry, a widget, or a settings section.
-
-Start by asking JSKIT what public placement targets already exist:
-
-```bash
-npx jskit list-placements
-```
-
-In a fresh `shell-web` app, the result includes entries like these:
-
-```text
-Available placements:
-- shell.primary-nav (default): Primary top-level navigation for the current surface.
-  - compact -> shell-layout:primary-bottom-nav
-  - medium -> shell-layout:primary-menu
-  - expanded -> shell-layout:primary-menu
-- page.section-nav [owner:home-settings]: Navigation between child pages in the home settings section.
-  - compact -> home-settings:primary-menu
-  - medium -> home-settings:primary-menu
-  - expanded -> home-settings:primary-menu
-```
-
-This command lists semantic placements, not the content inside them. Later, when you place things into the shell, this list stays stable unless the public placement topology changes.
-
-The concrete outlets still exist, but they are implementation details. If you need to inspect them directly, use:
-
-```bash
-npx jskit list-placements --concrete
-```
-
-Those concrete target names come from real `ShellOutlet` elements in the app. See `src/components/ShellLayout.vue`:
-
-```html
-...
-<ShellOutlet target="shell-layout:top-left" />
-...
-<ShellOutlet target="shell-layout:top-right" />
-...
-<ShellOutlet
-  target="shell-layout:primary-menu"
-  default
-/>
-...
-<ShellOutlet target="shell-layout:secondary-menu" />
-...
-<ShellOutlet target="shell-layout:primary-bottom-nav" />
-...
-<ShellOutlet target="shell-layout:supporting-bottom-sheet" />
-<ShellOutlet target="shell-layout:supporting-side-panel" />
-```
-
-And the settings page introduces its own nested outlet in `src/pages/home/settings.vue`:
-
-```html
-<ShellOutlet target="home-settings:primary-menu" />
-```
-
-That nested example matters. It shows that the shell is not the only place that can host placements. A page inside the shell can define its own insertion point too. That is how JSKIT can later build menus inside sections such as settings without rewriting the whole shell.
-
-Just as importantly, `shell-web` uses that placement system itself. The starter app exposes semantic placement targets and seeds real placement entries into them. `Home` and `Settings` land in primary navigation, and `General` lands in the nested settings menu. The shell is exercising the same extension contract that later package and generator output uses.
-
-The shell also ships with a few app-owned component tokens that it can use as default link renderers. You can inspect those too:
-
-```bash
-npx jskit list-component-tokens --prefix local.main.
-```
-
-The starter result looks like this:
-
-```text
-Available placement component tokens:
-Showing link-item tokens only (token must end with "link-item"). Tip: use --all for full token list.
-- local.main.ui.menu-link-item [app:packages/main/src/client/providers/MainClientProvider.js]
-- local.main.ui.surface-aware-menu-link-item [app:packages/main/src/client/providers/MainClientProvider.js, app:src/placement.js, package:@jskit-ai/shell-web:templates/src/placement.js]
-- local.main.ui.tab-link-item [app:packages/main/src/client/providers/MainClientProvider.js]
-```
-
-The shell knows about three local link-item tokens. They are app-owned components registered by the local package, and topology uses them when an outlet needs to render links or tabs.
-
-At this point the shell is using placements itself. The next step is to add one of our own.
-
-### Adding generic elements directly
-
-To add a small UI element to the shell itself:
-
-```bash
-npx jskit generate ui-generator placed-element --name "Alerts Widget"
-```
-
-That command creates a Vue component under `src/components/` (in this case `src/components/AlertsWidgetElement.vue`), registers a local token for it, and adds a placement entry targeting `shell.status`. After running it, refresh the home page in the browser. The shell renders the app-owned widget inside one of its named placement targets.
-
-In this app, there is no need to pass `--surface`: since the app only has one enabled surface, JSKIT can infer it automatically.
-
-### Adding a page with automatic menu placement
-
-The settings host uses the same placement machinery, but the normal way to grow it is not by dropping a free-standing widget there. The more interesting case is adding a child page and letting JSKIT wire the menu entry for you.
-
-The owner in the `list-placements` output helps you reason about where child pages belong. When you see:
-
-```text
-- page.section-nav [owner:home-settings]
-```
-
-you know that the semantic placement is owned by the settings host page. So if you want a child page to appear in that menu, you should create it under that part of the route tree instead of treating the menu like a generic widget area. For example, `src/pages/home/settings/profile/index.vue` belongs to that settings section, so JSKIT can wire its preferred menu entry into `page.section-nav` with owner `home-settings` automatically.
-
-Now use the settings host the way it is normally meant to be used: add a real child page under it.
-
-```bash
-npx jskit generate ui-generator page home/settings/profile/index.vue --name "Profile"
-```
-
-This is a more interesting example than the widget case. JSKIT creates the page file, notices that `src/pages/home/settings.vue` owns the settings section navigation, and adds the preferred semantic menu entry there automatically. You do not have to write that placement entry by hand.
-
-Open `/home/settings/profile` in the browser. The settings shell shows a second real child page and a second real menu entry created by the same page-generation command. `General` comes from `shell-web`; `Profile` is the first additional settings page you add yourself. This is the important part of the chapter: the exact same placement system works both at the top shell level and inside a page-owned nested outlet.
-
-Add a second sibling page:
-
-```bash
-npx jskit generate ui-generator page home/settings/notifications/index.vue --name "Notifications"
-```
-
-Open `/home/settings/notifications` in the browser. You get a third settings menu entry without touching `settings.vue`, without writing a second menu component, and without hand-editing `src/placement.js`. JSKIT appends another placement entry targeting the same `page.section-nav` owner, so the links stack in the menu for free.
-
-The order is also easy to reason about:
-
-- `General` comes first because `shell-web` seeds it with a lower order than generated child pages.
-- `Profile` and `Notifications` both use the generator's default order, so between those two the menu keeps source order.
-
-**Routing: Child Pages Under Layouts**
-
-In JSKIT's file-based routing, a page file can act as a layout if it renders a `RouterView`.
-
-- `src/pages/home/settings.vue` owns the settings shell and wraps its child routes.
-- `src/pages/home/settings/index.vue` is just a redirect, so `/home/settings` lands on `/home/settings/general`.
-- `src/pages/home/settings/general/index.vue` is the first real child page created by the starter shell.
-- `src/pages/home/settings/profile/index.vue` becomes `/home/settings/profile` and still renders inside the layout from `settings.vue`.
-
-JSKIT uses a small helper for that redirect instead of hand-building the child path:
-
-```js
-import { redirectToChild } from "@jskit-ai/kernel/client/pageRedirects";
-
-definePage({
-  redirect: redirectToChild("general")
-});
-```
-
-This is why the `page.section-nav` owner from `list-placements` is such a useful clue: it tells you which page is acting as the host.
-
-Even an `index.vue` page can have children. If you want an index page to stay visible while child routes render underneath it, put those children under an `index/` directory such as `src/pages/home/settings/profile/index/details.vue`.
-
-**Icons: Menu Metadata Is Not The Same As Vue Icon Props**
-
-When you start customizing generated pages and menu links, icons are one of the first details you usually add.
-
-There are two different paths to keep straight:
-
-1. placement and menu metadata such as `src/placement.js`
-2. direct Vuetify icon props inside normal `.vue` components
-
-For placement metadata, prefer importing app-specific icons from `@mdi/js` in the placement file itself. The shell menu runtime accepts the resolved SVG path value and passes it through to Vuetify:
-
-```js
-import { mdiAccountCircleOutline } from "@mdi/js";
-
-addPlacement({
-  id: "home.settings.profile.link",
-  target: "page.section-nav",
-  owner: "home-settings",
-  kind: "link",
-  surfaces: ["home"],
-  props: {
-    label: "Profile",
-    to: "./profile",
-    icon: mdiAccountCircleOutline
-  }
-});
-```
-
-Do not copy raw `mdi-*` strings into a normal Vue component:
-
-```vue
-<v-list-item prepend-icon="mdi-account-circle-outline" />
-```
-
-JSKIT apps use Vuetify's SVG MDI renderer, so direct Vue icon props should use the same `@mdi/js` path or a Vuetify alias instead:
-
-```vue
-<script setup>
-import { mdiAccountCircleOutline } from "@mdi/js";
-</script>
-
-<v-list-item :prepend-icon="mdiAccountCircleOutline" />
-```
-
-So the practical rule is:
-
-- editing `src/placement.js` or other shell menu metadata: import app-specific icons from `@mdi/js` and pass the constant
-- raw `mdi-*` metadata strings are only safe for shell-web's small core normalized icon map
-- editing a normal `.vue` file: use `@mdi/js` or a Vuetify alias such as `$close`
-
-Later in the guide, `jskit doctor` will help catch the second mistake automatically.
-
-### Component tokens
-
-If you rerun the token listing, the widget command is the only command in this chapter that created an app-owned component token:
-
-```bash
-npx jskit list-component-tokens --all --prefix local.main.
-```
-
-The output includes:
-
-```text
-- local.main.ui.element.alerts-widget
-- local.main.ui.menu-link-item
-- local.main.ui.surface-aware-menu-link-item
-- local.main.ui.tab-link-item
-```
-
-That difference is useful. `npx jskit generate ui-generator placed-element` creates a new component token. `page` reuses the existing default link-item token for the parent outlet and adds a placement entry for the new route.
-
-So the shell story in this chapter is:
-
-- `ShellOutlet` defines named places where UI can appear
-- `jskit list-placements` shows those places
-- `shell-web` already uses those places for the starter `Home`, `Settings`, and `General` entries
-- `jskit generate ui-generator placed-element ...` creates app-owned UI and places it into one of them
-- `jskit generate ui-generator page ...` can also discover a parent outlet and add the right menu entry automatically
-- repeating that page command for the same host gives you a stacked menu, still without hand-editing the host page
-- nested pages can host placements too, not just the top shell
-
-That is the first real example of JSKIT behaving like an extension system rather than just a scaffold generator.
-
-## What `shell-web` owns in the app
-
-The most interesting files look roughly like this:
-
-```text
-src/
-  components/
-    AlertsWidgetElement.vue
-    ShellLayout.vue
-    menus/
-      MenuLinkItem.vue
-      SurfaceAwareMenuLinkItem.vue
-      TabLinkItem.vue
-  error.js
-  placement.js
-  pages/
-    home.vue
-    home/
-      index.vue
-      settings.vue
-      settings/
-        index.vue
-        general/
-          index.vue
-        profile/
-          index.vue
-        notifications/
-          index.vue
-```
-
-This chapter is where the default scaffold starts to feel layered instead of flat.
-
-### `package.json`
-
-The first file worth reopening is still `package.json`. Because the default app includes `shell-web`, the important shell dependency entries are already present:
-
-```json
-{
-  "dependencies": {
-    "@jskit-ai/shell-web": "0.1.152",
-    "@mdi/js": "^7.4.47"
-  }
-}
-```
-
-The important part is not just that `@jskit-ai/shell-web` appears. The package brings in shell runtime code and icon data; Vue Query is already owned by the base app bootstrap so every client package uses the same query client.
-
-It is also worth noticing what does **not** happen here. The `placed-element` and `page` commands from this chapter mutate app-owned files, but they do not add a permanent runtime dependency to `package.json`. They are tooling actions, not runtime package installs.
-
-The installed package exposes its runtime and generator metadata through
-`package.json.jskit`. The source created in the application is then reviewed
-and maintained as normal application code.
-
-### The `home` surface gets a real wrapper
-
-The surface itself did not change. `home` is still the same surface defined in `config/public.js`. What changed is the page tree inside it.
-
-In the shell-web scaffold, `src/pages/home.vue` is more than a tiny route owner with a `RouterView`. It wraps the surface in the app-owned shell layout:
-
-```vue
-<route lang="json">
-{
-  "meta": {
-    "jskit": {
-      "surface": "home"
-    }
-  }
-}
-</route>
-
-<script setup>
-import ShellLayout from "@/components/ShellLayout.vue";
-import { RouterView } from "vue-router";
-</script>
-
-<template>
-  <ShellLayout title="" subtitle="">
-    <RouterView />
-  </ShellLayout>
-</template>
-```
-
-That one change explains a lot. The `home` surface is a shell-wrapped surface. Every child page under `src/pages/home/` renders inside that app-owned `ShellLayout`.
-
-### `src/placement.js` is the placement registry
-
-The app has a placement registry file:
-
-```js
-import { createPlacementRegistry } from "@jskit-ai/shell-web/client/placement";
-
-const registry = createPlacementRegistry();
-const { addPlacement } = registry;
-
-export { addPlacement };
-
-export default function getPlacements() {
-  return registry.build();
-}
-```
-
-That file is the app-owned seam for placements. `shell-web` owns the runtime that can render placements, but the app owns the registry source that lists what should appear in those targets.
-
-After the scaffold's shell entries plus the `placed-element` and `page` commands from this chapter, the bottom of the file contains real placement entries:
-
-```js
-addPlacement({
-  id: "shell-web.home.menu.home",
-  target: "shell.primary-nav",
-  kind: "link",
-  surfaces: ["home"],
-  order: 50,
-  props: {
-    label: "Home",
-    surface: "home",
-    scopedSuffix: "/",
-    unscopedSuffix: "/",
-    exact: true
-  }
-});
-
-addPlacement({
-  id: "shell-web.home.menu.settings",
-  target: "shell.primary-nav",
-  kind: "link",
-  surfaces: ["home"],
-  order: 100,
-  props: {
-    label: "Settings",
-    surface: "home",
-    scopedSuffix: "/settings",
-    unscopedSuffix: "/settings"
-  }
-});
-
-addPlacement({
-  id: "shell-web.home.settings.general",
-  target: "page.section-nav",
-  owner: "home-settings",
-  kind: "link",
-  surfaces: ["home"],
-  order: 100,
-  props: {
-    label: "General",
-    surface: "home",
-    scopedSuffix: "/settings/general",
-    unscopedSuffix: "/settings/general",
-    to: "./general"
-  }
-});
-
-addPlacement({
-  id: "ui-generator.element.alerts-widget",
-  target: "shell.status",
-  kind: "component",
-  surfaces: ["home"],
-  order: 155,
-  componentToken: "local.main.ui.element.alerts-widget"
-});
-
-addPlacement({
-  id: "ui-generator.page.home.settings.profile.link",
-  target: "page.section-nav",
-  owner: "home-settings",
-  kind: "link",
-  surfaces: ["home"],
-  order: 155,
-  props: {
-    label: "Profile",
-    surface: "home",
-    scopedSuffix: "/settings/profile",
-    unscopedSuffix: "/settings/profile",
-    to: "./profile"
-  }
-});
-
-addPlacement({
-  id: "ui-generator.page.home.settings.notifications.link",
-  target: "page.section-nav",
-  owner: "home-settings",
-  kind: "link",
-  surfaces: ["home"],
-  order: 155,
-  props: {
-    label: "Notifications",
-    surface: "home",
-    scopedSuffix: "/settings/notifications",
-    unscopedSuffix: "/settings/notifications",
-    to: "./notifications"
-  }
-});
-```
-
-That snippet shows the full placement contract clearly:
-
-- the target says which semantic placement should receive the entry
-- the owner disambiguates page-owned semantic placements such as `page.section-nav`
-- `kind: "link"` lets topology choose the concrete link renderer for the current layout
-- component placements still provide their own `componentToken`
-- `props.to` tells the generated menu link which child route to open
-- `props.icon`, when you add one, belongs to menu metadata rather than direct Vuetify icon rendering
-- the surface list says where it is active
-- lower `order` values come first
-- when multiple entries target the same semantic placement with the same order, the shell keeps their source order
-
-That is why the settings menu shows `General` first, followed by `Profile` and `Notifications`: `General` is seeded by `shell-web` with a lower order, while the two generated pages share the same later order and keep their source order.
-
-So the shell itself remains stable. What changes is the registry that feeds it.
-
-### The local client provider publishes the app-owned components
-
-The placement registry only points at tokens. Those tokens still need to resolve to real Vue components somewhere. That happens in the app-local client provider in `packages/main/src/client/providers/MainClientProvider.js`.
-
-After the scaffold's shell registrations and the `Alerts Widget` generator command, that file contains registrations like these:
-
-```js
-import AlertsWidgetElement from "/src/components/AlertsWidgetElement.vue";
-
-registerMainClientComponent("local.main.ui.element.alerts-widget", () => AlertsWidgetElement);
-
-registerMainClientComponent("local.main.ui.menu-link-item", () => MenuLinkItem);
-registerMainClientComponent("local.main.ui.surface-aware-menu-link-item", () => SurfaceAwareMenuLinkItem);
-registerMainClientComponent("local.main.ui.tab-link-item", () => TabLinkItem);
-```
-
-This is the same app-local provider seam from the previous chapter, and this chapter shows why it matters. The provider is what lets the placement runtime resolve app-owned components by token instead of hard-coding imports inside the shell runtime.
-
-The `Profile` and `Notifications` pages did not need to add another provider registration because they reuse the existing `local.main.ui.surface-aware-menu-link-item` token for their menu entries.
-
-So the flow is:
-
-1. a placement entry names a component token
-2. the local client provider publishes that token
-3. the `ShellOutlet` resolves it at runtime
-
-That is why the placement system feels dynamic even though the app still owns all of the concrete Vue files.
-
-### `App.vue` and `error.js` provide shell-level errors
-
-The top-level app root includes the normal route outlet and the shell error host:
-
-```vue
-<script setup>
-import { RouterView } from "vue-router";
-import ShellErrorHost from "@jskit-ai/shell-web/client/components/ShellErrorHost";
-</script>
-
-<template>
-  <v-app>
-    <RouterView />
-    <ShellErrorHost />
-  </v-app>
-</template>
-```
-
-That host is backed by the app-owned `src/error.js` file:
-
-```js
-import { createDefaultErrorPolicy } from "@jskit-ai/shell-web/client/error";
-
-export default Object.freeze({
-  defaultPresenterId: "material.snackbar",
-  policy: createDefaultErrorPolicy({
-    resourceLoadChannel: "silent",
-    actionFeedbackChannel: "snackbar",
-    appRecoverableChannel: "banner",
-    blockingChannel: "dialog"
-  }),
-  presenters: []
-});
-```
-
-The idea is the same as with placements: `shell-web` provides the runtime, but the app owns the configuration file that the runtime reads.
-
-The default error policy is intent-based. Runtime code reports what kind of error happened and the app-owned policy decides the presentation:
-
-- `resource-load` uses `silent`; the screen keeps the load message and retry action local.
-- `action-feedback` uses `snackbar`; saves, commands, and other user-triggered actions report through one lightweight feedback channel.
-- `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 safe-read 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.
-
-That recovery path is intentionally a safe `GET`/`HEAD` read refetch system, not a general HTTP replay system. User-visible reads should go through Query-backed JSKIT primitives such as `useEndpointResource()`, `useList()`, `useView()`, `useAddEdit()`, or generated CRUD screen composables. Those primitives mark Query entries with `jskit.requestRecoveryMethod`, so the shell only offers Retry for safe reads. Do not catch raw `fetch(...)` failures in each panel just to call the shell recovery runtime manually.
-
-These neutral request and CRUD client APIs are exported by `@jskit-ai/http-web`. They do not require the users, authentication, uploads, storage, or database products.
-
-For a custom endpoint read, attach the recovery label to the Query-backed resource:
-
-```js
-const projectAccess = useEndpointResource({
-  queryKey: ["project-access", projectId],
-  path: `/api/projects/${projectId}/access`,
-  requestRecoveryLabel: "Project access"
-});
-```
-
-If you need lower-level Query options, the same metadata can live on query meta:
-
-```js
-const projectAccess = useEndpointResource({
-  queryKey: ["project-access", projectId],
-  path: `/api/projects/${projectId}/access`,
-  queryOptions: {
-    meta: {
-      jskit: {
-        requestRecoveryLabel: "Project access",
-        requestRecoveryMethod: "GET"
-      }
-    }
-  }
-});
-```
-
-For JSKIT read-composable screens, the default is automatic. Hand-written TanStack Query reads outside those composables must set `meta.jskit.requestRecoveryMethod` to `GET` or `HEAD`; unmarked queries are ignored by the shell recovery observer. Set `meta: { jskit: { requestRecovery: false } }` only when a query deliberately owns its entire connectivity recovery UI.
-
-Writes are different. JSKIT does not automatically replay `POST`, `PATCH`, `PUT`, or `DELETE` after a network failure because the server may already have received the request. Save and command screens keep ownership of mutation state, field errors, conflict handling, and user feedback.
-
-Some apps need API URLs to be scoped by the active route before the browser request is sent. Configure that once at app startup instead of replacing `fetchImpl` in a local transport wrapper:
-
-```js
-import { configureHttpWebClient } from "@jskit-ai/http-web/client/lib/httpClient";
-
-configureHttpWebClient({
-  csrf: {
-    enabled: false
-  },
-  resolveRequestUrl(url, context) {
-    if (!url.startsWith("/api/")) {
-      return url;
-    }
-
-    const projectSlug = readProjectSlugFromAppRoute();
-    return url.replace(/^\/api\//u, `/api/app/${encodeURIComponent(projectSlug)}/`);
-  }
-});
-```
-
-Call `configureHttpWebClient()` before Vue mounts or before JSKIT composables are created. The resolver can close over the app router/store when it needs route data, and the `context` argument carries request details such as `originalUrl`, `method`, `requestOptions`, and whether the request is a stream. After configuration, normal `useEndpointResource()`, `useList()`, `useView()`, `useAddEdit()`, and `useCommand()` calls use the configured client. `resolveRequestUrl` runs after JSKIT adds query strings and before the underlying browser `fetch`, so request recovery metadata, JSON:API transport, credentials, CSRF, and command feedback stay on the standard path.
-
-For packages that create their own client, use the same lower-level hook directly:
-
-```js
-import { createTransientRetryHttpClient } from "@jskit-ai/http-runtime/client";
-
-const studioHttpClient = createTransientRetryHttpClient({
-  credentials: "include",
-  csrf: {
-    enabled: false
-  },
-  resolveRequestUrl(url) {
-    return scopedStudioApiUrl(url);
-  }
-});
-```
-
-### 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.
-
-That is why this chapter keeps running both `npm run dev` and `npm run server`. The page expects the backend to be alive.
-
-This matters because it is a tiny example of the frontend and backend participating in the same shell. The request itself is simple, but it proves the shell can surface runtime status instead of only rendering static chrome.
-
-### The first client stores appear
-
-`shell-web` also exposes app-facing Pinia stores:
-
-```js
-import {
-  useShellLayoutStore,
-  useShellErrorPresentationStore
-} from "@jskit-ai/shell-web/client";
-```
-
-`useShellLayoutStore()` owns the shell drawer state:
-
-- whether the drawer is open right now
-- whether the drawer should open by default on load
-
-The closed presentation is adaptive and uses Vuetify's Material navigation
-components. On compact/mobile layouts the temporary drawer closes completely.
-On medium and expanded layouts it collapses to a navigation rail by default,
-so primary navigation remains visible. Opening it restores the full drawer.
-Escape and outside dismissal close only the compact temporary drawer and return
-focus to the shell navigation toggle. They do not collapse permanent desktop
-navigation.
-
-The open drawer is content-aware by default. After the visible semantic
-placements and fonts settle, `ShellLayout` measures the rendered labels and
-uses Material's 12px outer item inset and one `navigationItemSpacing` value for
-the icon-to-label gap and the space between the widest label and the drawer
-edge. The spacing defaults to 12 CSS pixels and can be set from 8–24px. The
-shell remeasures when placements, localization, fonts, spacing, the active
-surface, or the window layout change, and clamps unusually long labels to a safe range. The
-surface label appears once in the top app bar; the drawer starts with its
-destinations instead of repeating that label as an uppercase subheader.
-
-The closed desktop rail remains 80 CSS pixels wide by default, with every icon
-and its Material selected-state indicator centred in the rail. The expanded
-drawer uses the same icon centreline, so toggling the drawer reveals or hides
-labels without making the icons jump sideways. The empty space around a 24px
-icon in the default rail is intentional Material touch/indicator space, not a
-second drawer padding. Products that deliberately need a denser rail can set
-`railWidth`; the shell still enforces a 48px minimum target. Rail tooltips use
-one explicit opaque theme color pair and open on pointer hover or keyboard
-focus.
-
-The app-owned `ShellLayout` can opt into a fully hidden wide drawer when the
-product has another discoverable navigation affordance:
-
-```vue
-<ShellLayout desktop-drawer-closed-mode="hidden">
-  <RouterView />
-</ShellLayout>
-```
-
-The default is `desktop-drawer-closed-mode="rail"`. Prefer that Material 3
-pattern; do not imitate a rail with custom CSS or a second menu registry.
-
-Applications that need product-specific dimensions or spacing can use the
-public props instead of overriding Vuetify drawer CSS:
-
-```vue
-<ShellLayout :drawer-width="280" :rail-width="64" :navigation-item-spacing="12">
-  <RouterView />
-</ShellLayout>
-```
-
-Omit `drawer-width` to retain content-aware sizing. Omit `rail-width` to retain
-the 80px Material navigation-rail default. Drawer overrides are clamped to
-120–360px and rail overrides to 48–160px so shell navigation cannot consume an
-unsafe share of the viewport or shrink below its touch targets. The app-owned
-`src/components/ShellLayout.vue` wrapper also forwards
-`navigation-item-spacing`, so an application does not need to copy or restyle
-the drawer implementation.
-
-### Updating an existing shell app
-
-Commit the app's work and run:
+Use `@jskit-ai/shell-web` when the product needs responsive navigation,
+semantic placements, settings sections, and a consistent application error
+host.
 
 ```bash
-npm run jskit:update
-```
-
-Keep the generated/app-owned `src/components/ShellLayout.vue` wrapper and let
-it continue forwarding attributes to the package component. No copied drawer,
-`.v-navigation-drawer` CSS, duplicate surface heading, or replacement smoke
-test is required. If the product intentionally wants a denser desktop rail,
-set the supported prop in that wrapper, for example `:rail-width="64"`; omit it
-to keep the Material 3 80px default.
-
-`useShellErrorPresentationStore()` exposes the current banner, snackbar, and dialog presentation state behind `ShellErrorHost`.
-
-The simplest direct store usage looks like this:
-
-```vue
-<script setup>
-import { computed } from "vue";
-import { useShellLayoutStore } from "@jskit-ai/shell-web/client";
-
-const shellLayout = useShellLayoutStore();
-
-const drawerDefaultOpenModel = computed({
-  get() {
-    return shellLayout.drawerDefaultOpen;
-  },
-  set(value) {
-    shellLayout.setDrawerDefaultOpen(Boolean(value));
-  }
-});
-</script>
+npm install @jskit-ai/shell-web
 ```
 
-That is the raw shared store behind the starter `General` settings page. It is just normal Pinia state and actions: read `drawerDefaultOpen`, write it back through `setDrawerDefaultOpen(...)`, and the shell reacts.
+Installing the package supplies runtime APIs; it does not rewrite the app. Use
+the `shell/application-shell` pattern for a complete shell or
+`ui/page-and-placement` for a smaller addition to an existing shell.
 
-The same store also exposes the live drawer state through `drawerOpen`, plus `setDrawerOpen(...)` and `toggleDrawer()` for components that need to control the drawer directly instead of only changing its default preference.
+## The shell contract
 
-You do not need either store very often in this chapter, because `shell-web` already mounts the shell and error host for you. The starter `General` settings page uses the higher-level `useShellLayoutState()` helper instead of talking to `useShellLayoutStore()` directly, because that helper combines the store-backed drawer state with the current route and surface context that `ShellLayout` also needs.
+- File routes remain application source.
+- Placements describe semantic destinations such as primary navigation,
+  section navigation, profile controls, and status elements.
+- Topology maps those placements to concrete outlets at compact, medium, and
+  expanded widths.
+- App-owned components are registered by stable component id through the
+  client provider.
+- Navigation links use the shell link components so current-route and surface
+  behavior stays consistent.
 
-That distinction is worth noticing:
+This is composition, not code injection. There is one visible placement
+registry and one route tree to inspect.
 
-- runtime services still do the operational work
-- Pinia stores are the normal Vue-facing shared-state surface
-
-### The first settings route appears
-
-`shell-web` also creates a settings shell for the `home` surface:
-
-```text
-src/pages/home/settings.vue
-src/pages/home/settings/index.vue
-src/pages/home/settings/general/index.vue
-```
-
-The important host file is still `src/pages/home/settings.vue`:
-
-```vue
-<v-list nav density="comfortable" rounded="lg" border>
-  <ShellOutlet target="home-settings:primary-menu" />
-</v-list>
-
-<RouterView />
-```
-
-This file matters for the same reason as `ShellLayout.vue`: it creates another named extension point instead of hard-coding a finished settings UI. The difference is that this one lives inside a page, not at the top shell level.
-
-The starter shell uses a real child-page structure right away:
-
-- `src/pages/home/settings/index.vue` is only a redirect into the first child page
-- `src/pages/home/settings/general/index.vue` is the first real settings page
-- `src/placement.js` already seeds a `General` link into `page.section-nav` with owner `home-settings`
-
-When you need that landing redirect yourself, use the same helper pattern:
-
-```js
-import { redirectToChild } from "@jskit-ai/kernel/client/pageRedirects";
-
-definePage({
-  redirect: redirectToChild("general")
-});
-```
+## Product decisions
 
-That is what makes the page-generation examples in this chapter important. They are not inventing a new pattern. They are extending the exact same host-and-child-page structure that `shell-web` already uses for its own starter `General` page.
+Choose the surfaces, routes, navigation hierarchy, labels, icons, section
+ownership, ordering, and compact behavior. Do not infer primary navigation from
+every route: detail and workflow pages usually should not appear there.
 
-### What did not change
+## UI invariants
 
-It is also worth being explicit about what `shell-web` does **not** do yet:
+- Compact controls have accessible names and at least 48 CSS-pixel targets.
+- Loading uses layout-stable skeletons, never indeterminate spinners.
+- Mutation failures use the standard toast instead of banners that push the
+  page down.
+- Cached route or resource data hydrates writable state immediately.
+- Browser back/forward restores the selected route and screen context.
 
-- it does not add authentication
-- it does not add a database
-- it does not add new surfaces
-- it does not change the local server provider model
+## Adaptive drawer
 
-The app is still structurally simple. `shell-web` just makes that simple app behave like a shell instead of a loose page.
+Use Vuetify Material navigation. On compact/mobile layouts, close dismisses the
+temporary drawer. Wide layouts normally use
+`desktopDrawerClosedMode="rail"`; choose `hidden` only when another navigation
+affordance remains. The public `drawerWidth`, `railWidth`, and
+`navigationItemSpacing` controls own density and spacing. The standard 80px
+rail centres 48px targets, and drawer items keep an outer inset of 12 CSS pixels.
+Do not override private shell CSS to imitate these states.
 
-## Summary
+## Verification
 
-After this chapter, the app is still small, but you have inspected the shell shape it starts with. `shell-web` provides an app-owned shell layout, a placement registry, a shell error host, menu-link tokens in the local client provider, real drawer navigation, and the first nested settings section under `home`.
+Exercise direct URLs, link navigation, current-link state, keyboard operation,
+warm-cache return navigation, and compact/medium/expanded widths. Run the
+client tests and production build.
 
-More importantly, this chapter is where placements stop being theory. The shell already uses them for `Home`, `Settings`, and the starter `General` settings page. Then you inspect the available targets, place real UI into the outer shell, and add more child settings pages that automatically land in the nested settings menu. That is the first real example of JSKIT working as an extension system rather than just a scaffold generator.
+Do not add a second navigation registry, generator markers, placement receipts,
+or source-append machinery.