@jskit-ai/shell-web 0.1.163 → 0.1.165

package/fixtures/adaptive-shell/src/ScreenPage.vue

@@ -7,7 +7,7 @@ const title = computed(() => String(route.meta.title || "Shell fixture"));
 </script>
 
 <template>
-  <main class="generated-ui-screen" tabindex="-1">
+  <main tabindex="-1">
     <h1>{{ title }}</h1>
     <p>Package-owned browser fixture for the adaptive shell contract.</p>
   </main>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/shell-web",
-  "version": "0.1.163",
+  "version": "0.1.165",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -12,7 +12,6 @@
     "./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",
     "./client/navigation/usePaths": "./src/client/navigation/usePaths.js",
     "./client/navigation/useSurfaceRouteContext": "./src/client/navigation/useSurfaceRouteContext.js",
@@ -30,7 +29,7 @@
   },
   "dependencies": {
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/kernel": "0.1.159"
+    "@jskit-ai/kernel": "0.1.161"
   },
   "peerDependencies": {
     "pinia": "^3.0.4",
@@ -43,10 +42,7 @@
     "kind": "runtime",
     "capabilities": {
       "provides": [
-        "runtime.web-placement",
-        "runtime.web-error",
-        "runtime.web-async-module-recovery",
-        "runtime.web-request-recovery"
+        "client.shell"
       ],
       "requires": []
     },
@@ -109,19 +105,7 @@
             "subpath": "./test/adaptiveShellSmoke",
             "summary": "Exports reusable Playwright smoke coverage for generated adaptive shell layouts."
           }
-        ],
-        "containerTokens": {
-          "server": [],
-          "client": [
-            "runtime.web-placement.client",
-            "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"
-          ]
-        }
+        ]
       },
       "ui": {
         "placements": {
@@ -180,7 +164,7 @@
               "surfaces": [
                 "home"
               ],
-              "source": "templates/src/pages/home/settings.vue"
+              "source": "patterns/application-shell/example/src/pages/home/settings.vue"
             }
           ],
           "topology": {
@@ -360,7 +344,7 @@
                 "home"
               ],
               "order": 50,
-              "source": "templates/src/placement.js"
+              "source": "patterns/application-shell/example/src/placement.js"
             },
             {
               "id": "shell-web.home.menu.settings",
@@ -370,7 +354,7 @@
                 "home"
               ],
               "order": 100,
-              "source": "templates/src/placement.js"
+              "source": "patterns/application-shell/example/src/placement.js"
             },
             {
               "id": "shell-web.home.settings.general",
@@ -381,240 +365,11 @@
                 "home"
               ],
               "order": 100,
-              "source": "templates/src/placement.js"
+              "source": "patterns/application-shell/example/src/placement.js"
             }
           ]
         }
       }
