@jskit-ai/kernel 0.1.65 → 0.1.67

package/client/moduleBootstrap.js

@@ -483,6 +483,7 @@ function createClientRuntimeApp({
   profile = "client",
   app,
   pinia = null,
+  queryClient = null,
   router,
   env,
   logger,
@@ -498,6 +499,7 @@ function createClientRuntimeApp({
   runtimeApp.instance("jskit.client.router", router || null);
   runtimeApp.instance("jskit.client.vue.app", app || null);
   runtimeApp.instance("jskit.client.pinia", pinia);
+  runtimeApp.instance("jskit.client.query-client", queryClient);
   runtimeApp.instance("jskit.client.env", isRecord(env) ? { ...env } : {});
   runtimeApp.instance("jskit.client.surface.runtime", surfaceRuntime || null);
   runtimeApp.instance("jskit.client.surface.mode", String(surfaceMode || "").trim());
@@ -510,6 +512,7 @@ async function bootClientModules({
   clientModules = [],
   app,
   pinia = null,
+  queryClient = null,
   router,
   surfaceRuntime,
   surfaceMode,
@@ -529,6 +532,7 @@ async function bootClientModules({
     profile: String(surfaceRuntime.normalizeSurfaceMode(surfaceMode) || "client"),
     app,
     pinia,
+    queryClient,
     router,
     env,
     logger: log,

package/client/moduleBootstrap.test.js

@@ -113,6 +113,7 @@ test("bootClientModules registers descriptor and clientRoutes with providers onl
   const events = [];
   const loginComponent = {};
   const pinia = { id: "pinia-instance" };
+  const queryClient = { id: "query-client-instance" };
   const implicitPinia = { id: "implicit-vue-global-pinia" };
   class ExampleClientProvider {
     static id = "example.client";
@@ -120,6 +121,7 @@ test("bootClientModules registers descriptor and clientRoutes with providers onl
       events.push("register");
       app.instance("example.value", 42);
       app.instance("example.pinia", app.make("jskit.client.pinia"));
+      app.instance("example.queryClient", app.make("jskit.client.query-client"));
     }
     boot() {
       events.push("boot");
@@ -190,6 +192,7 @@ test("bootClientModules registers descriptor and clientRoutes with providers onl
       }
     },
     pinia,
+    queryClient,
     router,
     surfaceRuntime,
     surfaceMode: "all",
@@ -206,6 +209,7 @@ test("bootClientModules registers descriptor and clientRoutes with providers onl
   assert.equal(router.routes[1].component, loginComponent);
   assert.equal(result.runtimeApp.make("example.value"), 42);
   assert.equal(result.runtimeApp.make("example.pinia"), pinia);
+  assert.equal(result.runtimeApp.make("example.queryClient"), queryClient);
   assert.notEqual(result.runtimeApp.make("example.pinia"), implicitPinia);
 });
 

package/client/shellBootstrap.js

@@ -109,6 +109,7 @@ async function bootstrapClientShellApp({
   appConfig = {},
   appPlugins = [],
   pinia = null,
+  queryClient = null,
   router,
   bootClientModules,
   surfaceRuntime,
@@ -161,6 +162,7 @@ async function bootstrapClientShellApp({
   const clientBootstrap = await bootClientModules({
     app,
     pinia,
+    queryClient,
     router,
     surfaceRuntime,
     surfaceMode,

package/client/shellBootstrap.test.js

@@ -86,6 +86,7 @@ test("bootstrapClientShellApp boots modules, reinstalls fallback route, and moun
   const surfaceRuntime = createSurfaceRuntimeFixture();
   const plugin = { name: "vuetify-like-plugin" };
   const pinia = { id: "pinia-instance" };
+  const queryClient = { id: "query-client-instance" };
   const fallbackRoute = {
     name: "not-found",
     path: "/:pathMatch(.*)*",
@@ -142,11 +143,13 @@ test("bootstrapClientShellApp boots modules, reinstalls fallback route, and moun
     },
     appPlugins: [plugin],
     pinia,
+    queryClient,
     router,
     bootClientModules: async (context) => {
       calls.push("bootClientModules");
       assert.equal(context.app, app);
       assert.equal(context.pinia, pinia);
+      assert.equal(context.queryClient, queryClient);
       assert.equal(context.router, router);
       assert.equal(typeof context.logger.debug, "function");
       return {

package/client/vite/clientBootstrapPlugin.js

@@ -14,6 +14,7 @@ const CLIENT_BOOTSTRAP_VIRTUAL_ID = "virtual:jskit-client-bootstrap";
 const CLIENT_BOOTSTRAP_RESOLVED_ID = `\0${CLIENT_BOOTSTRAP_VIRTUAL_ID}`;
 const CLIENT_RUNTIME_DEDUPE_SPECIFIERS = Object.freeze([
   "@tanstack/vue-query",
+  "pinia",
   "vue",
   "vue-router",
   "vuetify"

package/client/vite/clientBootstrapPlugin.test.js

@@ -404,7 +404,7 @@ test("createJskitClientBootstrapPlugin config excludes installed client package
     assert.equal(Array.isArray(result?.optimizeDeps?.exclude), true);
     assert.deepEqual(result.optimizeDeps.exclude, ["already/excluded"]);
     assert.deepEqual(result.optimizeDeps.include, ["@example/has-client/client", "a"]);
-    assert.deepEqual(result.resolve.dedupe, ["@tanstack/vue-query", "vue", "vue-router", "vuetify"]);
+    assert.deepEqual(result.resolve.dedupe, ["@tanstack/vue-query", "pinia", "vue", "vue-router", "vuetify"]);
   } finally {
     process.chdir(previousCwd);
   }
@@ -469,7 +469,7 @@ test("createJskitClientBootstrapPlugin config excludes local package roots and c
       "@example/local-client/shared"
     ]);
     assert.deepEqual(result.optimizeDeps.include, ["@example/remote-client/client", "mime-match"]);
-    assert.deepEqual(result.resolve.dedupe, ["@tanstack/vue-query", "vue", "vue-router", "vuetify"]);
+    assert.deepEqual(result.resolve.dedupe, ["@tanstack/vue-query", "pinia", "vue", "vue-router", "vuetify"]);
   } finally {
     process.chdir(previousCwd);
   }
@@ -500,7 +500,7 @@ test("createJskitClientBootstrapPlugin config preserves user resolve fields and
     assert.deepEqual(result.resolve.alias, {
       "@": "/tmp/app/src"
     });
-    assert.deepEqual(result.resolve.dedupe, ["@tanstack/vue-query", "custom-lib", "vue", "vue-router", "vuetify"]);
+    assert.deepEqual(result.resolve.dedupe, ["@tanstack/vue-query", "custom-lib", "pinia", "vue", "vue-router", "vuetify"]);
   } finally {
     process.chdir(previousCwd);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.65",
+  "version": "0.1.67",
   "type": "module",
   "dependencies": {
     "json-rest-schema": "1.x.x"
@@ -42,6 +42,7 @@
     "./shared/support/crudListFilters": "./shared/support/crudListFilters.js",
     "./shared/support/crudFieldContract": "./shared/support/crudFieldContract.js",
     "./shared/support/crudLookup": "./shared/support/crudLookup.js",
+    "./shared/support/generatedUiContract": "./shared/support/generatedUiContract.js",
     "./shared/support/deepFreeze": "./shared/support/deepFreeze.js",
     "./shared/support/listenerSet": "./shared/support/listenerSet.js",
     "./shared/support/shellLayoutTargets": "./shared/support/shellLayoutTargets.js",

package/server/http/lib/httpRuntime.js

@@ -1,5 +1,5 @@
 import { normalizeObject } from "../../../shared/support/normalize.js";
-import { ensureApiErrorHandling } from "../../runtime/fastifyBootstrap.js";
+import { ensureApiErrorHandling, registerBodylessContentTypeNormalizer } from "../../runtime/fastifyBootstrap.js";
 import { resolveDefaultSurfaceId } from "../../support/appConfig.js";
 import { RouteRegistrationError } from "./errors.js";
 import { createRouter } from "./router.js";
@@ -25,6 +25,8 @@ function registerHttpRuntime(app, options = {}) {
     defaultSurfaceId: routeRegistrationOptions.requestActionDefaultSurface
   });
 
+  registerBodylessContentTypeNormalizer(fastify);
+
   if (autoRegisterApiErrorHandling !== false) {
     ensureApiErrorHandling(app, {
       fastifyToken,

package/server/http/lib/kernel.test.js

@@ -14,9 +14,13 @@ function createFastifyStub() {
     setErrorHandlerCalls: 0,
     errorHandler: null,
     contentTypeParsers: new Map(),
+    hooks: {},
     route(definition) {
       routes.push(definition);
     },
+    addHook(name, handler) {
+      this.hooks[name] = handler;
+    },
     setErrorHandler(handler) {
       this.errorHandler = handler;
       this.setErrorHandlerCalls += 1;

package/server/runtime/fastifyBootstrap.js

@@ -5,6 +5,7 @@ import { resolveDefaultSurfaceId } from "../support/appConfig.js";
 
 const JSON_API_CONTENT_TYPE = "application/vnd.api+json";
 const JSON_API_CONTENT_TYPE_PARSER_MARKER = Symbol.for("jskit.fastify.jsonApiContentTypeParserRegistered");
+const BODYLESS_CONTENT_TYPE_NORMALIZER_MARKER = Symbol.for("jskit.fastify.bodylessContentTypeNormalizerRegistered");
 
 function resolveLoggerLevel({ configuredLevel = "", nodeEnv = "development", allowedLevels = [] } = {}) {
   const normalizedConfiguredLevel = String(configuredLevel || "")
@@ -83,6 +84,64 @@ function registerJsonApiContentTypeParser(fastify) {
   return true;
 }
 
+function hasHeaderValue(headers = {}, key = "") {
+  return String(headers?.[key] ?? "").trim().length > 0;
+}
+
+function hasRequestBody(headers = {}) {
+  const transferEncoding = String(headers?.["transfer-encoding"] ?? "").trim();
+  if (transferEncoding) {
+    return true;
+  }
+
+  const contentLengthHeader = String(headers?.["content-length"] ?? "").trim();
+  if (!contentLengthHeader) {
+    return false;
+  }
+
+  const contentLength = Number(contentLengthHeader);
+  if (!Number.isFinite(contentLength)) {
+    return true;
+  }
+
+  return contentLength > 0;
+}
+
+function normalizeBodylessContentTypeHeader(request = null) {
+  const headers = request?.headers;
+  if (!headers || typeof headers !== "object" || Array.isArray(headers)) {
+    return false;
+  }
+
+  if (!hasHeaderValue(headers, "content-type") && !hasHeaderValue(headers, "Content-Type")) {
+    return false;
+  }
+
+  if (hasRequestBody(headers)) {
+    return false;
+  }
+
+  delete headers["content-type"];
+  delete headers["Content-Type"];
+  return true;
+}
+
+function registerBodylessContentTypeNormalizer(fastify) {
+  if (!fastify || typeof fastify.addHook !== "function") {
+    throw new TypeError("registerBodylessContentTypeNormalizer requires a Fastify instance.");
+  }
+
+  if (fastify[BODYLESS_CONTENT_TYPE_NORMALIZER_MARKER]) {
+    return false;
+  }
+
+  fastify.addHook("onRequest", async (request) => {
+    normalizeBodylessContentTypeHeader(request);
+  });
+  fastify[BODYLESS_CONTENT_TYPE_NORMALIZER_MARKER] = true;
+  return true;
+}
+
 function registerRequestLoggingHooks(
   app,
   {
@@ -483,6 +542,8 @@ export {
   resolveLoggerLevel,
   createFastifyLoggerOptions,
   registerJsonApiContentTypeParser,
+  normalizeBodylessContentTypeHeader,
+  registerBodylessContentTypeNormalizer,
   registerRequestLoggingHooks,
   registerApiErrorHandler,
   ensureApiErrorHandling,

package/server/runtime/fastifyBootstrap.test.js

@@ -2,7 +2,13 @@ import assert from "node:assert/strict";
 import test from "node:test";
 
 import { AppError, isAppError } from "./errors.js";
-import { registerApiErrorHandler, registerJsonApiContentTypeParser, registerRequestLoggingHooks } from "./fastifyBootstrap.js";
+import {
+  normalizeBodylessContentTypeHeader,
+  registerApiErrorHandler,
+  registerBodylessContentTypeNormalizer,
+  registerJsonApiContentTypeParser,
+  registerRequestLoggingHooks
+} from "./fastifyBootstrap.js";
 
 function createFastifyStub() {
   return {
@@ -275,6 +281,46 @@ test("registerJsonApiContentTypeParser installs the JSON:API media type parser o
   assert.equal(fastify.contentTypeParsers.size, 1);
 });
 
+test("normalizeBodylessContentTypeHeader strips meaningless content type from empty requests", () => {
+  const request = {
+    headers: {
+      "content-type": "text/plain;charset=UTF-8"
+    }
+  };
+
+  assert.equal(normalizeBodylessContentTypeHeader(request), true);
+  assert.deepEqual(request.headers, {});
+});
+
+test("normalizeBodylessContentTypeHeader keeps content type when a body is declared", () => {
+  const request = {
+    headers: {
+      "content-type": "text/plain;charset=UTF-8",
+      "content-length": "12"
+    }
+  };
+
+  assert.equal(normalizeBodylessContentTypeHeader(request), false);
+  assert.equal(request.headers["content-type"], "text/plain;charset=UTF-8");
+});
+
+test("registerBodylessContentTypeNormalizer installs the request hook once", async () => {
+  const fastify = createFastifyStub();
+  assert.equal(registerBodylessContentTypeNormalizer(fastify), true);
+  assert.equal(registerBodylessContentTypeNormalizer(fastify), false);
+
+  const request = {
+    headers: {
+      "content-type": "text/plain;charset=UTF-8",
+      "content-length": "0"
+    }
+  };
+  await fastify.hooks.onRequest(request);
+  assert.deepEqual(request.headers, {
+    "content-length": "0"
+  });
+});
+
 test("registerRequestLoggingHooks uses configured default surface when getSurface is absent", async () => {
   const fastify = createFastifyStub();
   let loggedPayload = null;

package/server/support/appConfigFiles.js

@@ -1,6 +1,7 @@
 import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { fileURLToPath } from "node:url";
 import { fileExists } from "../../internal/node/fileSystem.js";
+import { importFreshModuleFromAbsolutePath } from "./importFreshModuleFromAbsolutePath.js";
 
 const PUBLIC_CONFIG_RELATIVE_PATH = "config/public.js";
 const SERVER_CONFIG_RELATIVE_PATH = "config/server.js";
@@ -35,7 +36,7 @@ async function loadConfigModuleAtPath(absolutePath) {
     return {};
   }
 
-  const loadedModule = await import(pathToFileURL(absolutePath).href);
+  const loadedModule = await importFreshModuleFromAbsolutePath(absolutePath);
   return normalizeConfigObject(loadedModule?.config);
 }
 

package/server/support/appConfigFiles.test.js

@@ -47,6 +47,21 @@ test("loadAppConfigFromAppRoot merges public and server config", async () => {
   assert.equal(Object.isFrozen(loaded), true);
 });
 
+test("loadAppConfigFromAppRoot re-reads config changes within the same process", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "kernel-app-config-"));
+  const appRoot = path.join(tempRoot, "app");
+  const publicConfigPath = path.join(appRoot, "config", "public.js");
+  await mkdir(path.dirname(publicConfigPath), { recursive: true });
+  await writeFile(publicConfigPath, "export const config = { mobile: { enabled: false } };", "utf8");
+
+  const firstLoaded = await loadAppConfigFromAppRoot({ appRoot });
+  await writeFile(publicConfigPath, "export const config = { mobile: { enabled: true } };", "utf8");
+  const secondLoaded = await loadAppConfigFromAppRoot({ appRoot });
+
+  assert.equal(firstLoaded.mobile.enabled, false);
+  assert.equal(secondLoaded.mobile.enabled, true);
+});
+
 test("loadAppConfigFromAppRoot requires an explicit appRoot", async () => {
   await assert.rejects(
     loadAppConfigFromAppRoot({ appRoot: "" }),

package/server/support/index.js

@@ -16,6 +16,9 @@ export {
   resolvePageLinkTargetDetails
 } from "./pageTargets.js";
 export {
+  discoverPlacementTopologyFromApp,
+  discoverShellOutletSourcePathsFromApp,
   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";
 
@@ -370,8 +373,8 @@ function buildAncestorRouteContexts(pageTarget = {}) {
 
   for (let visiblePrefixLength = visibleRouteSegments.length - 1; visiblePrefixLength >= 1; visiblePrefixLength -= 1) {
     const parentVisibleSegments = visibleRouteSegments.slice(0, visiblePrefixLength);
-      const actualRouteSegments = [];
-      let collectedVisibleSegments = 0;
+    const actualRouteSegments = [];
+    let collectedVisibleSegments = 0;
 
     for (const segment of routeSegments) {
       actualRouteSegments.push(segment);
@@ -562,6 +565,64 @@ 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 = "",
+  context = "page target"
+} = {}) {
+  const normalizedConcreteTarget = normalizeShellOutletTargetId(concreteTarget);
+  if (!normalizedConcreteTarget) {
+    return null;
+  }
+
+  const topology = await discoverPlacementTopologyFromApp({ appRoot });
+  const owner = resolveConcreteTargetOwner(normalizedConcreteTarget);
+  const normalizedSurface = normalizeSurfaceId(surface);
+  const candidates = (Array.isArray(topology.placements) ? topology.placements : []).filter((placement) => {
+    if (!topologyPlacementTargetsConcreteOutlet(placement, normalizedConcreteTarget)) {
+      return false;
+    }
+    const surfaces = Array.isArray(placement.surfaces) ? placement.surfaces : ["*"];
+    return !normalizedSurface || surfaces.includes("*") || surfaces.includes(normalizedSurface);
+  });
+
+  const exactOwnerMatches = candidates.filter((placement) => placement.owner && placement.owner === owner);
+  const globalMatches = candidates.filter((placement) => !placement.owner);
+  const selectedMatches = exactOwnerMatches.length > 0 ? exactOwnerMatches : globalMatches;
+  if (selectedMatches.length < 1) {
+    return null;
+  }
+  if (selectedMatches.length === 1) {
+    return selectedMatches[0];
+  }
+
+  const targetLabels = selectedMatches.map((placement) =>
+    placement.owner ? `${placement.id} [owner:${placement.owner}]` : placement.id
+  );
+  throw new Error(
+    `${context} found multiple semantic placements mapped to concrete outlet "${normalizedConcreteTarget}": ` +
+    `${targetLabels.join(", ")}. Pass --link-placement or make the topology mapping unambiguous.`
+  );
+}
+
 function resolveRelativeLinkToFromParent(pageTarget = {}, parentHost = null) {
   const childSegments = Array.isArray(pageTarget?.visibleRouteSegments) ? pageTarget.visibleRouteSegments : [];
   const parentSegments = Array.isArray(parentHost?.visibleRouteSegments) ? parentHost.visibleRouteSegments : [];
@@ -598,7 +659,7 @@ function resolveInferredPageLinkTo({
   explicitLinkTo = "",
   pageTarget = {},
   parentHost = null,
-  placementTarget = null,
+  preservesRelativeSubpageLinks = false,
   suppressImplicitRelativeLinks = false
 } = {}) {
   const normalizedExplicitLinkTo = normalizeText(explicitLinkTo);
@@ -609,14 +670,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 +684,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 +699,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 +711,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
     })
   });
 }