@jskit-ai/shell-web 0.1.35 → 0.1.37

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/shell-web",
-  version: "0.1.35",
+  version: "0.1.37",
   kind: "runtime",
   description: "Web shell layout runtime with outlet-based placement contributions.",
   dependsOn: [],
@@ -83,7 +83,32 @@ export default Object.freeze({
             source: "templates/src/pages/home/settings.vue"
           }
         ],
-        contributions: []
+        contributions: [
+          {
+            id: "shell-web.home.menu.home",
+            target: "shell-layout:primary-menu",
+            surfaces: ["*"],
+            order: 50,
+            componentToken: "local.main.ui.surface-aware-menu-link-item",
+            source: "templates/src/placement.js"
+          },
+          {
+            id: "shell-web.home.menu.settings",
+            target: "shell-layout:primary-menu",
+            surfaces: ["home"],
+            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"
+          }
+        ]
       }
     }
   },
@@ -92,7 +117,7 @@ export default Object.freeze({
       runtime: {
         "@mdi/js": "^7.4.47",
         "@tanstack/vue-query": "^5.90.5",
-        "@jskit-ai/kernel": "0.1.36",
+        "@jskit-ai/kernel": "0.1.38",
         "vuetify": "^4.0.0"
       },
       dev: {}
@@ -258,9 +283,18 @@ export default Object.freeze({
         toSurface: "home",
         toSurfacePath: "settings/index.vue",
         ownership: "app",
-        reason: "Install shell-driven home settings index stub scaffold for app-owned landing or redirect behavior.",
+        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.35",
+  "version": "0.1.37",
   "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.36",
+    "@jskit-ai/kernel": "0.1.38",
+    "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/composables/shellLayoutDrawerPreference.js

@@ -0,0 +1,43 @@
+const SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY = "jskit.shell-web.drawer-default-open";
+
+function readDrawerDefaultOpenPreference({
+  storage = typeof window === "object" ? window?.localStorage : null
+} = {}) {
+  if (!storage || typeof storage.getItem !== "function") {
+    return true;
+  }
+
+  try {
+    const storedValue = String(storage.getItem(SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY) || "").trim().toLowerCase();
+    if (storedValue === "false") {
+      return false;
+    }
+    if (storedValue === "true") {
+      return true;
+    }
+  } catch {
+    return true;
+  }
+
+  return true;
+}
+
+function writeDrawerDefaultOpenPreference(open, {
+  storage = typeof window === "object" ? window?.localStorage : null
+} = {}) {
+  if (!storage || typeof storage.setItem !== "function") {
+    return;
+  }
+
+  try {
+    storage.setItem(SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY, open ? "true" : "false");
+  } catch {
+    // Ignore localStorage write failures in unsupported or locked-down environments.
+  }
+}
+
+export {
+  SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY,
+  readDrawerDefaultOpenPreference,
+  writeDrawerDefaultOpenPreference
+};

package/src/client/composables/useShellLayoutState.js

@@ -1,7 +1,9 @@
-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,
@@ -22,6 +24,8 @@ function toSurfaceLabel(surfaceId = "") {
 }
 
 function useShellLayoutState(props = {}) {
+  const shellLayoutStore = useShellLayoutStore();
+  const { drawerDefaultOpen, drawerOpen } = storeToRefs(shellLayoutStore);
   let route = null;
   try {
     route = useRoute();
@@ -30,10 +34,9 @@ function useShellLayoutState(props = {}) {
   }
 
   const { context: placementContext } = useWebPlacementContext();
-  const drawerOpen = ref(true);
 
   function toggleDrawer() {
-    drawerOpen.value = !drawerOpen.value;
+    shellLayoutStore.toggleDrawer();
   }
 
   const resolvedSurface = computed(() => {
@@ -78,7 +81,9 @@ function useShellLayoutState(props = {}) {
   });
 
   return Object.freeze({
+    drawerDefaultOpen,
     drawerOpen,
+    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/templates/src/components/ShellLayout.vue

@@ -48,7 +48,7 @@ const { drawerOpen, toggleDrawer, resolvedSurface, resolvedSurfaceLabel } = useS
     <v-navigation-drawer v-model="drawerOpen" border class="bg-surface" :width="248">
       <slot name="menu" :surface="resolvedSurface">
         <v-list nav density="comfortable" class="pt-2">
-          <v-list-subheader class="text-uppercase text-caption">{{ resolvedSurfaceLabel }}</v-list-subheader>
+          <v-list-subheader class="text-uppercase text-caption">Navigation</v-list-subheader>
           <ShellOutlet
             target="shell-layout:primary-menu"
             default

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

@@ -45,11 +45,7 @@ const health = computed(() => {
       <p class="text-medium-emphasis mb-0">
         This is your primary landing page. Replace this content with your actual product home.
       </p>
-      <div class="d-flex flex-wrap ga-3">
-        <v-btn color="primary" variant="flat" to="/home/settings">Open settings</v-btn>
-        <v-btn color="primary" variant="flat" to="/console">Open console surface</v-btn>
-        <v-btn color="secondary" variant="outlined" to="/auth/signout">Sign out</v-btn>
-      </div>
+      <p class="text-body-2 text-medium-emphasis mb-0">Use the navigation drawer to move around the shell.</p>
     </v-card-text>
   </v-card>
 </template>

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,8 +1,5 @@
 <script setup>
-// To redirect this settings shell to a child page, uncomment and edit the example below.
-// definePage({
-//   redirect: (to) => `${to.path}/your_child_segment`
-// });
+definePage({
+  redirect: (to) => `${String(to.path || "").replace(/\/$/, "")}/general`
+});
 </script>
-
-<template />

package/templates/src/placement.js

@@ -10,3 +10,47 @@ export { addPlacement };
 export default function getPlacements() {
   return registry.build();
 }
+
+addPlacement({
+  id: "shell-web.home.menu.home",
+  target: "shell-layout:primary-menu",
+  surfaces: ["*"],
+  order: 50,
+  componentToken: "local.main.ui.surface-aware-menu-link-item",
+  props: {
+    label: "Home",
+    surface: "home",
+    workspaceSuffix: "/",
+    nonWorkspaceSuffix: "/",
+    exact: true
+  }
+});
+
+addPlacement({
+  id: "shell-web.home.menu.settings",
+  target: "shell-layout:primary-menu",
+  surfaces: ["home"],
+  order: 100,
+  componentToken: "local.main.ui.surface-aware-menu-link-item",
+  props: {
+    label: "Settings",
+    surface: "home",
+    workspaceSuffix: "/settings",
+    nonWorkspaceSuffix: "/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",
+    workspaceSuffix: "/settings/general",
+    nonWorkspaceSuffix: "/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

@@ -8,10 +8,19 @@ import descriptor from "../package.descriptor.mjs";
 const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_DIR = path.resolve(TEST_DIRECTORY, "..");
 
-function readSettingsOutlets() {
+function readOutlets(target = "") {
   const outlets = descriptor?.metadata?.ui?.placements?.outlets;
+  const normalizedTarget = String(target || "").trim();
   return Array.isArray(outlets)
-    ? outlets.filter((entry) => String(entry?.target || "").trim() === "home-settings:primary-menu")
+    ? outlets.filter((entry) => String(entry?.target || "").trim() === normalizedTarget)
+    : [];
+}
+
+function readContributions(target = "") {
+  const contributions = descriptor?.metadata?.ui?.placements?.contributions;
+  const normalizedTarget = String(target || "").trim();
+  return Array.isArray(contributions)
+    ? contributions.filter((entry) => String(entry?.target || "").trim() === normalizedTarget)
     : [];
 }
 
@@ -30,16 +39,47 @@ test("shell-web home settings template exposes surface-derived settings outlets"
   assert.match(source, /<RouterView \/>/);
 });
 
-test("shell-web home settings index template is a simple developer-owned stub", 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, /your_child_segment/);
+  assert.match(source, /redirect:/);
+  assert.match(source, /\/general/);
 });
 
-test("shell-web descriptor metadata advertises home settings outlets and installs the scaffold page", () => {
+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/);
+  assert.match(source, /Open navigation drawer by default/);
+  assert.match(source, /live in this browser only/);
+});
+
+test("shell-web placement template seeds default Home and Settings drawer navigation", async () => {
+  const source = await readFile(path.join(PACKAGE_DIR, "templates", "src", "placement.js"), "utf8");
+
+  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, /id: "shell-web\.home\.menu\.settings"/);
+  assert.match(source, /label: "Settings"/);
+  assert.match(source, /nonWorkspaceSuffix: "\/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, /nonWorkspaceSuffix: "\/settings\/general"/);
+  assert.match(source, /to: "\.\/general"/);
+});
+
+test("shell-web descriptor metadata advertises home settings outlets, default drawer links, and installs the scaffold page", () => {
   assert.deepEqual(
-    readSettingsOutlets(),
+    readOutlets("home-settings:primary-menu"),
     [
       {
         target: "home-settings:primary-menu",
@@ -50,6 +90,42 @@ test("shell-web descriptor metadata advertises home settings outlets and install
     ]
   );
 
+  assert.deepEqual(
+    readContributions("shell-layout:primary-menu"),
+    [
+      {
+        id: "shell-web.home.menu.home",
+        target: "shell-layout:primary-menu",
+        surfaces: ["*"],
+        order: 50,
+        componentToken: "local.main.ui.surface-aware-menu-link-item",
+        source: "templates/src/placement.js"
+      },
+      {
+        id: "shell-web.home.menu.settings",
+        target: "shell-layout:primary-menu",
+        surfaces: ["home"],
+        order: 100,
+        componentToken: "local.main.ui.surface-aware-menu-link-item",
+        source: "templates/src/placement.js"
+      }
+    ]
+  );
+
+  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",
@@ -65,14 +141,27 @@ test("shell-web descriptor metadata advertises home settings outlets and install
     toSurface: "home",
     toSurfacePath: "settings/index.vue",
     ownership: "app",
-    reason: "Install shell-driven home settings index stub scaffold for app-owned landing or redirect behavior.",
+    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 links to the home settings scaffold", async () => {
+test("shell-web home starter page relies on drawer navigation instead of dead feature buttons", async () => {
   const source = await readFile(path.join(PACKAGE_DIR, "templates", "src", "pages", "home", "index.vue"), "utf8");
 
-  assert.match(source, /to="\/home\/settings"/);
+  assert.match(source, /Use the navigation drawer to move around the shell\./);
+  assert.doesNotMatch(source, /\/home\/settings/);
+  assert.doesNotMatch(source, /\/console/);
+  assert.doesNotMatch(source, /\/auth\/signout/);
 });

package/test/useShellLayoutState.test.js

@@ -0,0 +1,67 @@
+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));
+  return {
+    getItem(key) {
+      return values.has(key) ? values.get(key) : null;
+    },
+    setItem(key, value) {
+      values.set(key, String(value));
+    }
+  };
+}
+
+test("readDrawerDefaultOpenPreference defaults to true when storage is missing or empty", () => {
+  assert.equal(readDrawerDefaultOpenPreference({ storage: null }), true);
+  assert.equal(readDrawerDefaultOpenPreference({ storage: createStorage() }), true);
+});
+
+test("readDrawerDefaultOpenPreference reads explicit stored booleans", () => {
+  assert.equal(
+    readDrawerDefaultOpenPreference({
+      storage: createStorage({ [SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY]: "false" })
+    }),
+    false
+  );
+
+  assert.equal(
+    readDrawerDefaultOpenPreference({
+      storage: createStorage({ [SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY]: "true" })
+    }),
+    true
+  );
+});
+
+test("writeDrawerDefaultOpenPreference persists normalized boolean strings", () => {
+  const storage = createStorage();
+
+  writeDrawerDefaultOpenPreference(false, { storage });
+  assert.equal(storage.getItem(SHELL_LAYOUT_DRAWER_DEFAULT_OPEN_STORAGE_KEY), "false");
+
+  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);
+});