-    },
-    "mutations": {
-      "dependencies": {
-        "runtime": {
-          "@mdi/js": "^7.4.47",
-          "@jskit-ai/kernel": "0.1.159"
-        },
-        "dev": {
-          "@playwright/test": "1.61.1"
-        }
-      },
-      "packageJson": {
-        "scripts": {
-          "dev:all": "vite",
-          "dev:home": "VITE_SURFACE=home vite"
-        }
-      },
-      "procfile": {},
-      "text": [],
-      "source": [
-        {
-          "op": "ensure-import",
-          "file": "packages/main/src/client/providers/MainClientProvider.js",
-          "defaultImport": "MenuLinkItem",
-          "from": "/src/components/menus/MenuLinkItem.vue",
-          "reason": "Bind app-owned shell menu link-item scaffold into local main client provider imports.",
-          "category": "shell-web",
-          "id": "shell-web-main-client-provider-menu-link-item-import"
-        },
-        {
-          "op": "ensure-import",
-          "file": "packages/main/src/client/providers/MainClientProvider.js",
-          "defaultImport": "SurfaceAwareMenuLinkItem",
-          "from": "/src/components/menus/SurfaceAwareMenuLinkItem.vue",
-          "reason": "Bind app-owned shell surface-aware menu link-item scaffold into local main client provider imports.",
-          "category": "shell-web",
-          "id": "shell-web-main-client-provider-surface-aware-menu-link-item-import"
-        },
-        {
-          "op": "ensure-import",
-          "file": "packages/main/src/client/providers/MainClientProvider.js",
-          "defaultImport": "TabLinkItem",
-          "from": "/src/components/menus/TabLinkItem.vue",
-          "reason": "Bind app-owned shell tab link-item scaffold into local main client provider imports.",
-          "category": "shell-web",
-          "id": "shell-web-main-client-provider-tab-link-item-import"
-        },
-        {
-          "op": "ensure-call",
-          "file": "packages/main/src/client/providers/MainClientProvider.js",
-          "callee": "registerMainClientComponent",
-          "args": [
-            "\"local.main.ui.menu-link-item\"",
-            "() => MenuLinkItem"
-          ],
-          "beforeClass": "MainClientProvider",
-          "reason": "Bind app-owned shell menu link-item token into local main client provider registry.",
-          "category": "shell-web",
-          "id": "shell-web-main-client-provider-menu-link-item-register"
-        },
-        {
-          "op": "ensure-call",
-          "file": "packages/main/src/client/providers/MainClientProvider.js",
-          "callee": "registerMainClientComponent",
-          "args": [
-            "\"local.main.ui.surface-aware-menu-link-item\"",
-            "() => SurfaceAwareMenuLinkItem"
-          ],
-          "beforeClass": "MainClientProvider",
-          "reason": "Bind app-owned shell surface-aware menu link-item token into local main client provider registry.",
-          "category": "shell-web",
-          "id": "shell-web-main-client-provider-surface-aware-menu-link-item-register"
-        },
-        {
-          "op": "ensure-call",
-          "file": "packages/main/src/client/providers/MainClientProvider.js",
-          "callee": "registerMainClientComponent",
-          "args": [
-            "\"local.main.ui.tab-link-item\"",
-            "() => TabLinkItem"
-          ],
-          "beforeClass": "MainClientProvider",
-          "reason": "Bind app-owned shell tab link-item token into local main client provider registry.",
-          "category": "shell-web",
-          "id": "shell-web-main-client-provider-tab-link-item-register"
-        }
-      ],
-      "files": [
-        {
-          "from": "templates/src/App.vue",
-          "to": "src/App.vue",
-          "ownership": "app",
-          "expectedExistingFrom": "templates/expected-existing/src/App.vue",
-          "reason": "Install full-width shell app root with shell-web error host and edge-to-edge layout.",
-          "category": "shell-web",
-          "id": "shell-web-app-root"
-        },
-        {
-          "from": "templates/src/components/ShellLayout.vue",
-          "to": "src/components/ShellLayout.vue",
-          "ownership": "app",
-          "reason": "Install app-owned shell layout component so apps can customize structure and slots.",
-          "category": "shell-web",
-          "id": "shell-web-component-shell-layout"
-        },
-        {
-          "from": "templates/src/components/menus/MenuLinkItem.vue",
-          "to": "src/components/menus/MenuLinkItem.vue",
-          "ownership": "app",
-          "reason": "Install app-owned shell menu link-item scaffold for local placement customization.",
-          "category": "shell-web",
-          "id": "shell-web-component-menu-link-item"
-        },
-        {
-          "from": "templates/src/components/menus/SurfaceAwareMenuLinkItem.vue",
-          "to": "src/components/menus/SurfaceAwareMenuLinkItem.vue",
-          "ownership": "app",
-          "reason": "Install app-owned surface-aware shell menu link-item scaffold for local placement customization.",
-          "category": "shell-web",
-          "id": "shell-web-component-surface-aware-menu-link-item"
-        },
-        {
-          "from": "templates/src/components/menus/TabLinkItem.vue",
-          "to": "src/components/menus/TabLinkItem.vue",
-          "ownership": "app",
-          "reason": "Install app-owned shell tab link-item scaffold for local placement customization.",
-          "category": "shell-web",
-          "id": "shell-web-component-tab-link-item"
-        },
-        {
-          "from": "templates/src/error.js",
-          "to": "src/error.js",
-          "ownership": "app",
-          "reason": "Install app-owned error runtime policy and presenter config scaffold.",
-          "category": "shell-web",
-          "id": "shell-web-error-config"
-        },
-        {
-          "from": "templates/src/placement.js",
-          "to": "src/placement.js",
-          "ownership": "app",
-          "reason": "Install app-owned placement registry scaffold used by shell-web placement runtime.",
-          "category": "shell-web",
-          "id": "shell-web-placement-registry"
-        },
-        {
-          "from": "templates/src/placementTopology.js",
-          "to": "src/placementTopology.js",
-          "ownership": "app",
-          "reason": "Install app-owned semantic placement topology used by shell-web placement runtime.",
-          "category": "shell-web",
-          "id": "shell-web-placement-topology"
-        },
-        {
-          "from": "templates/src/pages/home.vue",
-          "toSurface": "home",
-          "toSurfaceRoot": true,
-          "ownership": "app",
-          "expectedExistingFrom": "templates/expected-existing/src/pages/home.vue",
-          "reason": "Install shell-driven home wrapper page.",
-          "category": "shell-web",
-          "id": "shell-web-page-home-wrapper",
-          "when": {
-            "config": "surfaceDefinitions.home.enabled",
-            "equals": "true"
-          }
-        },
-        {
-          "from": "templates/src/pages/home/index.vue",
-          "toSurface": "home",
-          "toSurfacePath": "index.vue",
-          "ownership": "app",
-          "expectedExistingFrom": "templates/expected-existing/src/pages/home/index.vue",
-          "reason": "Install shell-driven home surface starter page.",
-          "category": "shell-web",
-          "id": "shell-web-page-home",
-          "when": {
-            "config": "surfaceDefinitions.home.enabled",
-            "equals": "true"
-          }
-        },
-        {
-          "from": "templates/src/pages/home/settings.vue",
-          "toSurface": "home",
-          "toSurfacePath": "settings.vue",
-          "ownership": "app",
-          "reason": "Install shell-driven home settings shell route with section navigation.",
-          "category": "shell-web",
-          "id": "shell-web-page-home-settings-shell",
-          "when": {
-            "config": "surfaceDefinitions.home.enabled",
-            "equals": "true"
-          }
-        },
-        {
-          "from": "templates/src/pages/home/settings/index.vue",
-          "toSurface": "home",
-          "toSurfacePath": "settings/index.vue",
-          "ownership": "app",
-          "reason": "Install shell-driven home settings redirect so the starter settings shell lands on a real child page.",
-          "category": "shell-web",
-          "id": "shell-web-page-home-settings",
-          "when": {
-            "config": "surfaceDefinitions.home.enabled",
-            "equals": "true"
-          }
-        },
-        {
-          "from": "templates/src/pages/home/settings/general/index.vue",
-          "toSurface": "home",
-          "toSurfacePath": "settings/general/index.vue",
-          "ownership": "app",
-          "reason": "Install shell-driven general settings child page with a tiny browser-local shell preference example.",
-          "category": "shell-web",
-          "id": "shell-web-page-home-settings-general",
-          "when": {
-            "config": "surfaceDefinitions.home.enabled",
-            "equals": "true"
-          }
-        },
-        {
-          "from": "templates/tests/e2e/adaptive-shell.spec.ts",
-          "to": "tests/e2e/adaptive-shell.spec.ts",
-          "ownership": "app",
-          "reason": "Install compact/medium/expanded Playwright smoke coverage for the adaptive shell.",
-          "category": "shell-web",
-          "id": "shell-web-test-adaptive-shell-smoke"
-        }
-      ]
     }
   }
 }

