@jskit-ai/shell-web 0.1.63 → 0.1.65

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/shell-web",
-  version: "0.1.63",
+  version: "0.1.65",
   kind: "runtime",
   description: "Web shell layout runtime with outlet-based placement contributions.",
   dependsOn: [],
@@ -71,46 +71,157 @@ export default Object.freeze({
           },
           {
             target: "shell-layout:primary-menu",
-            defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
             surfaces: ["*"],
             source: "src/client/components/ShellLayout.vue"
           },
           {
             target: "shell-layout:secondary-menu",
-            defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
             surfaces: ["*"],
             source: "src/client/components/ShellLayout.vue"
           },
           {
             target: "home-settings:primary-menu",
-            defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
             surfaces: ["home"],
             source: "templates/src/pages/home/settings.vue"
           }
         ],
+        topology: {
+          placements: [
+            {
+              id: "shell.primary-nav",
+              description: "Primary top-level navigation for the current surface.",
+              surfaces: ["*"],
+              default: true,
+              variants: {
+                compact: {
+                  outlet: "shell-layout:primary-menu",
+                  renderers: {
+                    link: "local.main.ui.surface-aware-menu-link-item"
+                  }
+                },
+                medium: {
+                  outlet: "shell-layout:primary-menu",
+                  renderers: {
+                    link: "local.main.ui.surface-aware-menu-link-item"
+                  }
+                },
+                expanded: {
+                  outlet: "shell-layout:primary-menu",
+                  renderers: {
+                    link: "local.main.ui.surface-aware-menu-link-item"
+                  }
+                }
+              }
+            },
+            {
+              id: "shell.status",
+              description: "Surface status, connection, and utility indicators.",
+              surfaces: ["*"],
+              variants: {
+                compact: {
+                  outlet: "shell-layout:top-right"
+                },
+                medium: {
+                  outlet: "shell-layout:top-right"
+                },
+                expanded: {
+                  outlet: "shell-layout:top-right"
+                }
+              }
+            },
+            {
+              id: "shell.secondary-nav",
+              description: "Secondary navigation for lower-priority shell links.",
+              surfaces: ["*"],
+              variants: {
+                compact: {
+                  outlet: "shell-layout:secondary-menu",
+                  renderers: {
+                    link: "local.main.ui.surface-aware-menu-link-item"
+                  }
+                },
+                medium: {
+                  outlet: "shell-layout:secondary-menu",
+                  renderers: {
+                    link: "local.main.ui.surface-aware-menu-link-item"
+                  }
+                },
+                expanded: {
+                  outlet: "shell-layout:secondary-menu",
+                  renderers: {
+                    link: "local.main.ui.surface-aware-menu-link-item"
+                  }
+                }
+              }
+            },
+            {
+              id: "shell.identity",
+              description: "Current user, workspace, and surface identity controls.",
+              surfaces: ["*"],
+              variants: {
+                compact: {
+                  outlet: "shell-layout:top-left"
+                },
+                medium: {
+                  outlet: "shell-layout:top-left"
+                },
+                expanded: {
+                  outlet: "shell-layout:top-left"
+                }
+              }
+            },
+            {
+              id: "page.section-nav",
+              owner: "home-settings",
+              description: "Navigation between child pages in the home settings section.",
+              surfaces: ["home"],
+              variants: {
+                compact: {
+                  outlet: "home-settings:primary-menu",
+                  renderers: {
+                    link: "local.main.ui.surface-aware-menu-link-item"
+                  }
+                },
+                medium: {
+                  outlet: "home-settings:primary-menu",
+                  renderers: {
+                    link: "local.main.ui.surface-aware-menu-link-item"
+                  }
+                },
+                expanded: {
+                  outlet: "home-settings:primary-menu",
+                  renderers: {
+                    link: "local.main.ui.surface-aware-menu-link-item"
+                  }
+                }
+              }
+            }
+          ]
+        },
         contributions: [
           {
             id: "shell-web.home.menu.home",
-            target: "shell-layout:primary-menu",
+            target: "shell.primary-nav",
+            kind: "link",
             surfaces: ["home"],
             order: 50,
-            componentToken: "local.main.ui.surface-aware-menu-link-item",
             source: "templates/src/placement.js"
           },
           {
             id: "shell-web.home.menu.settings",
-            target: "shell-layout:primary-menu",
+            target: "shell.primary-nav",
+            kind: "link",
             surfaces: ["home"],
             order: 100,
-            componentToken: "local.main.ui.surface-aware-menu-link-item",
             source: "templates/src/placement.js"
           },
           {
             id: "shell-web.home.settings.general",
-            target: "home-settings:primary-menu",
+            target: "page.section-nav",
+            owner: "home-settings",
+            kind: "link",
             surfaces: ["home"],
             order: 100,
-            componentToken: "local.main.ui.surface-aware-menu-link-item",
             source: "templates/src/placement.js"
           }
         ]
