@jskit-ai/shell-web 0.1.36 → 0.1.38

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/shell-web",
-  version: "0.1.36",
+  version: "0.1.38",
   kind: "runtime",
   description: "Web shell layout runtime with outlet-based placement contributions.",
   dependsOn: [],
@@ -99,6 +99,14 @@ export default Object.freeze({
             order: 100,
             componentToken: "local.main.ui.surface-aware-menu-link-item",
             source: "templates/src/placement.js"
+          },
+          {
+            id: "shell-web.home.settings.general",
+            target: "home-settings:primary-menu",
+            surfaces: ["home"],
+            order: 100,
+            componentToken: "local.main.ui.surface-aware-menu-link-item",
+            source: "templates/src/placement.js"
           }
         ]
       }
@@ -109,7 +117,7 @@ export default Object.freeze({
       runtime: {
         "@mdi/js": "^7.4.47",
         "@tanstack/vue-query": "^5.90.5",
-        "@jskit-ai/kernel": "0.1.37",
+        "@jskit-ai/kernel": "0.1.39",
         "vuetify": "^4.0.0"
       },
       dev: {}
@@ -275,9 +283,18 @@ export default Object.freeze({
         toSurface: "home",
         toSurfacePath: "settings/index.vue",
         ownership: "app",
-        reason: "Install shell-driven home settings landing page with a tiny browser-local shell preference example.",
+        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"
+      },
+      {
+        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"
       }
     ]
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/shell-web",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -24,7 +24,8 @@
   "dependencies": {
     "@mdi/js": "^7.4.47",
     "@tanstack/vue-query": "^5.90.5",
-    "@jskit-ai/kernel": "0.1.37",
+    "@jskit-ai/kernel": "0.1.39",
+    "pinia": "^3.0.4",
     "vuetify": "^4.0.0"
   }
 }

package/src/client/components/ShellErrorHost.vue

@@ -1,19 +1,16 @@
 <script setup>
 import { computed } from "vue";
 import {
-  useShellWebErrorPresentationState,
   useShellWebErrorRuntime
 } from "../error/inject.js";
+import { useShellErrorPresentationStore } from "../stores/useShellErrorPresentationStore.js";
 
 const runtime = useShellWebErrorRuntime();
-const {
-  state,
-  store
-} = useShellWebErrorPresentationState();
-
-const snackbarEntry = computed(() => state.value.channels.snackbar[0] || null);
-const bannerEntries = computed(() => state.value.channels.banner || []);
-const dialogEntry = computed(() => state.value.channels.dialog[0] || null);
+const store = useShellErrorPresentationStore();
+
+const snackbarEntry = computed(() => store.channels.snackbar[0] || null);
+const bannerEntries = computed(() => store.channels.banner || []);
+const dialogEntry = computed(() => store.channels.dialog[0] || null);
 
 function resolveSeverityColor(severity = "error") {
   const normalized = String(severity || "error").trim().toLowerCase();

package/src/client/components/ShellSurfaceAwareMenuLinkItem.vue

@@ -27,11 +27,11 @@ const props = defineProps({
     type: String,
     default: ""
   },
-  workspaceSuffix: {
+  scopedSuffix: {
     type: String,
     default: "/"
   },
-  nonWorkspaceSuffix: {
+  unscopedSuffix: {
     type: String,
     default: "/"
   },
@@ -61,8 +61,8 @@ const resolvedTo = computed(() => {
     surface: props.surface,
     currentSurfaceId: currentSurfaceId.value,
     placementContext: placementContext.value,
-    workspaceSuffix: props.workspaceSuffix,
-    nonWorkspaceSuffix: props.nonWorkspaceSuffix,
+    scopedSuffix: props.scopedSuffix,
+    unscopedSuffix: props.unscopedSuffix,
     routeParams: route.params || {},
     resolvePagePath(relativePath, options = {}) {
       return resolveShellLinkPath({

package/src/client/components/ShellTabLinkItem.vue

@@ -25,11 +25,11 @@ const props = defineProps({
     type: String,
     default: ""
   },
-  workspaceSuffix: {
+  scopedSuffix: {
     type: String,
     default: "/"
   },
-  nonWorkspaceSuffix: {
+  unscopedSuffix: {
     type: String,
     default: "/"
   },
@@ -55,8 +55,8 @@ const resolvedTo = computed(() => {
     surface: props.surface,
     currentSurfaceId: currentSurfaceId.value,
     placementContext: placementContext.value,
-    workspaceSuffix: props.workspaceSuffix,
-    nonWorkspaceSuffix: props.nonWorkspaceSuffix,
+    scopedSuffix: props.scopedSuffix,
+    unscopedSuffix: props.unscopedSuffix,
     routeParams: route.params || {},
     resolvePagePath(relativePath, options = {}) {
       return resolveShellLinkPath({

package/src/client/composables/useShellLayoutState.js

@@ -1,16 +1,14 @@
-import { computed, ref } from "vue";
+import { computed } from "vue";
+import { storeToRefs } from "pinia";
 import { useRoute } from "vue-router";
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface";
 import { useWebPlacementContext } from "../placement/inject.js";
+import { useShellLayoutStore } from "../stores/useShellLayoutStore.js";
 import {
   readPlacementSurfaceConfig,
   resolveSurfaceDefinitionFromPlacementContext,
   resolveSurfaceIdFromPlacementPathname
 } from "../placement/surfaceContext.js";
-import {
-  readDrawerDefaultOpenPreference,
-  writeDrawerDefaultOpenPreference
-} from "./shellLayoutDrawerPreference.js";
 
 function toSurfaceLabel(surfaceId = "") {
   const normalizedSurfaceId = String(surfaceId || "").trim().toLowerCase();
@@ -25,17 +23,9 @@ function toSurfaceLabel(surfaceId = "") {
     .join(" ");
 }
 
-const drawerDefaultOpen = ref(readDrawerDefaultOpenPreference());
-const drawerOpen = ref(drawerDefaultOpen.value);
-
-function setDrawerDefaultOpen(open) {
-  const normalized = Boolean(open);
-  drawerDefaultOpen.value = normalized;
-  drawerOpen.value = normalized;
-  writeDrawerDefaultOpenPreference(normalized);
-}
-
 function useShellLayoutState(props = {}) {
+  const shellLayoutStore = useShellLayoutStore();
+  const { drawerDefaultOpen, drawerOpen } = storeToRefs(shellLayoutStore);
   let route = null;
   try {
     route = useRoute();
@@ -46,7 +36,7 @@ function useShellLayoutState(props = {}) {
   const { context: placementContext } = useWebPlacementContext();
 
   function toggleDrawer() {
-    drawerOpen.value = !drawerOpen.value;
+    shellLayoutStore.toggleDrawer();
   }
 
   const resolvedSurface = computed(() => {
@@ -93,7 +83,7 @@ function useShellLayoutState(props = {}) {
   return Object.freeze({
     drawerDefaultOpen,
     drawerOpen,
-    setDrawerDefaultOpen,
+    setDrawerDefaultOpen: shellLayoutStore.setDrawerDefaultOpen,
     toggleDrawer,
     resolvedSurface,
     resolvedSurfaceLabel

package/src/client/error/index.js

@@ -1,2 +1,3 @@
 export { createDefaultErrorPolicy } from "./policy.js";
 export { useShellWebErrorRuntime } from "./inject.js";
+export { useShellErrorPresentationStore } from "../stores/useShellErrorPresentationStore.js";

package/src/client/error/inject.js

@@ -1,19 +1,7 @@
 import {
-  inject,
-  onBeforeUnmount,
-  onMounted,
-  shallowRef
+  inject
 } from "vue";
 
-const EMPTY_PRESENTATION_STATE = Object.freeze({
-  revision: 0,
-  channels: Object.freeze({
-    snackbar: Object.freeze([]),
-    banner: Object.freeze([]),
-    dialog: Object.freeze([])
-  })
-});
-
 const EMPTY_ERROR_RUNTIME = Object.freeze({
   report() {
     return Object.freeze({
@@ -60,24 +48,6 @@ const EMPTY_ERROR_RUNTIME = Object.freeze({
   }
 });
 
-const EMPTY_PRESENTATION_STORE = Object.freeze({
-  getState() {
-    return EMPTY_PRESENTATION_STATE;
-  },
-  subscribe() {
-    return () => {};
-  },
-  present() {
-    throw new Error("Shell web error presentation store is not available.");
-  },
-  dismiss() {
-    return 0;
-  },
-  clear() {
-    return 0;
-  }
-});
-
 function useShellWebErrorRuntime({ required = false } = {}) {
   const runtime = inject("jskit.shell-web.runtime.web-error.client", null);
   if (runtime && typeof runtime.report === "function") {
@@ -91,48 +61,7 @@ function useShellWebErrorRuntime({ required = false } = {}) {
   return EMPTY_ERROR_RUNTIME;
 }
 
-function useShellWebErrorPresentationStore({ required = false } = {}) {
-  const store = inject("jskit.shell-web.runtime.web-error.presentation-store.client", null);
-  if (store && typeof store.getState === "function" && typeof store.subscribe === "function") {
-    return store;
-  }
-
-  if (required) {
-    throw new Error("Shell web error presentation store is not available in Vue injection context.");
-  }
-
-  return EMPTY_PRESENTATION_STORE;
-}
-
-function useShellWebErrorPresentationState({ required = false } = {}) {
-  const store = useShellWebErrorPresentationStore({ required });
-  const state = shallowRef(store.getState());
-  let unsubscribe = null;
-
-  onMounted(() => {
-    unsubscribe = store.subscribe((nextState) => {
-      state.value = nextState;
-    });
-  });
-
-  onBeforeUnmount(() => {
-    if (typeof unsubscribe === "function") {
-      unsubscribe();
-      unsubscribe = null;
-    }
-  });
-
-  return Object.freeze({
-    state,
-    store
-  });
-}
-
 export {
   EMPTY_ERROR_RUNTIME,
-  EMPTY_PRESENTATION_STORE,
-  EMPTY_PRESENTATION_STATE,
-  useShellWebErrorRuntime,
-  useShellWebErrorPresentationStore,
-  useShellWebErrorPresentationState
+  useShellWebErrorRuntime
 };

package/src/client/error/presentationDefaults.js

@@ -0,0 +1,31 @@
+const EMPTY_PRESENTATION_STATE = Object.freeze({
+  revision: 0,
+  channels: Object.freeze({
+    snackbar: Object.freeze([]),
+    banner: Object.freeze([]),
+    dialog: Object.freeze([])
+  })
+});
+
+const EMPTY_PRESENTATION_STORE = Object.freeze({
+  getState() {
+    return EMPTY_PRESENTATION_STATE;
+  },
+  subscribe() {
+    return () => {};
+  },
+  present() {
+    throw new Error("Shell web error presentation store is not available.");
+  },
+  dismiss() {
+    return 0;
+  },
+  clear() {
+    return 0;
+  }
+});
+
+export {
+  EMPTY_PRESENTATION_STATE,
+  EMPTY_PRESENTATION_STORE
+};

package/src/client/index.js

@@ -14,6 +14,8 @@ export { default as ShellMenuLinkItem } from "./components/ShellMenuLinkItem.vue
 export { default as ShellSurfaceAwareMenuLinkItem } from "./components/ShellSurfaceAwareMenuLinkItem.vue";
 export { default as ShellTabLinkItem } from "./components/ShellTabLinkItem.vue";
 export { useShellLayoutState } from "./composables/useShellLayoutState.js";
+export { useShellLayoutStore } from "./stores/useShellLayoutStore.js";
+export { useShellErrorPresentationStore } from "./stores/useShellErrorPresentationStore.js";
 
 const clientProviders = Object.freeze([ShellWebClientProvider]);
 

package/src/client/providers/ShellWebClientProvider.js

@@ -22,6 +22,7 @@ import {
   createErrorPresentationStore
 } from "../error/store.js";
 import { createWebPlacementRuntime } from "../placement/runtime.js";
+import { useShellErrorPresentationStore } from "../stores/useShellErrorPresentationStore.js";
 import { buildSurfaceConfigContext } from "../placement/surfaceContext.js";
 
 // Keep this constant for diagnostics, but keep import() below as a literal string so Vite can statically analyze it.
@@ -292,6 +293,12 @@ class ShellWebClientProvider {
     if (!vueApp || typeof vueApp.provide !== "function" || typeof vueApp.use !== "function") {
       return;
     }
+    const pinia = app.make("jskit.client.pinia");
+    if (!pinia) {
+      throw new Error("ShellWebClientProvider requires Pinia installed in the client app.");
+    }
+    const errorPresentationStore = app.make("runtime.web-error.presentation-store.client");
+    useShellErrorPresentationStore(pinia).attachRuntimeStore(errorPresentationStore);
 
     vueApp.use(VueQueryPlugin, {
       queryClient: app.make("shell.web.query-client")
@@ -300,7 +307,7 @@ class ShellWebClientProvider {
     vueApp.provide("jskit.shell-web.runtime.web-error.client", errorRuntime);
     vueApp.provide(
       "jskit.shell-web.runtime.web-error.presentation-store.client",
-      app.make("runtime.web-error.presentation-store.client")
+      errorPresentationStore
     );
 
     installVueErrorBridge(vueApp, errorRuntime, logger);

package/src/client/stores/useShellErrorPresentationStore.js

@@ -0,0 +1,96 @@
+import { computed, markRaw, shallowRef } from "vue";
+import { defineStore } from "pinia";
+import { EMPTY_PRESENTATION_STATE, EMPTY_PRESENTATION_STORE } from "../error/presentationDefaults.js";
+
+function normalizePresentationState(nextState) {
+  if (!nextState || typeof nextState !== "object") {
+    return EMPTY_PRESENTATION_STATE;
+  }
+
+  return nextState;
+}
+
+function isPresentationRuntimeStore(value) {
+  return Boolean(
+    value &&
+      typeof value.getState === "function" &&
+      typeof value.subscribe === "function" &&
+      typeof value.present === "function" &&
+      typeof value.dismiss === "function" &&
+      typeof value.clear === "function"
+  );
+}
+
+export const useShellErrorPresentationStore = defineStore("jskit.shell-web.error-presentation", () => {
+  const runtimeStore = shallowRef(markRaw(EMPTY_PRESENTATION_STORE));
+  const presentationState = shallowRef(EMPTY_PRESENTATION_STATE);
+  let unsubscribe = null;
+
+  function setPresentationState(nextState) {
+    presentationState.value = normalizePresentationState(nextState);
+    return presentationState.value;
+  }
+
+  function detachRuntimeStore() {
+    if (typeof unsubscribe === "function") {
+      unsubscribe();
+      unsubscribe = null;
+    }
+  }
+
+  function attachRuntimeStore(nextRuntimeStore = EMPTY_PRESENTATION_STORE) {
+    if (!isPresentationRuntimeStore(nextRuntimeStore)) {
+      throw new TypeError("useShellErrorPresentationStore.attachRuntimeStore requires an error presentation store.");
+    }
+
+    if (runtimeStore.value === nextRuntimeStore) {
+      setPresentationState(nextRuntimeStore.getState());
+      return runtimeStore.value;
+    }
+
+    detachRuntimeStore();
+    runtimeStore.value = markRaw(nextRuntimeStore);
+    setPresentationState(nextRuntimeStore.getState());
+    unsubscribe = nextRuntimeStore.subscribe((nextState) => {
+      setPresentationState(nextState);
+    });
+
+    return runtimeStore.value;
+  }
+
+  function getState() {
+    return presentationState.value;
+  }
+
+  function subscribe(listener) {
+    return runtimeStore.value.subscribe(listener);
+  }
+
+  function present(channel, payload = {}) {
+    return runtimeStore.value.present(channel, payload);
+  }
+
+  function dismiss(channel, presentationId = "") {
+    return runtimeStore.value.dismiss(channel, presentationId);
+  }
+
+  function clear(channel = "") {
+    return runtimeStore.value.clear(channel);
+  }
+
+  const revision = computed(() => Number(presentationState.value.revision || 0));
+  const channels = computed(() => presentationState.value.channels || EMPTY_PRESENTATION_STATE.channels);
+
+  return {
+    runtimeStore,
+    presentationState,
+    revision,
+    channels,
+    attachRuntimeStore,
+    getState,
+    subscribe,
+    present,
+    dismiss,
+    clear
+  };
+});

package/src/client/stores/useShellLayoutStore.js

@@ -0,0 +1,34 @@
+import { ref } from "vue";
+import { defineStore } from "pinia";
+import {
+  readDrawerDefaultOpenPreference,
+  writeDrawerDefaultOpenPreference
+} from "../composables/shellLayoutDrawerPreference.js";
+
+export const useShellLayoutStore = defineStore("jskit.shell-web.layout", () => {
+  const drawerDefaultOpen = ref(readDrawerDefaultOpenPreference());
+  const drawerOpen = ref(drawerDefaultOpen.value);
+
+  function setDrawerDefaultOpen(open) {
+    const normalized = Boolean(open);
+    drawerDefaultOpen.value = normalized;
+    drawerOpen.value = normalized;
+    writeDrawerDefaultOpenPreference(normalized);
+  }
+
+  function setDrawerOpen(open) {
+    drawerOpen.value = Boolean(open);
+  }
+
+  function toggleDrawer() {
+    drawerOpen.value = !drawerOpen.value;
+  }
+
+  return {
+    drawerDefaultOpen,
+    drawerOpen,
+    setDrawerDefaultOpen,
+    setDrawerOpen,
+    toggleDrawer
+  };
+});

package/src/client/support/menuLinkTarget.js

@@ -59,15 +59,15 @@ function resolveMenuLinkTarget({
   surface = "",
   currentSurfaceId = "",
   placementContext = null,
-  workspaceSuffix = "/",
-  nonWorkspaceSuffix = "/",
+  scopedSuffix = "/",
+  unscopedSuffix = "/",
   routeParams = {},
   resolvePagePath = null
 } = {}) {
   const explicitTarget = normalizeText(to);
   const targetSurfaceId = resolveMenuLinkSurfaceId(surface, currentSurfaceId);
-  const workspaceRequired = surfaceRequiresWorkspaceFromPlacementContext(placementContext, targetSurfaceId);
-  const suffixTemplate = normalizeText(workspaceRequired ? workspaceSuffix : nonWorkspaceSuffix) || "/";
+  const scopedRouteRequired = surfaceRequiresWorkspaceFromPlacementContext(placementContext, targetSurfaceId);
+  const suffixTemplate = normalizeText(scopedRouteRequired ? scopedSuffix : unscopedSuffix) || "/";
   const interpolatedSuffix = interpolateBracketParams(suffixTemplate, routeParams);
   const resolvedSuffixTarget =
     typeof resolvePagePath === "function" &&

package/templates/src/components/menus/SurfaceAwareMenuLinkItem.vue

@@ -18,11 +18,11 @@ const props = defineProps({
     type: String,
     default: ""
   },
-  workspaceSuffix: {
+  scopedSuffix: {
     type: String,
     default: "/"
   },
-  nonWorkspaceSuffix: {
+  unscopedSuffix: {
     type: String,
     default: "/"
   },

package/templates/src/components/menus/TabLinkItem.vue

@@ -14,11 +14,11 @@ const props = defineProps({
     type: String,
     default: ""
   },
-  workspaceSuffix: {
+  scopedSuffix: {
     type: String,
     default: "/"
   },
-  nonWorkspaceSuffix: {
+  unscopedSuffix: {
     type: String,
     default: "/"
   },

package/templates/src/pages/home/settings/general/index.vue

@@ -0,0 +1,37 @@
+<script setup>
+import { computed } from "vue";
+import { useShellLayoutState } from "@jskit-ai/shell-web/client/composables/useShellLayoutState";
+
+const { drawerDefaultOpen, setDrawerDefaultOpen } = useShellLayoutState();
+
+const drawerDefaultOpenModel = computed({
+  get() {
+    return drawerDefaultOpen.value;
+  },
+  set(value) {
+    setDrawerDefaultOpen(Boolean(value));
+  }
+});
+</script>
+
+<template>
+  <section class="d-flex flex-column ga-4">
+    <div>
+      <h2 class="text-h6 mb-2">General</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">These starter settings live in this browser only.</p>
+    </div>
+
+    <v-switch
+      v-model="drawerDefaultOpenModel"
+      color="primary"
+      inset
+      hide-details="auto"
+      label="Open navigation drawer by default"
+    />
+
+    <p class="text-body-2 text-medium-emphasis mb-0">
+      This tiny example exists to prove that shell-level settings can work without auth or a database. Real apps will
+      usually replace it.
+    </p>
+  </section>
+</template>

package/templates/src/pages/home/settings/index.vue

@@ -1,37 +1,5 @@
 <script setup>
-import { computed } from "vue";
-import { useShellLayoutState } from "@jskit-ai/shell-web/client/composables/useShellLayoutState";
-
-const { drawerDefaultOpen, setDrawerDefaultOpen } = useShellLayoutState();
-
-const drawerDefaultOpenModel = computed({
-  get() {
-    return drawerDefaultOpen.value;
-  },
-  set(value) {
-    setDrawerDefaultOpen(Boolean(value));
-  }
+definePage({
+  redirect: (to) => `${String(to.path || "").replace(/\/$/, "")}/general`
 });
 </script>
-
-<template>
-  <section class="d-flex flex-column ga-4">
-    <div>
-      <h2 class="text-h6 mb-2">Shell settings</h2>
-      <p class="text-body-2 text-medium-emphasis mb-0">These starter settings live in this browser only.</p>
-    </div>
-
-    <v-switch
-      v-model="drawerDefaultOpenModel"
-      color="primary"
-      inset
-      hide-details="auto"
-      label="Open navigation drawer by default"
-    />
-
-    <p class="text-body-2 text-medium-emphasis mb-0">
-      This tiny example exists to prove that shell-level settings can work without auth or a database. Real apps will
-      usually replace it.
-    </p>
-  </section>
-</template>

package/templates/src/placement.js

@@ -20,8 +20,8 @@ addPlacement({
   props: {
     label: "Home",
     surface: "home",
-    workspaceSuffix: "/",
-    nonWorkspaceSuffix: "/",
+    scopedSuffix: "/",
+    unscopedSuffix: "/",
     exact: true
   }
 });
@@ -35,7 +35,22 @@ addPlacement({
   props: {
     label: "Settings",
     surface: "home",
-    workspaceSuffix: "/settings",
-    nonWorkspaceSuffix: "/settings"
+    scopedSuffix: "/settings",
+    unscopedSuffix: "/settings"
+  }
+});
+
+addPlacement({
+  id: "shell-web.home.settings.general",
+  target: "home-settings:primary-menu",
+  surfaces: ["home"],
+  order: 100,
+  componentToken: "local.main.ui.surface-aware-menu-link-item",
+  props: {
+    label: "General",
+    surface: "home",
+    scopedSuffix: "/settings/general",
+    unscopedSuffix: "/settings/general",
+    to: "./general"
   }
 });

package/test/errorStore.test.js

@@ -1,6 +1,8 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { createPinia } from "pinia";
 import { createErrorPresentationStore } from "../src/client/error/store.js";
+import { useShellErrorPresentationStore } from "../src/client/stores/useShellErrorPresentationStore.js";
 
 test("error presentation store keeps banner channel singleton", () => {
   const store = createErrorPresentationStore({ now: () => 1000 });
@@ -24,3 +26,16 @@ test("error presentation store still queues snackbar channel entries", () => {
   assert.equal(state.channels.snackbar[0].message, "One");
   assert.equal(state.channels.snackbar[1].message, "Two");
 });
+
+test("shell error presentation Pinia store mirrors runtime presentation state", () => {
+  const pinia = createPinia();
+  const runtimeStore = createErrorPresentationStore({ now: () => 1000 });
+  const store = useShellErrorPresentationStore(pinia);
+
+  store.attachRuntimeStore(runtimeStore);
+  runtimeStore.present("snackbar", { message: "Hello" });
+
+  assert.equal(store.channels.snackbar.length, 1);
+  assert.equal(store.channels.snackbar[0].message, "Hello");
+  assert.equal(store.getState().channels.snackbar[0].message, "Hello");
+});

package/test/provider.test.js

@@ -1,6 +1,8 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { createPinia } from "pinia";
 import { ShellWebClientProvider } from "../src/client/providers/ShellWebClientProvider.js";
+import { useShellErrorPresentationStore } from "../src/client/stores/useShellErrorPresentationStore.js";
 const CLIENT_APP_CONFIG_GLOBAL_KEY = "__JSKIT_CLIENT_APP_CONFIG__";
 
 function setClientAppConfig(source = {}) {
@@ -17,9 +19,14 @@ function createAppDouble({ surfaceRuntime = null } = {}) {
   const singletonInstances = new Map();
   const provided = [];
   const plugins = [];
+  const pinia = createPinia();
 
   const vueApp = {
-    config: {},
+    config: {
+      globalProperties: {
+        $pinia: pinia
+      }
+    },
     use(plugin, options) {
       plugins.push({ plugin, options });
       return this;
@@ -33,6 +40,7 @@ function createAppDouble({ surfaceRuntime = null } = {}) {
     singletons,
     provided,
     plugins,
+    pinia,
     vueApp,
     singleton(token, factory) {
       singletons.set(token, factory);
@@ -41,6 +49,9 @@ function createAppDouble({ surfaceRuntime = null } = {}) {
       if (token === "jskit.client.vue.app") {
         return true;
       }
+      if (token === "jskit.client.pinia") {
+        return true;
+      }
       if (token === "jskit.client.surface.runtime") {
         return Boolean(surfaceRuntime);
       }
@@ -50,6 +61,9 @@ function createAppDouble({ surfaceRuntime = null } = {}) {
       if (token === "jskit.client.vue.app") {
         return vueApp;
       }
+      if (token === "jskit.client.pinia") {
+        return pinia;
+      }
       if (token === "jskit.client.surface.runtime" && surfaceRuntime) {
         return surfaceRuntime;
       }
@@ -103,6 +117,12 @@ test("shell web client provider binds runtime and injects it into Vue app", asyn
   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");
+
+  const errorPresentationStore = useShellErrorPresentationStore(app.pinia);
+  assert.equal(errorPresentationStore.revision, 0);
+  assert.equal(typeof errorPresentationStore.present, "function");
+  errorStore.present("banner", { message: "Hello" });
+  assert.equal(errorPresentationStore.channels.banner[0].message, "Hello");
 });
 
 test("shell web client provider resolves surface config from client app config", async () => {

package/test/settingsPlacementContract.test.js

@@ -39,9 +39,20 @@ test("shell-web home settings template exposes surface-derived settings outlets"
   assert.match(source, /<RouterView \/>/);
 });
 
-test("shell-web settings landing page exposes a tiny browser-local drawer preference", async () => {
+test("shell-web settings landing page redirects to the starter child page", async () => {
   const source = await readFile(path.join(PACKAGE_DIR, "templates", "src", "pages", "home", "settings", "index.vue"), "utf8");
 
+  assert.match(source, /definePage/);
+  assert.match(source, /redirect:/);
+  assert.match(source, /\/general/);
+});
+
+test("shell-web settings general child page exposes a tiny browser-local drawer preference", async () => {
+  const source = await readFile(
+    path.join(PACKAGE_DIR, "templates", "src", "pages", "home", "settings", "general", "index.vue"),
+    "utf8"
+  );
+
   assert.match(source, /useShellLayoutState/);
   assert.match(source, /drawerDefaultOpen/);
   assert.match(source, /setDrawerDefaultOpen/);
@@ -55,10 +66,15 @@ test("shell-web placement template seeds default Home and Settings drawer naviga
   assert.match(source, /id: "shell-web\.home\.menu\.home"/);
   assert.match(source, /target: "shell-layout:primary-menu"/);
   assert.match(source, /label: "Home"/);
-  assert.match(source, /nonWorkspaceSuffix: "\/"/);
+  assert.match(source, /unscopedSuffix: "\/"/);
   assert.match(source, /id: "shell-web\.home\.menu\.settings"/);
   assert.match(source, /label: "Settings"/);
-  assert.match(source, /nonWorkspaceSuffix: "\/settings"/);
+  assert.match(source, /unscopedSuffix: "\/settings"/);
+  assert.match(source, /id: "shell-web\.home\.settings\.general"/);
+  assert.match(source, /target: "home-settings:primary-menu"/);
+  assert.match(source, /label: "General"/);
+  assert.match(source, /unscopedSuffix: "\/settings\/general"/);
+  assert.match(source, /to: "\.\/general"/);
 });
 
 test("shell-web descriptor metadata advertises home settings outlets, default drawer links, and installs the scaffold page", () => {
@@ -96,6 +112,20 @@ test("shell-web descriptor metadata advertises home settings outlets, default dr
     ]
   );
 
+  assert.deepEqual(
+    readContributions("home-settings:primary-menu"),
+    [
+      {
+        id: "shell-web.home.settings.general",
+        target: "home-settings:primary-menu",
+        surfaces: ["home"],
+        order: 100,
+        componentToken: "local.main.ui.surface-aware-menu-link-item",
+        source: "templates/src/placement.js"
+      }
+    ]
+  );
+
   assert.deepEqual(findFileMutation("shell-web-page-home-settings-shell"), {
     from: "templates/src/pages/home/settings.vue",
     toSurface: "home",
@@ -111,10 +141,20 @@ test("shell-web descriptor metadata advertises home settings outlets, default dr
     toSurface: "home",
     toSurfacePath: "settings/index.vue",
     ownership: "app",
-    reason: "Install shell-driven home settings landing page with a tiny browser-local shell preference example.",
+    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"
   });
+
+  assert.deepEqual(findFileMutation("shell-web-page-home-settings-general"), {
+    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"
+  });
 });
 
 test("shell-web home starter page relies on drawer navigation instead of dead feature buttons", async () => {

package/test/useShellLayoutState.test.js

@@ -1,10 +1,12 @@
 import assert from "node:assert/strict";
 import test from "node:test";
+import { createPinia } from "pinia";
 import {
   SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY,
   readDrawerDefaultOpenPreference,
   writeDrawerDefaultOpenPreference
 } from "../src/client/composables/shellLayoutDrawerPreference.js";
+import { useShellLayoutStore } from "../src/client/stores/useShellLayoutStore.js";
 
 function createStorage(initial = {}) {
   const values = new Map(Object.entries(initial));
@@ -48,3 +50,18 @@ test("writeDrawerDefaultOpenPreference persists normalized boolean strings", ()
   writeDrawerDefaultOpenPreference(true, { storage });
   assert.equal(storage.getItem(SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY), "true");
 });
+
+test("shell layout store keeps drawer state and default preference in sync", () => {
+  const pinia = createPinia();
+  const store = useShellLayoutStore(pinia);
+
+  store.setDrawerDefaultOpen(false);
+  assert.equal(store.drawerDefaultOpen, false);
+  assert.equal(store.drawerOpen, false);
+
+  store.toggleDrawer();
+  assert.equal(store.drawerOpen, true);
+
+  store.setDrawerOpen(false);
+  assert.equal(store.drawerOpen, false);
+});