@jskit-ai/kernel 0.1.65 → 0.1.66

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.65",
+  "version": "0.1.66",
   "type": "module",
   "dependencies": {
     "json-rest-schema": "1.x.x"

package/server/support/index.js

@@ -16,6 +16,8 @@ export {
   resolvePageLinkTargetDetails
 } from "./pageTargets.js";
 export {
+  discoverPlacementTopologyFromApp,
   discoverShellOutletTargetsFromApp,
+  resolveSemanticPlacementTargetFromApp,
   resolveShellOutletPlacementTargetFromApp
 } from "./shellOutlets.js";

package/server/support/pageTargets.js

@@ -14,7 +14,10 @@ import {
   findShellOutletTargetById,
   normalizeShellOutletTargetId
 } from "../../shared/support/shellLayoutTargets.js";
-import { resolveShellOutletPlacementTargetFromApp } from "./shellOutlets.js";
+import {
+  discoverPlacementTopologyFromApp,
+  resolveSemanticPlacementTargetFromApp
+} from "./shellOutlets.js";
 import { resolveRequiredAppRoot, toPosixPath } from "./path.js";
 import { loadAppConfigFromModuleUrl } from "./appConfigFiles.js";
 
@@ -562,6 +565,48 @@ function normalizePlacementTargetId(target = {}) {
   return normalizeShellOutletTargetId(target?.id || target?.target || target);
 }
 
+function resolveConcreteTargetOwner(target = "") {
+  const normalizedTarget = normalizeShellOutletTargetId(target);
+  if (!normalizedTarget) {
+    return "";
+  }
+  return normalizedTarget.slice(0, normalizedTarget.indexOf(":"));
+}
+
+function topologyPlacementTargetsConcreteOutlet(placement = {}, target = "") {
+  const normalizedTarget = normalizeShellOutletTargetId(target);
+  if (!normalizedTarget) {
+    return false;
+  }
+  const variants = placement?.variants && typeof placement.variants === "object" ? placement.variants : {};
+  return Object.values(variants).some((variant) => normalizeShellOutletTargetId(variant?.outlet) === normalizedTarget);
+}
+
+async function resolveSemanticPlacementTargetForConcreteOutlet({
+  appRoot,
+  concreteTarget = "",
+  surface = ""
+} = {}) {
+  const normalizedConcreteTarget = normalizeShellOutletTargetId(concreteTarget);
+  if (!normalizedConcreteTarget) {
+    return null;
+  }
+
+  const topology = await discoverPlacementTopologyFromApp({ appRoot });
+  const owner = resolveConcreteTargetOwner(normalizedConcreteTarget);
+  const normalizedSurface = normalizeSurfaceId(surface);
+  return (Array.isArray(topology.placements) ? topology.placements : []).find((placement) => {
+    if (!topologyPlacementTargetsConcreteOutlet(placement, normalizedConcreteTarget)) {
+      return false;
+    }
+    if (placement.owner && placement.owner !== owner) {
+      return false;
+    }
+    const surfaces = Array.isArray(placement.surfaces) ? placement.surfaces : ["*"];
+    return !normalizedSurface || surfaces.includes("*") || surfaces.includes(normalizedSurface);
+  }) || null;
+}
+
 function resolveRelativeLinkToFromParent(pageTarget = {}, parentHost = null) {
   const childSegments = Array.isArray(pageTarget?.visibleRouteSegments) ? pageTarget.visibleRouteSegments : [];
   const parentSegments = Array.isArray(parentHost?.visibleRouteSegments) ? parentHost.visibleRouteSegments : [];
@@ -598,7 +643,7 @@ function resolveInferredPageLinkTo({
   explicitLinkTo = "",
   pageTarget = {},
   parentHost = null,
-  placementTarget = null,
+  preservesRelativeSubpageLinks = false,
   suppressImplicitRelativeLinks = false
 } = {}) {
   const normalizedExplicitLinkTo = normalizeText(explicitLinkTo);
@@ -609,14 +654,10 @@ function resolveInferredPageLinkTo({
     return "";
   }
 
-  const parentTargetId = normalizePlacementTargetId(parentHost);
-  const placementTargetId = normalizePlacementTargetId(placementTarget);
-  if (parentTargetId && parentTargetId === placementTargetId) {
-    if (parentHost?.isSectionSubpagesHost === true) {
-      const inferredLinkTo = resolveRelativeLinkToFromParent(pageTarget, parentHost);
-      if (inferredLinkTo) {
-        return inferredLinkTo;
-      }
+  if (preservesRelativeSubpageLinks === true && parentHost?.isSectionSubpagesHost === true) {
+    const inferredLinkTo = resolveRelativeLinkToFromParent(pageTarget, parentHost);
+    if (inferredLinkTo) {
+      return inferredLinkTo;
     }
   }
 
@@ -627,36 +668,6 @@ function resolveInferredPageLinkTo({
   return "";
 }
 
-function resolveInferredPageLinkComponentToken({
-  explicitComponentToken = "",
-  parentHost = null,
-  placementTarget = null,
-  defaultComponentToken = DEFAULT_PAGE_LINK_COMPONENT_TOKEN,
-  subpageComponentToken = DEFAULT_SUBPAGE_LINK_COMPONENT_TOKEN
-} = {}) {
-  const normalizedExplicitToken = normalizeText(explicitComponentToken);
-  if (normalizedExplicitToken) {
-    return normalizedExplicitToken;
-  }
-
-  const normalizedPlacementTargetDefaultToken = normalizeText(placementTarget?.defaultLinkComponentToken);
-  if (normalizedPlacementTargetDefaultToken) {
-    return normalizedPlacementTargetDefaultToken;
-  }
-
-  const parentTargetId = normalizePlacementTargetId(parentHost);
-  const placementTargetId = normalizePlacementTargetId(placementTarget);
-  if (
-    parentHost?.isSectionSubpagesHost === true &&
-    parentTargetId &&
-    parentTargetId === placementTargetId
-  ) {
-    return normalizeText(subpageComponentToken) || DEFAULT_SUBPAGE_LINK_COMPONENT_TOKEN;
-  }
-
-  return normalizeText(defaultComponentToken) || DEFAULT_PAGE_LINK_COMPONENT_TOKEN;
-}
-
 function renderPageLinkWhenLine(pageTarget = {}) {
   if (pageTarget?.surfaceRequiresAuth !== true) {
     return "";
@@ -672,8 +683,6 @@ async function resolvePageLinkTargetDetails({
   placement = "",
   componentToken = "",
   linkTo = "",
-  defaultComponentToken = DEFAULT_PAGE_LINK_COMPONENT_TOKEN,
-  subpageComponentToken = DEFAULT_SUBPAGE_LINK_COMPONENT_TOKEN,
   context = "page target"
 } = {}) {
   const resolvedPageTarget = pageTarget || await resolvePageTargetDetails({
@@ -686,39 +695,49 @@ async function resolvePageLinkTargetDetails({
     pageTarget: resolvedPageTarget,
     context
   });
-  const placementTarget = await resolveShellOutletPlacementTargetFromApp({
-    appRoot: resolvedPageTarget.appRoot,
-    context,
-    placement: normalizeText(placement) || parentHost?.id || ""
-  });
-  const resolvedComponentToken = resolveInferredPageLinkComponentToken({
-    explicitComponentToken: componentToken,
-    parentHost,
-    placementTarget,
-    defaultComponentToken,
-    subpageComponentToken
-  });
   const parentTargetId = normalizePlacementTargetId(parentHost);
-  const placementTargetId = normalizePlacementTargetId(placementTarget);
+  let placementTarget = null;
+  const explicitPlacement = normalizeText(placement);
+  if (explicitPlacement) {
+    placementTarget = await resolveSemanticPlacementTargetFromApp({
+      appRoot: resolvedPageTarget.appRoot,
+      context,
+      placement: explicitPlacement,
+      owner: parentTargetId ? resolveConcreteTargetOwner(parentTargetId) : "",
+      surface: resolvedPageTarget.surfaceId
+    });
+  } else if (parentTargetId) {
+    placementTarget = await resolveSemanticPlacementTargetForConcreteOutlet({
+      appRoot: resolvedPageTarget.appRoot,
+      concreteTarget: parentTargetId,
+      surface: resolvedPageTarget.surfaceId,
+      context
+    });
+  }
+  if (!placementTarget) {
+    placementTarget = await resolveSemanticPlacementTargetFromApp({
+      appRoot: resolvedPageTarget.appRoot,
+      context,
+      surface: resolvedPageTarget.surfaceId
+    });
+  }
   const preservesRelativeSubpageLinks =
     parentHost?.isSectionSubpagesHost === true &&
     Boolean(parentTargetId) &&
-    parentTargetId === placementTargetId;
+    topologyPlacementTargetsConcreteOutlet(placementTarget, parentTargetId);
 
   return Object.freeze({
     pageTarget: resolvedPageTarget,
     parentHost,
     placementTarget,
-    componentToken: resolvedComponentToken,
+    componentToken: normalizeText(componentToken),
     whenLine: renderPageLinkWhenLine(resolvedPageTarget),
     linkTo: resolveInferredPageLinkTo({
       explicitLinkTo: linkTo,
       pageTarget: resolvedPageTarget,
       parentHost,
-      placementTarget,
-      suppressImplicitRelativeLinks:
-        resolvedComponentToken === (normalizeText(defaultComponentToken) || DEFAULT_PAGE_LINK_COMPONENT_TOKEN) &&
-        preservesRelativeSubpageLinks !== true
+      preservesRelativeSubpageLinks,
+      suppressImplicitRelativeLinks: preservesRelativeSubpageLinks !== true
     })
   });
 }

package/server/support/pageTargets.test.js

@@ -40,10 +40,71 @@ async function writeShellLayout(appRoot, source = "") {
     <ShellOutlet
       target="shell-layout:primary-menu"
       default
-      default-link-component-token="local.main.ui.surface-aware-menu-link-item"
     />
   </div>
 </template>
+`
+  );
+  await writePlacementTopology(appRoot);
+}
+
+function renderTopologyVariant(outlet, { linkRenderer = "" } = {}) {
+  const rendererLines = linkRenderer
+    ? `,
+      renderers: {
+        link: "${linkRenderer}"
+      }`
+    : "";
+  return `{
+      outlet: "${outlet}"${rendererLines}
+    }`;
+}
+
+function renderTopologyEntry({
+  id = "",
+  owner = "",
+  surfaces = ["*"],
+  defaultPlacement = false,
+  outlet = "",
+  linkRenderer = ""
+} = {}) {
+  const ownerLine = owner ? `    owner: "${owner}",\n` : "";
+  const defaultLine = defaultPlacement ? "    default: true,\n" : "";
+  return `  {
+    id: "${id}",
+${ownerLine}    surfaces: ${JSON.stringify(surfaces)},
+${defaultLine}    variants: {
+      compact: ${renderTopologyVariant(outlet, { linkRenderer })},
+      medium: ${renderTopologyVariant(outlet, { linkRenderer })},
+      expanded: ${renderTopologyVariant(outlet, { linkRenderer })}
+    }
+  }`;
+}
+
+async function writePlacementTopology(appRoot, entries = []) {
+  const defaultEntries = [
+    renderTopologyEntry({
+      id: "shell.primary-nav",
+      surfaces: ["*"],
+      defaultPlacement: true,
+      outlet: "shell-layout:primary-menu",
+      linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+    }),
+    renderTopologyEntry({
+      id: "shell.status",
+      surfaces: ["*"],
+      outlet: "shell-layout:top-right",
+      linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+    })
+  ];
+  await writeFileInApp(
+    appRoot,
+    "src/placementTopology.js",
+    `export default {
+  placements: [
+${[...defaultEntries, ...entries].join(",\n")}
+  ]
+};
 `
   );
 }
@@ -246,8 +307,8 @@ test("resolvePageLinkTargetDetails falls back to the app default placement targe
     });
 
     assert.equal(details.pageTarget.surfaceId, "admin");
-    assert.equal(details.placementTarget.id, "shell-layout:primary-menu");
-    assert.equal(details.componentToken, "local.main.ui.surface-aware-menu-link-item");
+    assert.equal(details.placementTarget.id, "shell.primary-nav");
+    assert.equal(details.componentToken, "");
     assert.equal(details.linkTo, "");
     assert.equal(details.whenLine, "");
   });
@@ -292,15 +353,21 @@ test("resolvePageLinkTargetDetails prefers an outlet-declared default link token
 };
 `
     );
+    await writePlacementTopology(appRoot, [
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "home-settings",
+        surfaces: ["home"],
+        outlet: "home-settings:primary-menu",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      })
+    ]);
     await writeFileInApp(
       appRoot,
       "src/pages/home/settings.vue",
       `<template>
   <section>
-    <ShellOutlet
-      target="home-settings:primary-menu"
-      default-link-component-token="local.main.ui.surface-aware-menu-link-item"
-    />
+    <ShellOutlet target="home-settings:primary-menu" />
     <RouterView />
   </section>
 </template>
@@ -314,8 +381,9 @@ test("resolvePageLinkTargetDetails prefers an outlet-declared default link token
     });
 
     assert.equal(details.parentHost?.id, "home-settings:primary-menu");
-    assert.equal(details.placementTarget.id, "home-settings:primary-menu");
-    assert.equal(details.componentToken, "local.main.ui.surface-aware-menu-link-item");
+    assert.equal(details.placementTarget.id, "page.section-nav");
+    assert.equal(details.placementTarget.owner, "home-settings");
+    assert.equal(details.componentToken, "");
     assert.equal(details.linkTo, "");
   });
 });
@@ -332,6 +400,15 @@ test("resolvePageLinkTargetDetails inherits a file-route parent subpages host",
 `
     );
     await writeShellLayout(appRoot);
+    await writePlacementTopology(appRoot, [
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "contact-view",
+        surfaces: ["admin"],
+        outlet: "contact-view:sub-pages",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      })
+    ]);
     await writeFileInApp(
       appRoot,
       "src/pages/admin/contacts/[contactId].vue",
@@ -353,8 +430,9 @@ test("resolvePageLinkTargetDetails inherits a file-route parent subpages host",
     });
 
     assert.equal(details.parentHost?.id, "contact-view:sub-pages");
-    assert.equal(details.placementTarget.id, "contact-view:sub-pages");
-    assert.equal(details.componentToken, "local.main.ui.surface-aware-menu-link-item");
+    assert.equal(details.placementTarget.id, "page.section-nav");
+    assert.equal(details.placementTarget.owner, "contact-view");
+    assert.equal(details.componentToken, "");
     assert.equal(details.linkTo, "./notes");
   });
 });
@@ -375,13 +453,13 @@ test("resolvePageLinkTargetDetails honors explicit placement and link overrides"
     const details = await resolvePageLinkTargetDetails({
       appRoot,
       targetFile: "admin/contacts/[contactId]/index/notes/index.vue",
-      placement: "shell-layout:top-right",
+      placement: "shell.status",
       componentToken: "custom.link-item",
       linkTo: "./assistant-notes",
       context: "page target"
     });
 
-    assert.equal(details.placementTarget.id, "shell-layout:top-right");
+    assert.equal(details.placementTarget.id, "shell.status");
     assert.equal(details.componentToken, "custom.link-item");
     assert.equal(details.linkTo, "./assistant-notes");
   });
@@ -399,6 +477,15 @@ test("resolvePageLinkTargetDetails inherits an index-route parent subpages host
 `
     );
     await writeShellLayout(appRoot);
+    await writePlacementTopology(appRoot, [
+      renderTopologyEntry({
+        id: "page.section-nav",
+        owner: "customer-view",
+        surfaces: ["admin"],
+        outlet: "customer-view:sub-pages",
+        linkRenderer: "local.main.ui.surface-aware-menu-link-item"
+      })
+    ]);
     await writeFileInApp(
       appRoot,
       "src/pages/admin/customers/[customerId]/index.vue",
@@ -421,8 +508,9 @@ test("resolvePageLinkTargetDetails inherits an index-route parent subpages host
 
     assert.equal(details.parentHost?.id, "customer-view:sub-pages");
     assert.equal(details.parentHost?.pageFile, "src/pages/admin/customers/[customerId]/index.vue");
-    assert.equal(details.placementTarget.id, "customer-view:sub-pages");
-    assert.equal(details.componentToken, "local.main.ui.surface-aware-menu-link-item");
+    assert.equal(details.placementTarget.id, "page.section-nav");
+    assert.equal(details.placementTarget.owner, "customer-view");
+    assert.equal(details.componentToken, "");
     assert.equal(details.linkTo, "./pets");
   });
 });

package/server/support/shellOutlets.js

@@ -8,13 +8,15 @@ import {
   describeShellOutletTargets,
   discoverShellOutletTargetsFromVueSource,
   findShellOutletTargetById,
+  normalizePlacementTopologyDefinition,
+  normalizeSemanticPlacementId,
   normalizeShellOutletTargetId,
   normalizeShellOutletTargetRecord
 } from "../../shared/support/shellLayoutTargets.js";
-import { loadAppConfigFromModuleUrl } from "./appConfigFiles.js";
 
 const VUE_DISCOVERY_IGNORED_ERROR_CODES = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM"]);
 const LOCK_FILE_RELATIVE_PATH = ".jskit/lock.json";
+const PLACEMENT_TOPOLOGY_RELATIVE_PATH = "src/placementTopology.js";
 const ROUTE_TAG_PATTERN = /<route\b([^>]*)>([\s\S]*?)<\/route>/g;
 const ATTRIBUTE_PATTERN = /([:@]?[A-Za-z_][A-Za-z0-9_-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'))?/g;
 
@@ -218,46 +220,6 @@ function normalizePackageOutletTarget({
   });
 }
 
-async function loadOutletDefaultOverrides(appRoot = "") {
-  const resolvedAppRoot = resolveRequiredAppRoot(appRoot, {
-    context: "discoverShellOutletTargetsFromApp"
-  });
-  let appConfig = {};
-  try {
-    appConfig = normalizeObject(
-      await loadAppConfigFromModuleUrl({
-        moduleUrl: pathToFileURL(path.join(resolvedAppRoot, "config", "public.js")).href
-      })
-    );
-  } catch {
-    return {};
-  }
-  return normalizeObject(normalizeObject(appConfig.ui).outletDefaults);
-}
-
-function applyOutletDefaultOverrides(target = {}, outletDefaultOverrides = {}) {
-  const targetRecord = normalizeObject(target);
-  const outletTargetId = normalizeShellOutletTargetId(targetRecord.id);
-  if (!outletTargetId) {
-    return targetRecord;
-  }
-
-  const overrideRecord = outletDefaultOverrides?.[outletTargetId];
-  const normalizedOverrideToken =
-    typeof overrideRecord === "string"
-      ? normalizeText(overrideRecord)
-      : normalizeText(normalizeObject(overrideRecord).linkComponentToken) ||
-        normalizeText(normalizeObject(overrideRecord)["link-component-token"]);
-  if (!normalizedOverrideToken) {
-    return targetRecord;
-  }
-
-  return Object.freeze({
-    ...targetRecord,
-    defaultLinkComponentToken: normalizedOverrideToken
-  });
-}
-
 async function collectInstalledPackageOutletTargets(appRoot) {
   const installedPackageStates = await readInstalledPackageStates(appRoot);
   const packageIds = Object.keys(installedPackageStates).sort((left, right) => left.localeCompare(right));
@@ -290,11 +252,180 @@ async function collectInstalledPackageOutletTargets(appRoot) {
   return targets;
 }
 
+function withTopologySource(placement = {}, sourcePath = "") {
+  return Object.freeze({
+    ...placement,
+    sourcePath
+  });
+}
+
+async function loadAppPlacementTopology(appRoot) {
+  const topologyPath = path.resolve(appRoot, PLACEMENT_TOPOLOGY_RELATIVE_PATH);
+  try {
+    await readFile(topologyPath, "utf8");
+  } catch (error) {
+    const errorCode = normalizeText(error?.code).toUpperCase();
+    if (errorCode === "ENOENT" || errorCode === "ENOTDIR") {
+      return [];
+    }
+    throw error;
+  }
+
+  let moduleNamespace = null;
+  try {
+    moduleNamespace = await import(pathToFileURL(topologyPath).href);
+  } catch (error) {
+    throw new Error(
+      `Could not load ${PLACEMENT_TOPOLOGY_RELATIVE_PATH}: ${String(error?.message || error || "unknown error")}`
+    );
+  }
+
+  const exported = moduleNamespace?.default;
+  const resolved = typeof exported === "function" ? exported() : exported;
+  const normalized = normalizePlacementTopologyDefinition(resolved, {
+    context: PLACEMENT_TOPOLOGY_RELATIVE_PATH
+  });
+  return normalized.placements.map((placement) => withTopologySource(placement, PLACEMENT_TOPOLOGY_RELATIVE_PATH));
+}
+
+async function collectInstalledPackagePlacementTopology(appRoot) {
+  const installedPackageStates = await readInstalledPackageStates(appRoot);
+  const packageIds = Object.keys(installedPackageStates).sort((left, right) => left.localeCompare(right));
+  const placements = [];
+
+  for (const packageId of packageIds) {
+    const installedPackageState = normalizeObject(installedPackageStates[packageId]);
+    const descriptorRecord = await loadInstalledPackageDescriptor({
+      appRoot,
+      packageId,
+      installedPackageState
+    });
+    const descriptor = normalizeObject(descriptorRecord.descriptor);
+    const metadata = normalizeObject(descriptor.metadata);
+    const ui = normalizeObject(metadata.ui);
+    const placementsMeta = normalizeObject(ui.placements);
+    const topology = placementsMeta.topology;
+    if (!topology) {
+      continue;
+    }
+
+    const normalized = normalizePlacementTopologyDefinition(topology, {
+      context: `package:${packageId}:metadata.ui.placements.topology`
+    });
+    for (const placement of normalized.placements) {
+      placements.push(
+        withTopologySource(
+          placement,
+          `package:${packageId}${descriptorRecord.descriptorPath ? `:${toPosixPath(descriptorRecord.descriptorPath)}` : ""}`
+        )
+      );
+    }
+  }
+
+  return placements;
+}
+
+async function discoverPlacementTopologyFromApp({ appRoot } = {}) {
+  const resolvedAppRoot = resolveRequiredAppRoot(appRoot, {
+    context: "discoverPlacementTopologyFromApp"
+  });
+  const appPlacements = await loadAppPlacementTopology(resolvedAppRoot);
+  const packagePlacements = await collectInstalledPackagePlacementTopology(resolvedAppRoot);
+  const placementByKey = new Map();
+
+  for (const placement of [...packagePlacements, ...appPlacements]) {
+    const key = `${placement.id}::${placement.owner || ""}`;
+    placementByKey.set(key, placement);
+  }
+
+  return Object.freeze({
+    placements: Object.freeze(
+      [...placementByKey.values()].sort((left, right) => {
+        const idCompare = left.id.localeCompare(right.id);
+        if (idCompare !== 0) {
+          return idCompare;
+        }
+        return String(left.owner || "").localeCompare(String(right.owner || ""));
+      })
+    )
+  });
+}
+
+function findSemanticPlacementById(placements = [], { id = "", owner = "", surface = "" } = {}) {
+  const normalizedId = normalizeSemanticPlacementId(id);
+  const normalizedOwner = normalizeText(owner).toLowerCase();
+  const normalizedSurface = normalizeText(surface).toLowerCase();
+  if (!normalizedId) {
+    return null;
+  }
+
+  return (Array.isArray(placements) ? placements : []).find((placement) => {
+    if (placement.id !== normalizedId) {
+      return false;
+    }
+    if (normalizedOwner && placement.owner !== normalizedOwner) {
+      return false;
+    }
+    if (!normalizedOwner && placement.owner) {
+      return false;
+    }
+    const surfaces = Array.isArray(placement.surfaces) ? placement.surfaces : ["*"];
+    return !normalizedSurface || surfaces.includes("*") || surfaces.includes(normalizedSurface);
+  }) || null;
+}
+
+async function resolveSemanticPlacementTargetFromApp({
+  appRoot,
+  placement = "",
+  owner = "",
+  surface = "",
+  context = "ui-generator"
+} = {}) {
+  const resolvedContext = normalizeText(context) || "ui-generator";
+  const topology = await discoverPlacementTopologyFromApp({ appRoot });
+  const placements = Array.isArray(topology.placements) ? topology.placements : [];
+  if (placements.length < 1) {
+    throw new Error(`${resolvedContext} could not find semantic placement topology in ${PLACEMENT_TOPOLOGY_RELATIVE_PATH}.`);
+  }
+
+  const requestedPlacement = normalizeText(placement);
+  if (requestedPlacement) {
+    const requestedId = normalizeSemanticPlacementId(requestedPlacement);
+    if (!requestedId) {
+      throw new Error(`${resolvedContext} option "placement" must be a semantic target in "area.slot" format.`);
+    }
+    const match = findSemanticPlacementById(placements, {
+      id: requestedId,
+      owner,
+      surface
+    }) || (owner
+      ? findSemanticPlacementById(placements, {
+          id: requestedId,
+          owner: "",
+          surface
+        })
+      : null);
+    if (!match) {
+      throw new Error(`${resolvedContext} semantic placement "${requestedId}" is not declared in app placement topology.`);
+    }
+    return match;
+  }
+
+  const defaultPlacement =
+    placements.find((entry) => entry.default === true && (!surface || entry.surfaces.includes("*") || entry.surfaces.includes(surface))) ||
+    placements.find((entry) => !entry.owner && (!surface || entry.surfaces.includes("*") || entry.surfaces.includes(surface))) ||
+    null;
+  if (defaultPlacement) {
+    return defaultPlacement;
+  }
+
+  throw new Error(`${resolvedContext} could not resolve a default semantic placement target.`);
+}
+
 async function discoverShellOutletTargetsFromApp({ appRoot, sourceRoot = "src" } = {}) {
   const resolvedAppRoot = resolveRequiredAppRoot(appRoot, {
     context: "discoverShellOutletTargetsFromApp"
   });
-  const outletDefaultOverrides = await loadOutletDefaultOverrides(resolvedAppRoot);
 
   const sourceDirectory = path.resolve(resolvedAppRoot, String(sourceRoot || "src"));
   const targetById = new Map();
@@ -363,10 +494,10 @@ async function discoverShellOutletTargetsFromApp({ appRoot, sourceRoot = "src" }
 
   const targets = [...targetById.values()].sort((left, right) => left.id.localeCompare(right.id));
   const normalizedTargets = targets.map((target) =>
-    applyOutletDefaultOverrides({
+    Object.freeze({
       ...target,
       default: target.id === defaultTargetId
-    }, outletDefaultOverrides)
+    })
   );
 
   return Object.freeze({
@@ -418,6 +549,8 @@ async function resolveShellOutletPlacementTargetFromApp({ appRoot, placement = "
 }
 
 export {
+  discoverPlacementTopologyFromApp,
   discoverShellOutletTargetsFromApp,
+  resolveSemanticPlacementTargetFromApp,
   resolveShellOutletPlacementTargetFromApp
 };

package/server/support/shellOutlets.test.js

@@ -99,7 +99,6 @@ test("discoverShellOutletTargetsFromApp includes installed package placement out
         outlets: [
           {
             target: "admin-cog:primary-menu",
-            defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
             source: "src/client/components/UsersWorkspaceToolsWidget.vue"
           }
         ]
@@ -118,7 +117,6 @@ test("discoverShellOutletTargetsFromApp includes installed package placement out
     assert.deepEqual(discovered.targets[0], {
       id: "admin-cog:primary-menu",
       default: false,
-      defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
       sourcePath: "package:@example/users-web:src/client/components/UsersWorkspaceToolsWidget.vue",
       sourcePackageId: "@example/users-web"
     });
@@ -132,68 +130,6 @@ test("discoverShellOutletTargetsFromApp includes installed package placement out
   });
 });
 
-test("discoverShellOutletTargetsFromApp applies app config default-link overrides by target id", async () => {
-  await withTempApp(async (appRoot) => {
-    await writeFileInApp(
-      appRoot,
-      "config/public.js",
-      `export const config = {
-  ui: {
-    outletDefaults: {
-      "admin-cog:primary-menu": {
-        linkComponentToken: "local.main.ui.surface-aware-menu-link-item"
-      }
-    }
-  }
-};
-`
-    );
-    await writeFileInApp(
-      appRoot,
-      ".jskit/lock.json",
-      `${JSON.stringify(
-        {
-          lockVersion: 1,
-          installedPackages: {
-            "@example/users-web": {
-              packageId: "@example/users-web",
-              source: {
-                type: "npm-installed-package",
-                descriptorPath: "node_modules/@example/users-web/package.descriptor.mjs"
-              }
-            }
-          }
-        },
-        null,
-        2
-      )}\n`
-    );
-    await writeFileInApp(
-      appRoot,
-      "node_modules/@example/users-web/package.descriptor.mjs",
-      `export default {
-  packageId: "@example/users-web",
-  metadata: {
-    ui: {
-      placements: {
-        outlets: [
-          {
-            target: "admin-cog:primary-menu",
-            defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item"
-          }
-        ]
-      }
-    }
-  }
-};
-`
-    );
-
-    const discovered = await discoverShellOutletTargetsFromApp({ appRoot });
-    assert.equal(discovered.targets[0].defaultLinkComponentToken, "local.main.ui.surface-aware-menu-link-item");
-  });
-});
-
 test("discoverShellOutletTargetsFromApp returns targets with sourcePath and default marker", async () => {
   await withTempApp(async (appRoot) => {
     await writeFileInApp(
@@ -223,13 +159,11 @@ test("discoverShellOutletTargetsFromApp returns targets with sourcePath and defa
       {
         id: "admin-toolbox:widgets",
         default: true,
-        defaultLinkComponentToken: "",
         sourcePath: "src/pages/admin/toolbox/index.vue"
       },
       {
         id: "shell-layout:primary-menu",
         default: false,
-        defaultLinkComponentToken: "",
         sourcePath: "src/components/ShellLayout.vue"
       }
     ]);
@@ -266,7 +200,6 @@ test("discoverShellOutletTargetsFromApp discovers route meta placement outlets",
       {
         id: "contact-tools:sub-pages",
         default: false,
-        defaultLinkComponentToken: "",
         sourcePath: "src/pages/w/[workspaceSlug]/admin/contacts/[contactId]/contact-tools.vue"
       }
     ]);

package/shared/support/shellLayoutTargets.js

@@ -5,6 +5,8 @@ import {
 
 const SHELL_OUTLET_TAG_PATTERN = /<ShellOutlet\b([^>]*)\/?>/g;
 const ATTRIBUTE_PATTERN = /([:@]?[A-Za-z_][A-Za-z0-9_-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'))?/g;
+const PLACEMENT_LAYOUT_CLASSES = Object.freeze(["compact", "medium", "expanded"]);
+const WEB_PLACEMENT_SURFACE_ANY = "*";
 
 function parseTagAttributes(attributesSource = "") {
   const attributes = {};
@@ -43,6 +45,211 @@ function normalizeShellOutletTargetId(value = "") {
   return `${host}:${position}`;
 }
 
+function normalizeSemanticPlacementId(value = "") {
+  const normalizedValue = normalizeText(value).toLowerCase();
+  if (!normalizedValue || normalizedValue.includes(":") || !normalizedValue.includes(".")) {
+    return "";
+  }
+
+  const segments = normalizedValue.split(".");
+  if (segments.length < 2) {
+    return "";
+  }
+
+  const normalizedSegments = [];
+  for (const segment of segments) {
+    const normalizedSegment = normalizeText(segment);
+    if (!/^[a-z0-9]+(?:[_-][a-z0-9]+)*$/.test(normalizedSegment)) {
+      return "";
+    }
+    normalizedSegments.push(normalizedSegment);
+  }
+
+  return normalizedSegments.join(".");
+}
+
+function normalizePlacementOwnerId(value = "") {
+  const normalizedValue = normalizeText(value).toLowerCase();
+  if (!normalizedValue) {
+    return "";
+  }
+  if (!/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/.test(normalizedValue)) {
+    return "";
+  }
+  return normalizedValue;
+}
+
+function normalizePlacementLayoutClass(value = "") {
+  const normalizedValue = normalizeText(value).toLowerCase();
+  if (PLACEMENT_LAYOUT_CLASSES.includes(normalizedValue)) {
+    return normalizedValue;
+  }
+  return "";
+}
+
+function normalizePlacementKind(value = "") {
+  const normalizedValue = normalizeText(value).toLowerCase();
+  if (normalizedValue === "link" || normalizedValue === "component") {
+    return normalizedValue;
+  }
+  return "";
+}
+
+function normalizePlacementSurfaceId(value = "") {
+  const normalizedValue = normalizeText(value).toLowerCase();
+  if (!normalizedValue) {
+    return "";
+  }
+  if (normalizedValue === WEB_PLACEMENT_SURFACE_ANY) {
+    return WEB_PLACEMENT_SURFACE_ANY;
+  }
+  if (/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/.test(normalizedValue)) {
+    return normalizedValue;
+  }
+  return "";
+}
+
+function normalizePlacementSurfaces(value) {
+  const candidates = Array.isArray(value) ? value : value === undefined || value === null ? [] : [value];
+  if (candidates.length < 1) {
+    return Object.freeze([WEB_PLACEMENT_SURFACE_ANY]);
+  }
+
+  const normalized = [];
+  const seen = new Set();
+  for (const candidate of candidates) {
+    const surface = normalizePlacementSurfaceId(candidate);
+    if (!surface || seen.has(surface)) {
+      continue;
+    }
+    if (surface === WEB_PLACEMENT_SURFACE_ANY) {
+      return Object.freeze([WEB_PLACEMENT_SURFACE_ANY]);
+    }
+    seen.add(surface);
+    normalized.push(surface);
+  }
+
+  if (normalized.length < 1) {
+    return Object.freeze([WEB_PLACEMENT_SURFACE_ANY]);
+  }
+
+  return Object.freeze(normalized);
+}
+
+function resolvePlacementTargetReference(value = "") {
+  const semanticId = normalizeSemanticPlacementId(value);
+  if (semanticId) {
+    return Object.freeze({
+      id: semanticId,
+      type: "semantic"
+    });
+  }
+
+  const concreteId = normalizeShellOutletTargetId(value);
+  if (concreteId) {
+    return Object.freeze({
+      id: concreteId,
+      type: "concrete"
+    });
+  }
+
+  return null;
+}
+
+function normalizePlacementRenderers(value = {}) {
+  const record = normalizeObject(value);
+  const renderers = {};
+  for (const [key, rendererToken] of Object.entries(record)) {
+    const kind = normalizePlacementKind(key);
+    const token = normalizeText(rendererToken);
+    if (!kind || !token) {
+      continue;
+    }
+    renderers[kind] = token;
+  }
+  return Object.freeze(renderers);
+}
+
+function normalizePlacementTopologyVariant(
+  value = {},
+  {
+    context = "placement topology variant"
+  } = {}
+) {
+  const record = normalizeObject(value);
+  const outlet = normalizeShellOutletTargetId(record.outlet || record.target);
+  if (!outlet) {
+    throw new Error(`${normalizeText(context) || "placement topology variant"} requires outlet in "host:position" format.`);
+  }
+
+  return Object.freeze({
+    outlet,
+    renderers: normalizePlacementRenderers(record.renderers)
+  });
+}
+
+function normalizePlacementTopologyEntry(
+  value = {},
+  {
+    context = "placement topology"
+  } = {}
+) {
+  const record = normalizeObject(value);
+  const resolvedContext = normalizeText(context) || "placement topology";
+  const id = normalizeSemanticPlacementId(record.id || record.target);
+  if (!id) {
+    throw new Error(`${resolvedContext} requires semantic placement id in "area.slot" format.`);
+  }
+
+  const owner = normalizePlacementOwnerId(record.owner);
+  const surfaces = normalizePlacementSurfaces(record.surfaces);
+  const variantsRecord = normalizeObject(record.variants);
+  const variants = {};
+  for (const layoutClass of PLACEMENT_LAYOUT_CLASSES) {
+    const variant = variantsRecord[layoutClass];
+    if (!variant) {
+      throw new Error(`${resolvedContext} "${id}" requires ${layoutClass} topology variant.`);
+    }
+    variants[layoutClass] = normalizePlacementTopologyVariant(variant, {
+      context: `${resolvedContext} "${id}" ${layoutClass}`
+    });
+  }
+
+  return Object.freeze({
+    id,
+    owner,
+    description: normalizeText(record.description),
+    surfaces,
+    default: record.default === true,
+    variants: Object.freeze(variants)
+  });
+}
+
+function normalizePlacementTopologyDefinition(
+  value = {},
+  {
+    context = "placement topology"
+  } = {}
+) {
+  const record = normalizeObject(value);
+  const entries = Array.isArray(record.placements) ? record.placements : Array.isArray(value) ? value : [];
+  const normalized = [];
+  const seen = new Set();
+  for (const entry of entries) {
+    const placement = normalizePlacementTopologyEntry(entry, { context });
+    const key = `${placement.id}::${placement.owner || ""}`;
+    if (seen.has(key)) {
+      throw new Error(`${normalizeText(context) || "placement topology"} contains duplicate semantic placement "${placement.id}"${placement.owner ? ` for owner "${placement.owner}"` : ""}.`);
+    }
+    seen.add(key);
+    normalized.push(placement);
+  }
+
+  return Object.freeze({
+    placements: Object.freeze(normalized)
+  });
+}
+
 function resolveShellOutletTargetParts(
   {
     target = ""
@@ -117,10 +324,7 @@ function normalizeShellOutletTargetRecord(
     ...targetParts,
     default:
       Object.hasOwn(record, "default") &&
-      isDefaultAttributeEnabled(record.default),
-    defaultLinkComponentToken:
-      normalizeText(record.defaultLinkComponentToken) ||
-      normalizeText(record["default-link-component-token"])
+      isDefaultAttributeEnabled(record.default)
   });
 }
 
@@ -161,10 +365,21 @@ function discoverShellOutletTargetsFromVueSource(source = "", { context = "shell
 }
 
 export {
+  PLACEMENT_LAYOUT_CLASSES,
   describeShellOutletTargets,
   discoverShellOutletTargetsFromVueSource,
   findShellOutletTargetById,
+  normalizePlacementKind,
+  normalizePlacementLayoutClass,
+  normalizePlacementOwnerId,
+  normalizePlacementSurfaceId,
+  normalizePlacementSurfaces,
+  normalizePlacementTopologyDefinition,
+  normalizePlacementTopologyEntry,
+  normalizePlacementTopologyVariant,
+  normalizeSemanticPlacementId,
   normalizeShellOutletTargetId,
   normalizeShellOutletTargetRecord,
+  resolvePlacementTargetReference,
   resolveShellOutletTargetParts
 };

package/shared/support/shellLayoutTargets.test.js

@@ -22,7 +22,6 @@ test("discoverShellOutletTargetsFromVueSource resolves legal targets and one def
       <ShellOutlet
         target="shell-layout:primary-menu"
         default
-        default-link-component-token="local.main.ui.surface-aware-menu-link-item"
       />
       <ShellOutlet target="shell-layout:secondary-menu" />
     </template>
@@ -37,7 +36,6 @@ test("discoverShellOutletTargetsFromVueSource resolves legal targets and one def
     discovered.targets.map((entry) => entry.id),
     ["shell-layout:top-left", "shell-layout:primary-menu", "shell-layout:secondary-menu"]
   );
-  assert.equal(discovered.targets[1].defaultLinkComponentToken, "local.main.ui.surface-aware-menu-link-item");
   assert.equal(
     describeShellOutletTargets(discovered.targets),
     "shell-layout:top-left, shell-layout:primary-menu, shell-layout:secondary-menu"