@jskit-ai/shell-web 0.1.53 → 0.1.55

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/shell-web",
-  version: "0.1.53",
+  version: "0.1.55",
   kind: "runtime",
   description: "Web shell layout runtime with outlet-based placement contributions.",
   dependsOn: [],
@@ -39,12 +39,17 @@ export default Object.freeze({
         {
           subpath: "./client/error",
           summary: "Exports default error policy and runtime error reporter hook."
+        },
+        {
+          subpath: "./client/bootstrap",
+          summary: "Exports the shared client bootstrap handler registry used to extend /api/bootstrap handling."
         }
       ],
       containerTokens: {
         server: [],
         client: [
           "runtime.web-placement.client",
+          "runtime.web-bootstrap.client",
           "runtime.web-error.client",
           "runtime.web-error.presentation-store.client",
           "shell.web.query-client"
@@ -117,7 +122,7 @@ export default Object.freeze({
       runtime: {
         "@mdi/js": "^7.4.47",
         "@tanstack/vue-query": "^5.90.5",
-        "@jskit-ai/kernel": "0.1.54",
+        "@jskit-ai/kernel": "0.1.56",
         "vuetify": "^4.0.0"
       },
       dev: {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/shell-web",
-  "version": "0.1.53",
+  "version": "0.1.55",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -9,6 +9,7 @@
     "./client": "./src/client/index.js",
     "./client/error": "./src/client/error/index.js",
     "./client/placement": "./src/client/placement/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/components/ShellLayout": "./src/client/components/ShellLayout.vue",
@@ -24,8 +25,12 @@
   "dependencies": {
     "@mdi/js": "^7.4.47",
     "@tanstack/vue-query": "^5.90.5",
-    "@jskit-ai/kernel": "0.1.54",
+    "@jskit-ai/kernel": "0.1.56",
     "pinia": "^3.0.4",
     "vuetify": "^4.0.0"
+  },
+  "peerDependencies": {
+    "vue": "^3.5.13",
+    "vue-router": "^5.0.4"
   }
 }

package/src/client/bootstrap/bootstrapErrorStatus.js

@@ -0,0 +1,6 @@
+function resolveBootstrapErrorStatusCode(error) {
+  const statusCode = Number(error?.statusCode || error?.status || 0);
+  return Number.isInteger(statusCode) && statusCode > 0 ? statusCode : 0;
+}
+
+export { resolveBootstrapErrorStatusCode };

package/src/client/bootstrap/bootstrapPayloadHandlerRegistry.js

@@ -0,0 +1,68 @@
+const BOOTSTRAP_PAYLOAD_HANDLER_TAG = "runtime.web-bootstrap.handlers.client";
+
+function assertTaggableApp(app, context = "bootstrap payload handler registry") {
+  if (!app || typeof app.singleton !== "function" || typeof app.tag !== "function") {
+    throw new Error(`${context} requires application singleton()/tag().`);
+  }
+}
+
+function registerBootstrapPayloadHandler(app, token, factory) {
+  assertTaggableApp(app, "registerBootstrapPayloadHandler");
+  app.singleton(token, factory);
+  app.tag(token, BOOTSTRAP_PAYLOAD_HANDLER_TAG);
+}
+
+function normalizeBootstrapPayloadHandler(entry) {
+  if (typeof entry === "function") {
+    return Object.freeze({
+      handlerId: String(entry.name || "anonymous"),
+      order: 0,
+      applyBootstrapPayload: entry
+    });
+  }
+
+  if (!entry || typeof entry !== "object" || typeof entry.applyBootstrapPayload !== "function") {
+    return null;
+  }
+
+  return Object.freeze({
+    ...entry,
+    handlerId: String(entry.handlerId || "anonymous"),
+    order: Number.isFinite(entry.order) ? Number(entry.order) : 0
+  });
+}
+
+function resolveBootstrapPayloadHandlers(scope) {
+  if (!scope || typeof scope.resolveTag !== "function") {
+    return [];
+  }
+
+  const rawEntries = scope.resolveTag(BOOTSTRAP_PAYLOAD_HANDLER_TAG);
+  const queue = Array.isArray(rawEntries) ? [...rawEntries] : [rawEntries];
+  const entries = [];
+
+  while (queue.length > 0) {
+    const entry = queue.shift();
+    if (Array.isArray(entry)) {
+      queue.push(...entry);
+      continue;
+    }
+    const normalized = normalizeBootstrapPayloadHandler(entry);
+    if (normalized) {
+      entries.push(normalized);
+    }
+  }
+
+  return entries.sort((left, right) => {
+    if (left.order !== right.order) {
+      return left.order - right.order;
+    }
+    return left.handlerId.localeCompare(right.handlerId);
+  });
+}
+
+export {
+  BOOTSTRAP_PAYLOAD_HANDLER_TAG,
+  registerBootstrapPayloadHandler,
+  resolveBootstrapPayloadHandlers
+};

package/src/client/bootstrap/index.js

@@ -0,0 +1,6 @@
+export {
+  BOOTSTRAP_PAYLOAD_HANDLER_TAG,
+  registerBootstrapPayloadHandler,
+  resolveBootstrapPayloadHandlers
+} from "./bootstrapPayloadHandlerRegistry.js";
+export { resolveBootstrapErrorStatusCode } from "./bootstrapErrorStatus.js";

package/src/client/components/ShellLayout.vue

@@ -64,9 +64,9 @@ const { drawerOpen, toggleDrawer, resolvedSurface, resolvedSurfaceLabel } = useS
     </v-navigation-drawer>
 
     <v-main class="bg-background">
-      <v-container fluid class="pa-4">
-        <h1 class="text-h5 mb-2">{{ title }}</h1>
-        <p class="text-body-2 text-medium-emphasis mb-4">{{ subtitle }}</p>
+      <v-container fluid class="shell-layout__content">
+        <h1 v-if="title" class="shell-layout__title text-h5">{{ title }}</h1>
+        <p v-if="subtitle" class="shell-layout__subtitle text-body-2 text-medium-emphasis">{{ subtitle }}</p>
         <slot />
       </v-container>
     </v-main>
@@ -77,4 +77,16 @@ const { drawerOpen, toggleDrawer, resolvedSurface, resolvedSurfaceLabel } = useS
 .shell-layout {
   min-height: 72vh;
 }
+
+.shell-layout__content {
+  padding: 0.75rem 1rem 1rem;
+}
+
+.shell-layout__title {
+  margin-bottom: 0.25rem;
+}
+
+.shell-layout__subtitle {
+  margin-bottom: 0.75rem;
+}
 </style>

package/src/client/index.js

@@ -16,6 +16,11 @@ 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";
+export {
+  BOOTSTRAP_PAYLOAD_HANDLER_TAG,
+  registerBootstrapPayloadHandler,
+  resolveBootstrapPayloadHandlers
+} from "./bootstrap/index.js";
 
 const clientProviders = Object.freeze([ShellWebClientProvider]);
 

package/src/client/providers/ShellWebClientProvider.js

@@ -24,6 +24,9 @@ import {
 import { createWebPlacementRuntime } from "../placement/runtime.js";
 import { useShellErrorPresentationStore } from "../stores/useShellErrorPresentationStore.js";
 import { buildSurfaceConfigContext } from "../placement/surfaceContext.js";
+import { createShellBootstrapRuntime } from "../runtime/bootstrapRuntime.js";
+import { registerBootstrapPayloadHandler } from "../bootstrap/bootstrapPayloadHandlerRegistry.js";
+import { resolveBootstrapErrorStatusCode } from "../bootstrap/bootstrapErrorStatus.js";
 
 // Keep this constant for diagnostics, but keep import() below as a literal string so Vite can statically analyze it.
 const APP_PLACEMENT_MODULE_SPECIFIER = "/src/placement.js";
@@ -229,12 +232,49 @@ class ShellWebClientProvider {
   static id = "shell.web.client";
 
   register(app) {
-    if (!app || typeof app.singleton !== "function") {
-      throw new Error("ShellWebClientProvider requires application singleton().");
+    if (!app || typeof app.singleton !== "function" || typeof app.tag !== "function") {
+      throw new Error("ShellWebClientProvider requires application singleton()/tag().");
     }
 
     const logger = createSharedProviderLogger(isRecord(app) ? app : null);
+    registerBootstrapPayloadHandler(app, "shell.web.bootstrap.surfaceAccessHandler", () =>
+      Object.freeze({
+        handlerId: "shell.web.bootstrap.surfaceAccess",
+        order: 0,
+        applyBootstrapPayload({ payload = {}, placementRuntime, source } = {}) {
+          placementRuntime.setContext(
+            {
+              surfaceAccess:
+                payload?.surfaceAccess && typeof payload.surfaceAccess === "object" ? payload.surfaceAccess : {}
+            },
+            {
+              source
+            }
+          );
+        },
+        handleBootstrapError({ error, placementRuntime, source } = {}) {
+          if (resolveBootstrapErrorStatusCode(error) !== 401) {
+            return;
+          }
+
+          placementRuntime.setContext(
+            {
+              surfaceAccess: {}
+            },
+            {
+              source
+            }
+          );
+        }
+      })
+    );
     app.singleton("runtime.web-placement.client", () => createWebPlacementRuntime({ app, logger }));
+    app.singleton("runtime.web-bootstrap.client", (scope) =>
+      createShellBootstrapRuntime({
+        app: scope,
+        logger
+      })
+    );
     app.singleton("shell.web.query-client", () => createShellWebQueryClient());
     app.singleton("runtime.web-error.presentation-store.client", () => createErrorPresentationStore());
     app.singleton("runtime.web-error.client", (scope) =>
@@ -285,6 +325,11 @@ class ShellWebClientProvider {
     const errorConfig = await loadAppErrorConfig(logger, errorRuntime);
     applyAppErrorConfig(errorRuntime, errorConfig);
 
+    const bootstrapRuntime = app.make("runtime.web-bootstrap.client");
+    if (bootstrapRuntime && typeof bootstrapRuntime.initialize === "function") {
+      await bootstrapRuntime.initialize();
+    }
+
     if (!app.has("jskit.client.vue.app")) {
       return;
     }

package/src/client/runtime/bootstrapRuntime.js

@@ -0,0 +1,195 @@
+import { createProviderLogger as createSharedProviderLogger } from "@jskit-ai/kernel/shared/support/providerLogger";
+import { resolveBootstrapPayloadHandlers } from "../bootstrap/bootstrapPayloadHandlerRegistry.js";
+
+const DEFAULT_BOOTSTRAP_PATH = "/api/bootstrap";
+
+function normalizeObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function buildBootstrapUrl({ path = DEFAULT_BOOTSTRAP_PATH, query = {} } = {}) {
+  const normalizedPath = String(path || DEFAULT_BOOTSTRAP_PATH).trim() || DEFAULT_BOOTSTRAP_PATH;
+  const params = new URLSearchParams();
+
+  for (const [key, value] of Object.entries(normalizeObject(query))) {
+    const normalizedKey = String(key || "").trim();
+    const normalizedValue = String(value || "").trim();
+    if (!normalizedKey || !normalizedValue) {
+      continue;
+    }
+    params.set(normalizedKey, normalizedValue);
+  }
+
+  const queryString = params.toString();
+  return queryString ? `${normalizedPath}?${queryString}` : normalizedPath;
+}
+
+function normalizeBootstrapResponseError(response, url) {
+  const error = new Error(`Bootstrap payload request failed with status ${response.status}.`);
+  error.statusCode = Number(response.status || 0);
+  error.url = url;
+  return error;
+}
+
+function createShellBootstrapRuntime({
+  app,
+  logger = null,
+  fetchImplementation = globalThis.fetch,
+  bootstrapPath = DEFAULT_BOOTSTRAP_PATH
+} = {}) {
+  if (!app || typeof app.has !== "function" || typeof app.make !== "function" || typeof app.resolveTag !== "function") {
+    throw new Error("createShellBootstrapRuntime requires application has()/make()/resolveTag().");
+  }
+  if (!app.has("runtime.web-placement.client")) {
+    throw new Error("createShellBootstrapRuntime requires shell-web placement runtime.");
+  }
+
+  const runtimeLogger = logger || createSharedProviderLogger(app);
+  const placementRuntime = app.make("runtime.web-placement.client");
+  const router = app.has("jskit.client.router") ? app.make("jskit.client.router") : null;
+  let initialized = false;
+  let refreshQueue = Promise.resolve();
+
+  async function resolveBootstrapRequest(reason = "manual") {
+    const handlers = resolveBootstrapPayloadHandlers(app);
+    let request = {
+      path: bootstrapPath,
+      query: {},
+      meta: {}
+    };
+
+    for (const handler of handlers) {
+      if (typeof handler.resolveBootstrapRequest !== "function") {
+        continue;
+      }
+
+      const contribution = normalizeObject(
+        await handler.resolveBootstrapRequest({
+          app,
+          router,
+          placementRuntime,
+          reason,
+          request: Object.freeze({
+            path: request.path,
+            query: Object.freeze({ ...request.query }),
+            meta: Object.freeze({ ...request.meta })
+          })
+        })
+      );
+
+      request = {
+        path: String(contribution.path || request.path || bootstrapPath).trim() || bootstrapPath,
+        query: {
+          ...request.query,
+          ...normalizeObject(contribution.query)
+        },
+        meta: {
+          ...request.meta,
+          ...normalizeObject(contribution.meta)
+        }
+      };
+    }
+
+    return Object.freeze({
+      path: request.path,
+      query: Object.freeze({ ...request.query }),
+      meta: Object.freeze({ ...request.meta })
+    });
+  }
+
+  async function applyBootstrapPayload(payload, reason = "manual", request = Object.freeze({})) {
+    const handlers = resolveBootstrapPayloadHandlers(app);
+    const source = `shell-web.bootstrap.${String(reason || "manual").trim() || "manual"}`;
+
+    for (const handler of handlers) {
+      await handler.applyBootstrapPayload({
+        app,
+        router,
+        placementRuntime,
+        payload,
+        request,
+        reason,
+        source
+      });
+    }
+
+    return payload;
+  }
+
+  async function applyBootstrapError(error, reason = "manual", request = Object.freeze({})) {
+    const handlers = resolveBootstrapPayloadHandlers(app);
+    const source = `shell-web.bootstrap.${String(reason || "manual").trim() || "manual"}`;
+
+    for (const handler of handlers) {
+      if (typeof handler.handleBootstrapError !== "function") {
+        continue;
+      }
+
+      await handler.handleBootstrapError({
+        app,
+        router,
+        placementRuntime,
+        error,
+        request,
+        reason,
+        source
+      });
+    }
+  }
+
+  async function performRefresh(reason = "manual") {
+    if (typeof fetchImplementation !== "function") {
+      throw new Error("Bootstrap payload fetch requires a fetch implementation.");
+    }
+
+    const request = await resolveBootstrapRequest(reason);
+    const url = buildBootstrapUrl(request);
+
+    try {
+      const response = await fetchImplementation(url, {
+        method: "GET",
+        credentials: "include",
+        headers: {
+          accept: "application/json"
+        }
+      });
+
+      if (!response.ok) {
+        throw normalizeBootstrapResponseError(response, url);
+      }
+
+      const payload = await response.json();
+      return applyBootstrapPayload(payload, reason, request);
+    } catch (error) {
+      await applyBootstrapError(error, reason, request);
+      runtimeLogger.warn(
+        {
+          reason,
+          error: String(error?.message || error || "unknown error")
+        },
+        "shell-web bootstrap refresh failed."
+      );
+      return null;
+    }
+  }
+
+  function refresh(reason = "manual") {
+    refreshQueue = refreshQueue.then(() => performRefresh(reason));
+    return refreshQueue;
+  }
+
+  async function initialize() {
+    if (initialized) {
+      return null;
+    }
+    initialized = true;
+    return refresh("init");
+  }
+
+  return Object.freeze({
+    initialize,
+    refresh
+  });
+}
+
+export { createShellBootstrapRuntime };

package/templates/src/components/ShellLayout.vue

@@ -64,9 +64,9 @@ const { drawerOpen, toggleDrawer, resolvedSurface, resolvedSurfaceLabel } = useS
     </v-navigation-drawer>
 
     <v-main class="bg-background">
-      <v-container fluid class="pa-4">
-        <h1 class="text-h5 mb-2">{{ title }}</h1>
-        <p class="text-body-2 text-medium-emphasis mb-4">{{ subtitle }}</p>
+      <v-container fluid class="shell-layout__content">
+        <h1 v-if="title" class="shell-layout__title text-h5">{{ title }}</h1>
+        <p v-if="subtitle" class="shell-layout__subtitle text-body-2 text-medium-emphasis">{{ subtitle }}</p>
         <slot />
       </v-container>
     </v-main>
@@ -77,4 +77,16 @@ const { drawerOpen, toggleDrawer, resolvedSurface, resolvedSurfaceLabel } = useS
 .shell-layout {
   min-height: 72vh;
 }
+
+.shell-layout__content {
+  padding: 0.75rem 1rem 1rem;
+}
+
+.shell-layout__title {
+  margin-bottom: 0.25rem;
+}
+
+.shell-layout__subtitle {
+  margin-bottom: 0.75rem;
+}
 </style>

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

@@ -29,7 +29,7 @@ const health = computed(() => {
 
 <template>
   <v-card rounded="lg" elevation="1" border>
-    <v-card-item>
+    <v-card-item class="home-surface-card__header">
       <template #prepend>
         <v-chip color="primary" size="small" label>Home</v-chip>
       </template>
@@ -37,7 +37,7 @@ const health = computed(() => {
       <v-card-subtitle>Main public surface</v-card-subtitle>
     </v-card-item>
     <v-divider />
-    <v-card-text class="d-flex flex-column ga-4">
+    <v-card-text class="home-surface-card__body d-flex flex-column ga-3">
       <div class="d-flex flex-wrap ga-3">
         <v-chip color="secondary" variant="tonal" label>Route: /home</v-chip>
         <v-chip color="info" variant="tonal" label>Health: {{ health }}</v-chip>
@@ -49,3 +49,13 @@ const health = computed(() => {
     </v-card-text>
   </v-card>
 </template>
+
+<style scoped>
+.home-surface-card__header {
+  padding: 0.875rem 1rem;
+}
+
+.home-surface-card__body {
+  padding: 0.875rem 1rem 1rem;
+}
+</style>

package/templates/src/placement.js

@@ -50,7 +50,6 @@ addPlacement({
     label: "General",
     surface: "home",
     scopedSuffix: "/settings/general",
-    unscopedSuffix: "/settings/general",
-    to: "./general"
+    unscopedSuffix: "/settings/general"
   }
 });

package/test/bootstrapRuntime.test.js

@@ -0,0 +1,187 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { registerBootstrapPayloadHandler } from "../src/client/bootstrap/bootstrapPayloadHandlerRegistry.js";
+import { createShellBootstrapRuntime } from "../src/client/runtime/bootstrapRuntime.js";
+
+function createPlacementRuntime(initialContext = {}) {
+  let context = Object.freeze({ ...initialContext });
+  const listeners = new Set();
+
+  return {
+    getContext() {
+      return context;
+    },
+    setContext(value = {}, { replace = false } = {}) {
+      const next = value && typeof value === "object" ? { ...value } : {};
+      context = Object.freeze(replace ? next : { ...context, ...next });
+      for (const listener of listeners) {
+        listener({
+          type: "context.updated"
+        });
+      }
+      return context;
+    },
+    subscribe(listener) {
+      if (typeof listener === "function") {
+        listeners.add(listener);
+      }
+      return () => {
+        listeners.delete(listener);
+      };
+    }
+  };
+}
+
+function createAppDouble({ placementRuntime, realtimeSocket = null } = {}) {
+  const singletons = new Map();
+  const singletonInstances = new Map();
+  return {
+    singleton(token, factory) {
+      singletons.set(token, factory);
+    },
+    tag(token, tagName) {
+      const current = this._tags.get(tagName) || [];
+      current.push(token);
+      this._tags.set(tagName, current);
+    },
+    resolveTag(tagName) {
+      return (this._tags.get(tagName) || []).map((token) => this.make(token));
+    },
+    _tags: new Map(),
+    has(token) {
+      if (token === "runtime.web-placement.client") {
+        return true;
+      }
+      if (token === "runtime.realtime.client.socket") {
+        return Boolean(realtimeSocket);
+      }
+      return singletons.has(token) || singletonInstances.has(token);
+    },
+    make(token) {
+      if (token === "runtime.web-placement.client") {
+        return placementRuntime;
+      }
+      if (token === "runtime.realtime.client.socket") {
+        return realtimeSocket;
+      }
+      if (singletonInstances.has(token)) {
+        return singletonInstances.get(token);
+      }
+      const factory = singletons.get(token);
+      if (!factory) {
+        throw new Error(`Unknown token ${String(token)}`);
+      }
+      const instance = factory(this);
+      singletonInstances.set(token, instance);
+      return instance;
+    }
+  };
+}
+
+test("shell bootstrap runtime refreshes /api/bootstrap on init and applies registered handlers", async () => {
+  const placementRuntime = createPlacementRuntime({
+    auth: {}
+  });
+  const payloads = [
+    {
+      surfaceAccess: {
+        consoleowner: false
+      }
+    },
+    {
+      surfaceAccess: {
+        consoleowner: true
+      }
+    }
+  ];
+  const calls = [];
+  const observedRequests = [];
+  const observedResolveMeta = [];
+  const app = createAppDouble({ placementRuntime });
+  registerBootstrapPayloadHandler(app, "test.bootstrap.request", () =>
+    Object.freeze({
+      handlerId: "test.bootstrap.request",
+      order: -10,
+      resolveBootstrapRequest() {
+        return {
+          query: {
+            workspaceSlug: "acme"
+          },
+          meta: {
+            path: "/w/acme/dashboard"
+          }
+        };
+      },
+      applyBootstrapPayload({ request }) {
+        observedRequests.push(request);
+      }
+    })
+  );
+  registerBootstrapPayloadHandler(app, "test.bootstrap.request-meta", () =>
+    Object.freeze({
+      handlerId: "test.bootstrap.request-meta",
+      order: -5,
+      resolveBootstrapRequest({ request }) {
+        observedResolveMeta.push(request?.meta?.path || "");
+        return {};
+      },
+      applyBootstrapPayload() {}
+    })
+  );
+  registerBootstrapPayloadHandler(app, "test.bootstrap.surfaceAccess", () =>
+    Object.freeze({
+      handlerId: "test.bootstrap.surfaceAccess",
+      order: 0,
+      applyBootstrapPayload({ payload, placementRuntime: targetRuntime }) {
+        targetRuntime.setContext({
+          surfaceAccess: payload.surfaceAccess || {}
+        });
+      }
+    })
+  );
+
+  const runtime = createShellBootstrapRuntime({
+    app,
+    fetchImplementation: async (url) => {
+      calls.push(String(url || ""));
+      const payload = payloads.shift() || {};
+      return {
+        ok: true,
+        async json() {
+          return payload;
+        }
+      };
+    }
+  });
+
+  await runtime.initialize();
+  assert.deepEqual(placementRuntime.getContext().surfaceAccess, {
+    consoleowner: false
+  });
+  await runtime.refresh("manual");
+  assert.deepEqual(calls, ["/api/bootstrap?workspaceSlug=acme", "/api/bootstrap?workspaceSlug=acme"]);
+  assert.deepEqual(observedResolveMeta, ["/w/acme/dashboard", "/w/acme/dashboard"]);
+  assert.deepEqual(observedRequests, [
+    {
+      path: "/api/bootstrap",
+      query: {
+        workspaceSlug: "acme"
+      },
+      meta: {
+        path: "/w/acme/dashboard"
+      }
+    },
+    {
+      path: "/api/bootstrap",
+      query: {
+        workspaceSlug: "acme"
+      },
+      meta: {
+        path: "/w/acme/dashboard"
+      }
+    }
+  ]);
+  assert.deepEqual(placementRuntime.getContext().surfaceAccess, {
+    consoleowner: true
+  });
+});

package/test/placementRegistry.test.js

@@ -41,15 +41,15 @@ test("placement registry accepts explicit non-global surface ids", () => {
   assert.equal(added, true);
 });
 
-test("placement registry rejects legacy split target fields", () => {
+test("placement registry rejects split target fields", () => {
   const registry = createPlacementRegistry();
 
   assert.throws(
     () => registry.addPlacement({
-      id: "example.legacy",
+      id: "example.split",
       host: "shell-layout",
       position: "top-right",
-      componentToken: "example.legacy.component"
+      componentToken: "example.split.component"
     }),
     /must use "target" only/
   );

package/test/provider.test.js

@@ -42,9 +42,15 @@ function createAppDouble({ surfaceRuntime = null } = {}) {
     plugins,
     pinia,
     vueApp,
+    _tags: new Map(),
     singleton(token, factory) {
       singletons.set(token, factory);
     },
+    tag(token, tagName) {
+      const current = this._tags.get(tagName) || [];
+      current.push(token);
+      this._tags.set(tagName, current);
+    },
     has(token) {
       if (token === "jskit.client.vue.app") {
         return true;
@@ -78,51 +84,88 @@ function createAppDouble({ surfaceRuntime = null } = {}) {
       singletonInstances.set(token, instance);
       return instance;
     },
-    resolveTag() {
-      return [];
+    resolveTag(tagName) {
+      return (this._tags.get(tagName) || []).map((token) => this.make(token));
     }
   };
 }
 
+async function withFetchStub(responsePayload, callback) {
+  const previousFetch = globalThis.fetch;
+  globalThis.fetch = async () => ({
+    ok: true,
+    async json() {
+      return responsePayload;
+    }
+  });
+
+  try {
+    return await callback();
+  } finally {
+    if (previousFetch === undefined) {
+      delete globalThis.fetch;
+    } else {
+      globalThis.fetch = previousFetch;
+    }
+  }
+}
+
+async function withFetchImplementation(fetchImplementation, callback) {
+  const previousFetch = globalThis.fetch;
+  globalThis.fetch = fetchImplementation;
+
+  try {
+    return await callback();
+  } finally {
+    if (previousFetch === undefined) {
+      delete globalThis.fetch;
+    } else {
+      globalThis.fetch = previousFetch;
+    }
+  }
+}
+
 test("shell web client provider binds runtime and injects it into Vue app", async () => {
-  const app = createAppDouble();
-  const provider = new ShellWebClientProvider();
-
-  provider.register(app);
-  assert.equal(app.singletons.has("runtime.web-placement.client"), true);
-  assert.equal(app.singletons.has("runtime.web-error.client"), true);
-  assert.equal(app.singletons.has("runtime.web-error.presentation-store.client"), true);
-
-  await provider.boot(app);
-  assert.equal(app.plugins.length, 1);
-  assert.equal(typeof app.plugins[0].plugin.install, "function");
-  assert.equal(typeof app.plugins[0].options?.queryClient, "object");
-
-  const providedByKey = new Map(app.provided.map((entry) => [entry.key, entry.value]));
-
-  assert.equal(providedByKey.has("jskit.shell-web.runtime.web-placement.client"), true);
-  assert.equal(providedByKey.has("jskit.shell-web.runtime.web-error.client"), true);
-  assert.equal(providedByKey.has("jskit.shell-web.runtime.web-error.presentation-store.client"), true);
-
-  const placementRuntime = providedByKey.get("jskit.shell-web.runtime.web-placement.client");
-  assert.equal(typeof placementRuntime.getPlacements, "function");
-  assert.equal(typeof placementRuntime.getContext, "function");
-  assert.equal(typeof placementRuntime.setContext, "function");
-  assert.equal(typeof placementRuntime.getContext().surfaceConfig, "object");
-
-  const errorRuntime = providedByKey.get("jskit.shell-web.runtime.web-error.client");
-  assert.equal(typeof errorRuntime.report, "function");
-  assert.equal(typeof errorRuntime.configure, "function");
-
-  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");
+  await withFetchStub({ surfaceAccess: {} }, async () => {
+    const app = createAppDouble();
+    const provider = new ShellWebClientProvider();
+
+    provider.register(app);
+    assert.equal(app.singletons.has("runtime.web-placement.client"), true);
+    assert.equal(app.singletons.has("runtime.web-error.client"), true);
+    assert.equal(app.singletons.has("runtime.web-error.presentation-store.client"), true);
+
+    await provider.boot(app);
+    assert.equal(app.plugins.length, 1);
+    assert.equal(typeof app.plugins[0].plugin.install, "function");
+    assert.equal(typeof app.plugins[0].options?.queryClient, "object");
+
+    const providedByKey = new Map(app.provided.map((entry) => [entry.key, entry.value]));
+
+    assert.equal(providedByKey.has("jskit.shell-web.runtime.web-placement.client"), true);
+    assert.equal(providedByKey.has("jskit.shell-web.runtime.web-error.client"), true);
+    assert.equal(providedByKey.has("jskit.shell-web.runtime.web-error.presentation-store.client"), true);
+
+    const placementRuntime = providedByKey.get("jskit.shell-web.runtime.web-placement.client");
+    assert.equal(typeof placementRuntime.getPlacements, "function");
+    assert.equal(typeof placementRuntime.getContext, "function");
+    assert.equal(typeof placementRuntime.setContext, "function");
+    assert.equal(typeof placementRuntime.getContext().surfaceConfig, "object");
+
+    const errorRuntime = providedByKey.get("jskit.shell-web.runtime.web-error.client");
+    assert.equal(typeof errorRuntime.report, "function");
+    assert.equal(typeof errorRuntime.configure, "function");
+
+    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 () => {
@@ -134,35 +177,63 @@ test("shell web client provider resolves surface config from client app config",
   });
 
   try {
-    const app = createAppDouble({
-      surfaceRuntime: {
-        DEFAULT_SURFACE_ID: "app",
-        listEnabledSurfaceIds() {
-          return ["app", "admin", "console"];
-        },
-        listSurfaceDefinitions() {
-          return [
-            { id: "app", pagesRoot: "w/[workspaceSlug]", requiresWorkspace: true, enabled: true },
-            { id: "admin", pagesRoot: "w/[workspaceSlug]/admin", requiresWorkspace: true, enabled: true },
-            { id: "console", pagesRoot: "console", requiresWorkspace: false, enabled: true }
-          ];
+    await withFetchStub({ surfaceAccess: {} }, async () => {
+      const app = createAppDouble({
+        surfaceRuntime: {
+          DEFAULT_SURFACE_ID: "app",
+          listEnabledSurfaceIds() {
+            return ["app", "admin", "console"];
+          },
+          listSurfaceDefinitions() {
+            return [
+              { id: "app", pagesRoot: "w/[workspaceSlug]", requiresWorkspace: true, enabled: true },
+              { id: "admin", pagesRoot: "w/[workspaceSlug]/admin", requiresWorkspace: true, enabled: true },
+              { id: "console", pagesRoot: "console", requiresWorkspace: false, enabled: true }
+            ];
+          }
         }
-      }
+      });
+      const provider = new ShellWebClientProvider();
+      provider.register(app);
+
+      await provider.boot(app);
+
+      const placementRuntime = app.make("runtime.web-placement.client");
+      const context = placementRuntime.getContext();
+      assert.equal(context.surfaceConfig.tenancyMode, "workspaces");
+      assert.equal(context.surfaceConfig.defaultSurfaceId, "app");
+      assert.deepEqual(context.surfaceConfig.enabledSurfaceIds, ["app", "admin", "console"]);
+      assert.deepEqual(context.surfaceAccessPolicies, {
+        public: {}
+      });
     });
+  } finally {
+    setClientAppConfig({});
+  }
+});
+
+test("shell web client provider clears generic surface access on bootstrap 401", async () => {
+  await withFetchImplementation(async () => ({
+    ok: false,
+    status: 401
+  }), async () => {
+    const app = createAppDouble();
     const provider = new ShellWebClientProvider();
     provider.register(app);
 
-    await provider.boot(app);
-
     const placementRuntime = app.make("runtime.web-placement.client");
-    const context = placementRuntime.getContext();
-    assert.equal(context.surfaceConfig.tenancyMode, "workspaces");
-    assert.equal(context.surfaceConfig.defaultSurfaceId, "app");
-    assert.deepEqual(context.surfaceConfig.enabledSurfaceIds, ["app", "admin", "console"]);
-    assert.deepEqual(context.surfaceAccessPolicies, {
-      public: {}
-    });
-  } finally {
-    setClientAppConfig({});
-  }
+    placementRuntime.setContext(
+      {
+        surfaceAccess: {
+          consoleowner: true
+        }
+      },
+      {
+        source: "test.seed"
+      }
+    );
+
+    await provider.boot(app);
+    assert.deepEqual(placementRuntime.getContext().surfaceAccess, {});
+  });
 });

package/test/settingsPlacementContract.test.js

@@ -75,7 +75,7 @@ test("shell-web placement template seeds default Home and Settings drawer naviga
   assert.match(source, /target: "home-settings:primary-menu"/);
   assert.match(source, /label: "General"/);
   assert.match(source, /unscopedSuffix: "\/settings\/general"/);
-  assert.match(source, /to: "\.\/general"/);
+  assert.doesNotMatch(source, /to: "\.\/general"/);
 });
 
 test("shell-web descriptor metadata advertises home settings outlets, default drawer links, and installs the scaffold page", () => {