@jskit-ai/kernel 0.1.33 → 0.1.35

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "type": "module",
   "dependencies": {
     "typebox": "^1.0.81"
@@ -37,6 +37,7 @@
     "./shared/support/crudLookup": "./shared/support/crudLookup.js",
     "./shared/support/deepFreeze": "./shared/support/deepFreeze.js",
     "./shared/support/listenerSet": "./shared/support/listenerSet.js",
+    "./shared/support/shellLayoutTargets": "./shared/support/shellLayoutTargets.js",
     "./shared/support/providerLogger": "./shared/support/providerLogger.js",
     "./shared/support/returnToPath": "./shared/support/returnToPath.js",
     "./shared/support/visibility": "./shared/support/visibility.js",

package/server/support/importFreshModuleFromAbsolutePath.js

@@ -0,0 +1,23 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+let freshImportCounter = 0;
+
+function nextFreshImportToken() {
+  freshImportCounter += 1;
+  return String(freshImportCounter);
+}
+
+async function importFreshModuleFromAbsolutePath(absolutePath) {
+  const normalizedPath = String(absolutePath || "").trim();
+  if (!normalizedPath || !path.isAbsolute(normalizedPath)) {
+    throw new Error("importFreshModuleFromAbsolutePath requires an absolute path.");
+  }
+
+  const resolvedPath = path.resolve(normalizedPath);
+  const moduleUrl = pathToFileURL(resolvedPath);
+  moduleUrl.searchParams.set("jskit_fresh", nextFreshImportToken());
+  return import(moduleUrl.href);
+}
+
+export { importFreshModuleFromAbsolutePath };

package/server/support/importFreshModuleFromAbsolutePath.test.js

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import { mkdtemp, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+import { importFreshModuleFromAbsolutePath } from "./importFreshModuleFromAbsolutePath.js";
+
+test("importFreshModuleFromAbsolutePath requires an absolute path", async () => {
+  await assert.rejects(
+    () => importFreshModuleFromAbsolutePath("relative/module.js"),
+    /requires an absolute path/
+  );
+});
+
+test("importFreshModuleFromAbsolutePath re-evaluates a module on each call", async () => {
+  const tempRoot = await mkdtemp(path.join(tmpdir(), "jskit-import-fresh-module-"));
+  const modulePath = path.join(tempRoot, "counter.mjs");
+  const counterKey = "__jskitKernelImportFreshCounter";
+  delete globalThis[counterKey];
+
+  await writeFile(
+    modulePath,
+    `globalThis.${counterKey} = Number(globalThis.${counterKey} || 0) + 1;
+export const loadCount = globalThis.${counterKey};
+`,
+    "utf8"
+  );
+
+  const first = await importFreshModuleFromAbsolutePath(modulePath);
+  const second = await importFreshModuleFromAbsolutePath(modulePath);
+
+  assert.equal(first.loadCount, 1);
+  assert.equal(second.loadCount, 2);
+
+  delete globalThis[counterKey];
+});

package/server/support/index.js

@@ -1,6 +1,7 @@
 export { symlinkSafeRequire } from "./symlinkSafeRequire.js";
 export { resolveAppConfig } from "./appConfig.js";
 export { loadAppConfigFromModuleUrl } from "./appConfigFiles.js";
+export { importFreshModuleFromAbsolutePath } from "./importFreshModuleFromAbsolutePath.js";
 export { resolveRequiredAppRoot, toPosixPath } from "./path.js";
 export {
   DEFAULT_PAGE_LINK_COMPONENT_TOKEN,

package/server/support/pageTargets.js

@@ -16,8 +16,9 @@ import {
 } from "../../shared/support/shellLayoutTargets.js";
 import { resolveShellOutletPlacementTargetFromApp } from "./shellOutlets.js";
 import { resolveRequiredAppRoot, toPosixPath } from "./path.js";
+import { loadAppConfigFromModuleUrl } from "./appConfigFiles.js";
 
-const DEFAULT_PAGE_LINK_COMPONENT_TOKEN = "users.web.shell.surface-aware-menu-link-item";
+const DEFAULT_PAGE_LINK_COMPONENT_TOKEN = "local.main.ui.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;
@@ -64,17 +65,17 @@ function resolvePagesRelativeAppPath(
   if (isAbsolutePathInput(normalizedValue)) {
     throw new Error(`${context} ${label} must be relative to src/pages/: ${normalizedValue}.`);
   }
-  if (
-    normalizedValue === "src/pages" ||
-    normalizedValue.startsWith(PAGE_ROOT_PREFIX)
-  ) {
+  if (normalizedValue === "src/pages" || normalizedValue === PAGE_ROOT_PREFIX) {
     throw new Error(
-      `${context} ${label} must be relative to src/pages/, without the src/pages/ prefix: ${normalizedValue}.`
+      `${context} ${label} must include a path under src/pages/: ${normalizedValue}.`
     );
   }
+  if (normalizedValue.startsWith(PAGE_ROOT_PREFIX)) {
+    return normalizedValue;
+  }
   if (normalizedValue.startsWith("src/")) {
     throw new Error(
-      `${context} ${label} must be relative to src/pages/, without a leading src/ segment: ${normalizedValue}.`
+      `${context} ${label} must be relative to src/pages/ or start with src/pages/: ${normalizedValue}.`
     );
   }
 
@@ -174,38 +175,46 @@ function humanizePageSegment(value = "", fallback = "Page") {
 
 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);
+    const config = normalizeObject(
+      await loadAppConfigFromModuleUrl({
+        moduleUrl: pathToFileURL(path.join(resolvedAppRoot, "config", "public.js")).href
+      })
+    );
+    if (Object.keys(config).length < 1) {
+      throw new Error("requires exported config in config/public.js.");
+    }
+    return config;
   } 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.`);
+function normalizeSurfaceAccessPolicyId(value = "") {
+  return normalizeText(value).toLowerCase();
+}
+
+function resolveSurfaceRequiresAuth(surfaceDefinition = {}, surfaceAccessPolicies = {}) {
+  const normalizedDefinition = normalizeObject(surfaceDefinition);
+  const normalizedPolicies = normalizeObject(surfaceAccessPolicies);
+  const accessPolicyId = normalizeSurfaceAccessPolicyId(normalizedDefinition.accessPolicyId);
+  const configuredPolicy = accessPolicyId
+    ? normalizeObject(normalizedPolicies[accessPolicyId])
+    : {};
+
+  if (Object.hasOwn(configuredPolicy, "requireAuth")) {
+    return configuredPolicy.requireAuth === true;
   }
 
-  return config;
+  return normalizedDefinition.requiresAuth === true;
 }
 
 async function listSurfacePageRoots(appRoot = "", { context = "page target" } = {}) {
   const config = await loadPublicConfig(appRoot, { context });
   const surfaceDefinitions = normalizeObject(config.surfaceDefinitions);
+  const surfaceAccessPolicies = normalizeObject(config.surfaceAccessPolicies);
 
   return Object.freeze(
     Object.entries(surfaceDefinitions)
@@ -218,7 +227,8 @@ async function listSurfacePageRoots(appRoot = "", { context = "page target" } =
 
         return Object.freeze({
           id: surfaceId,
-          pagesRoot: normalizeSurfacePagesRoot(definition.pagesRoot)
+          pagesRoot: normalizeSurfacePagesRoot(definition.pagesRoot),
+          requiresAuth: resolveSurfaceRequiresAuth(definition, surfaceAccessPolicies)
         });
       })
       .filter(Boolean)
@@ -239,6 +249,7 @@ function deriveSurfaceMatchesFromPageFile(relativePath = "", surfacePageRoots =
         return Object.freeze({
           surfaceId: normalizeSurfaceId(surface?.id),
           pagesRoot,
+          requiresAuth: surface?.requiresAuth === true,
           surfaceRelativeFilePath: pagePathWithinPagesRoot
         });
       }
@@ -251,6 +262,7 @@ function deriveSurfaceMatchesFromPageFile(relativePath = "", surfacePageRoots =
       return Object.freeze({
         surfaceId: normalizeSurfaceId(surface?.id),
         pagesRoot,
+        requiresAuth: surface?.requiresAuth === true,
         surfaceRelativeFilePath: pagePathWithinPagesRoot.slice(requiredPrefix.length)
       });
     })
@@ -433,9 +445,7 @@ function resolveSubpagesHostTargetFromPageSource(source = "") {
   }
 
   return Object.freeze({
-    id: target.id,
-    host: target.host,
-    position: target.position
+    id: target.id
   });
 }
 
@@ -468,6 +478,7 @@ async function resolvePageTargetDetails({
     }),
     surfaceId: surfaceMatch.surfaceId,
     surfacePagesRoot: surfaceMatch.pagesRoot,
+    surfaceRequiresAuth: surfaceMatch.requiresAuth === true,
     surfaceRelativeFilePath: surfaceMatch.surfaceRelativeFilePath,
     ...routeInfo
   });
@@ -530,12 +541,7 @@ async function resolveNearestParentSubpagesHost({
 }
 
 function normalizePlacementTargetId(target = {}) {
-  const host = normalizeText(target?.host);
-  const position = normalizeText(target?.position);
-  if (!host || !position) {
-    return "";
-  }
-  return normalizeShellOutletTargetId(`${host}:${position}`);
+  return normalizeShellOutletTargetId(target?.id || target?.target || target);
 }
 
 function resolveRelativeLinkToFromParent(pageTarget = {}, parentHost = null) {
@@ -616,6 +622,11 @@ function resolveInferredPageLinkComponentToken({
     return normalizedExplicitToken;
   }
 
+  const normalizedPlacementTargetDefaultToken = normalizeText(placementTarget?.defaultLinkComponentToken);
+  if (normalizedPlacementTargetDefaultToken) {
+    return normalizedPlacementTargetDefaultToken;
+  }
+
   const parentTargetId = normalizePlacementTargetId(parentHost);
   const placementTargetId = normalizePlacementTargetId(placementTarget);
   if (parentTargetId && parentTargetId === placementTargetId) {
@@ -625,6 +636,14 @@ function resolveInferredPageLinkComponentToken({
   return normalizeText(defaultComponentToken) || DEFAULT_PAGE_LINK_COMPONENT_TOKEN;
 }
 
+function renderPageLinkWhenLine(pageTarget = {}) {
+  if (pageTarget?.surfaceRequiresAuth !== true) {
+    return "";
+  }
+
+  return "    when: ({ auth }) => Boolean(auth?.authenticated)\n";
+}
+
 async function resolvePageLinkTargetDetails({
   appRoot,
   targetFile = "",
@@ -663,6 +682,7 @@ async function resolvePageLinkTargetDetails({
       defaultComponentToken,
       subpageComponentToken
     }),
+    whenLine: renderPageLinkWhenLine(resolvedPageTarget),
     linkTo: resolveInferredPageLinkTo({
       explicitLinkTo: linkTo,
       pageTarget: resolvedPageTarget,

package/server/support/pageTargets.test.js

@@ -36,8 +36,12 @@ async function writeShellLayout(appRoot, source = "") {
     source ||
       `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="top-right" />
-    <ShellOutlet host="shell-layout" position="primary-menu" default />
+    <ShellOutlet target="shell-layout:top-right" />
+    <ShellOutlet
+      target="shell-layout:primary-menu"
+      default
+      default-link-component-token="local.main.ui.surface-aware-menu-link-item"
+    />
   </div>
 </template>
 `
@@ -128,6 +132,41 @@ test("resolvePageTargetDetails chooses the most specific matching surface pagesR
   });
 });
 
+test("resolvePageTargetDetails derives surface auth requirement from surface access policy", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceAccessPolicies: {
+    public: {},
+    authenticated: {
+      requireAuth: true
+    }
+  },
+  surfaceDefinitions: {
+    home: { id: "home", pagesRoot: "home", enabled: true, accessPolicyId: "public" },
+    app: { id: "app", pagesRoot: "app", enabled: true, accessPolicyId: "authenticated" }
+  }
+};
+`
+    );
+
+    const publicPageTarget = await resolvePageTargetDetails({
+      appRoot,
+      targetFile: "home/index.vue",
+      context: "page target"
+    });
+    const authenticatedPageTarget = await resolvePageTargetDetails({
+      appRoot,
+      targetFile: "app/index.vue",
+      context: "page target"
+    });
+
+    assert.equal(publicPageTarget.surfaceRequiresAuth, false);
+    assert.equal(authenticatedPageTarget.surfaceRequiresAuth, true);
+  });
+});
+
 test("resolvePageTargetDetails rejects duplicate matching surface pagesRoot definitions", async () => {
   await withTempApp(async (appRoot) => {
     await writeConfig(
@@ -153,7 +192,7 @@ test("resolvePageTargetDetails rejects duplicate matching surface pagesRoot defi
   });
 });
 
-test("resolvePageTargetDetails rejects target files with a src/pages prefix", async () => {
+test("resolvePageTargetDetails accepts target files with a src/pages prefix", async () => {
   await withTempApp(async (appRoot) => {
     await writeConfig(
       appRoot,
@@ -165,26 +204,25 @@ test("resolvePageTargetDetails rejects target files with a src/pages prefix", as
 `
     );
 
-    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/
-    );
+    const details = await resolvePageTargetDetails({
+      appRoot,
+      targetFile: "src/pages/admin/reports/index.vue",
+      context: "page target"
+    });
+
+    assert.equal(details.targetFilePath.relativePath, "src/pages/admin/reports/index.vue");
+    assert.equal(details.surfaceId, "admin");
+    assert.equal(details.routeUrlSuffix, "/reports");
   });
 });
 
-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("normalizePagesRelativeTargetRoot accepts route roots with a src/pages prefix", () => {
+  assert.equal(
+    normalizePagesRelativeTargetRoot("src/pages/admin/customers", {
+      context: "crud-ui-generator",
+      label: 'option "target-root"'
+    }),
+    "src/pages/admin/customers"
   );
 });
 
@@ -208,10 +246,77 @@ test("resolvePageLinkTargetDetails falls back to the app default placement targe
     });
 
     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.placementTarget.id, "shell-layout:primary-menu");
+    assert.equal(details.componentToken, "local.main.ui.surface-aware-menu-link-item");
     assert.equal(details.linkTo, "");
+    assert.equal(details.whenLine, "");
+  });
+});
+
+test("resolvePageLinkTargetDetails emits an auth guard when the surface policy requires auth", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceAccessPolicies: {
+    authenticated: {
+      requireAuth: true
+    }
+  },
+  surfaceDefinitions: {
+    app: { id: "app", pagesRoot: "app", enabled: true, accessPolicyId: "authenticated" }
+  }
+};
+`
+    );
+    await writeShellLayout(appRoot);
+
+    const details = await resolvePageLinkTargetDetails({
+      appRoot,
+      targetFile: "app/reports/index.vue",
+      context: "page target"
+    });
+
+    assert.equal(details.whenLine, "    when: ({ auth }) => Boolean(auth?.authenticated)\n");
+  });
+});
+
+test("resolvePageLinkTargetDetails prefers an outlet-declared default link token over subpage heuristics", async () => {
+  await withTempApp(async (appRoot) => {
+    await writeConfig(
+      appRoot,
+      `export const config = {
+  surfaceDefinitions: {
+    home: { id: "home", pagesRoot: "home", enabled: true }
+  }
+};
+`
+    );
+    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"
+    />
+    <RouterView />
+  </section>
+</template>
+`
+    );
+
+    const details = await resolvePageLinkTargetDetails({
+      appRoot,
+      targetFile: "home/settings/pollen-types/index.vue",
+      context: "page target"
+    });
+
+    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.linkTo, "./pollen-types");
   });
 });
 
@@ -233,7 +338,7 @@ test("resolvePageLinkTargetDetails inherits a file-route parent subpages host",
       `<template>
   <SectionContainerShell>
     <template #tabs>
-      <ShellOutlet host="contact-view" position="sub-pages" />
+      <ShellOutlet target="contact-view:sub-pages" />
     </template>
     <RouterView />
   </SectionContainerShell>
@@ -248,8 +353,7 @@ test("resolvePageLinkTargetDetails inherits a file-route parent subpages host",
     });
 
     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.placementTarget.id, "contact-view:sub-pages");
     assert.equal(details.componentToken, "local.main.ui.tab-link-item");
     assert.equal(details.linkTo, "./notes");
   });
@@ -277,8 +381,7 @@ test("resolvePageLinkTargetDetails honors explicit placement and link overrides"
       context: "page target"
     });
 
-    assert.equal(details.placementTarget.host, "shell-layout");
-    assert.equal(details.placementTarget.position, "top-right");
+    assert.equal(details.placementTarget.id, "shell-layout:top-right");
     assert.equal(details.componentToken, "custom.link-item");
     assert.equal(details.linkTo, "./assistant-notes");
   });
@@ -302,7 +405,7 @@ test("resolvePageLinkTargetDetails inherits an index-route parent subpages host
       `<template>
   <SectionContainerShell>
     <template #tabs>
-      <ShellOutlet host="customer-view" position="sub-pages" />
+      <ShellOutlet target="customer-view:sub-pages" />
     </template>
     <RouterView />
   </SectionContainerShell>
@@ -318,8 +421,7 @@ 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.host, "customer-view");
-    assert.equal(details.placementTarget.position, "sub-pages");
+    assert.equal(details.placementTarget.id, "customer-view:sub-pages");
     assert.equal(details.componentToken, "local.main.ui.tab-link-item");
     assert.equal(details.linkTo, "./pets");
   });

package/server/support/shellOutlets.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { readdir, readFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
 import { loadInstalledPackageDescriptor } from "../../internal/node/installedPackageDescriptor.js";
 import { normalizeObject, normalizeText } from "../../shared/support/normalize.js";
 import { resolveRequiredAppRoot, toPosixPath } from "./path.js";
@@ -7,8 +8,10 @@ import {
   describeShellOutletTargets,
   discoverShellOutletTargetsFromVueSource,
   findShellOutletTargetById,
-  normalizeShellOutletTargetId
+  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";
@@ -52,22 +55,15 @@ function normalizeAppRouteOutletTarget({
   outlet = {},
   sourcePath = ""
 } = {}) {
-  const outletRecord = normalizeObject(outlet);
-  const outletTargetId = normalizeShellOutletTargetId(
-    `${normalizeText(outletRecord.host)}:${normalizeText(outletRecord.position)}`
-  );
-  if (!outletTargetId) {
+  const normalizedTarget = normalizeShellOutletTargetRecord(outlet, {
+    context: sourcePath || "route meta"
+  });
+  if (!normalizedTarget) {
     return null;
   }
-
-  const separatorIndex = outletTargetId.indexOf(":");
-  const host = outletTargetId.slice(0, separatorIndex);
-  const position = outletTargetId.slice(separatorIndex + 1);
   return Object.freeze({
-    id: outletTargetId,
-    host,
-    position,
-    default: isDefaultEnabled(outletRecord.default),
+    ...normalizedTarget,
+    default: isDefaultEnabled(normalizedTarget.default),
     sourcePath
   });
 }
@@ -201,32 +197,67 @@ function normalizePackageOutletTarget({
     return null;
   }
 
-  const outletRecord = normalizeObject(outlet);
-  const outletTargetId = normalizeShellOutletTargetId(
-    `${normalizeText(outletRecord.host)}:${normalizeText(outletRecord.position)}`
-  );
-  if (!outletTargetId) {
+  const normalizedTarget = normalizeShellOutletTargetRecord(outlet, {
+    context: `package:${normalizedPackageId}`
+  });
+  if (!normalizedTarget) {
     return null;
   }
 
-  const separatorIndex = outletTargetId.indexOf(":");
-  const host = outletTargetId.slice(0, separatorIndex);
-  const position = outletTargetId.slice(separatorIndex + 1);
+  const outletRecord = normalizeObject(outlet);
   const source = normalizeText(outletRecord.source);
   const sourcePath = source
     ? `package:${normalizedPackageId}:${toPosixPath(source)}`
     : `package:${normalizedPackageId}${descriptorPath ? `:${toPosixPath(descriptorPath)}` : ""}`;
 
   return Object.freeze({
-    id: outletTargetId,
-    host,
-    position,
+    ...normalizedTarget,
     default: false,
     sourcePath,
     sourcePackageId: normalizedPackageId
   });
 }
 
+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));
@@ -263,6 +294,7 @@ 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();
@@ -331,10 +363,10 @@ async function discoverShellOutletTargetsFromApp({ appRoot, sourceRoot = "src" }
 
   const targets = [...targetById.values()].sort((left, right) => left.id.localeCompare(right.id));
   const normalizedTargets = targets.map((target) =>
-    Object.freeze({
+    applyOutletDefaultOverrides({
       ...target,
       default: target.id === defaultTargetId
-    })
+    }, outletDefaultOverrides)
   );
 
   return Object.freeze({
@@ -348,7 +380,7 @@ async function resolveShellOutletPlacementTargetFromApp({ appRoot, placement = "
   const requestedPlacementOption = normalizeText(placement);
   const requestedPlacementTargetId = normalizeShellOutletTargetId(requestedPlacementOption);
   if (requestedPlacementOption && !requestedPlacementTargetId) {
-    throw new Error(`${resolvedContext} option "placement" must be in "host:position" format.`);
+    throw new Error(`${resolvedContext} option "placement" must be a target in "host:position" format.`);
   }
 
   const discovered = await discoverShellOutletTargetsFromApp({ appRoot, sourceRoot: "src" });
@@ -380,8 +412,8 @@ async function resolveShellOutletPlacementTargetFromApp({ appRoot, placement = "
   const availableTargets = describeShellOutletTargets(targets);
   throw new Error(
     `${resolvedContext} could not resolve a default ShellOutlet target from app Vue outlets. ` +
-    `Set one outlet as default (e.g. <ShellOutlet host="shell-layout" position="primary-menu" default />) ` +
-    `or pass "--placement host:position". Available targets: ${availableTargets || "<none>"}.`
+    `Set one outlet as default (e.g. <ShellOutlet target="shell-layout:primary-menu" default />) ` +
+    `or pass "--placement shell-layout:primary-menu". Available targets: ${availableTargets || "<none>"}.`
   );
 }
 

package/server/support/shellOutlets.test.js

@@ -30,8 +30,8 @@ test("resolveShellOutletPlacementTargetFromApp reads outlets across app Vue file
       "src/components/ShellLayout.vue",
       `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="primary-menu" />
-    <ShellOutlet host="shell-layout" position="top-right" />
+    <ShellOutlet target="shell-layout:primary-menu" />
+    <ShellOutlet target="shell-layout:top-right" />
   </div>
 </template>
 `
@@ -41,7 +41,7 @@ test("resolveShellOutletPlacementTargetFromApp reads outlets across app Vue file
       "src/pages/admin/workspace/settings/index.vue",
       `<template>
   <section>
-    <ShellOutlet host="admin-settings" position="forms" default />
+    <ShellOutlet target="admin-settings:forms" default />
   </section>
 </template>
 `
@@ -52,8 +52,7 @@ test("resolveShellOutletPlacementTargetFromApp reads outlets across app Vue file
       context: "ui-generator"
     });
 
-    assert.equal(target.host, "admin-settings");
-    assert.equal(target.position, "forms");
+    assert.equal(target.id, "admin-settings:forms");
   });
 });
 
@@ -64,7 +63,7 @@ test("discoverShellOutletTargetsFromApp includes installed package placement out
       "src/components/ShellLayout.vue",
       `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="primary-menu" default />
+    <ShellOutlet target="shell-layout:primary-menu" default />
   </div>
 </template>
 `
@@ -98,7 +97,11 @@ test("discoverShellOutletTargetsFromApp includes installed package placement out
     ui: {
       placements: {
         outlets: [
-          { host: "workspace-tools", position: "primary-menu", source: "src/client/components/UsersWorkspaceToolsWidget.vue" }
+          {
+            target: "workspace-tools:primary-menu",
+            defaultLinkComponentToken: "local.main.ui.surface-aware-menu-link-item",
+            source: "src/client/components/UsersWorkspaceToolsWidget.vue"
+          }
         ]
       }
     }
@@ -114,9 +117,8 @@ test("discoverShellOutletTargetsFromApp includes installed package placement out
     );
     assert.deepEqual(discovered.targets[1], {
       id: "workspace-tools:primary-menu",
-      host: "workspace-tools",
-      position: "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"
     });
@@ -130,6 +132,68 @@ 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: {
+      "workspace-tools: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: "workspace-tools: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(
@@ -137,7 +201,7 @@ test("discoverShellOutletTargetsFromApp returns targets with sourcePath and defa
       "src/components/ShellLayout.vue",
       `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="primary-menu" />
+    <ShellOutlet target="shell-layout:primary-menu" />
   </div>
 </template>
 `
@@ -147,7 +211,7 @@ test("discoverShellOutletTargetsFromApp returns targets with sourcePath and defa
       "src/pages/admin/toolbox/index.vue",
       `<template>
   <section>
-    <ShellOutlet host="admin-toolbox" position="widgets" default />
+    <ShellOutlet target="admin-toolbox:widgets" default />
   </section>
 </template>
 `
@@ -158,16 +222,14 @@ test("discoverShellOutletTargetsFromApp returns targets with sourcePath and defa
     assert.deepEqual(discovered.targets, [
       {
         id: "admin-toolbox:widgets",
-        host: "admin-toolbox",
-        position: "widgets",
         default: true,
+        defaultLinkComponentToken: "",
         sourcePath: "src/pages/admin/toolbox/index.vue"
       },
       {
         id: "shell-layout:primary-menu",
-        host: "shell-layout",
-        position: "primary-menu",
         default: false,
+        defaultLinkComponentToken: "",
         sourcePath: "src/components/ShellLayout.vue"
       }
     ]);
@@ -188,8 +250,7 @@ test("discoverShellOutletTargetsFromApp discovers route meta placement outlets",
       "placements": {
         "outlets": [
           {
-            "host": "contact-tools",
-            "position": "sub-pages"
+            "target": "contact-tools:sub-pages"
           }
         ]
       }
@@ -204,9 +265,8 @@ test("discoverShellOutletTargetsFromApp discovers route meta placement outlets",
     assert.deepEqual(discovered.targets, [
       {
         id: "contact-tools:sub-pages",
-        host: "contact-tools",
-        position: "sub-pages",
         default: false,
+        defaultLinkComponentToken: "",
         sourcePath: "src/pages/w/[workspaceSlug]/admin/contacts/[contactId]/contact-tools.vue"
       }
     ]);
@@ -227,8 +287,8 @@ test("resolveShellOutletPlacementTargetFromApp supports explicit placement overr
       "src/components/ShellLayout.vue",
       `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="primary-menu" default />
-    <ShellOutlet host="shell-layout" position="top-right" />
+    <ShellOutlet target="shell-layout:primary-menu" default />
+    <ShellOutlet target="shell-layout:top-right" />
   </div>
 </template>
 `
@@ -240,8 +300,7 @@ test("resolveShellOutletPlacementTargetFromApp supports explicit placement overr
       placement: "shell-layout:top-right"
     });
 
-    assert.equal(target.host, "shell-layout");
-    assert.equal(target.position, "top-right");
+    assert.equal(target.id, "shell-layout:top-right");
   });
 });
 
@@ -252,7 +311,7 @@ test("resolveShellOutletPlacementTargetFromApp validates placement format", asyn
       "src/components/ShellLayout.vue",
       `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="primary-menu" default />
+    <ShellOutlet target="shell-layout:primary-menu" default />
   </div>
 </template>
 `
@@ -265,7 +324,7 @@ test("resolveShellOutletPlacementTargetFromApp validates placement format", asyn
           context: "ui-generator",
           placement: "invalid-placement"
         }),
-      /option "placement" must be in "host:position" format/
+      /option "placement" must be a target in "host:position" format/
     );
   });
 });
@@ -277,7 +336,7 @@ test("resolveShellOutletPlacementTargetFromApp throws when multiple default outl
       "src/components/ShellLayout.vue",
       `<template>
   <div>
-    <ShellOutlet host="shell-layout" position="primary-menu" default />
+    <ShellOutlet target="shell-layout:primary-menu" default />
   </div>
 </template>
 `
@@ -287,7 +346,7 @@ test("resolveShellOutletPlacementTargetFromApp throws when multiple default outl
       "src/pages/admin/workspace/settings/index.vue",
       `<template>
   <section>
-    <ShellOutlet host="admin-settings" position="forms" default />
+    <ShellOutlet target="admin-settings:forms" default />
   </section>
 </template>
 `

package/shared/support/shellLayoutTargets.js

@@ -1,4 +1,7 @@
-import { normalizeText } from "./normalize.js";
+import {
+  normalizeObject,
+  normalizeText
+} from "./normalize.js";
 
 const SHELL_OUTLET_TAG_PATTERN = /<ShellOutlet\b([^>]*)\/?>/g;
 const ATTRIBUTE_PATTERN = /([:@]?[A-Za-z_][A-Za-z0-9_-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'))?/g;
@@ -40,6 +43,21 @@ function normalizeShellOutletTargetId(value = "") {
   return `${host}:${position}`;
 }
 
+function resolveShellOutletTargetParts(
+  {
+    target = ""
+  } = {}
+) {
+  const normalizedTargetId = normalizeShellOutletTargetId(target);
+  if (!normalizedTargetId) {
+    return null;
+  }
+
+  return Object.freeze({
+    id: normalizedTargetId
+  });
+}
+
 function findShellOutletTargetById(targets = [], targetId = "") {
   const entries = Array.isArray(targets) ? targets : [];
   const normalizedTargetId = normalizeShellOutletTargetId(targetId);
@@ -70,6 +88,42 @@ function isDefaultAttributeEnabled(value) {
   return normalized !== "false" && normalized !== "0" && normalized !== "no" && normalized !== "off";
 }
 
+function normalizeShellOutletTargetRecord(
+  value = {},
+  {
+    context = "shell layout"
+  } = {}
+) {
+  const record = normalizeObject(value);
+  const resolvedContext = normalizeText(context) || "shell layout";
+  if (Object.hasOwn(record, "host") || Object.hasOwn(record, "position")) {
+    throw new Error(
+      `${resolvedContext} must declare ShellOutlet targets with "target" only. ` +
+      `Legacy "host" and "position" attributes are not supported.`
+    );
+  }
+
+  const targetParts = resolveShellOutletTargetParts(
+    {
+      target: record.target
+    },
+    { context: resolvedContext }
+  );
+  if (!targetParts) {
+    return null;
+  }
+
+  return Object.freeze({
+    ...targetParts,
+    default:
+      Object.hasOwn(record, "default") &&
+      isDefaultAttributeEnabled(record.default),
+    defaultLinkComponentToken:
+      normalizeText(record.defaultLinkComponentToken) ||
+      normalizeText(record["default-link-component-token"])
+  });
+}
+
 function discoverShellOutletTargetsFromVueSource(source = "", { context = "shell layout" } = {}) {
   const sourceText = String(source || "");
   const resolvedContext = normalizeText(context) || "shell layout";
@@ -78,39 +132,26 @@ function discoverShellOutletTargetsFromVueSource(source = "", { context = "shell
 
   for (const tagMatch of sourceText.matchAll(SHELL_OUTLET_TAG_PATTERN)) {
     const attributes = parseTagAttributes(tagMatch[1]);
-    const host = normalizeText(attributes.host);
-    const position = normalizeText(attributes.position);
-    if (!host || !position) {
+    const normalizedTarget = normalizeShellOutletTargetRecord(attributes, {
+      context: resolvedContext
+    });
+    if (!normalizedTarget) {
       continue;
     }
-
-    const id = normalizeShellOutletTargetId(`${host}:${position}`);
-    if (!id) {
-      continue;
-    }
-    if (targetById.has(id)) {
-      throw new Error(`${resolvedContext} contains duplicate ShellOutlet target "${id}".`);
+    if (targetById.has(normalizedTarget.id)) {
+      throw new Error(`${resolvedContext} contains duplicate ShellOutlet target "${normalizedTarget.id}".`);
     }
 
-    const hasDefaultAttribute = Object.hasOwn(attributes, "default") && isDefaultAttributeEnabled(attributes.default);
-    if (hasDefaultAttribute) {
+    if (normalizedTarget.default) {
       if (defaultTargetId) {
         throw new Error(
-          `${resolvedContext} defines multiple default ShellOutlet targets: "${defaultTargetId}" and "${id}".`
+          `${resolvedContext} defines multiple default ShellOutlet targets: "${defaultTargetId}" and "${normalizedTarget.id}".`
         );
       }
-      defaultTargetId = id;
+      defaultTargetId = normalizedTarget.id;
     }
 
-    targetById.set(
-      id,
-      Object.freeze({
-        id,
-        host,
-        position,
-        default: hasDefaultAttribute
-      })
-    );
+    targetById.set(normalizedTarget.id, normalizedTarget);
   }
 
   return Object.freeze({
@@ -123,5 +164,7 @@ export {
   describeShellOutletTargets,
   discoverShellOutletTargetsFromVueSource,
   findShellOutletTargetById,
-  normalizeShellOutletTargetId
+  normalizeShellOutletTargetId,
+  normalizeShellOutletTargetRecord,
+  resolveShellOutletTargetParts
 };

package/shared/support/shellLayoutTargets.test.js

@@ -18,9 +18,13 @@ test("normalizeShellOutletTargetId validates host:position tokens", () => {
 test("discoverShellOutletTargetsFromVueSource resolves legal targets and one default", () => {
   const source = `
     <template>
-      <ShellOutlet host="shell-layout" position="top-left" />
-      <ShellOutlet host="shell-layout" position="primary-menu" default />
-      <ShellOutlet host="shell-layout" position="secondary-menu" />
+      <ShellOutlet target="shell-layout:top-left" />
+      <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>
   `;
 
@@ -33,6 +37,7 @@ 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"
@@ -46,8 +51,8 @@ test("discoverShellOutletTargetsFromVueSource resolves legal targets and one def
 test("discoverShellOutletTargetsFromVueSource throws for duplicate targets", () => {
   const source = `
     <template>
-      <ShellOutlet host="shell-layout" position="top-right" />
-      <ShellOutlet host="shell-layout" position="top-right" />
+      <ShellOutlet target="shell-layout:top-right" />
+      <ShellOutlet target="shell-layout:top-right" />
     </template>
   `;
 
@@ -60,8 +65,8 @@ test("discoverShellOutletTargetsFromVueSource throws for duplicate targets", ()
 test("discoverShellOutletTargetsFromVueSource throws for multiple defaults", () => {
   const source = `
     <template>
-      <ShellOutlet host="shell-layout" position="primary-menu" default />
-      <ShellOutlet host="shell-layout" position="secondary-menu" default />
+      <ShellOutlet target="shell-layout:primary-menu" default />
+      <ShellOutlet target="shell-layout:secondary-menu" default />
     </template>
   `;
 
@@ -74,11 +79,24 @@ test("discoverShellOutletTargetsFromVueSource throws for multiple defaults", ()
 test("discoverShellOutletTargetsFromVueSource ignores disabled default markers", () => {
   const source = `
     <template>
-      <ShellOutlet host="shell-layout" position="primary-menu" default="false" />
-      <ShellOutlet host="shell-layout" position="secondary-menu" />
+      <ShellOutlet target="shell-layout:primary-menu" default="false" />
+      <ShellOutlet target="shell-layout:secondary-menu" />
     </template>
   `;
 
   const discovered = discoverShellOutletTargetsFromVueSource(source, { context: "ShellLayout.vue" });
   assert.equal(discovered.defaultTargetId, "");
 });
+
+test("discoverShellOutletTargetsFromVueSource rejects legacy split outlet attributes", () => {
+  const source = `
+    <template>
+      <ShellOutlet target="shell-layout:primary-menu" host="other-host" position="primary-menu" />
+    </template>
+  `;
+
+  assert.throws(
+    () => discoverShellOutletTargetsFromVueSource(source, { context: "ShellLayout.vue" }),
+    /must declare ShellOutlet targets with "target" only/
+  );
+});

package/README.md

@@ -1,24 +0,0 @@
-# kernel
-
-Internal JSKIT framework runtime package.
-
-This package contains the merged runtime internals:
-- container
-- kernel
-- http fastify bridge
-- server runtime primitives
-- support primitives
-- surface routing primitives
-- platform runtime bootstrap
-
-## Historical note
-
-kernel was assembled moving code from these legacy packages and then deleting them:
-
-  - @jskit-ai/container-core
-  - @jskit-ai/http-fastify-core
-  - @jskit-ai/kernel
-  - @jskit-ai/platform-server-runtime
-  - @jskit-ai/server-runtime-core
-  - @jskit-ai/support-core
-  - @jskit-ai/surface-routing