@jskit-ai/users-web 0.1.48 → 0.1.49

package/package.descriptor.mjs

@@ -1,10 +1,16 @@
+import {
+  HOME_TOOLS_OUTLET,
+  WORKSPACE_TOOLS_OUTLET
+} from "./src/shared/toolsOutletContracts.js";
+
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/users-web",
-  version: "0.1.48",
+  version: "0.1.49",
   kind: "runtime",
-  description: "Users web module: account/profile UI plus shared shell link components.",
+  description: "Users web module: account/profile UI plus shared users web widgets.",
   dependsOn: [
+    "@jskit-ai/auth-web",
     "@jskit-ai/http-runtime",
     "@jskit-ai/shell-web",
     "@jskit-ai/uploads-image-web",
@@ -47,14 +53,6 @@ export default Object.freeze({
           subpath: "./client/components/ProfileClientElement",
           summary: "Exports profile settings client element scaffold component."
         },
-        {
-          subpath: "./client/components/ConsoleSettingsClientElement",
-          summary: "Exports console settings landing-page client element."
-        },
-        {
-          subpath: "./client/components/WorkspaceSettingsClientElement",
-          summary: "Exports workspace settings client element."
-        },
         {
           subpath: "./client/composables/useAddEdit",
           summary: "Exports add/edit operation composable."
@@ -95,9 +93,8 @@ export default Object.freeze({
       containerTokens: {
         server: [],
         client: [
-          "users.web.shell.menu-link-item",
-          "users.web.shell.surface-aware-menu-link-item",
           "users.web.profile.menu.surface-switch-item",
+          "users.web.home.tools.widget",
           "users.web.profile.element",
           "users.web.bootstrap-placement.runtime"
         ]
@@ -107,8 +104,20 @@ export default Object.freeze({
       placements: {
         outlets: [
           {
-            host: "console-settings",
-            position: "primary-menu",
+            target: HOME_TOOLS_OUTLET.target,
+            defaultLinkComponentToken: HOME_TOOLS_OUTLET.defaultLinkComponentToken,
+            surfaces: ["home"],
+            source: "src/client/components/UsersHomeToolsWidget.vue"
+          },
+          {
+            target: WORKSPACE_TOOLS_OUTLET.target,
+            defaultLinkComponentToken: WORKSPACE_TOOLS_OUTLET.defaultLinkComponentToken,
+            surfaces: ["admin"],
+            source: "src/client/components/UsersWorkspaceToolsWidget.vue"
+          },
+          {
+            target: "console-settings:primary-menu",
+            defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
             surfaces: ["console"],
             source: "templates/src/pages/console/settings.vue"
           }
@@ -116,8 +125,7 @@ export default Object.freeze({
         contributions: [
           {
             id: "users.profile.menu.surface-switch",
-            host: "auth-profile-menu",
-            position: "primary-menu",
+            target: "auth-profile-menu:primary-menu",
             surfaces: ["*"],
             order: 100,
             componentToken: "users.web.profile.menu.surface-switch-item",
@@ -126,23 +134,48 @@ export default Object.freeze({
           },
           {
             id: "users.profile.menu.settings",
-            host: "auth-profile-menu",
-            position: "primary-menu",
+            target: "auth-profile-menu:primary-menu",
             surfaces: ["*"],
             order: 500,
-            componentToken: "users.web.shell.menu-link-item",
+            componentToken: "auth.web.profile.menu.link-item",
             when: "auth.authenticated === true",
             source: "mutations.text#users-web-profile-settings-placement"
           },
+          {
+            id: "users.home.menu.home",
+            target: "shell-layout:primary-menu",
+            surfaces: ["*"],
+            order: 50,
+            componentToken: "local.main.ui.surface-aware-menu-link-item",
+            when: "auth.authenticated === true",
+            source: "mutations.text#users-web-home-shell-menu-placement"
+          },
           {
             id: "users.console.menu.settings",
-            host: "shell-layout",
-            position: "primary-menu",
+            target: "shell-layout:primary-menu",
             surfaces: ["console"],
             order: 100,
-            componentToken: "users.web.shell.menu-link-item",
+            componentToken: "local.main.ui.menu-link-item",
             when: "auth.authenticated === true",
             source: "mutations.text#users-web-console-settings-placement"
+          },
+          {
+            id: "users.home.tools.widget",
+            target: "shell-layout:top-right",
+            surfaces: ["home"],
+            order: 900,
+            componentToken: "users.web.home.tools.widget",
+            when: "auth.authenticated === true",
+            source: "mutations.text#users-web-home-tools-placement"
+          },
+          {
+            id: "users.home.menu.settings",
+            target: "home-tools:primary-menu",
+            surfaces: ["home"],
+            order: 100,
+            componentToken: "local.main.ui.surface-aware-menu-link-item",
+            when: "auth.authenticated === true",
+            source: "mutations.text#users-web-home-tools-placement"
           }
         ]
       }
@@ -153,12 +186,12 @@ export default Object.freeze({
       runtime: {
         "@tanstack/vue-query": "5.92.12",
         "@mdi/js": "^7.4.47",
-        "@jskit-ai/http-runtime": "0.1.32",
-        "@jskit-ai/realtime": "0.1.32",
-        "@jskit-ai/kernel": "0.1.33",
-        "@jskit-ai/shell-web": "0.1.32",
-        "@jskit-ai/uploads-image-web": "0.1.11",
-        "@jskit-ai/users-core": "0.1.43",
+        "@jskit-ai/http-runtime": "0.1.33",
+        "@jskit-ai/realtime": "0.1.33",
+        "@jskit-ai/kernel": "0.1.34",
+        "@jskit-ai/shell-web": "0.1.33",
+        "@jskit-ai/uploads-image-web": "0.1.12",
+        "@jskit-ai/users-core": "0.1.44",
         vuetify: "^4.0.0"
       },
       dev: {}
@@ -226,7 +259,7 @@ export default Object.freeze({
         from: "templates/src/pages/console/settings/index.vue",
         toSurface: "console",
         toSurfacePath: "settings/index.vue",
-        reason: "Install console settings landing page scaffold for users-web console UI.",
+        reason: "Install console settings index stub scaffold for app-owned landing or redirect behavior.",
         category: "users-web",
         id: "users-web-page-console-settings"
       }
@@ -249,7 +282,7 @@ export default Object.freeze({
         position: "bottom",
         skipIfContains: "id: \"users.profile.menu.surface-switch\"",
         value:
-          "\naddPlacement({\n  id: \"users.profile.menu.surface-switch\",\n  host: \"auth-profile-menu\",\n  position: \"primary-menu\",\n  surfaces: [\"*\"],\n  order: 100,\n  componentToken: \"users.web.profile.menu.surface-switch-item\",\n  when: ({ auth }) => Boolean(auth?.authenticated)\n});\n",
+          "\naddPlacement({\n  id: \"users.profile.menu.surface-switch\",\n  target: \"auth-profile-menu:primary-menu\",\n  surfaces: [\"*\"],\n  order: 100,\n  componentToken: \"users.web.profile.menu.surface-switch-item\",\n  when: ({ auth }) => Boolean(auth?.authenticated)\n});\n",
         reason: "Append users-web profile surface switch placement into app-owned placement registry.",
         category: "users-web",
         id: "users-web-profile-surface-switch-placement"
@@ -260,21 +293,43 @@ export default Object.freeze({
         position: "bottom",
         skipIfContains: "id: \"users.profile.menu.settings\"",
         value:
-          "\naddPlacement({\n  id: \"users.profile.menu.settings\",\n  host: \"auth-profile-menu\",\n  position: \"primary-menu\",\n  surfaces: [\"*\"],\n  order: 500,\n  componentToken: \"users.web.shell.menu-link-item\",\n  props: {\n    label: \"Settings\",\n    to: \"/account\"\n  },\n  when: ({ auth }) => Boolean(auth?.authenticated)\n});\n",
+          "\naddPlacement({\n  id: \"users.profile.menu.settings\",\n  target: \"auth-profile-menu:primary-menu\",\n  surfaces: [\"*\"],\n  order: 500,\n  componentToken: \"auth.web.profile.menu.link-item\",\n  props: {\n    label: \"Settings\",\n    to: \"/account\"\n  },\n  when: ({ auth }) => Boolean(auth?.authenticated)\n});\n",
         reason: "Append users-web profile settings menu placement into app-owned placement registry.",
         category: "users-web",
         id: "users-web-profile-settings-placement"
       },
+      {
+        op: "append-text",
+        file: "src/placement.js",
+        position: "bottom",
+        skipIfContains: "id: \"users.home.menu.home\"",
+        value:
+          "\naddPlacement({\n  id: \"users.home.menu.home\",\n  target: \"shell-layout:primary-menu\",\n  surfaces: [\"*\"],\n  order: 50,\n  componentToken: \"local.main.ui.surface-aware-menu-link-item\",\n  props: {\n    label: \"Home\",\n    surface: \"home\",\n    workspaceSuffix: \"/\",\n    nonWorkspaceSuffix: \"/\",\n    exact: true\n  },\n  when: ({ auth }) => Boolean(auth?.authenticated)\n});\n",
+        reason: "Append users-web home shell menu placement into app-owned placement registry.",
+        category: "users-web",
+        id: "users-web-home-shell-menu-placement"
+      },
       {
         op: "append-text",
         file: "src/placement.js",
         position: "bottom",
         skipIfContains: "id: \"users.console.menu.settings\"",
         value:
-          "\naddPlacement({\n  id: \"users.console.menu.settings\",\n  host: \"shell-layout\",\n  position: \"primary-menu\",\n  surfaces: [\"console\"],\n  order: 100,\n  componentToken: \"users.web.shell.menu-link-item\",\n  props: {\n    label: \"Settings\",\n    to: \"/console/settings\",\n    icon: \"mdi-cog-outline\"\n  },\n  when: ({ auth }) => Boolean(auth?.authenticated)\n});\n",
+          "\naddPlacement({\n  id: \"users.console.menu.settings\",\n  target: \"shell-layout:primary-menu\",\n  surfaces: [\"console\"],\n  order: 100,\n  componentToken: \"local.main.ui.menu-link-item\",\n  props: {\n    label: \"Settings\",\n    to: \"/console/settings\",\n    icon: \"mdi-cog-outline\"\n  },\n  when: ({ auth }) => Boolean(auth?.authenticated)\n});\n",
         reason: "Append users-web console settings menu placement into app-owned placement registry.",
         category: "users-web",
         id: "users-web-console-settings-placement"
+      },
+      {
+        op: "append-text",
+        file: "src/placement.js",
+        position: "bottom",
+        skipIfContains: "id: \"users.home.tools.widget\"",
+        value:
+          "\naddPlacement({\n  id: \"users.home.tools.widget\",\n  target: \"shell-layout:top-right\",\n  surfaces: [\"home\"],\n  order: 900,\n  componentToken: \"users.web.home.tools.widget\",\n  when: ({ auth }) => Boolean(auth?.authenticated)\n});\n\naddPlacement({\n  id: \"users.home.menu.settings\",\n  target: \"home-tools:primary-menu\",\n  surfaces: [\"home\"],\n  order: 100,\n  componentToken: \"local.main.ui.surface-aware-menu-link-item\",\n  props: {\n    label: \"Settings\",\n    surface: \"home\",\n    workspaceSuffix: \"/settings\",\n    nonWorkspaceSuffix: \"/settings\"\n  },\n  when: ({ auth }) => Boolean(auth?.authenticated)\n});\n",
+        reason: "Append users-web home tools widget and settings menu placements into app-owned placement registry.",
+        category: "users-web",
+        id: "users-web-home-tools-placement"
       }
     ]
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/users-web",
-  "version": "0.1.48",
+  "version": "0.1.49",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -8,8 +8,6 @@
   "exports": {
     "./client": "./src/client/index.js",
     "./client/providers/UsersWorkspacesClientProvider": "./src/client/providers/UsersWorkspacesClientProvider.js",
-    "./client/components/ConsoleSettingsClientElement": "./src/client/components/ConsoleSettingsClientElement.vue",
-    "./client/components/WorkspaceSettingsClientElement": "./src/client/components/WorkspaceSettingsClientElement.vue",
     "./client/components/WorkspaceMembersClientElement": "./src/client/components/WorkspaceMembersClientElement.vue",
     "./client/composables/useAddEdit": "./src/client/composables/records/useAddEdit.js",
     "./client/composables/useCrudAddEdit": "./src/client/composables/records/useCrudAddEdit.js",
@@ -28,12 +26,12 @@
   "dependencies": {
     "@tanstack/vue-query": "5.92.12",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/http-runtime": "0.1.32",
-    "@jskit-ai/kernel": "0.1.33",
-    "@jskit-ai/realtime": "0.1.32",
-    "@jskit-ai/shell-web": "0.1.32",
-    "@jskit-ai/uploads-image-web": "0.1.11",
-    "@jskit-ai/users-core": "0.1.43",
+    "@jskit-ai/http-runtime": "0.1.33",
+    "@jskit-ai/kernel": "0.1.34",
+    "@jskit-ai/realtime": "0.1.33",
+    "@jskit-ai/shell-web": "0.1.33",
+    "@jskit-ai/uploads-image-web": "0.1.12",
+    "@jskit-ai/users-core": "0.1.44",
     "vuetify": "^4.0.0"
   }
 }

package/src/client/components/UsersHomeToolsWidget.vue

@@ -0,0 +1,12 @@
+<script setup>
+import ShellOutletMenuWidget from "@jskit-ai/shell-web/client/components/ShellOutletMenuWidget";
+import { HOME_TOOLS_OUTLET } from "../../shared/toolsOutletContracts.js";
+</script>
+
+<template>
+  <ShellOutletMenuWidget
+    :target="HOME_TOOLS_OUTLET.target"
+    :default-link-component-token="HOME_TOOLS_OUTLET.defaultLinkComponentToken"
+    :aria-label="HOME_TOOLS_OUTLET.ariaLabel"
+  />
+</template>

package/src/client/components/UsersWorkspaceToolsWidget.vue

@@ -1,23 +1,12 @@
 <script setup>
-import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";
-import { mdiCogOutline } from "@mdi/js";
+import ShellOutletMenuWidget from "@jskit-ai/shell-web/client/components/ShellOutletMenuWidget";
+import { WORKSPACE_TOOLS_OUTLET } from "../../shared/toolsOutletContracts.js";
 </script>
 
 <template>
-  <v-menu location="bottom end" offset="10" eager>
-    <template #activator="{ props: activatorProps }">
-      <v-btn
-        v-bind="activatorProps"
-        icon
-        variant="text"
-        aria-label="Workspace tools"
-      >
-        <v-icon :icon="mdiCogOutline" />
-      </v-btn>
-    </template>
-
-    <v-list min-width="220" density="comfortable" class="py-1">
-      <ShellOutlet host="workspace-tools" position="primary-menu" />
-    </v-list>
-  </v-menu>
+  <ShellOutletMenuWidget
+    :target="WORKSPACE_TOOLS_OUTLET.target"
+    :default-link-component-token="WORKSPACE_TOOLS_OUTLET.defaultLinkComponentToken"
+    :aria-label="WORKSPACE_TOOLS_OUTLET.ariaLabel"
+  />
 </template>

package/src/client/index.js

@@ -2,8 +2,6 @@ import { UsersWebClientProvider } from "./providers/UsersWebClientProvider.js";
 
 export { UsersWebClientProvider } from "./providers/UsersWebClientProvider.js";
 export { UsersWorkspacesClientProvider } from "./providers/UsersWorkspacesClientProvider.js";
-export { default as ConsoleSettingsClientElement } from "./components/ConsoleSettingsClientElement.vue";
-export { default as WorkspaceSettingsClientElement } from "./components/WorkspaceSettingsClientElement.vue";
 
 const clientProviders = Object.freeze([UsersWebClientProvider]);
 

package/src/client/providers/UsersWebClientProvider.js

@@ -1,6 +1,5 @@
-import UsersShellMenuLinkItem from "../components/UsersShellMenuLinkItem.vue";
-import UsersSurfaceAwareMenuLinkItem from "../components/UsersSurfaceAwareMenuLinkItem.vue";
 import UsersProfileSurfaceSwitchMenuItem from "../components/UsersProfileSurfaceSwitchMenuItem.vue";
+import UsersHomeToolsWidget from "../components/UsersHomeToolsWidget.vue";
 import ProfileClientElement from "../components/ProfileClientElement.vue";
 import {
   createBootstrapPlacementRuntime
@@ -15,9 +14,8 @@ class UsersWebClientProvider {
       throw new Error("UsersWebClientProvider requires application singleton().");
     }
 
-    app.singleton("users.web.shell.menu-link-item", () => UsersShellMenuLinkItem);
-    app.singleton("users.web.shell.surface-aware-menu-link-item", () => UsersSurfaceAwareMenuLinkItem);
     app.singleton("users.web.profile.menu.surface-switch-item", () => UsersProfileSurfaceSwitchMenuItem);
+    app.singleton("users.web.home.tools.widget", () => UsersHomeToolsWidget);
     app.singleton("users.web.profile.element", () => ProfileClientElement);
     app.singleton("users.web.bootstrap-placement.runtime", (scope) => createBootstrapPlacementRuntime({ app: scope }));
   }

package/src/client/providers/UsersWorkspacesClientProvider.js

@@ -3,7 +3,6 @@ import UsersWorkspaceToolsWidget from "../components/UsersWorkspaceToolsWidget.v
 import UsersWorkspaceSettingsMenuItem from "../components/UsersWorkspaceSettingsMenuItem.vue";
 import UsersWorkspaceMembersMenuItem from "../components/UsersWorkspaceMembersMenuItem.vue";
 import MembersAdminClientElement from "../components/MembersAdminClientElement.vue";
-import WorkspaceSettingsClientElement from "../components/WorkspaceSettingsClientElement.vue";
 
 class UsersWorkspacesClientProvider {
   static id = "workspaces.web.client";
@@ -19,7 +18,6 @@ class UsersWorkspacesClientProvider {
     app.singleton("users.web.workspace-settings.menu-item", () => UsersWorkspaceSettingsMenuItem);
     app.singleton("users.web.workspace-members.menu-item", () => UsersWorkspaceMembersMenuItem);
     app.singleton("users.web.members-admin.element", () => MembersAdminClientElement);
-    app.singleton("users.web.workspace-settings.element", () => WorkspaceSettingsClientElement);
   }
 }
 

package/src/shared/toolsOutletContracts.js

@@ -0,0 +1,19 @@
+const DEFAULT_TOOLS_LINK_COMPONENT_TOKEN = "local.main.ui.surface-aware-menu-link-item";
+
+const HOME_TOOLS_OUTLET = Object.freeze({
+  target: "home-tools:primary-menu",
+  defaultLinkComponentToken: DEFAULT_TOOLS_LINK_COMPONENT_TOKEN,
+  ariaLabel: "Home tools"
+});
+
+const WORKSPACE_TOOLS_OUTLET = Object.freeze({
+  target: "workspace-tools:primary-menu",
+  defaultLinkComponentToken: DEFAULT_TOOLS_LINK_COMPONENT_TOKEN,
+  ariaLabel: "Workspace tools"
+});
+
+export {
+  DEFAULT_TOOLS_LINK_COMPONENT_TOKEN,
+  HOME_TOOLS_OUTLET,
+  WORKSPACE_TOOLS_OUTLET
+};

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

@@ -1,7 +1,8 @@
 <script setup>
-import ConsoleSettingsClientElement from "@jskit-ai/users-web/client/components/ConsoleSettingsClientElement";
+// To redirect this settings shell to a child page, uncomment and edit the example below.
+// definePage({
+//   redirect: (to) => `${to.path}/your_child_segment`
+// });
 </script>
 
-<template>
-  <ConsoleSettingsClientElement />
-</template>
+<template />

package/templates/src/pages/console/settings.vue

@@ -15,7 +15,10 @@ import { RouterView } from "vue-router";
         <v-row no-gutters>
           <v-col cols="12" md="3" lg="2" class="pr-md-4 mb-4 mb-md-0">
             <v-list nav density="comfortable" rounded="lg" border>
-              <ShellOutlet host="console-settings" position="primary-menu" />
+              <ShellOutlet
+                target="console-settings:primary-menu"
+                default-link-component-token="local.main.ui.surface-aware-menu-link-item"
+              />
             </v-list>
           </v-col>
 

package/test/settingsPlacementContract.test.js

@@ -8,30 +8,217 @@ 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(host = "") {
   const outlets = descriptor?.metadata?.ui?.placements?.outlets;
+  const normalizedTarget = String(host || "").trim();
   return Array.isArray(outlets)
-    ? outlets.filter((entry) => String(entry?.host || "").trim() === "console-settings")
+    ? outlets.filter((entry) => String(entry?.target || "").trim() === normalizedTarget)
     : [];
 }
 
+function findContribution(id) {
+  const contributions = descriptor?.metadata?.ui?.placements?.contributions;
+  return Array.isArray(contributions)
+    ? contributions.find((entry) => String(entry?.id || "").trim() === id) || null
+    : null;
+}
+
+function findTextMutation(id) {
+  const textMutations = descriptor?.mutations?.text;
+  return Array.isArray(textMutations)
+    ? textMutations.find((entry) => String(entry?.id || "").trim() === id) || null
+    : null;
+}
+
+function findFileMutation(id) {
+  const fileMutations = descriptor?.mutations?.files;
+  return Array.isArray(fileMutations)
+    ? fileMutations.find((entry) => String(entry?.id || "").trim() === id) || null
+    : null;
+}
+
+function expectContribution(id, expected = {}) {
+  const contribution = findContribution(id);
+  assert.ok(contribution, `Expected contribution "${id}".`);
+
+  for (const [key, value] of Object.entries(expected)) {
+    assert.deepEqual(contribution[key], value);
+  }
+}
+
+function expectTextMutation(id, { reason = "", category = "", skipIfContains = "", snippets = [] } = {}) {
+  const mutation = findTextMutation(id);
+  assert.ok(mutation, `Expected text mutation "${id}".`);
+  assert.equal(mutation.op, "append-text");
+  assert.equal(mutation.file, "src/placement.js");
+  assert.equal(mutation.position, "bottom");
+  assert.equal(mutation.id, id);
+
+  if (reason) {
+    assert.equal(mutation.reason, reason);
+  }
+
+  if (category) {
+    assert.equal(mutation.category, category);
+  }
+
+  if (skipIfContains) {
+    assert.equal(mutation.skipIfContains, skipIfContains);
+  }
+
+  for (const snippet of snippets) {
+    assert.ok(mutation.value.includes(snippet), `Expected mutation "${id}" to include "${snippet}".`);
+  }
+}
+
 test("users-web console settings template exposes surface-derived settings outlets", async () => {
   const source = await readFile(path.join(PACKAGE_DIR, "templates", "src", "pages", "console", "settings.vue"), "utf8");
 
-  assert.match(source, /<ShellOutlet host="console-settings" position="primary-menu" \/>/);
+  assert.match(source, /target="console-settings:primary-menu"/);
+  assert.match(source, /default-link-component-token="local\.main\.ui\.surface-aware-menu-link-item"/);
+  assert.match(source, /<RouterView \/>/);
+});
+
+test("users-web console settings index template is a simple developer-owned stub", async () => {
+  const source = await readFile(path.join(PACKAGE_DIR, "templates", "src", "pages", "console", "settings", "index.vue"), "utf8");
+
+  assert.match(source, /definePage/);
+  assert.match(source, /your_child_segment/);
 });
 
 test("users-web descriptor metadata advertises console settings outlets with standard positions", () => {
-  const outlets = readSettingsOutlets();
+  const outlets = readOutlets("console-settings:primary-menu");
   assert.deepEqual(
     outlets,
     [
       {
-        host: "console-settings",
-        position: "primary-menu",
+        target: "console-settings:primary-menu",
+        defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
         surfaces: ["console"],
         source: "templates/src/pages/console/settings.vue"
       }
     ]
   );
+  assert.deepEqual(findFileMutation("users-web-page-console-settings"), {
+    from: "templates/src/pages/console/settings/index.vue",
+    toSurface: "console",
+    toSurfacePath: "settings/index.vue",
+    reason: "Install console settings index stub scaffold for app-owned landing or redirect behavior.",
+    category: "users-web",
+    id: "users-web-page-console-settings"
+  });
+});
+
+test("users-web home tools widget exposes home-tools outlet", async () => {
+  const source = await readFile(path.join(PACKAGE_DIR, "src", "client", "components", "UsersHomeToolsWidget.vue"), "utf8");
+
+  assert.match(source, /import \{ HOME_TOOLS_OUTLET \} from "\.\.\/\.\.\/shared\/toolsOutletContracts\.js";/);
+  assert.match(source, /<ShellOutletMenuWidget/);
+  assert.match(source, /:target="HOME_TOOLS_OUTLET\.target"/);
+  assert.match(source, /:default-link-component-token="HOME_TOOLS_OUTLET\.defaultLinkComponentToken"/);
+});
+
+test("users-web workspace tools widget exposes workspace-tools outlet", async () => {
+  const source = await readFile(path.join(PACKAGE_DIR, "src", "client", "components", "UsersWorkspaceToolsWidget.vue"), "utf8");
+
+  assert.match(source, /import \{ WORKSPACE_TOOLS_OUTLET \} from "\.\.\/\.\.\/shared\/toolsOutletContracts\.js";/);
+  assert.match(source, /<ShellOutletMenuWidget/);
+  assert.match(source, /:target="WORKSPACE_TOOLS_OUTLET\.target"/);
+  assert.match(source, /:default-link-component-token="WORKSPACE_TOOLS_OUTLET\.defaultLinkComponentToken"/);
+});
+
+test("users-web descriptor metadata advertises home tools outlet and standard home settings placements", () => {
+  assert.deepEqual(
+    readOutlets("home-tools:primary-menu"),
+    [
+      {
+        target: "home-tools:primary-menu",
+        defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
+        surfaces: ["home"],
+        source: "src/client/components/UsersHomeToolsWidget.vue"
+      }
+    ]
+  );
+
+  expectContribution("users.home.menu.home", {
+    target: "shell-layout:primary-menu",
+    surfaces: ["*"],
+    order: 50,
+    componentToken: "local.main.ui.surface-aware-menu-link-item",
+    when: "auth.authenticated === true",
+    source: "mutations.text#users-web-home-shell-menu-placement"
+  });
+
+  expectContribution("users.profile.menu.settings", {
+    target: "auth-profile-menu:primary-menu",
+    surfaces: ["*"],
+    order: 500,
+    componentToken: "auth.web.profile.menu.link-item",
+    when: "auth.authenticated === true",
+    source: "mutations.text#users-web-profile-settings-placement"
+  });
+
+  expectContribution("users.home.tools.widget", {
+    target: "shell-layout:top-right",
+    surfaces: ["home"],
+    order: 900,
+    componentToken: "users.web.home.tools.widget",
+    when: "auth.authenticated === true",
+    source: "mutations.text#users-web-home-tools-placement"
+  });
+
+  expectContribution("users.home.menu.settings", {
+    target: "home-tools:primary-menu",
+    surfaces: ["home"],
+    order: 100,
+    componentToken: "local.main.ui.surface-aware-menu-link-item",
+    when: "auth.authenticated === true",
+    source: "mutations.text#users-web-home-tools-placement"
+  });
+  assert.equal(findContribution("users.home.settings.general"), null);
+
+  expectTextMutation("users-web-home-tools-placement", {
+    reason: "Append users-web home tools widget and settings menu placements into app-owned placement registry.",
+    category: "users-web",
+    skipIfContains: 'id: "users.home.tools.widget"',
+    snippets: [
+      'id: "users.home.tools.widget"',
+      'componentToken: "users.web.home.tools.widget"',
+      'id: "users.home.menu.settings"',
+      'target: "home-tools:primary-menu"',
+      'componentToken: "local.main.ui.surface-aware-menu-link-item"',
+      'workspaceSuffix: "/settings"',
+      'nonWorkspaceSuffix: "/settings"'
+    ]
+  });
+
+  expectTextMutation("users-web-profile-settings-placement", {
+    reason: "Append users-web profile settings menu placement into app-owned placement registry.",
+    category: "users-web",
+    skipIfContains: 'id: "users.profile.menu.settings"',
+    snippets: [
+      'id: "users.profile.menu.settings"',
+      'target: "auth-profile-menu:primary-menu"',
+      'componentToken: "auth.web.profile.menu.link-item"',
+      'label: "Settings"',
+      'to: "/account"'
+    ]
+  });
+
+  expectTextMutation("users-web-home-shell-menu-placement", {
+    reason: "Append users-web home shell menu placement into app-owned placement registry.",
+    category: "users-web",
+    skipIfContains: 'id: "users.home.menu.home"',
+    snippets: [
+      'id: "users.home.menu.home"',
+      'target: "shell-layout:primary-menu"',
+      'componentToken: "local.main.ui.surface-aware-menu-link-item"',
+      'label: "Home"',
+      'surface: "home"',
+      'workspaceSuffix: "/"',
+      'nonWorkspaceSuffix: "/"',
+      'exact: true'
+    ]
+  });
+
 });

package/src/client/components/UsersShellMenuLinkItem.vue

@@ -1,140 +0,0 @@
-<script setup>
-import { computed } from "vue";
-import { useRoute } from "vue-router";
-import { appendQueryString } from "@jskit-ai/kernel/shared/support";
-import { isExternalLinkTarget, splitPathQueryHash } from "@jskit-ai/kernel/shared/support/linkPath";
-import {
-  useWebPlacementContext,
-  resolveSurfaceNavigationTargetFromPlacementContext
-} from "@jskit-ai/shell-web/client/placement";
-import { resolveAccountSettingsPathFromPlacementContext } from "../lib/workspaceSurfacePaths.js";
-import { resolveMenuLinkIcon } from "../lib/menuIcons.js";
-
-const props = defineProps({
-  label: {
-    type: String,
-    default: ""
-  },
-  to: {
-    type: String,
-    default: ""
-  },
-  icon: {
-    type: String,
-    default: ""
-  },
-  disabled: {
-    type: Boolean,
-    default: false
-  }
-});
-
-const route = useRoute();
-const { context: placementContext } = useWebPlacementContext();
-
-function resolveFallbackReturnTo() {
-  if (typeof window !== "object" || !window || !window.location) {
-    return "/";
-  }
-  const pathname = String(window.location.pathname || "").trim() || "/";
-  const search = String(window.location.search || "").trim();
-  const hash = String(window.location.hash || "").trim();
-  return `${pathname}${search}${hash}`;
-}
-
-function resolveFallbackReturnToHref() {
-  if (typeof window !== "object" || !window || !window.location) {
-    return "/";
-  }
-  return String(window.location.href || "").trim() || resolveFallbackReturnTo();
-}
-
-function resolvePathnameFromLinkTarget(target = "") {
-  const normalizedTarget = String(target || "").trim();
-  if (!normalizedTarget) {
-    return "";
-  }
-
-  if (isExternalLinkTarget(normalizedTarget)) {
-    try {
-      const parsed = new URL(normalizedTarget);
-      return String(parsed.pathname || "").trim();
-    } catch {
-      return "";
-    }
-  }
-
-  return splitPathQueryHash(normalizedTarget).pathname;
-}
-
-const accountSettingsPathname = computed(() => {
-  const settingsPath = resolveAccountSettingsPathFromPlacementContext(placementContext.value);
-  return resolvePathnameFromLinkTarget(settingsPath);
-});
-
-const resolvedTo = computed(() => {
-  const target = String(props.to || "").trim();
-  if (!target) {
-    return "";
-  }
-
-  const targetPathname = resolvePathnameFromLinkTarget(target);
-  if (!targetPathname || targetPathname !== accountSettingsPathname.value) {
-    return target;
-  }
-  if (target.includes("returnTo=")) {
-    return target;
-  }
-
-  const accountSettingsTarget = resolveSurfaceNavigationTargetFromPlacementContext(placementContext.value, {
-    path: target,
-    surfaceId: "account"
-  });
-  const routeFullPath = String(route?.fullPath || "").trim();
-  const routePath = String(route?.path || "").trim();
-  const returnTo = accountSettingsTarget.sameOrigin
-    ? routeFullPath || routePath || resolveFallbackReturnTo()
-    : resolveFallbackReturnToHref();
-  const queryParams = new URLSearchParams({
-    returnTo
-  });
-
-  return appendQueryString(target, queryParams.toString());
-});
-
-const resolvedNavigationTarget = computed(() => {
-  const target = String(resolvedTo.value || "").trim();
-  if (!target) {
-    return {
-      href: "",
-      sameOrigin: true
-    };
-  }
-
-  const navigationTarget = resolveSurfaceNavigationTargetFromPlacementContext(placementContext.value, {
-    path: target
-  });
-  return {
-    href: navigationTarget.href,
-    sameOrigin: navigationTarget.sameOrigin
-  };
-});
-
-const resolvedIcon = computed(() =>
-  resolveMenuLinkIcon({
-    icon: props.icon,
-    label: props.label,
-    to: resolvedTo.value
-  })
-);
-</script>
-
-<template>
-  <v-list-item
-    :title="props.label"
-    :to="resolvedNavigationTarget.sameOrigin ? resolvedNavigationTarget.href : undefined"
-    :href="resolvedNavigationTarget.sameOrigin ? undefined : resolvedNavigationTarget.href"
-    :prepend-icon="resolvedIcon || undefined"
-    :disabled="props.disabled"
-  />
-</template>

package/src/client/components/UsersSurfaceAwareMenuLinkItem.vue

@@ -1,76 +0,0 @@
-<script setup>
-import { computed } from "vue";
-import { useRoute } from "vue-router";
-import { useWebPlacementContext } from "@jskit-ai/shell-web/client/placement";
-import { usePaths } from "../composables/usePaths.js";
-import { resolveMenuLinkIcon } from "../lib/menuIcons.js";
-import { resolveMenuLinkTarget } from "../support/menuLinkTarget.js";
-
-const props = defineProps({
-  label: {
-    type: String,
-    default: ""
-  },
-  to: {
-    type: String,
-    default: ""
-  },
-  icon: {
-    type: String,
-    default: ""
-  },
-  surface: {
-    type: String,
-    default: ""
-  },
-  workspaceSuffix: {
-    type: String,
-    default: "/"
-  },
-  nonWorkspaceSuffix: {
-    type: String,
-    default: "/"
-  },
-  disabled: {
-    type: Boolean,
-    default: false
-  }
-});
-
-const route = useRoute();
-const paths = usePaths();
-const { context: placementContext } = useWebPlacementContext();
-
-const resolvedTo = computed(() => {
-  return resolveMenuLinkTarget({
-    to: props.to,
-    surface: props.surface,
-    currentSurfaceId: paths.currentSurfaceId.value,
-    placementContext: placementContext.value,
-    workspaceSuffix: props.workspaceSuffix,
-    nonWorkspaceSuffix: props.nonWorkspaceSuffix,
-    routeParams: route.params || {},
-    resolvePagePath(relativePath, options = {}) {
-      return paths.page(relativePath, options);
-    }
-  });
-});
-
-const resolvedIcon = computed(() =>
-  resolveMenuLinkIcon({
-    icon: props.icon,
-    label: props.label,
-    to: resolvedTo.value
-  })
-);
-</script>
-
-<template>
-  <v-list-item
-    v-if="resolvedTo"
-    :title="props.label"
-    :to="resolvedTo"
-    :prepend-icon="resolvedIcon || undefined"
-    :disabled="props.disabled"
-  />
-</template>