@jskit-ai/shell-web 0.1.31 → 0.1.33

package/src/server/support/localLinkItemScaffolds.js

@@ -0,0 +1,80 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
+
+function createLocalLinkItemDefinition({
+  token = "",
+  componentFile = "",
+  componentName = "",
+  templateFile = ""
+} = {}) {
+  return Object.freeze({
+    token: String(token || "").trim(),
+    componentFile: String(componentFile || "").trim(),
+    componentName: String(componentName || "").trim(),
+    templateFile: String(templateFile || "").trim()
+  });
+}
+
+const LOCAL_LINK_ITEM_COMPONENT_DEFINITIONS = Object.freeze([
+  createLocalLinkItemDefinition({
+    token: "local.main.ui.menu-link-item",
+    componentFile: "src/components/menus/MenuLinkItem.vue",
+    componentName: "MenuLinkItem",
+    templateFile: "templates/src/components/menus/MenuLinkItem.vue"
+  }),
+  createLocalLinkItemDefinition({
+    token: "local.main.ui.surface-aware-menu-link-item",
+    componentFile: "src/components/menus/SurfaceAwareMenuLinkItem.vue",
+    componentName: "SurfaceAwareMenuLinkItem",
+    templateFile: "templates/src/components/menus/SurfaceAwareMenuLinkItem.vue"
+  }),
+  createLocalLinkItemDefinition({
+    token: "local.main.ui.tab-link-item",
+    componentFile: "src/components/menus/TabLinkItem.vue",
+    componentName: "TabLinkItem",
+    templateFile: "templates/src/components/menus/TabLinkItem.vue"
+  })
+]);
+
+const LOCAL_LINK_ITEM_COMPONENT_TOKENS = Object.freeze(
+  LOCAL_LINK_ITEM_COMPONENT_DEFINITIONS.map((entry) => entry.token)
+);
+
+function findLocalLinkItemDefinition(componentToken = "") {
+  const normalizedComponentToken = String(componentToken || "").trim();
+  return LOCAL_LINK_ITEM_COMPONENT_DEFINITIONS.find((entry) => entry.token === normalizedComponentToken) || null;
+}
+
+function resolveLocalLinkItemDefinition(componentTokenOrDefinition = "") {
+  if (
+    componentTokenOrDefinition &&
+    typeof componentTokenOrDefinition === "object" &&
+    !Array.isArray(componentTokenOrDefinition)
+  ) {
+    return componentTokenOrDefinition;
+  }
+  return findLocalLinkItemDefinition(componentTokenOrDefinition);
+}
+
+function resolveLocalLinkItemTemplateAbsolutePath(componentTokenOrDefinition = "") {
+  const definition = resolveLocalLinkItemDefinition(componentTokenOrDefinition);
+  if (!definition) {
+    throw new Error(`Unknown local link-item scaffold: ${String(componentTokenOrDefinition || "").trim() || "(empty)"}.`);
+  }
+  return path.join(PACKAGE_DIR, definition.templateFile);
+}
+
+async function readLocalLinkItemComponentSource(componentTokenOrDefinition = "") {
+  return await readFile(resolveLocalLinkItemTemplateAbsolutePath(componentTokenOrDefinition), "utf8");
+}
+
+export {
+  LOCAL_LINK_ITEM_COMPONENT_DEFINITIONS,
+  LOCAL_LINK_ITEM_COMPONENT_TOKENS,
+  findLocalLinkItemDefinition,
+  readLocalLinkItemComponentSource,
+  resolveLocalLinkItemTemplateAbsolutePath
+};

package/templates/expected-existing/src/App.vue

@@ -0,0 +1,13 @@
+<template>
+  <v-app>
+    <v-main>
+      <v-container class="py-10 py-md-14">
+        <v-row justify="center">
+          <v-col cols="12" sm="11" md="10" lg="8" xl="7">
+            <RouterView />
+          </v-col>
+        </v-row>
+      </v-container>
+    </v-main>
+  </v-app>
+</template>

package/templates/expected-existing/src/pages/console/index.vue

@@ -0,0 +1,12 @@
+<template>
+  <v-card class="mx-auto" max-width="960" rounded="xl" border elevation="1">
+    <v-card-item class="px-6 py-5 px-md-8 py-md-7">
+      <v-card-title class="text-h4">console</v-card-title>
+      <v-card-subtitle class="text-subtitle-1 mt-2">operations surface</v-card-subtitle>
+    </v-card-item>
+    <v-divider />
+    <v-card-text class="px-6 py-5 px-md-8 py-md-7 text-body-1 text-medium-emphasis">
+      This surface is intended for operational tooling.
+    </v-card-text>
+  </v-card>
+</template>

