@jskit-ai/kernel 0.1.30 → 0.1.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "type": "module",
   "dependencies": {
     "typebox": "^1.0.81"

package/server/support/index.js

@@ -2,6 +2,16 @@ export { symlinkSafeRequire } from "./symlinkSafeRequire.js";
 export { resolveAppConfig } from "./appConfig.js";
 export { loadAppConfigFromModuleUrl } from "./appConfigFiles.js";
 export { resolveRequiredAppRoot, toPosixPath } from "./path.js";
+export {
+  DEFAULT_PAGE_LINK_COMPONENT_TOKEN,
+  DEFAULT_SUBPAGE_LINK_COMPONENT_TOKEN,
+  normalizePagesRelativeTargetFile,
+  normalizePagesRelativeTargetRoot,
+  resolvePageTargetDetails,
+  deriveDefaultSubpagesHost,
+  resolveNearestParentSubpagesHost,
+  resolvePageLinkTargetDetails
+} from "./pageTargets.js";
 export {
   discoverShellOutletTargetsFromApp,
   resolveShellOutletPlacementTargetFromApp

package/server/support/pageTargets.js

@@ -0,0 +1,684 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import {
+  normalizeSurfaceId,
+  normalizeSurfacePagesRoot
+} from "../../shared/surface/index.js";
+import {
+  normalizeObject,
+  normalizeText
+} from "../../shared/support/normalize.js";
+import {
+  discoverShellOutletTargetsFromVueSource,
+  findShellOutletTargetById,
+  normalizeShellOutletTargetId
+} from "../../shared/support/shellLayoutTargets.js";
+import { resolveShellOutletPlacementTargetFromApp } from "./shellOutlets.js";
+import { resolveRequiredAppRoot, toPosixPath } from "./path.js";
+
+const DEFAULT_PAGE_LINK_COMPONENT_TOKEN = "users.web.shell.surface-aware-menu-link-item";
+const DEFAULT_SUBPAGE_LINK_COMPONENT_TOKEN = "local.main.ui.tab-link-item";
+const PAGE_ROOT_PREFIX = "src/pages/";
+const ROUTER_VIEW_TAG_PATTERN = /<RouterView\b/i;
+
+function normalizeRelativeFilePath(value = "") {
+  return String(value || "")
+    .replaceAll("\\", "/")
+    .replace(/^\.\/+/, "")
+    .trim();
+}
+
+function validateVueTargetFile(relativePath = "", { context = "page target" } = {}) {
+  const normalizedRelativePath = normalizeRelativeFilePath(relativePath);
+  if (!normalizedRelativePath.endsWith(".vue")) {
+    throw new Error(`${context} target file must be a .vue file: ${normalizedRelativePath || "<empty>"}.`);
+  }
+  return normalizedRelativePath;
+}
+
+function isAbsolutePathInput(value = "") {
+  const normalizedValue = normalizeRelativeFilePath(value);
+  if (!normalizedValue) {
+    return false;
+  }
+
+  if (normalizedValue.startsWith("/")) {
+    return true;
+  }
+
+  return /^[A-Za-z]:\//u.test(normalizedValue);
+}
+
+function resolvePagesRelativeAppPath(
+  value = "",
+  {
+    context = "page target",
+    label = "target path"
+  } = {}
+) {
+  const normalizedValue = normalizeRelativeFilePath(value);
+  if (!normalizedValue) {
+    throw new Error(`${context} requires ${label}.`);
+  }
+  if (isAbsolutePathInput(normalizedValue)) {
+    throw new Error(`${context} ${label} must be relative to src/pages/: ${normalizedValue}.`);
+  }
+  if (
+    normalizedValue === "src/pages" ||
+    normalizedValue.startsWith(PAGE_ROOT_PREFIX)
+  ) {
+    throw new Error(
+      `${context} ${label} must be relative to src/pages/, without the src/pages/ prefix: ${normalizedValue}.`
+    );
+  }
+  if (normalizedValue.startsWith("src/")) {
+    throw new Error(
+      `${context} ${label} must be relative to src/pages/, without a leading src/ segment: ${normalizedValue}.`
+    );
+  }
+
+  return `${PAGE_ROOT_PREFIX}${normalizedValue}`;
+}
+
+function normalizePagesRelativeTargetFile(
+  targetFile = "",
+  {
+    context = "page target",
+    label = "target file"
+  } = {}
+) {
+  return validateVueTargetFile(
+    resolvePagesRelativeAppPath(targetFile, { context, label }),
+    { context }
+  );
+}
+
+function normalizePagesRelativeTargetRoot(
+  targetRoot = "",
+  {
+    context = "page target",
+    label = "target root"
+  } = {}
+) {
+  const normalizedRelativePath = resolvePagesRelativeAppPath(targetRoot, {
+    context,
+    label
+  });
+  if (normalizedRelativePath.endsWith(".vue")) {
+    throw new Error(`${context} ${label} must be a route directory, not a .vue file: ${normalizedRelativePath}.`);
+  }
+  return normalizedRelativePath;
+}
+
+function splitTextIntoWords(value = "") {
+  const normalized = String(value || "")
+    .replace(/^\[|\]$/g, "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[^A-Za-z0-9]+/g, " ")
+    .trim();
+  if (!normalized) {
+    return [];
+  }
+
+  return normalized
+    .split(/\s+/)
+    .map((entry) => entry.toLowerCase())
+    .filter(Boolean);
+}
+
+function wordsToKebab(words = []) {
+  return (Array.isArray(words) ? words : [])
+    .map((entry) => String(entry || "").toLowerCase())
+    .filter(Boolean)
+    .join("-");
+}
+
+function toTitleCase(words = []) {
+  return (Array.isArray(words) ? words : [])
+    .map((word) => {
+      const value = String(word || "");
+      if (!value) {
+        return "";
+      }
+      return `${value.slice(0, 1).toUpperCase()}${value.slice(1)}`;
+    })
+    .filter(Boolean)
+    .join(" ");
+}
+
+function isRouteGroupSegment(value = "") {
+  const normalizedValue = normalizeText(value);
+  return normalizedValue.startsWith("(") && normalizedValue.endsWith(")");
+}
+
+function isIndexRouteSegment(value = "") {
+  return normalizeText(value).toLowerCase() === "index";
+}
+
+function isPathlessRouteSegment(value = "") {
+  return isRouteGroupSegment(value) || isIndexRouteSegment(value);
+}
+
+function normalizePlacementIdSegment(value = "") {
+  return wordsToKebab(splitTextIntoWords(value));
+}
+
+function humanizePageSegment(value = "", fallback = "Page") {
+  const words = splitTextIntoWords(value);
+  if (words.length < 1) {
+    return fallback;
+  }
+  return toTitleCase(words);
+}
+
+async function loadPublicConfig(appRoot = "", { context = "page target" } = {}) {
+  const resolvedAppRoot = resolveRequiredAppRoot(appRoot, { context });
+  const configPath = path.join(resolvedAppRoot, "config", "public.js");
+
+  try {
+    await readFile(configPath, "utf8");
+  } catch {
+    throw new Error(`${context} requires app config at config/public.js.`);
+  }
+
+  let moduleNamespace = null;
+  try {
+    moduleNamespace = await import(pathToFileURL(configPath).href);
+  } catch (error) {
+    throw new Error(
+      `${context} could not load config/public.js: ${String(error?.message || error || "unknown error")}`
+    );
+  }
+
+  const config = normalizeObject(
+    moduleNamespace?.config ||
+    moduleNamespace?.default?.config ||
+    moduleNamespace?.default
+  );
+  if (Object.keys(config).length < 1) {
+    throw new Error(`${context} requires exported config in config/public.js.`);
+  }
+
+  return config;
+}
+
+async function listSurfacePageRoots(appRoot = "", { context = "page target" } = {}) {
+  const config = await loadPublicConfig(appRoot, { context });
+  const surfaceDefinitions = normalizeObject(config.surfaceDefinitions);
+
+  return Object.freeze(
+    Object.entries(surfaceDefinitions)
+      .map(([key, value]) => {
+        const definition = normalizeObject(value);
+        const surfaceId = normalizeSurfaceId(definition.id || key);
+        if (!surfaceId || definition.enabled === false) {
+          return null;
+        }
+
+        return Object.freeze({
+          id: surfaceId,
+          pagesRoot: normalizeSurfacePagesRoot(definition.pagesRoot)
+        });
+      })
+      .filter(Boolean)
+  );
+}
+
+function deriveSurfaceMatchesFromPageFile(relativePath = "", surfacePageRoots = []) {
+  const normalizedRelativePath = normalizeRelativeFilePath(relativePath);
+  if (!normalizedRelativePath.startsWith(PAGE_ROOT_PREFIX)) {
+    return [];
+  }
+
+  const pagePathWithinPagesRoot = normalizedRelativePath.slice(PAGE_ROOT_PREFIX.length);
+  return (Array.isArray(surfacePageRoots) ? surfacePageRoots : [])
+    .map((surface) => {
+      const pagesRoot = normalizeSurfacePagesRoot(surface?.pagesRoot);
+      if (!pagesRoot) {
+        return Object.freeze({
+          surfaceId: normalizeSurfaceId(surface?.id),
+          pagesRoot,
+          surfaceRelativeFilePath: pagePathWithinPagesRoot
+        });
+      }
+
+      const requiredPrefix = `${pagesRoot}/`;
+      if (!pagePathWithinPagesRoot.startsWith(requiredPrefix)) {
+        return null;
+      }
+
+      return Object.freeze({
+        surfaceId: normalizeSurfaceId(surface?.id),
+        pagesRoot,
+        surfaceRelativeFilePath: pagePathWithinPagesRoot.slice(requiredPrefix.length)
+      });
+    })
+    .filter(Boolean);
+}
+
+function compareSurfaceMatchSpecificity(leftMatch = {}, rightMatch = {}) {
+  const leftPagesRoot = normalizeSurfacePagesRoot(leftMatch?.pagesRoot);
+  const rightPagesRoot = normalizeSurfacePagesRoot(rightMatch?.pagesRoot);
+  const leftSegmentCount = leftPagesRoot ? leftPagesRoot.split("/").filter(Boolean).length : 0;
+  const rightSegmentCount = rightPagesRoot ? rightPagesRoot.split("/").filter(Boolean).length : 0;
+
+  if (leftSegmentCount !== rightSegmentCount) {
+    return rightSegmentCount - leftSegmentCount;
+  }
+  if (leftPagesRoot.length !== rightPagesRoot.length) {
+    return rightPagesRoot.length - leftPagesRoot.length;
+  }
+  return leftPagesRoot.localeCompare(rightPagesRoot);
+}
+
+function resolveBestSurfaceMatchFromPageFile(relativePath = "", surfacePageRoots = [], { context = "page target" } = {}) {
+  const matches = deriveSurfaceMatchesFromPageFile(relativePath, surfacePageRoots);
+  if (matches.length < 1) {
+    return null;
+  }
+
+  const sortedMatches = [...matches].sort(compareSurfaceMatchSpecificity);
+  const bestMatch = sortedMatches[0];
+  const bestPagesRoot = normalizeSurfacePagesRoot(bestMatch?.pagesRoot);
+  const conflictingMatches = sortedMatches.filter(
+    (match) => normalizeSurfacePagesRoot(match?.pagesRoot) === bestPagesRoot
+  );
+  if (conflictingMatches.length > 1) {
+    const surfaceIds = conflictingMatches.map((match) => match.surfaceId).filter(Boolean).join(", ");
+    const pagesRootLabel = bestPagesRoot || "/";
+    throw new Error(
+      `${context} target file is ambiguous because multiple surfaces share pagesRoot "${pagesRootLabel}" (${surfaceIds}): ${normalizeRelativeFilePath(relativePath)}.`
+    );
+  }
+
+  return bestMatch;
+}
+
+function deriveRouteInfoFromSurfaceRelativeFile(surfaceRelativeFilePath = "", surfaceId = "") {
+  const normalizedRelativeFilePath = validateVueTargetFile(surfaceRelativeFilePath, {
+    context: "page target"
+  });
+  const withoutExtension = normalizedRelativeFilePath.slice(0, -".vue".length);
+  const fileSegments = withoutExtension
+    .split("/")
+    .map((segment) => normalizeText(segment))
+    .filter(Boolean);
+
+  const routeSegments = [...fileSegments];
+  if (routeSegments[routeSegments.length - 1] === "index") {
+    routeSegments.pop();
+  }
+
+  const visibleRouteSegments = routeSegments.filter((segment) => !isPathlessRouteSegment(segment));
+  const routeUrlSuffix = visibleRouteSegments.length > 0 ? `/${visibleRouteSegments.join("/")}` : "/";
+  const surfacePlacementIdSegment = normalizePlacementIdSegment(surfaceId || "root") || "root";
+  const placementIdSegments = visibleRouteSegments
+    .map((segment) => normalizePlacementIdSegment(segment))
+    .filter(Boolean);
+  const pageLeafSegment = visibleRouteSegments[visibleRouteSegments.length - 1] || "";
+  const defaultNameSource = pageLeafSegment || surfaceId || "page";
+  const defaultName = humanizePageSegment(defaultNameSource, "Page");
+
+  return Object.freeze({
+    fileSegments,
+    routeSegments,
+    visibleRouteSegments,
+    routeUrlSuffix,
+    pageLeafSegment,
+    defaultName,
+    placementId:
+      placementIdSegments.length > 0
+        ? `ui-generator.page.${surfacePlacementIdSegment}.${placementIdSegments.join(".")}.link`
+        : `ui-generator.page.${surfacePlacementIdSegment}.link`
+  });
+}
+
+function buildRouteUrlSuffixFromVisibleSegments(segments = []) {
+  const visibleSegments = (Array.isArray(segments) ? segments : [])
+    .map((segment) => normalizeText(segment))
+    .filter(Boolean);
+  return visibleSegments.length > 0 ? `/${visibleSegments.join("/")}` : "/";
+}
+
+function buildAncestorRouteContexts(pageTarget = {}) {
+  const routeSegments = Array.isArray(pageTarget?.routeSegments)
+    ? pageTarget.routeSegments
+    : [];
+  const visibleRouteSegments = Array.isArray(pageTarget?.visibleRouteSegments)
+    ? pageTarget.visibleRouteSegments
+    : [];
+  if (visibleRouteSegments.length < 2) {
+    return [];
+  }
+
+  const ancestors = [];
+
+  for (let visiblePrefixLength = visibleRouteSegments.length - 1; visiblePrefixLength >= 1; visiblePrefixLength -= 1) {
+    const parentVisibleSegments = visibleRouteSegments.slice(0, visiblePrefixLength);
+      const actualRouteSegments = [];
+      let collectedVisibleSegments = 0;
+
+    for (const segment of routeSegments) {
+      actualRouteSegments.push(segment);
+      if (!isPathlessRouteSegment(segment)) {
+        collectedVisibleSegments += 1;
+      }
+      if (collectedVisibleSegments >= visiblePrefixLength) {
+        break;
+      }
+    }
+
+    if (collectedVisibleSegments !== visiblePrefixLength) {
+      continue;
+    }
+
+    const nextRouteSegment = normalizeText(routeSegments[actualRouteSegments.length]);
+    ancestors.push(
+      Object.freeze({
+        visibleRouteSegments: parentVisibleSegments,
+        actualRouteSegments,
+        childUsesIndexRouteOwner: isIndexRouteSegment(nextRouteSegment)
+      })
+    );
+  }
+
+  return ancestors;
+}
+
+function buildParentPageFileCandidates(pageTarget = {}, ancestorRoute = {}) {
+  const surfacePagesRootSegments = normalizeRelativeFilePath(pageTarget?.surfacePagesRoot)
+    .split("/")
+    .map((segment) => normalizeText(segment))
+    .filter(Boolean);
+  const routeSegments = (Array.isArray(ancestorRoute?.actualRouteSegments) ? ancestorRoute.actualRouteSegments : [])
+    .map((segment) => normalizeText(segment))
+    .filter(Boolean);
+  if (routeSegments.length < 1) {
+    return [];
+  }
+
+  const baseSegments = ["src/pages", ...surfacePagesRootSegments, ...routeSegments];
+  const fileRoutePath = `${baseSegments.join("/")}.vue`;
+  const indexRoutePath = [...baseSegments, "index.vue"].join("/");
+  const preferredCandidates = ancestorRoute?.childUsesIndexRouteOwner === true
+    ? [indexRoutePath, fileRoutePath]
+    : [fileRoutePath, indexRoutePath];
+
+  return preferredCandidates.map((relativePath) =>
+    Object.freeze({
+      relativePath,
+      pageShape: relativePath.endsWith("/index.vue") ? "index" : "file"
+    })
+  );
+}
+
+function resolveSubpagesHostTargetFromPageSource(source = "") {
+  const sourceText = String(source || "");
+  if (!ROUTER_VIEW_TAG_PATTERN.test(sourceText)) {
+    return null;
+  }
+
+  const discoveredTargets = discoverShellOutletTargetsFromVueSource(sourceText, {
+    context: "subpages host"
+  });
+  const targets = Array.isArray(discoveredTargets.targets) ? discoveredTargets.targets : [];
+  if (targets.length !== 1) {
+    return null;
+  }
+
+  const target = findShellOutletTargetById(targets, targets[0]?.id);
+  if (!target) {
+    return null;
+  }
+
+  return Object.freeze({
+    id: target.id,
+    host: target.host,
+    position: target.position
+  });
+}
+
+async function resolvePageTargetDetails({
+  appRoot,
+  targetFile = "",
+  context = "page target"
+} = {}) {
+  const resolvedAppRoot = resolveRequiredAppRoot(appRoot, { context });
+  const normalizedRelativePath = normalizePagesRelativeTargetFile(targetFile, {
+    context,
+    label: "target file"
+  });
+
+  const surfacePageRoots = await listSurfacePageRoots(resolvedAppRoot, { context });
+  const surfaceMatch = resolveBestSurfaceMatchFromPageFile(normalizedRelativePath, surfacePageRoots, { context });
+  if (!surfaceMatch) {
+    throw new Error(
+      `${context} target file must be relative to src/pages/ and resolve to a configured surface: ${normalizeRelativeFilePath(targetFile)}.`
+    );
+  }
+  const routeInfo = deriveRouteInfoFromSurfaceRelativeFile(surfaceMatch.surfaceRelativeFilePath, surfaceMatch.surfaceId);
+  const absolutePath = path.resolve(resolvedAppRoot, normalizedRelativePath);
+
+  return Object.freeze({
+    appRoot: resolvedAppRoot,
+    targetFilePath: Object.freeze({
+      absolutePath,
+      relativePath: normalizedRelativePath
+    }),
+    surfaceId: surfaceMatch.surfaceId,
+    surfacePagesRoot: surfaceMatch.pagesRoot,
+    surfaceRelativeFilePath: surfaceMatch.surfaceRelativeFilePath,
+    ...routeInfo
+  });
+}
+
+function deriveDefaultSubpagesHost(pageTarget = {}) {
+  const visibleRouteSegments = Array.isArray(pageTarget?.visibleRouteSegments)
+    ? pageTarget.visibleRouteSegments
+    : [];
+  const hostSegments = visibleRouteSegments
+    .map((segment) => normalizePlacementIdSegment(segment))
+    .filter(Boolean);
+
+  if (hostSegments.length > 0) {
+    return hostSegments.join("-");
+  }
+
+  return normalizePlacementIdSegment(pageTarget?.surfaceId || "page") || "page";
+}
+
+async function resolveNearestParentSubpagesHost({
+  appRoot,
+  pageTarget = {},
+  context = "page target"
+} = {}) {
+  const resolvedAppRoot = resolveRequiredAppRoot(appRoot, { context });
+  const ancestorRoutes = buildAncestorRouteContexts(pageTarget);
+  if (ancestorRoutes.length < 1) {
+    return null;
+  }
+
+  for (const ancestorRoute of ancestorRoutes) {
+    const candidatePages = buildParentPageFileCandidates(pageTarget, ancestorRoute);
+
+    for (const candidatePage of candidatePages) {
+      const candidatePath = path.resolve(resolvedAppRoot, candidatePage.relativePath);
+      let source = "";
+      try {
+        source = await readFile(candidatePath, "utf8");
+      } catch {
+        continue;
+      }
+
+      const target = resolveSubpagesHostTargetFromPageSource(source);
+      if (!target) {
+        continue;
+      }
+
+      return Object.freeze({
+        ...target,
+        pageFile: toPosixPath(path.relative(resolvedAppRoot, candidatePath)),
+        pageShape: candidatePage.pageShape,
+        visibleRouteSegments: ancestorRoute.visibleRouteSegments,
+        routeUrlSuffix: buildRouteUrlSuffixFromVisibleSegments(ancestorRoute.visibleRouteSegments)
+      });
+    }
+  }
+
+  return null;
+}
+
+function normalizePlacementTargetId(target = {}) {
+  const host = normalizeText(target?.host);
+  const position = normalizeText(target?.position);
+  if (!host || !position) {
+    return "";
+  }
+  return normalizeShellOutletTargetId(`${host}:${position}`);
+}
+
+function resolveRelativeLinkToFromParent(pageTarget = {}, parentHost = null) {
+  const childSegments = Array.isArray(pageTarget?.visibleRouteSegments) ? pageTarget.visibleRouteSegments : [];
+  const parentSegments = Array.isArray(parentHost?.visibleRouteSegments) ? parentHost.visibleRouteSegments : [];
+  if (parentSegments.length < 1 || childSegments.length <= parentSegments.length) {
+    return "";
+  }
+
+  const relativeSegments = childSegments.slice(parentSegments.length);
+  if (relativeSegments.length < 1) {
+    return "";
+  }
+
+  return `./${relativeSegments.join("/")}`;
+}
+
+function resolveRelativeLinkToFromNearestIndexOwner(pageTarget = {}) {
+  const routeSegments = Array.isArray(pageTarget?.routeSegments) ? pageTarget.routeSegments : [];
+  const deepestIndexOwnerIndex = routeSegments.findLastIndex((segment) => isIndexRouteSegment(segment));
+  if (deepestIndexOwnerIndex < 0 || deepestIndexOwnerIndex >= routeSegments.length - 1) {
+    return "";
+  }
+
+  const relativeSegments = routeSegments
+    .slice(deepestIndexOwnerIndex + 1)
+    .filter((segment) => !isPathlessRouteSegment(segment));
+  if (relativeSegments.length < 1) {
+    return "";
+  }
+
+  return `./${relativeSegments.join("/")}`;
+}
+
+function resolveInferredPageLinkTo({
+  explicitLinkTo = "",
+  pageTarget = {},
+  parentHost = null,
+  placementTarget = null
+} = {}) {
+  const normalizedExplicitLinkTo = normalizeText(explicitLinkTo);
+  if (normalizedExplicitLinkTo) {
+    return normalizedExplicitLinkTo;
+  }
+
+  const parentTargetId = normalizePlacementTargetId(parentHost);
+  const placementTargetId = normalizePlacementTargetId(placementTarget);
+  if (parentTargetId && parentTargetId === placementTargetId) {
+    const inferredLinkTo = resolveRelativeLinkToFromParent(pageTarget, parentHost);
+    if (inferredLinkTo) {
+      return inferredLinkTo;
+    }
+  }
+
+  if (normalizeText(parentHost?.pageShape) === "index") {
+    const inferredLinkTo = resolveRelativeLinkToFromParent(pageTarget, parentHost);
+    if (inferredLinkTo) {
+      return inferredLinkTo;
+    }
+  }
+
+  const inferredLinkTo = resolveRelativeLinkToFromNearestIndexOwner(pageTarget);
+  if (inferredLinkTo) {
+    return inferredLinkTo;
+  }
+  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 parentTargetId = normalizePlacementTargetId(parentHost);
+  const placementTargetId = normalizePlacementTargetId(placementTarget);
+  if (parentTargetId && parentTargetId === placementTargetId) {
+    return normalizeText(subpageComponentToken) || DEFAULT_SUBPAGE_LINK_COMPONENT_TOKEN;
+  }
+
+  return normalizeText(defaultComponentToken) || DEFAULT_PAGE_LINK_COMPONENT_TOKEN;
+}
+
+async function resolvePageLinkTargetDetails({
+  appRoot,
+  targetFile = "",
+  pageTarget = null,
+  placement = "",
+  componentToken = "",
+  linkTo = "",
+  defaultComponentToken = DEFAULT_PAGE_LINK_COMPONENT_TOKEN,
+  subpageComponentToken = DEFAULT_SUBPAGE_LINK_COMPONENT_TOKEN,
+  context = "page target"
+} = {}) {
+  const resolvedPageTarget = pageTarget || await resolvePageTargetDetails({
+    appRoot,
+    targetFile,
+    context
+  });
+  const parentHost = await resolveNearestParentSubpagesHost({
+    appRoot: resolvedPageTarget.appRoot,
+    pageTarget: resolvedPageTarget,
+    context
+  });
+  const placementTarget = await resolveShellOutletPlacementTargetFromApp({
+    appRoot: resolvedPageTarget.appRoot,
+    context,
+    placement: normalizeText(placement) || parentHost?.id || ""
+  });
+
+  return Object.freeze({
+    pageTarget: resolvedPageTarget,
+    parentHost,
+    placementTarget,
+    componentToken: resolveInferredPageLinkComponentToken({
+      explicitComponentToken: componentToken,
+      parentHost,
+      placementTarget,
+      defaultComponentToken,
+      subpageComponentToken
+    }),
+    linkTo: resolveInferredPageLinkTo({
+      explicitLinkTo: linkTo,
+      pageTarget: resolvedPageTarget,
+      parentHost,
+      placementTarget
+    })
+  });
+}
+
+export {
+  DEFAULT_PAGE_LINK_COMPONENT_TOKEN,
+  DEFAULT_SUBPAGE_LINK_COMPONENT_TOKEN,
+  normalizePagesRelativeTargetFile,
+  normalizePagesRelativeTargetRoot,
+  resolvePageTargetDetails,
+  deriveDefaultSubpagesHost,
+  resolveNearestParentSubpagesHost,
+  resolvePageLinkTargetDetails
+};

package/server/support/pageTargets.test.js

@@ -0,0 +1,326 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+import {
+  deriveDefaultSubpagesHost,
+  normalizePagesRelativeTargetRoot,
+  resolvePageLinkTargetDetails,
+  resolvePageTargetDetails
+} from "./pageTargets.js";
+
+async function withTempApp(run) {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "kernel-page-targets-"));
+  try {
+    return await run(appRoot);
+  } finally {
+    await rm(appRoot, { recursive: true, force: true });
+  }
+}
+
+async function writeFileInApp(appRoot, relativePath, source) {
+  const absoluteFile = path.join(appRoot, relativePath);
+  await mkdir(path.dirname(absoluteFile), { recursive: true });
+  await writeFile(absoluteFile, source, "utf8");
+}
+
+async function writeConfig(appRoot, source) {
+  await writeFileInApp(appRoot, "config/public.js", source);
+}
+
+async function writeShellLayout(appRoot, source = "") {
+  await writeFileInApp(
+    appRoot,
+    "src/components/ShellLayout.vue",
+    source ||
+      `<template>
+  <div>
+    <ShellOutlet host="shell-layout" position="top-right" />
+    <ShellOutlet host="shell-layout" position="primary-menu" default />
+  </div>
+</template>
+`
+  );
+}
+
+test("resolvePageTargetDetails derives the surface and route data from an explicit page file", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "w/[workspaceSlug]/admin", enabled: true }
+  }
+};
+`
+    );
+
+    const pageTarget = await resolvePageTargetDetails({
+      appRoot,
+      targetFile: "w/[workspaceSlug]/admin/catalog/index/products/index.vue",
+      context: "page target"
+    });
+
+    assert.equal(pageTarget.surfaceId, "admin");
+    assert.equal(pageTarget.surfacePagesRoot, "w/[workspaceSlug]/admin");
+    assert.equal(pageTarget.routeUrlSuffix, "/catalog/products");
+    assert.equal(pageTarget.placementId, "ui-generator.page.admin.catalog.products.link");
+    assert.deepEqual(pageTarget.visibleRouteSegments, ["catalog", "products"]);
+    assert.equal(deriveDefaultSubpagesHost(pageTarget), "catalog-products");
+  });
+});
+
+test("resolvePageTargetDetails includes surface in placement ids for identical routes on different surfaces", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    app: { id: "app", pagesRoot: "app", enabled: true },
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+
+    const appPageTarget = await resolvePageTargetDetails({
+      appRoot,
+      targetFile: "app/reports/index.vue",
+      context: "page target"
+    });
+    const adminPageTarget = await resolvePageTargetDetails({
+      appRoot,
+      targetFile: "admin/reports/index.vue",
+      context: "page target"
+    });
+
+    assert.equal(appPageTarget.placementId, "ui-generator.page.app.reports.link");
+    assert.equal(adminPageTarget.placementId, "ui-generator.page.admin.reports.link");
+    assert.notEqual(appPageTarget.placementId, adminPageTarget.placementId);
+  });
+});
+
+test("resolvePageTargetDetails chooses the most specific matching surface pagesRoot", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    app: { id: "app", pagesRoot: "w/[workspaceSlug]", enabled: true },
+    admin: { id: "admin", pagesRoot: "w/[workspaceSlug]/admin", enabled: true }
+  }
+};
+`
+    );
+
+    const pageTarget = await resolvePageTargetDetails({
+      appRoot,
+      targetFile: "w/[workspaceSlug]/admin/catalog/index.vue",
+      context: "page target"
+    });
+
+    assert.equal(pageTarget.surfaceId, "admin");
+    assert.equal(pageTarget.surfacePagesRoot, "w/[workspaceSlug]/admin");
+    assert.equal(pageTarget.surfaceRelativeFilePath, "catalog/index.vue");
+    assert.equal(pageTarget.routeUrlSuffix, "/catalog");
+    assert.equal(pageTarget.placementId, "ui-generator.page.admin.catalog.link");
+  });
+});
+
+test("resolvePageTargetDetails rejects duplicate matching surface pagesRoot definitions", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    adminA: { id: "admin-a", pagesRoot: "w/[workspaceSlug]/admin", enabled: true },
+    adminB: { id: "admin-b", pagesRoot: "w/[workspaceSlug]/admin", enabled: true }
+  }
+};
+`
+    );
+
+    await assert.rejects(
+      () =>
+        resolvePageTargetDetails({
+          appRoot,
+          targetFile: "w/[workspaceSlug]/admin/catalog/index.vue",
+          context: "page target"
+        }),
+      /multiple surfaces share pagesRoot "w\/\[workspaceSlug\]\/admin" \(admin-a, admin-b\)/
+    );
+  });
+});
+
+test("resolvePageTargetDetails rejects target files with a src/pages prefix", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+
+    await assert.rejects(
+      () =>
+        resolvePageTargetDetails({
+          appRoot,
+          targetFile: "src/pages/admin/reports/index.vue",
+          context: "page target"
+        }),
+      /must be relative to src\/pages\/, without the src\/pages\/ prefix/
+    );
+  });
+});
+
+test("normalizePagesRelativeTargetRoot rejects route roots with a src/pages prefix", () => {
+  assert.throws(
+    () =>
+      normalizePagesRelativeTargetRoot("src/pages/admin/customers", {
+        context: "crud-ui-generator",
+        label: 'option "target-root"'
+      }),
+    /must be relative to src\/pages\/, without the src\/pages\/ prefix/
+  );
+});
+
+test("resolvePageLinkTargetDetails falls back to the app default placement target", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+
+    const details = await resolvePageLinkTargetDetails({
+      appRoot,
+      targetFile: "admin/reports/index.vue",
+      context: "page target"
+    });
+
+    assert.equal(details.pageTarget.surfaceId, "admin");
+    assert.equal(details.placementTarget.host, "shell-layout");
+    assert.equal(details.placementTarget.position, "primary-menu");
+    assert.equal(details.componentToken, "users.web.shell.surface-aware-menu-link-item");
+    assert.equal(details.linkTo, "");
+  });
+});
+
+test("resolvePageLinkTargetDetails inherits a file-route parent subpages host", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+    await writeFileInApp(
+      appRoot,
+      "src/pages/admin/contacts/[contactId].vue",
+      `<template>
+  <SectionContainerShell>
+    <template #tabs>
+      <ShellOutlet host="contact-view" position="sub-pages" />
+    </template>
+    <RouterView />
+  </SectionContainerShell>
+</template>
+`
+    );
+
+    const details = await resolvePageLinkTargetDetails({
+      appRoot,
+      targetFile: "admin/contacts/[contactId]/notes/index.vue",
+      context: "page target"
+    });
+
+    assert.equal(details.parentHost?.id, "contact-view:sub-pages");
+    assert.equal(details.placementTarget.host, "contact-view");
+    assert.equal(details.placementTarget.position, "sub-pages");
+    assert.equal(details.componentToken, "local.main.ui.tab-link-item");
+    assert.equal(details.linkTo, "./notes");
+  });
+});
+
+test("resolvePageLinkTargetDetails honors explicit placement and link overrides", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+
+    const details = await resolvePageLinkTargetDetails({
+      appRoot,
+      targetFile: "admin/contacts/[contactId]/index/notes/index.vue",
+      placement: "shell-layout:top-right",
+      componentToken: "custom.link-item",
+      linkTo: "./assistant-notes",
+      context: "page target"
+    });
+
+    assert.equal(details.placementTarget.host, "shell-layout");
+    assert.equal(details.placementTarget.position, "top-right");
+    assert.equal(details.componentToken, "custom.link-item");
+    assert.equal(details.linkTo, "./assistant-notes");
+  });
+});
+
+test("resolvePageLinkTargetDetails inherits an index-route parent subpages host for index children", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    admin: { id: "admin", pagesRoot: "admin", enabled: true }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+    await writeFileInApp(
+      appRoot,
+      "src/pages/admin/customers/[customerId]/index.vue",
+      `<template>
+  <SectionContainerShell>
+    <template #tabs>
+      <ShellOutlet host="customer-view" position="sub-pages" />
+    </template>
+    <RouterView />
+  </SectionContainerShell>
+</template>
+`
+    );
+
+    const details = await resolvePageLinkTargetDetails({
+      appRoot,
+      targetFile: "admin/customers/[customerId]/index/pets/index.vue",
+      context: "page target"
+    });
+
+    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.host, "customer-view");
+    assert.equal(details.placementTarget.position, "sub-pages");
+    assert.equal(details.componentToken, "local.main.ui.tab-link-item");
+    assert.equal(details.linkTo, "./pets");
+  });
+});