package/patterns/application-shell/PATTERN.md

@@ -0,0 +1,66 @@
+---
+id: shell/application-shell
+title: Responsive application shell
+summary: Compose the JSKIT responsive shell, semantic placements, settings navigation, and accessible adaptive-shell browser checks.
+keywords: adaptive, app, layout, navigation, placement, responsive, settings, shell
+requires: @jskit-ai/kernel, @jskit-ai/shell-web
+---
+
+# Responsive application shell
+
+## Use when
+
+Use this pattern when adding the standard responsive JSKIT shell to an existing
+application foundation.
+
+## Do not use when
+
+Do not copy the entire shell into an application that already has a coherent
+JSKIT shell. Use the narrower page-and-placement pattern for incremental UI.
+
+## Product decisions
+
+Choose the product navigation, settings sections, surfaces, labels, icons, and
+which controls remain visible at compact, medium, and expanded widths.
+
+## Framework APIs
+
+Use the shell provider, `ShellLayout`, `ShellOutlet`, link components,
+placement registry, topology, and adaptive smoke helper exported by
+`@jskit-ai/shell-web`.
+
+## Invariants
+
+- `App.vue`, the shell layout, placements, topology, and route pages agree.
+- Navigation uses semantic placements rather than direct component injection.
+- Compact controls have accessible names and at least 48 CSS-pixel targets.
+- Cached route/resource state hydrates writable UI state synchronously or with
+  immediate watchers.
+- Loading uses stable skeletons, not spinners or shifting status banners.
+- The adaptive browser check closes navigation through its public close control.
+
+## Example files
+
+`example/src/` contains the complete shell composition, standard link
+components, settings routes, placement registry, and topology. The browser
+example under `example/tests/` exercises the public adaptive-shell contract.
+The `expected-existing/` files show the minimal foundation shapes replaced by
+the complete shell; they are reference inputs, not merge instructions.
+
+## Variation points
+
+Change product navigation, surfaces, routes, settings sections, placements,
+responsive outlet mappings, labels, icons, and application-owned components.
+
+## Verification
+
+Exercise direct navigation, browser back/forward with a warm cache, keyboard
+navigation, current-link state, and compact/medium/expanded layouts. Run client
+tests and a production build.
+
+## Avoid
+
+- custom navigation registries beside placements
+- clicking Vuetify scrims or coordinates in browser tests
+- magic generated-page classes
+- source mutation or overwrite machinery