package/templates/expected-existing/src/pages/console.vue

@@ -0,0 +1,13 @@
+<route lang="json">
+{
+  "meta": {
+    "jskit": {
+      "surface": "console"
+    }
+  }
+}
+</route>
+
+<template>
+  <RouterView />
+</template>

package/templates/expected-existing/src/pages/home/index.vue

@@ -0,0 +1,12 @@
+<template>
+  <v-card class="mx-auto" max-width="960" rounded="xl" border elevation="1">
+    <v-card-item class="px-6 py-5 px-md-8 py-md-7">
+      <v-card-title class="text-h4">welcome</v-card-title>
+      <v-card-subtitle class="text-subtitle-1 mt-2">starter app</v-card-subtitle>
+    </v-card-item>
+    <v-divider />
+    <v-card-text class="px-6 py-5 px-md-8 py-md-7 text-body-1 text-medium-emphasis">
+      Start by adding packages and pages to this app.
+    </v-card-text>
+  </v-card>
+</template>

package/templates/expected-existing/src/pages/home.vue

@@ -0,0 +1,13 @@
+<route lang="json">
+{
+  "meta": {
+    "jskit": {
+      "surface": "home"
+    }
+  }
+}
+</route>
+
+<template>
+  <RouterView />
+</template>

package/templates/src/components/ShellLayout.vue

@@ -32,7 +32,7 @@ const { drawerOpen, toggleDrawer, resolvedSurface, resolvedSurfaceLabel } = useS
       <slot name="top-left" :surface="resolvedSurface">
         <div class="d-flex align-center ga-2">
           <v-chip color="primary" size="small" label>{{ resolvedSurfaceLabel }}</v-chip>
-          <ShellOutlet host="shell-layout" position="top-left" />
+          <ShellOutlet target="shell-layout:top-left" />
         </div>
       </slot>
 
@@ -40,7 +40,7 @@ const { drawerOpen, toggleDrawer, resolvedSurface, resolvedSurfaceLabel } = useS
 
       <slot name="top-right" :surface="resolvedSurface">
         <div class="d-flex align-center ga-2">
-          <ShellOutlet host="shell-layout" position="top-right" />
+          <ShellOutlet target="shell-layout:top-right" />
         </div>
       </slot>
     </v-app-bar>
@@ -49,9 +49,16 @@ const { drawerOpen, toggleDrawer, resolvedSurface, resolvedSurfaceLabel } = useS
       <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>
-          <ShellOutlet host="shell-layout" position="primary-menu" default />
+          <ShellOutlet
+            target="shell-layout:primary-menu"
+            default
+            default-link-component-token="local.main.ui.surface-aware-menu-link-item"
+          />
           <v-divider class="my-2" />
-          <ShellOutlet host="shell-layout" position="secondary-menu" />
+          <ShellOutlet
+            target="shell-layout:secondary-menu"
+            default-link-component-token="local.main.ui.surface-aware-menu-link-item"
+          />
         </v-list>
       </slot>
     </v-navigation-drawer>

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

@@ -0,0 +1,30 @@
+<script setup>
+import ShellMenuLinkItem from "@jskit-ai/shell-web/client/components/ShellMenuLinkItem";
+
+const props = defineProps({
+  label: {
+    type: String,
+    default: ""
+  },
+  to: {
+    type: String,
+    default: ""
+  },
+  icon: {
+    type: String,
+    default: ""
+  },
+  disabled: {
+    type: Boolean,
+    default: false
+  },
+  exact: {
+    type: Boolean,
+    default: false
+  }
+});
+</script>
+
+<template>
+  <ShellMenuLinkItem v-bind="props" />
+</template>

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

@@ -0,0 +1,42 @@
+<script setup>
+import ShellSurfaceAwareMenuLinkItem from "@jskit-ai/shell-web/client/components/ShellSurfaceAwareMenuLinkItem";
+
+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
+  },
+  exact: {
+    type: Boolean,
+    default: false
+  }
+});
+</script>
+
+<template>
+  <ShellSurfaceAwareMenuLinkItem v-bind="props" />
+</template>

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