@@ -122,7 +233,7 @@ export default Object.freeze({
       runtime: {
         "@mdi/js": "^7.4.47",
         "@tanstack/vue-query": "^5.90.5",
-        "@jskit-ai/kernel": "0.1.64",
+        "@jskit-ai/kernel": "0.1.66",
         "vuetify": "^4.0.0"
       },
       dev: {}
@@ -254,6 +365,14 @@ export default Object.freeze({
         category: "shell-web",
         id: "shell-web-placement-registry"
       },
+      {
+        from: "templates/src/placementTopology.js",
+        to: "src/placementTopology.js",
+        ownership: "app",
+        reason: "Install app-owned semantic placement topology used by shell-web placement runtime.",
+        category: "shell-web",
+        id: "shell-web-placement-topology"
+      },
       {
         from: "templates/src/pages/home.vue",
         toSurface: "home",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/shell-web",
-  "version": "0.1.63",
+  "version": "0.1.65",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -25,7 +25,7 @@
   "dependencies": {
     "@mdi/js": "^7.4.47",
     "@tanstack/vue-query": "^5.90.5",
-    "@jskit-ai/kernel": "0.1.64",
+    "@jskit-ai/kernel": "0.1.66",
     "pinia": "^3.0.4",
     "vuetify": "^4.0.0"
   },

package/src/client/components/ShellLayout.vue

@@ -52,13 +52,9 @@ const { drawerOpen, toggleDrawer, resolvedSurface, resolvedSurfaceLabel } = useS
           <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
-            target="shell-layout:secondary-menu"
-            default-link-component-token="local.main.ui.surface-aware-menu-link-item"
-          />
+          <ShellOutlet target="shell-layout:secondary-menu" />
         </v-list>
       </slot>
     </v-navigation-drawer>

package/src/client/components/ShellOutlet.vue

@@ -6,6 +6,7 @@ import {
   ref
 } from "vue";
 import { useRoute } from "vue-router";
+import { useDisplay } from "vuetify";
 import { useWebPlacementContext, useWebPlacementRuntime } from "../placement/inject.js";
 import { resolveRuntimePathname } from "../placement/pathname.js";
 import {
@@ -25,10 +26,6 @@ const props = defineProps({
   context: {
     type: Object,
     default: () => ({})
-  },
-  defaultLinkComponentToken: {
-    type: String,
-    default: ""
   }
 });
 
@@ -39,6 +36,13 @@ try {
   route = null;
 }
 
+let display = null;
+try {
+  display = useDisplay();
+} catch {
+  display = null;
+}
+
 const placementRuntime = useWebPlacementRuntime();
 const { context: placementContext } = useWebPlacementContext();
 const revision = ref(
@@ -82,11 +86,37 @@ const resolvedTargetId = computed(() => {
   return String(props.target || "").trim();
 });
 
+const resolvedLayoutClass = computed(() => {
+  const displayName = String(display?.name?.value || "").trim().toLowerCase();
+  if (displayName === "xs" || displayName === "sm") {
+    return "compact";
+  }
+  if (displayName === "md") {
+    return "medium";
+  }
+  if (displayName === "lg" || displayName === "xl" || displayName === "xxl") {
+    return "expanded";
+  }
+
+  const viewportWidth =
+    typeof window === "object" && window?.innerWidth
+      ? Number(window.innerWidth)
+      : 0;
+  if (viewportWidth > 0 && viewportWidth < 600) {
+    return "compact";
+  }
+  if (viewportWidth > 0 && viewportWidth < 1280) {
+    return "medium";
+  }
+  return "expanded";
+});
+
 const placements = computed(() => {
   void revision.value;
   return placementRuntime.getPlacements({
     surface: resolvedSurface.value,
     target: resolvedTargetId.value,
+    layoutClass: resolvedLayoutClass.value,
     context: props.context
   });
 });

package/src/client/components/ShellOutletMenuWidget.vue

@@ -7,10 +7,6 @@ const props = defineProps({
     type: String,
     required: true
   },
-  defaultLinkComponentToken: {
-    type: String,
-    default: ""
-  },
   icon: {
     type: String,
     default: mdiCogOutline
@@ -48,10 +44,7 @@ const props = defineProps({
     </template>
 
     <v-list :min-width="props.minWidth" density="comfortable" class="py-1">
-      <ShellOutlet
-        :target="props.target"
-        :default-link-component-token="props.defaultLinkComponentToken"
-      />
+      <ShellOutlet :target="props.target" />
     </v-list>
   </v-menu>
 </template>

package/src/client/placement/index.js

@@ -2,6 +2,11 @@ export {
   createPlacementRegistry
 } from "./registry.js";
 
+export {
+  definePlacement,
+  definePlacementTopology
+} from "./validators.js";
+
 export {
   useWebPlacementContext
 } from "./inject.js";

package/src/client/placement/runtime.js

@@ -1,6 +1,10 @@
 import { DEFAULT_DEBUG_DEPTH, explodePayload } from "./debug.js";
 import { createListenerSubscription } from "@jskit-ai/kernel/shared/support/listenerSet";
 import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import {
+  normalizePlacementLayoutClass,
+  normalizePlacementTopologyDefinition
+} from "@jskit-ai/kernel/shared/support/shellLayoutTargets";
 import {
   isRenderableComponent,
   normalizePlacementDefinition,
@@ -100,6 +104,40 @@ function normalizePlacementList(placements, context = {}) {
     .map((entry) => entry.placement);
 }
 
+function normalizeTopologyList(topology, context = {}) {
+  if (Array.isArray(topology)) {
+    const normalized = normalizePlacementTopologyDefinition(
+      { placements: topology },
+      {
+        context: context.source || "placement topology"
+      }
+    );
+    return normalizeTopologyList(normalized, context);
+  }
+
+  const candidates = ensureArray(topology);
+  const entries = [];
+  for (const candidate of candidates) {
+    const normalized = normalizePlacementTopologyDefinition(candidate, {
+      context: context.source || "placement topology"
+    });
+    entries.push(...normalized.placements);
+  }
+
+  const byKey = new Map();
+  for (const entry of entries) {
+    const key = `${entry.id}::${entry.owner || ""}`;
+    if (byKey.has(key)) {
+      throw new Error(
+        `Duplicate semantic placement "${entry.id}"${entry.owner ? ` for owner "${entry.owner}"` : ""} in ${context.source || "placement topology"}.`
+      );
+    }
+    byKey.set(key, entry);
+  }
+
+  return Object.freeze([...byKey.values()]);
+}
+
 function matchesSurface(placementSurfaces, requestedSurface) {
   if (requestedSurface === WEB_PLACEMENT_SURFACE_ANY) {
     return true;
@@ -108,6 +146,67 @@ function matchesSurface(placementSurfaces, requestedSurface) {
   return surfaces.includes(WEB_PLACEMENT_SURFACE_ANY) || surfaces.includes(requestedSurface);
 }
 
+function resolveTopologyPlacement(topologyEntries = [], placement = {}, requestedSurface = WEB_PLACEMENT_SURFACE_ANY) {
+  const semanticTarget = String(placement.target || "").trim();
+  const owner = String(placement.owner || "").trim();
+  const matches = topologyEntries.filter((entry) => {
+    if (entry.id !== semanticTarget) {
+      return false;
+    }
+    if (owner && entry.owner !== owner) {
+      return false;
+    }
+    if (!owner && entry.owner) {
+      return false;
+    }
+    return matchesSurface(entry.surfaces, requestedSurface);
+  });
+
+  if (matches.length === 1) {
+    return matches[0];
+  }
+  return null;
+}
+
+function resolveRenderablePlacement({
+  placement = {},
+  topologyEntries = [],
+  requestedSurface = WEB_PLACEMENT_SURFACE_ANY,
+  requestedTarget = "",
+  requestedLayoutClass = "compact"
+} = {}) {
+  if (placement.targetType === "concrete") {
+    if (placement.target !== requestedTarget) {
+      return null;
+    }
+    return placement;
+  }
+
+  const topologyPlacement = resolveTopologyPlacement(topologyEntries, placement, requestedSurface);
+  if (!topologyPlacement) {
+    return null;
+  }
+
+  const variant = topologyPlacement.variants?.[requestedLayoutClass] || null;
+  if (!variant || variant.outlet !== requestedTarget) {
+    return null;
+  }
+
+  const componentToken = String(placement.componentToken || variant.renderers?.[placement.kind] || "").trim();
+  if (!componentToken) {
+    return null;
+  }
+
+  return Object.freeze({
+    ...placement,
+    target: requestedTarget,
+    semanticTarget: placement.target,
+    topologyOwner: topologyPlacement.owner || "",
+    layoutClass: requestedLayoutClass,
+    componentToken
+  });
+}
+
 function resolveContextContributors(app, baseContext = {}, logger) {
   const contributors = app.resolveTag("web-placement.context.client");
   let merged = {};
@@ -232,6 +331,7 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
   const listeners = new Set();
   const subscribe = createListenerSubscription(listeners);
   let placementDefinitions = Object.freeze([]);
+  let placementTopology = Object.freeze([]);
   let sharedContext = Object.freeze({});
   let revision = 0;
 
@@ -276,6 +376,22 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
     });
   }
 
+  function replacePlacementTopology(topology = [], { source = "app placement topology" } = {}) {
+    missingTokens.clear();
+    invalidComponentTokens.clear();
+    failedTokens.clear();
+    placementTopology = normalizeTopologyList(topology, { source });
+    debugLog("replacePlacementTopology", {
+      source,
+      count: placementTopology.length,
+      ids: placementTopology.map((entry) => entry.owner ? `${entry.id}#${entry.owner}` : entry.id)
+    });
+    notify({
+      type: "placement-topology.replaced",
+      source
+    });
+  }
+
   function getContext() {
     return sharedContext;
   }
@@ -308,13 +424,17 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
     return revision;
   }
 
-  function getPlacements({ surface = WEB_PLACEMENT_SURFACE_ANY, target = "", context = {} } = {}) {
+  function getPlacements({ surface = WEB_PLACEMENT_SURFACE_ANY, target = "", layoutClass = "", context = {} } = {}) {
     const normalizedTarget = normalizePlacementTarget(target, { strict: false });
     if (!normalizedTarget) {
       return Object.freeze([]);
     }
 
     const normalizedSurface = normalizeSurface(surface);
+    const normalizedLayoutClass =
+      normalizePlacementLayoutClass(layoutClass) ||
+      normalizePlacementLayoutClass(sharedContext?.layoutClass) ||
+      "compact";
     const baseContext = isRecord(context) ? { ...context } : {};
     const contextFromRuntime = isRecord(sharedContext) ? sharedContext : {};
     const contextFromContributors = resolveContextContributors(
@@ -323,6 +443,7 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
         app,
         surface: normalizedSurface,
         target: normalizedTarget,
+        layoutClass: normalizedLayoutClass,
         context: {
           ...contextFromRuntime,
           ...baseContext
@@ -336,44 +457,54 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
       ...baseContext,
       app,
       surface: normalizedSurface,
-      target: normalizedTarget
+      target: normalizedTarget,
+      layoutClass: normalizedLayoutClass
     };
 
     debugLog("getPlacements:start", {
       surface: normalizedSurface,
       target: normalizedTarget,
+      layoutClass: normalizedLayoutClass,
       contextKeys: Object.keys(baseContext),
       sharedContextKeys: Object.keys(contextFromRuntime),
-      placementCount: placementDefinitions.length
+      placementCount: placementDefinitions.length,
+      topologyCount: placementTopology.length
     });
 
     const matches = [];
     for (const placement of placementDefinitions) {
-      if (placement.target !== normalizedTarget) {
+      const renderablePlacement = resolveRenderablePlacement({
+        placement,
+        topologyEntries: placementTopology,
+        requestedSurface: normalizedSurface,
+        requestedTarget: normalizedTarget,
+        requestedLayoutClass: normalizedLayoutClass
+      });
+      if (!renderablePlacement) {
         continue;
       }
-      const placementSurfaces = Array.isArray(placement.surfaces)
-        ? placement.surfaces
+      const placementSurfaces = Array.isArray(renderablePlacement.surfaces)
+        ? renderablePlacement.surfaces
         : [WEB_PLACEMENT_SURFACE_ANY];
 
       if (!matchesSurface(placementSurfaces, normalizedSurface)) {
         debugLog("getPlacements:skip-surfaces", {
-          placementId: placement.id,
+          placementId: renderablePlacement.id,
           placementSurfaces,
           requestedSurface: normalizedSurface
         });
         continue;
       }
-      if (!shouldIncludePlacement(placement, placementContext, runtimeLogger)) {
+      if (!shouldIncludePlacement(renderablePlacement, placementContext, runtimeLogger)) {
         debugLog("getPlacements:skip-when", {
-          placementId: placement.id
+          placementId: renderablePlacement.id
         });
         continue;
       }
 
       const component = resolvePlacementComponent(
         app,
-        placement,
+        renderablePlacement,
         runtimeLogger,
         missingTokens,
         invalidComponentTokens,
@@ -381,22 +512,22 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
       );
       if (!component) {
         debugLog("getPlacements:skip-component", {
-          placementId: placement.id,
-          componentToken: placement.componentToken
+          placementId: renderablePlacement.id,
+          componentToken: renderablePlacement.componentToken
         });
         continue;
       }
 
       debugLog("getPlacements:include", {
-        placementId: placement.id,
-        componentToken: placement.componentToken,
+        placementId: renderablePlacement.id,
+        componentToken: renderablePlacement.componentToken,
         placementSurfaces,
-        order: placement.order
+        order: renderablePlacement.order
       });
 
       matches.push(
         Object.freeze({
-          ...placement,
+          ...renderablePlacement,
           component
         })
       );
@@ -405,6 +536,7 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
     debugLog("getPlacements:done", {
       surface: normalizedSurface,
       target: normalizedTarget,
+      layoutClass: normalizedLayoutClass,
       resultIds: matches.map((entry) => entry.id)
     });
 
@@ -413,6 +545,7 @@ function createWebPlacementRuntime({ app, logger = null } = {}) {
 
   return Object.freeze({
     replacePlacements,
+    replacePlacementTopology,
     getPlacements,
     getContext,
     setContext,

package/src/client/placement/validators.js

@@ -1,5 +1,10 @@
 import { isRecord, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
-import { normalizeShellOutletTargetId } from "@jskit-ai/kernel/shared/support/shellLayoutTargets";
+import {
+  normalizePlacementKind,
+  normalizePlacementTopologyDefinition,
+  normalizeSemanticPlacementId,
+  resolvePlacementTargetReference
+} from "@jskit-ai/kernel/shared/support/shellLayoutTargets";
 
 const WEB_PLACEMENT_SURFACE_ANY = "*";
 
@@ -57,13 +62,13 @@ function toInteger(value, fallback = 1000) {
 }
 
 function normalizePlacementTarget(value, { strict = false, source = "placement" } = {}) {
-  const normalized = normalizeShellOutletTargetId(String(value || "").toLowerCase());
-  if (normalized) {
-    return normalized;
+  const reference = resolvePlacementTargetReference(String(value || "").toLowerCase());
+  if (reference?.id) {
+    return reference.id;
   }
 
   if (strict) {
-    throw new TypeError(`${source} requires target in "host:position" format.`);
+    throw new TypeError(`${source} requires semantic target in "area.slot" format or internal concrete target in "host:position" format.`);
   }
   return "";
 }
@@ -132,8 +137,19 @@ function normalizePlacementDefinition(value, { strict = false, source = "placeme
     return null;
   }
 
+  const targetReference = resolvePlacementTargetReference(target);
+  const internal = value.internal === true;
+  if (targetReference?.type === "concrete" && internal !== true) {
+    if (strict) {
+      throw new TypeError(`${source} "${id}" targets concrete outlet "${target}" without internal: true.`);
+    }
+    return null;
+  }
+
+  const owner = normalizeText(value.owner).toLowerCase();
+  const kind = normalizePlacementKind(value.kind) || (normalizeText(value.componentToken) ? "component" : "link");
   const componentToken = normalizeText(value.componentToken);
-  if (!componentToken) {
+  if (kind === "component" && !componentToken) {
     if (strict) {
       throw new TypeError(`${source} "${id}" requires componentToken.`);
     }
@@ -150,12 +166,16 @@ function normalizePlacementDefinition(value, { strict = false, source = "placeme
   return Object.freeze({
     id,
     target,
+    targetType: targetReference?.type || "",
+    owner,
+    kind,
     surfaces,
     order: toInteger(value.order, 1000),
     componentToken,
     props,
     when,
-    enabled: value.enabled !== false
+    enabled: value.enabled !== false,
+    internal
   });
 }
 
@@ -166,6 +186,12 @@ function definePlacement(value = {}) {
   });
 }
 
+function definePlacementTopology(value = {}) {
+  return normalizePlacementTopologyDefinition(value, {
+    context: "placement topology"
+  });
+}
+
 export {
   isRecord,
   isRenderableComponent,
@@ -174,5 +200,7 @@ export {
   normalizePlacementTarget,
   normalizePlacementSurfaces,
   normalizePlacementDefinition,
-  definePlacement
+  definePlacement,
+  definePlacementTopology,
+  normalizeSemanticPlacementId
 };

package/src/client/providers/ShellWebClientProvider.js

@@ -30,6 +30,7 @@ import { resolveBootstrapErrorStatusCode } from "../bootstrap/bootstrapErrorStat
 
 // 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";
+const APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER = "/src/placementTopology.js";
 const APP_ERROR_MODULE_SPECIFIER = "/src/error.js";
 
 function createShellWebQueryClient() {
@@ -88,6 +89,42 @@ async function loadAppPlacementDefinitions(logger) {
   return [];
 }
 
+async function loadAppPlacementTopology(logger) {
+  try {
+    const moduleNamespace = await import("/src/placementTopology.js");
+    const exported = moduleNamespace?.default;
+    const resolved = typeof exported === "function" ? exported() : exported;
+    if (Array.isArray(resolved)) {
+      return resolved;
+    }
+    if (resolved && typeof resolved === "object") {
+      return [resolved];
+    }
+
+    logger.warn(
+      {
+        module: APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER,
+        exportedType: typeof exported
+      },
+      "App placement topology module default export did not resolve to an object or array; using empty topology."
+    );
+  } catch (error) {
+    if (isMissingDynamicModule(error, APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER)) {
+      return [];
+    }
+
+    logger.warn(
+      {
+        module: APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER,
+        error: String(error?.message || error || "unknown error")
+      },
+      "Failed to load app placement topology module; using empty topology."
+    );
+  }
+
+  return [];
+}
+
 function createErrorConfigToolkit(errorRuntime) {
   return Object.freeze({
     createDefaultErrorPolicy,
@@ -297,6 +334,10 @@ class ShellWebClientProvider {
     const logger = createSharedProviderLogger(isRecord(app) ? app : null);
     const placementRuntime = app.make("runtime.web-placement.client");
     if (placementRuntime && typeof placementRuntime.replacePlacements === "function") {
+      const placementTopology = await loadAppPlacementTopology(logger);
+      if (typeof placementRuntime.replacePlacementTopology === "function") {
+        placementRuntime.replacePlacementTopology(placementTopology, { source: APP_PLACEMENT_TOPOLOGY_MODULE_SPECIFIER });
+      }
       const placements = await loadAppPlacementDefinitions(logger);
       placementRuntime.replacePlacements(placements, { source: APP_PLACEMENT_MODULE_SPECIFIER });
       const appConfig = getClientAppConfig();

package/templates/src/components/ShellLayout.vue

@@ -52,13 +52,9 @@ const { drawerOpen, toggleDrawer, resolvedSurface, resolvedSurfaceLabel } = useS
           <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
-            target="shell-layout:secondary-menu"
-            default-link-component-token="local.main.ui.surface-aware-menu-link-item"
-          />
+          <ShellOutlet target="shell-layout:secondary-menu" />
         </v-list>
       </slot>
     </v-navigation-drawer>

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

@@ -15,10 +15,7 @@ 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
-                target="home-settings:primary-menu"
-                default-link-component-token="local.main.ui.surface-aware-menu-link-item"
-              />
+              <ShellOutlet target="home-settings:primary-menu" />
             </v-list>
           </v-col>
 

package/templates/src/placement.js

@@ -13,10 +13,10 @@ export default function getPlacements() {
 
 addPlacement({
   id: "shell-web.home.menu.home",
-  target: "shell-layout:primary-menu",
+  target: "shell.primary-nav",
+  kind: "link",
   surfaces: ["home"],
   order: 50,
-  componentToken: "local.main.ui.surface-aware-menu-link-item",
   props: {
     label: "Home",
     surface: "home",
@@ -28,10 +28,10 @@ addPlacement({
 
 addPlacement({
   id: "shell-web.home.menu.settings",
-  target: "shell-layout:primary-menu",
+  target: "shell.primary-nav",
+  kind: "link",
   surfaces: ["home"],
   order: 100,
-  componentToken: "local.main.ui.surface-aware-menu-link-item",
   props: {
     label: "Settings",
     surface: "home",
@@ -42,10 +42,11 @@ addPlacement({
 
 addPlacement({
   id: "shell-web.home.settings.general",
-  target: "home-settings:primary-menu",
+  target: "page.section-nav",
+  owner: "home-settings",
+  kind: "link",
   surfaces: ["home"],
   order: 100,
-  componentToken: "local.main.ui.surface-aware-menu-link-item",
   props: {
     label: "General",
     surface: "home",

package/templates/src/placementTopology.js

@@ -0,0 +1,108 @@
+const placements = [];
+
+function addPlacementTopology(value = {}) {
+  placements.push(value);
+}
+
+export { addPlacementTopology };
+export default { placements };
+
+const menuLinkRenderers = Object.freeze({
+  link: "local.main.ui.surface-aware-menu-link-item"
+});
+
+addPlacementTopology({
+  id: "shell.primary-nav",
+  description: "Primary top-level navigation for the current surface.",
+  surfaces: ["*"],
+  default: true,
+  variants: {
+    compact: {
+      outlet: "shell-layout:primary-menu",
+      renderers: menuLinkRenderers
+    },
+    medium: {
+      outlet: "shell-layout:primary-menu",
+      renderers: menuLinkRenderers
+    },
+    expanded: {
+      outlet: "shell-layout:primary-menu",
+      renderers: menuLinkRenderers
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "shell.secondary-nav",
+  description: "Secondary navigation for the current surface.",
+  surfaces: ["*"],
+  variants: {
+    compact: {
+      outlet: "shell-layout:secondary-menu",
+      renderers: menuLinkRenderers
+    },
+    medium: {
+      outlet: "shell-layout:secondary-menu",
+      renderers: menuLinkRenderers
+    },
+    expanded: {
+      outlet: "shell-layout:secondary-menu",
+      renderers: menuLinkRenderers
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "shell.identity",
+  description: "Current surface identity and switcher controls.",
+  surfaces: ["*"],
+  variants: {
+    compact: {
+      outlet: "shell-layout:top-left"
+    },
+    medium: {
+      outlet: "shell-layout:top-left"
+    },
+    expanded: {
+      outlet: "shell-layout:top-left"
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "shell.status",
+  description: "Surface status, connection, and utility indicators.",
+  surfaces: ["*"],
+  variants: {
+    compact: {
+      outlet: "shell-layout:top-right"
+    },
+    medium: {
+      outlet: "shell-layout:top-right"
+    },
+    expanded: {
+      outlet: "shell-layout:top-right"
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "page.section-nav",
+  owner: "home-settings",
+  description: "Navigation between child pages in the home settings section.",
+  surfaces: ["home"],
+  variants: {
+    compact: {
+      outlet: "home-settings:primary-menu",
+      renderers: menuLinkRenderers
+    },
+    medium: {
+      outlet: "home-settings:primary-menu",
+      renderers: menuLinkRenderers
+    },
+    expanded: {
+      outlet: "home-settings:primary-menu",
+      renderers: menuLinkRenderers
+    }
+  }
+});

package/test/outletMenuWidgetContract.test.js

@@ -14,9 +14,9 @@ test("shell-web outlet menu widget exposes a configurable nested outlet", async
   );
 
   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.doesNotMatch(source, /defaultLinkComponentToken/);
+  assert.doesNotMatch(source, /default-link-component-token/);
   assert.match(source, /default: mdiCogOutline/);
   assert.doesNotMatch(source, /mdi-[a-z0-9-]+/);
 });

package/test/placementRegistry.test.js

@@ -7,13 +7,13 @@ test("placement registry stores unique entries and builds immutable array", () =
 
   const firstAdded = registry.addPlacement({
     id: "example.profile",
-    target: "shell-layout:top-right",
+    target: "shell.status",
     surfaces: ["*"],
     componentToken: "example.profile.component"
   });
   const duplicateAdded = registry.addPlacement({
     id: "example.profile",
-    target: "shell-layout:top-right",
+    target: "shell.status",
     surfaces: ["*"],
     componentToken: "example.profile.component.duplicate"
   });
@@ -33,7 +33,7 @@ test("placement registry accepts explicit non-global surface ids", () => {
 
   const added = registry.addPlacement({
     id: "example.admin",
-    target: "shell-layout:top-right",
+    target: "shell.status",
     surfaces: ["admin"],
     componentToken: "example.admin.component"
   });

package/test/placementRuntime.test.js

@@ -32,6 +32,82 @@ function createPlacementContext() {
   };
 }
 
+function semanticTopologyEntry({
+  id = "shell.primary-nav",
+  owner = "",
+  surfaces = ["*"],
+  compact = "shell-layout:primary-menu",
+  medium = "shell-layout:primary-menu",
+  expanded = "shell-layout:primary-menu",
+  compactRenderer = "component.menu",
+  mediumRenderer = "component.menu",
+  expandedRenderer = "component.menu"
+} = {}) {
+  const createVariant = (outlet, renderer) => ({
+    outlet,
+    renderers: renderer ? { link: renderer } : {}
+  });
+  return {
+    id,
+    owner,
+    surfaces,
+    variants: {
+      compact: createVariant(compact, compactRenderer),
+      medium: createVariant(medium, mediumRenderer),
+      expanded: createVariant(expanded, expandedRenderer)
+    }
+  };
+}
+
+test("web placement runtime resolves semantic targets through topology variants", () => {
+  const app = createAppStub({
+    tokens: {
+      "component.bottom": () => null,
+      "component.menu": () => null
+    }
+  });
+
+  const runtime = createWebPlacementRuntime({ app });
+  runtime.replacePlacementTopology([
+    semanticTopologyEntry({
+      id: "shell.primary-nav",
+      compact: "shell-layout:bottom-nav",
+      medium: "shell-layout:primary-menu",
+      expanded: "shell-layout:primary-menu",
+      compactRenderer: "component.bottom",
+      mediumRenderer: "component.menu",
+      expandedRenderer: "component.menu"
+    })
+  ]);
+  runtime.replacePlacements([
+    definePlacement({
+      id: "test.home",
+      target: "shell.primary-nav",
+      kind: "link",
+      surfaces: ["app"],
+      order: 10
+    })
+  ]);
+  runtime.setContext(createPlacementContext());
+
+  const compactEntries = runtime.getPlacements({
+    surface: "app",
+    target: "shell-layout:bottom-nav",
+    layoutClass: "compact"
+  });
+  assert.deepEqual(compactEntries.map((entry) => entry.id), ["test.home"]);
+  assert.equal(compactEntries[0].semanticTarget, "shell.primary-nav");
+  assert.equal(compactEntries[0].componentToken, "component.bottom");
+
+  const mediumEntries = runtime.getPlacements({
+    surface: "app",
+    target: "shell-layout:primary-menu",
+    layoutClass: "medium"
+  });
+  assert.deepEqual(mediumEntries.map((entry) => entry.id), ["test.home"]);
+  assert.equal(mediumEntries[0].componentToken, "component.menu");
+});
+
 test("web placement runtime filters by surface/host/position, resolves component tokens, and sorts by order", () => {
   const app = createAppStub({
     tokens: {
@@ -48,21 +124,24 @@ test("web placement runtime filters by surface/host/position, resolves component
       target: "shell-layout:primary-menu",
       surfaces: ["app"],
       order: 30,
-      componentToken: "component.menu"
+      componentToken: "component.menu",
+      internal: true
     }),
     definePlacement({
       id: "test.profile",
       target: "shell-layout:top-right",
       surfaces: ["*"],
       order: 20,
-      componentToken: "component.profile"
+      componentToken: "component.profile",
+      internal: true
     }),
     definePlacement({
       id: "test.alerts",
       target: "shell-layout:top-right",
       surfaces: ["app"],
       order: 10,
-      componentToken: "component.alerts"
+      componentToken: "component.alerts",
+      internal: true
     })
   ]);
   runtime.setContext(createPlacementContext());
@@ -93,14 +172,16 @@ test("web placement runtime preserves source order when placements share the sam
       target: "home-settings:primary-menu",
       surfaces: ["app"],
       order: 155,
-      componentToken: "component.beta"
+      componentToken: "component.beta",
+      internal: true
     }),
     definePlacement({
       id: "test.alpha",
       target: "home-settings:primary-menu",
       surfaces: ["app"],
       order: 155,
-      componentToken: "component.alpha"
+      componentToken: "component.alpha",
+      internal: true
     })
   ]);
   runtime.setContext(createPlacementContext());
@@ -129,6 +210,7 @@ test("web placement runtime applies context contributors and placement when() pr
       target: "auth-profile-menu:primary-menu",
       surfaces: ["*"],
       componentToken: "component.guest",
+      internal: true,
       when: ({ auth }) => !Boolean(auth?.authenticated)
     }),
     definePlacement({
@@ -136,6 +218,7 @@ test("web placement runtime applies context contributors and placement when() pr
       target: "auth-profile-menu:primary-menu",
       surfaces: ["*"],
       componentToken: "component.authenticated",
+      internal: true,
       when: ({ auth }) => Boolean(auth?.authenticated)
     })
   ]);
@@ -165,6 +248,7 @@ test("web placement runtime uses runtime context and local context overrides con
       target: "auth-profile-menu:primary-menu",
       surfaces: ["*"],
       componentToken: "component.allowed",
+      internal: true,
       when: ({ auth }) => Boolean(auth?.authenticated)
     })
   ]);
@@ -224,13 +308,15 @@ test("web placement runtime rejects duplicate placement ids", () => {
         id: "dup.entry",
         target: "shell-layout:top-right",
         surfaces: ["*"],
-        componentToken: "component.a"
+        componentToken: "component.a",
+        internal: true
       }),
       definePlacement({
         id: "dup.entry",
         target: "shell-layout:primary-menu",
         surfaces: ["*"],
-        componentToken: "component.b"
+        componentToken: "component.b",
+        internal: true
       })
     ]);
   }, /Duplicate placement id/);
@@ -271,13 +357,15 @@ test("web placement runtime skips throwing component tokens and logs resolution
       id: "bad",
       target: "shell-layout:top-right",
       surfaces: ["*"],
-      componentToken: "component.bad"
+      componentToken: "component.bad",
+      internal: true
     }),
     definePlacement({
       id: "good",
       target: "shell-layout:top-right",
       surfaces: ["*"],
-      componentToken: "component.good"
+      componentToken: "component.good",
+      internal: true
     })
   ]);
 
@@ -323,7 +411,8 @@ test("web placement runtime clears failed token cache when placements are replac
       id: "toggle",
       target: "shell-layout:top-right",
       surfaces: ["*"],
-      componentToken: "component.toggle"
+      componentToken: "component.toggle",
+      internal: true
     })
   ]);
 
@@ -339,7 +428,8 @@ test("web placement runtime clears failed token cache when placements are replac
       id: "toggle",
       target: "shell-layout:top-right",
       surfaces: ["*"],
-      componentToken: "component.toggle"
+      componentToken: "component.toggle",
+      internal: true
     })
   ]);
 
@@ -362,21 +452,24 @@ test("web placement runtime follows explicit surface targeting without role indi
       target: "shell-layout:top-right",
       surfaces: ["*"],
       order: 10,
-      componentToken: "component.global"
+      componentToken: "component.global",
+      internal: true
     }),
     definePlacement({
       id: "app.link",
       target: "shell-layout:top-right",
       surfaces: ["app"],
       order: 20,
-      componentToken: "component.app"
+      componentToken: "component.app",
+      internal: true
     }),
     definePlacement({
       id: "admin.link",
       target: "shell-layout:top-right",
       surfaces: ["admin"],
       order: 30,
-      componentToken: "component.admin"
+      componentToken: "component.admin",
+      internal: true
     })
   ]);
   runtime.setContext(createPlacementContext());

package/test/settingsPlacementContract.test.js

@@ -24,6 +24,18 @@ function readContributions(target = "") {
     : [];
 }
 
+function readTopology(id = "", owner = "") {
+  const placements = descriptor?.metadata?.ui?.placements?.topology?.placements;
+  const normalizedId = String(id || "").trim();
+  const normalizedOwner = String(owner || "").trim();
+  return Array.isArray(placements)
+    ? placements.filter((entry) =>
+        String(entry?.id || "").trim() === normalizedId &&
+        String(entry?.owner || "").trim() === normalizedOwner
+      )
+    : [];
+}
+
 function findFileMutation(id) {
   const files = descriptor?.mutations?.files;
   return Array.isArray(files)
@@ -35,7 +47,7 @@ test("shell-web home settings template exposes surface-derived settings outlets"
   const source = await readFile(path.join(PACKAGE_DIR, "templates", "src", "pages", "home", "settings.vue"), "utf8");
 
   assert.match(source, /target="home-settings:primary-menu"/);
-  assert.match(source, /default-link-component-token="local\.main\.ui\.surface-aware-menu-link-item"/);
+  assert.doesNotMatch(source, /default-link-component-token/);
   assert.match(source, /<RouterView \/>/);
 });
 
@@ -64,7 +76,8 @@ test("shell-web placement template seeds default Home and Settings drawer naviga
   const source = await readFile(path.join(PACKAGE_DIR, "templates", "src", "placement.js"), "utf8");
 
   assert.match(source, /id: "shell-web\.home\.menu\.home"/);
-  assert.match(source, /target: "shell-layout:primary-menu"/);
+  assert.match(source, /target: "shell\.primary-nav"/);
+  assert.match(source, /kind: "link"/);
   assert.match(source, /surfaces: \["home"\]/);
   assert.match(source, /label: "Home"/);
   assert.match(source, /unscopedSuffix: "\/"/);
@@ -72,7 +85,8 @@ test("shell-web placement template seeds default Home and Settings drawer naviga
   assert.match(source, /label: "Settings"/);
   assert.match(source, /unscopedSuffix: "\/settings"/);
   assert.match(source, /id: "shell-web\.home\.settings\.general"/);
-  assert.match(source, /target: "home-settings:primary-menu"/);
+  assert.match(source, /target: "page\.section-nav"/);
+  assert.match(source, /owner: "home-settings"/);
   assert.match(source, /label: "General"/);
   assert.match(source, /unscopedSuffix: "\/settings\/general"/);
   assert.doesNotMatch(source, /to: "\.\/general"/);
@@ -84,7 +98,6 @@ test("shell-web descriptor metadata advertises home settings outlets, default dr
     [
       {
         target: "home-settings:primary-menu",
-        defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
         surfaces: ["home"],
         source: "templates/src/pages/home/settings.vue"
       }
@@ -92,41 +105,45 @@ test("shell-web descriptor metadata advertises home settings outlets, default dr
   );
 
   assert.deepEqual(
-    readContributions("shell-layout:primary-menu"),
+    readContributions("shell.primary-nav"),
     [
       {
         id: "shell-web.home.menu.home",
-        target: "shell-layout:primary-menu",
+        target: "shell.primary-nav",
+        kind: "link",
         surfaces: ["home"],
         order: 50,
-        componentToken: "local.main.ui.surface-aware-menu-link-item",
         source: "templates/src/placement.js"
       },
       {
         id: "shell-web.home.menu.settings",
-        target: "shell-layout:primary-menu",
+        target: "shell.primary-nav",
+        kind: "link",
         surfaces: ["home"],
         order: 100,
-        componentToken: "local.main.ui.surface-aware-menu-link-item",
         source: "templates/src/placement.js"
       }
     ]
   );
 
   assert.deepEqual(
-    readContributions("home-settings:primary-menu"),
+    readContributions("page.section-nav"),
     [
       {
         id: "shell-web.home.settings.general",
-        target: "home-settings:primary-menu",
+        target: "page.section-nav",
+        owner: "home-settings",
+        kind: "link",
         surfaces: ["home"],
         order: 100,
-        componentToken: "local.main.ui.surface-aware-menu-link-item",
         source: "templates/src/placement.js"
       }
     ]
   );
 
+  assert.equal(readTopology("shell.primary-nav").length, 1);
+  assert.equal(readTopology("page.section-nav", "home-settings").length, 1);
+
   assert.deepEqual(findFileMutation("shell-web-page-home-settings-shell"), {
     from: "templates/src/pages/home/settings.vue",
     toSurface: "home",