package/{templates → patterns/application-shell/example}/expected-existing/src/pages/home/index.vue

@@ -1,5 +1,5 @@
 <template>
-  <section class="generated-ui-screen generated-ui-screen--app home-start-screen d-flex flex-column ga-4">
+  <section class="home-start-screen d-flex flex-column ga-4">
     <header>
       <p class="text-overline text-medium-emphasis mb-1">Home</p>
       <h1 class="home-start-screen__title">Home base</h1>
@@ -18,9 +18,9 @@
 </template>
 
 <style scoped>
-.generated-ui-screen {
-  --generated-ui-screen-title-size: 2rem;
-  --generated-ui-screen-panel-padding: 1rem;
+.home-start-screen {
+  --home-start-title-size: 2rem;
+  --home-start-panel-padding: 1rem;
 }
 
 .home-start-screen {
@@ -29,7 +29,7 @@
 }
 
 .home-start-screen__title {
-  font-size: var(--generated-ui-screen-title-size);
+  font-size: var(--home-start-title-size);
   font-weight: 700;
   letter-spacing: 0;
   line-height: 1.08;
@@ -37,12 +37,12 @@
 }
 
 .home-start-screen__panel {
-  padding: var(--generated-ui-screen-panel-padding);
+  padding: var(--home-start-panel-padding);
 }
 
 @media (max-width: 640px) {
-  .generated-ui-screen {
-    --generated-ui-screen-title-size: 1.5rem;
+  .home-start-screen {
+    --home-start-title-size: 1.5rem;
   }
 }
 </style>

package/{templates → patterns/application-shell/example}/src/pages/home/index.vue

@@ -28,7 +28,7 @@ const health = computed(() => {
 </script>
 
 <template>
-  <section class="generated-ui-screen generated-ui-screen--app home-surface-screen d-flex flex-column ga-4">
+  <section class="home-surface-screen d-flex flex-column ga-4">
     <header class="home-surface-screen__header">
       <div>
         <p class="text-overline text-medium-emphasis mb-1">Home</p>
@@ -55,9 +55,9 @@ const health = computed(() => {
 </template>
 
 <style scoped>
-.generated-ui-screen {
-  --generated-ui-screen-title-size: 2rem;
-  --generated-ui-screen-panel-padding: 1rem;
+.home-surface-screen {
+  --home-surface-title-size: 2rem;
+  --home-surface-panel-padding: 1rem;
 }
 
 .home-surface-screen__header {
@@ -68,7 +68,7 @@ const health = computed(() => {
 }
 
 .home-surface-screen__title {
-  font-size: var(--generated-ui-screen-title-size);
+  font-size: var(--home-surface-title-size);
   font-weight: 700;
   letter-spacing: 0;
   line-height: 1.1;
@@ -80,7 +80,7 @@ const health = computed(() => {
   display: flex;
   flex-wrap: wrap;
   gap: 1rem;
-  padding: var(--generated-ui-screen-panel-padding);
+  padding: var(--home-surface-panel-padding);
 }
 
 .home-surface-screen__status {
@@ -90,8 +90,8 @@ const health = computed(() => {
 }
 
 @media (max-width: 640px) {
-  .generated-ui-screen {
-    --generated-ui-screen-title-size: 1.5rem;
+  .home-surface-screen {
+    --home-surface-title-size: 1.5rem;
   }
 
   .home-surface-screen__header {

package/{templates → patterns/application-shell/example}/src/pages/home/settings/general/index.vue

@@ -15,7 +15,7 @@ const drawerDefaultOpenModel = computed({
 </script>
 
 <template>
-  <section class="generated-ui-screen generated-ui-screen--settings settings-general-screen d-flex flex-column ga-4">
+  <section class="settings-general-screen d-flex flex-column ga-4">
     <div>
       <h2 class="text-h6 mb-2">Navigation</h2>
       <p class="text-body-2 text-medium-emphasis mb-0">

package/{templates → patterns/application-shell/example}/src/pages/home/settings.vue

@@ -4,7 +4,7 @@ import { RouterView } from "vue-router";
 </script>
 
 <template>
-  <section class="generated-ui-screen generated-ui-screen--settings settings-shell d-flex flex-column ga-4">
+  <section class="settings-shell d-flex flex-column ga-4">
     <header>
       <p class="text-overline text-medium-emphasis mb-1">Settings</p>
       <h1 class="settings-shell__title">Home settings</h1>
@@ -28,13 +28,13 @@ import { RouterView } from "vue-router";
 </template>
 
 <style scoped>
-.generated-ui-screen {
-  --generated-ui-screen-title-size: 1.85rem;
-  --generated-ui-screen-panel-padding: 1rem;
+.settings-shell {
+  --settings-shell-title-size: 1.85rem;
+  --settings-shell-panel-padding: 1rem;
 }
 
 .settings-shell__title {
-  font-size: var(--generated-ui-screen-title-size);
+  font-size: var(--settings-shell-title-size);
   font-weight: 650;
   letter-spacing: 0;
   line-height: 1.15;
@@ -49,7 +49,7 @@ import { RouterView } from "vue-router";
   display: grid;
   gap: 1rem;
   grid-template-columns: minmax(12rem, 16rem) minmax(0, 1fr);
-  padding: var(--generated-ui-screen-panel-padding);
+  padding: var(--settings-shell-panel-padding);
 }
 
 .settings-shell__content {
@@ -81,8 +81,8 @@ import { RouterView } from "vue-router";
 }
 
 @media (max-width: 960px) {
-  .generated-ui-screen {
-    --generated-ui-screen-title-size: 1.35rem;
+  .settings-shell {
+    --settings-shell-title-size: 1.35rem;
   }
 
   .settings-shell__body {

package/patterns/page-and-placement/PATTERN.md

@@ -0,0 +1,76 @@
+---
+id: ui/page-and-placement
+title: Routed page, section navigation, and placed element
+summary: Add product routes and shell extensions through file routing, semantic placements, topology, and registered component tokens.
+keywords: component, navigation, outlet, page, placement, routes, section, shell, subpages, vue
+requires: @jskit-ai/kernel, @jskit-ai/shell-web
+---
+
+# Routed page, section navigation, and placed element
+
+## Use when
+
+Use this pattern for an application-owned route page, a section with child
+routes, or a component rendered in an existing shell placement. It demonstrates
+the same public contracts for all three without a page generator.
+
+## Do not use when
+
+Do not use section navigation for a single page, add a primary link for a detail
+or workflow route, or create a new placement system when an existing semantic
+placement fits. CRUD routes should use the CRUD screen pattern.
+
+## Product decisions
+
+Decide the route, surface, navigation role, label, icon, section ownership,
+ordering, and whether the content belongs in navigation or a component outlet.
+These are product information architecture decisions, not defaults to infer from
+a filename alone.
+
+## Invariants
+
+- File routes and placement destinations agree.
+- Placement ids describe product ownership, not the authoring mechanism.
+- Child links share an explicit section owner.
+- Topology maps each semantic placement to concrete responsive outlets.
+- Placed components are registered by token through a client provider.
+- Compact navigation controls remain accessible and at least 48 CSS pixels.
+- Application source has no generated-file marker, receipt, or overwrite state.
+
+## Framework APIs
+
+Use `createPlacementRegistry()`, `addPlacement()`, `addPlacementTopology()`, and
+`ShellOutlet` from `@jskit-ai/shell-web`. Use file routes and
+`redirectToChild()` from `@jskit-ai/kernel`. Register app-owned component tokens
+through the application's normal client provider.
+
+## Example files
+
+`example/` contains a Reports section with Overview and Activity child routes,
+the matching section-navigation placements/topology, and a Sync Status component
+placed in the existing shell status area.
+
+## Variation points
+
+Change the route hierarchy, surface, semantic target, section owner, component
+token, order, label, icon, and responsive outlet mapping. Omit the parent host
+and topology when no child navigation is needed. Omit provider registration for
+link-only placements.
+
+## Verification
+
+- navigate directly to each route and through each visible link
+- verify the section index redirects to its intended child
+- verify the placed component resolves through its provider token
+- exercise compact, medium, and expanded variants
+- verify current-link state, keyboard operation, target size, and no overflow
+- run client tests and the production build
+
+## Avoid
+
+- generator-branded placement ids or CSS classes
+- navigation links for detail/workflow routes unless explicitly chosen
+- duplicated route tables beside file routing
+- hard-coded component instances where a semantic placement is required
+- placeholder pages that instruct developers to replace their content
+- provenance comments, receipts, or hidden mutation markers

package/patterns/page-and-placement/example/packages/main/src/client/providers/MainClientProvider.js

@@ -0,0 +1,14 @@
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import SyncStatusElement from "/src/components/SyncStatusElement.vue";
+
+const MainClientProvider = defineProvider({
+  id: "local.main.client",
+  requires: {
+    components: "client.components"
+  },
+  setup({ components }) {
+    components.register("local.main.ui.sync-status", SyncStatusElement);
+  }
+});
+
+export { MainClientProvider };

package/patterns/page-and-placement/example/src/components/SyncStatusElement.vue

@@ -0,0 +1,16 @@
+<template>
+  <div class="sync-status" role="status" aria-label="Catalogue synchronized">
+    <v-icon icon="mdi-cloud-check-outline" size="small" aria-hidden="true" />
+    <span class="text-body-2">Synced</span>
+  </div>
+</template>
+
+<style scoped>
+.sync-status {
+  align-items: center;
+  display: inline-flex;
+  gap: 0.5rem;
+  min-height: 48px;
+  min-width: 0;
+}
+</style>

package/patterns/page-and-placement/example/src/pages/home/reports/activity.vue

@@ -0,0 +1,8 @@
+<template>
+  <section aria-labelledby="reports-activity-title">
+    <h2 id="reports-activity-title" class="text-h5 mb-2">Activity</h2>
+    <p class="text-body-1 text-medium-emphasis mb-0">
+      Recent catalogue changes appear here.
+    </p>
+  </section>
+</template>