@@ -0,0 +1,34 @@
+<script setup>
+import ShellTabLinkItem from "@jskit-ai/shell-web/client/components/ShellTabLinkItem";
+
+const props = defineProps({
+  label: {
+    type: String,
+    default: ""
+  },
+  to: {
+    type: String,
+    default: ""
+  },
+  surface: {
+    type: String,
+    default: ""
+  },
+  workspaceSuffix: {
+    type: String,
+    default: "/"
+  },
+  nonWorkspaceSuffix: {
+    type: String,
+    default: "/"
+  },
+  disabled: {
+    type: Boolean,
+    default: false
+  }
+});
+</script>
+
+<template>
+  <ShellTabLinkItem v-bind="props" />
+</template>

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

@@ -1,8 +1,8 @@
-<template>
-  <v-sheet rounded="lg" border class="pa-6">
-    <h2 class="text-h6 mb-2">Settings</h2>
-    <p class="text-body-2 text-medium-emphasis mb-0">
-      Select a settings section from the menu.
-    </p>
-  </v-sheet>
-</template>
+<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`
+// });
+</script>
+
+<template />

package/templates/src/pages/home/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="home-settings" position="primary-menu" />
+              <ShellOutlet
+                target="home-settings:primary-menu"
+                default-link-component-token="local.main.ui.surface-aware-menu-link-item"
+              />
             </v-list>
           </v-col>
 

package/test/bootstrapClaimContract.test.js

@@ -0,0 +1,88 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import descriptor from "../package.descriptor.mjs";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_DIR = path.resolve(TEST_DIRECTORY, "..");
+const CREATE_APP_TEMPLATE_DIR = path.resolve(PACKAGE_DIR, "..", "..", "tooling", "create-app", "templates", "base-shell");
+
+function findFileMutation(id) {
+  const files = descriptor?.mutations?.files;
+  return Array.isArray(files)
+    ? files.find((entry) => String(entry?.id || "").trim() === id) || null
+    : null;
+}
+
+test("shell-web claims starter shell files as app-owned scaffolds", () => {
+  assert.deepEqual(findFileMutation("shell-web-app-root"), {
+    from: "templates/src/App.vue",
+    to: "src/App.vue",
+    ownership: "app",
+    expectedExistingFrom: "templates/expected-existing/src/App.vue",
+    reason: "Install full-width shell app root with shell-web error host and edge-to-edge layout.",
+    category: "shell-web",
+    id: "shell-web-app-root"
+  });
+  assert.deepEqual(findFileMutation("shell-web-page-home-wrapper"), {
+    from: "templates/src/pages/home.vue",
+    toSurface: "home",
+    toSurfaceRoot: true,
+    ownership: "app",
+    expectedExistingFrom: "templates/expected-existing/src/pages/home.vue",
+    reason: "Install shell-driven home wrapper page.",
+    category: "shell-web",
+    id: "shell-web-page-home-wrapper"
+  });
+  assert.deepEqual(findFileMutation("shell-web-page-home"), {
+    from: "templates/src/pages/home/index.vue",
+    toSurface: "home",
+    toSurfacePath: "index.vue",
+    ownership: "app",
+    expectedExistingFrom: "templates/expected-existing/src/pages/home/index.vue",
+    reason: "Install shell-driven home surface starter page.",
+    category: "shell-web",
+    id: "shell-web-page-home"
+  });
+  assert.deepEqual(findFileMutation("shell-web-page-console-wrapper"), {
+    from: "templates/src/pages/console.vue",
+    toSurface: "console",
+    toSurfaceRoot: true,
+    ownership: "app",
+    expectedExistingFrom: "templates/expected-existing/src/pages/console.vue",
+    reason: "Install shell-driven console wrapper page.",
+    category: "shell-web",
+    id: "shell-web-page-console-wrapper"
+  });
+  assert.deepEqual(findFileMutation("shell-web-page-console"), {
+    from: "templates/src/pages/console/index.vue",
+    toSurface: "console",
+    toSurfacePath: "index.vue",
+    ownership: "app",
+    expectedExistingFrom: "templates/expected-existing/src/pages/console/index.vue",
+    reason: "Install shell-driven console page starter.",
+    category: "shell-web",
+    id: "shell-web-page-console"
+  });
+});
+
+test("shell-web expected-existing starter files stay aligned with create-app base-shell", async () => {
+  const comparedFiles = [
+    "src/App.vue",
+    "src/pages/home.vue",
+    "src/pages/home/index.vue",
+    "src/pages/console.vue",
+    "src/pages/console/index.vue"
+  ];
+
+  for (const relativeFile of comparedFiles) {
+    const shellWebExpectedSource = await readFile(
+      path.join(PACKAGE_DIR, "templates", "expected-existing", relativeFile),
+      "utf8"
+    );
+    const createAppSource = await readFile(path.join(CREATE_APP_TEMPLATE_DIR, relativeFile), "utf8");
+    assert.equal(shellWebExpectedSource, createAppSource, relativeFile);
+  }
+});

package/test/linkItemScaffoldContract.test.js

@@ -0,0 +1,209 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import descriptor from "../package.descriptor.mjs";
+import {
+  LOCAL_LINK_ITEM_COMPONENT_DEFINITIONS,
+  findLocalLinkItemDefinition,
+  readLocalLinkItemComponentSource
+} from "../src/server/support/localLinkItemScaffolds.js";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_DIR = path.resolve(TEST_DIRECTORY, "..");
+
+function findFileMutation(id) {
+  const files = descriptor?.mutations?.files;
+  return Array.isArray(files)
+    ? files.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;
+}
+
+test("shell-web exports generic link-item components for app-owned shell wrappers", async () => {
+  const clientIndexSource = await readFile(path.join(PACKAGE_DIR, "src", "client", "index.js"), "utf8");
+  assert.match(clientIndexSource, /ShellMenuLinkItem/);
+  assert.match(clientIndexSource, /ShellSurfaceAwareMenuLinkItem/);
+  assert.match(clientIndexSource, /ShellTabLinkItem/);
+
+  const packageJson = JSON.parse(await readFile(path.join(PACKAGE_DIR, "package.json"), "utf8"));
+  assert.equal(
+    packageJson?.exports?.["./client/components/ShellMenuLinkItem"],
+    "./src/client/components/ShellMenuLinkItem.vue"
+  );
+  assert.equal(
+    packageJson?.exports?.["./client/components/ShellSurfaceAwareMenuLinkItem"],
+    "./src/client/components/ShellSurfaceAwareMenuLinkItem.vue"
+  );
+  assert.equal(
+    packageJson?.exports?.["./client/components/ShellTabLinkItem"],
+    "./src/client/components/ShellTabLinkItem.vue"
+  );
+  assert.equal(
+    packageJson?.exports?.["./server/support/localLinkItemScaffolds"],
+    "./src/server/support/localLinkItemScaffolds.js"
+  );
+});
+
+test("shell-web scaffolds app-owned local link-item wrappers under src/components/menus", async () => {
+  const menuWrapperSource = await readFile(
+    path.join(PACKAGE_DIR, "templates", "src", "components", "menus", "MenuLinkItem.vue"),
+    "utf8"
+  );
+  const surfaceAwareWrapperSource = await readFile(
+    path.join(PACKAGE_DIR, "templates", "src", "components", "menus", "SurfaceAwareMenuLinkItem.vue"),
+    "utf8"
+  );
+  const tabWrapperSource = await readFile(
+    path.join(PACKAGE_DIR, "templates", "src", "components", "menus", "TabLinkItem.vue"),
+    "utf8"
+  );
+
+  assert.match(menuWrapperSource, /@jskit-ai\/shell-web\/client\/components\/ShellMenuLinkItem/);
+  assert.match(surfaceAwareWrapperSource, /@jskit-ai\/shell-web\/client\/components\/ShellSurfaceAwareMenuLinkItem/);
+  assert.match(tabWrapperSource, /@jskit-ai\/shell-web\/client\/components\/ShellTabLinkItem/);
+  assert.match(menuWrapperSource, /exact:\s*\{/);
+  assert.match(surfaceAwareWrapperSource, /exact:\s*\{/);
+
+  assert.deepEqual(findFileMutation("shell-web-component-menu-link-item"), {
+    from: "templates/src/components/menus/MenuLinkItem.vue",
+    to: "src/components/menus/MenuLinkItem.vue",
+    ownership: "app",
+    reason: "Install app-owned shell menu link-item scaffold for local placement customization.",
+    category: "shell-web",
+    id: "shell-web-component-menu-link-item"
+  });
+  assert.deepEqual(findFileMutation("shell-web-component-surface-aware-menu-link-item"), {
+    from: "templates/src/components/menus/SurfaceAwareMenuLinkItem.vue",
+    to: "src/components/menus/SurfaceAwareMenuLinkItem.vue",
+    ownership: "app",
+    reason: "Install app-owned surface-aware shell menu link-item scaffold for local placement customization.",
+    category: "shell-web",
+    id: "shell-web-component-surface-aware-menu-link-item"
+  });
+  assert.deepEqual(findFileMutation("shell-web-component-tab-link-item"), {
+    from: "templates/src/components/menus/TabLinkItem.vue",
+    to: "src/components/menus/TabLinkItem.vue",
+    ownership: "app",
+    reason: "Install app-owned shell tab link-item scaffold for local placement customization.",
+    category: "shell-web",
+    id: "shell-web-component-tab-link-item"
+  });
+
+  assert.deepEqual(
+    LOCAL_LINK_ITEM_COMPONENT_DEFINITIONS.map((entry) => ({
+      token: entry.token,
+      componentFile: entry.componentFile,
+      componentName: entry.componentName,
+      templateFile: entry.templateFile
+    })),
+    [
+      {
+        token: "local.main.ui.menu-link-item",
+        componentFile: "src/components/menus/MenuLinkItem.vue",
+        componentName: "MenuLinkItem",
+        templateFile: "templates/src/components/menus/MenuLinkItem.vue"
+      },
+      {
+        token: "local.main.ui.surface-aware-menu-link-item",
+        componentFile: "src/components/menus/SurfaceAwareMenuLinkItem.vue",
+        componentName: "SurfaceAwareMenuLinkItem",
+        templateFile: "templates/src/components/menus/SurfaceAwareMenuLinkItem.vue"
+      },
+      {
+        token: "local.main.ui.tab-link-item",
+        componentFile: "src/components/menus/TabLinkItem.vue",
+        componentName: "TabLinkItem",
+        templateFile: "templates/src/components/menus/TabLinkItem.vue"
+      }
+    ]
+  );
+  assert.equal(findLocalLinkItemDefinition("local.main.ui.tab-link-item")?.componentName, "TabLinkItem");
+  assert.equal(await readLocalLinkItemComponentSource("local.main.ui.tab-link-item"), tabWrapperSource);
+});
+
+test("shell-web generic menu link items support exact route matching", async () => {
+  const shellMenuSource = await readFile(
+    path.join(PACKAGE_DIR, "src", "client", "components", "ShellMenuLinkItem.vue"),
+    "utf8"
+  );
+  const shellSurfaceAwareSource = await readFile(
+    path.join(PACKAGE_DIR, "src", "client", "components", "ShellSurfaceAwareMenuLinkItem.vue"),
+    "utf8"
+  );
+
+  assert.match(shellMenuSource, /exact:\s*\{/);
+  assert.match(shellMenuSource, /:exact="props\.exact"/);
+  assert.match(shellSurfaceAwareSource, /exact:\s*\{/);
+  assert.match(shellSurfaceAwareSource, /:exact="props\.exact"/);
+});
+
+test("shell-web binds the local link-item wrapper tokens into MainClientProvider", () => {
+  assert.deepEqual(findTextMutation("shell-web-main-client-provider-menu-link-item-import"), {
+    op: "append-text",
+    file: "packages/main/src/client/providers/MainClientProvider.js",
+    position: "top",
+    skipIfContains: "import MenuLinkItem from \"/src/components/menus/MenuLinkItem.vue\";",
+    value: "import MenuLinkItem from \"/src/components/menus/MenuLinkItem.vue\";\n",
+    reason: "Bind app-owned shell menu link-item scaffold into local main client provider imports.",
+    category: "shell-web",
+    id: "shell-web-main-client-provider-menu-link-item-import"
+  });
+  assert.deepEqual(findTextMutation("shell-web-main-client-provider-surface-aware-menu-link-item-import"), {
+    op: "append-text",
+    file: "packages/main/src/client/providers/MainClientProvider.js",
+    position: "top",
+    skipIfContains: "import SurfaceAwareMenuLinkItem from \"/src/components/menus/SurfaceAwareMenuLinkItem.vue\";",
+    value: "import SurfaceAwareMenuLinkItem from \"/src/components/menus/SurfaceAwareMenuLinkItem.vue\";\n",
+    reason: "Bind app-owned shell surface-aware menu link-item scaffold into local main client provider imports.",
+    category: "shell-web",
+    id: "shell-web-main-client-provider-surface-aware-menu-link-item-import"
+  });
+  assert.deepEqual(findTextMutation("shell-web-main-client-provider-tab-link-item-import"), {
+    op: "append-text",
+    file: "packages/main/src/client/providers/MainClientProvider.js",
+    position: "top",
+    skipIfContains: "import TabLinkItem from \"/src/components/menus/TabLinkItem.vue\";",
+    value: "import TabLinkItem from \"/src/components/menus/TabLinkItem.vue\";\n",
+    reason: "Bind app-owned shell tab link-item scaffold into local main client provider imports.",
+    category: "shell-web",
+    id: "shell-web-main-client-provider-tab-link-item-import"
+  });
+  assert.deepEqual(findTextMutation("shell-web-main-client-provider-menu-link-item-register"), {
+    op: "append-text",
+    file: "packages/main/src/client/providers/MainClientProvider.js",
+    position: "bottom",
+    skipIfContains: "registerMainClientComponent(\"local.main.ui.menu-link-item\", () => MenuLinkItem);",
+    value: "\nregisterMainClientComponent(\"local.main.ui.menu-link-item\", () => MenuLinkItem);\n",
+    reason: "Bind app-owned shell menu link-item token into local main client provider registry.",
+    category: "shell-web",
+    id: "shell-web-main-client-provider-menu-link-item-register"
+  });
+  assert.deepEqual(findTextMutation("shell-web-main-client-provider-surface-aware-menu-link-item-register"), {
+    op: "append-text",
+    file: "packages/main/src/client/providers/MainClientProvider.js",
+    position: "bottom",
+    skipIfContains: "registerMainClientComponent(\"local.main.ui.surface-aware-menu-link-item\", () => SurfaceAwareMenuLinkItem);",
+    value: "\nregisterMainClientComponent(\"local.main.ui.surface-aware-menu-link-item\", () => SurfaceAwareMenuLinkItem);\n",
+    reason: "Bind app-owned shell surface-aware menu link-item token into local main client provider registry.",
+    category: "shell-web",
+    id: "shell-web-main-client-provider-surface-aware-menu-link-item-register"
+  });
+  assert.deepEqual(findTextMutation("shell-web-main-client-provider-tab-link-item-register"), {
+    op: "append-text",
+    file: "packages/main/src/client/providers/MainClientProvider.js",
+    position: "bottom",
+    skipIfContains: "registerMainClientComponent(\"local.main.ui.tab-link-item\", () => TabLinkItem);",
+    value: "\nregisterMainClientComponent(\"local.main.ui.tab-link-item\", () => TabLinkItem);\n",
+    reason: "Bind app-owned shell tab link-item token into local main client provider registry.",
+    category: "shell-web",
+    id: "shell-web-main-client-provider-tab-link-item-register"
+  });
+});

package/test/outletMenuWidgetContract.test.js

@@ -0,0 +1,33 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_DIR = path.resolve(TEST_DIRECTORY, "..");
+
+test("shell-web outlet menu widget exposes a configurable nested outlet", async () => {
+  const source = await readFile(
+    path.join(PACKAGE_DIR, "src", "client", "components", "ShellOutletMenuWidget.vue"),
+    "utf8"
+  );
+
+  assert.match(source, /import \{ mdiCogOutline \} from "@mdi\/js";/);
+  assert.match(source, /defaultLinkComponentToken: \{/);
+  assert.match(source, /:target="props\.target"/);
+  assert.match(source, /:default-link-component-token="props\.defaultLinkComponentToken"/);
+  assert.match(source, /default: mdiCogOutline/);
+  assert.doesNotMatch(source, /mdi-[a-z0-9-]+/);
+});
+
+test("shell-web exports the outlet menu widget from both client index and package exports", async () => {
+  const clientIndexSource = await readFile(path.join(PACKAGE_DIR, "src", "client", "index.js"), "utf8");
+  assert.match(clientIndexSource, /export \{ default as ShellOutletMenuWidget \} from "\.\/components\/ShellOutletMenuWidget\.vue";/);
+
+  const packageJson = JSON.parse(await readFile(path.join(PACKAGE_DIR, "package.json"), "utf8"));
+  assert.equal(
+    packageJson?.exports?.["./client/components/ShellOutletMenuWidget"],
+    "./src/client/components/ShellOutletMenuWidget.vue"
+  );
+});