@jskit-ai/kernel 0.1.244 → 0.1.246

package/client/appConfig.js

@@ -1,4 +1,5 @@
-import { isRecord, normalizeMobileConfig } from "../shared/support/normalize.js";
+import { isRecord } from "../shared/support/normalize.js";
+import { normalizeMobileConfig } from "../shared/support/mobileConfig.js";
 
 const CLIENT_APP_CONFIG_GLOBAL_KEY = "__JSKIT_CLIENT_APP_CONFIG__";
 const EMPTY_CLIENT_APP_CONFIG = Object.freeze({});

package/client/asyncModuleRecovery.js

@@ -1,3 +1,5 @@
+import { isRecord } from "../shared/support/normalize.js";
+
 const DYNAMIC_IMPORT_ERROR_PATTERNS = Object.freeze([
   /ChunkLoadError/iu,
   /Failed to fetch dynamically imported module/iu,
@@ -7,10 +9,6 @@ const DYNAMIC_IMPORT_ERROR_PATTERNS = Object.freeze([
   /Unable to preload CSS/iu
 ]);
 
-function isRecord(value) {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-
 function errorText(error = null) {
   return String(error?.message || error || "").trim();
 }

package/client/index.d.ts

@@ -6,100 +6,40 @@ export type ClientLogger = {
   isDebugEnabled?: boolean;
 };
 
-export type AsyncModuleRecoveryState = {
-  attempt: number;
-  error: any;
-  label: string;
-  message: string;
-  retry: (() => any) | null;
-  stale: boolean;
-  visible: boolean;
-};
-
-export function createAsyncModuleRecoveryState(options?: {
-  label?: string;
-  message?: string;
-  retry?: (() => any) | null;
-}): AsyncModuleRecoveryState;
-
-export function isDynamicImportError(error?: any): boolean;
-
-export function dynamicImportErrorMessage(error?: any, options?: {
-  label?: string;
-  stale?: boolean;
-}): string;
+export * from "./asyncModuleRecovery";
 
-export function notifyAsyncModuleLoadError(
-  state: AsyncModuleRecoveryState,
-  error?: any,
-  options?: {
-    label?: string;
-    message?: string;
-    retry?: (() => any) | null;
-    stale?: boolean;
-  }
-): AsyncModuleRecoveryState;
-
-export function dismissAsyncModuleRecovery(state: AsyncModuleRecoveryState): boolean;
-
-export function guardedReloadApp(options?: {
-  browserWindow?: any;
-  fetchFn?: ((input: string, init?: Record<string, any>) => Promise<any>) | null;
-  state?: AsyncModuleRecoveryState | null;
-  label?: string;
-  message?: string;
-}): Promise<boolean>;
-
-export function installAsyncModuleRecoveryHandlers(options?: {
-  router?: any;
-  state: AsyncModuleRecoveryState;
-  label?: string;
-  onNotify?: (state: AsyncModuleRecoveryState) => void;
-  windowObject?: any;
-}): Readonly<{
-  dispose: () => void;
-}>;
+export const DEFAULT_GUARD_EVALUATOR_KEY: "__JSKIT_WEB_SHELL_GUARD_EVALUATOR__";
 
 export function getClientAppConfig(): Readonly<Record<string, any>>;
 export function resolveMobileConfig(appConfig?: Record<string, any>): Readonly<Record<string, any>>;
 export function resolveClientAssetMode(appConfig?: Record<string, any>): string;
-export function normalizeIncomingAppUrl(
-  url?: string,
-  mobileConfig?: Record<string, any>,
-  options?: {
-    currentOrigin?: string;
-    allowedHttpOrigins?: string[];
-  }
-): string;
-export function registerMobileLaunchRouting(options?: {
-  router: any;
-  mobileConfig?: Record<string, any>;
-  getInitialLaunchUrl?: () => Promise<string> | string;
-  subscribeToLaunchUrls?: (handler: (url: string) => void) => (() => void) | void;
-  currentOrigin?: string;
-  allowedHttpOrigins?: string[];
-  logger?: ClientLogger;
-}): Readonly<{
-  initialize: () => Promise<string>;
-  dispose: () => void;
-  applyIncomingUrl: (url?: string, reason?: string) => Promise<string>;
-}>;
-
 export function resolveClientBootstrapDebugEnabled(options?: {
   env?: Record<string, any>;
   debugEnabled?: boolean;
   debugEnvKey?: string;
 }): boolean;
 
+export function shellScrollBehavior(to: any, from: any, savedPosition: any): any;
+
 export function createShellRouter(options?: {
-  createRouter: (options: { history?: any; routes: any[] }) => any;
+  createRouter: (options: { history?: any; routes: any[]; scrollBehavior?: (to: any, from: any, savedPosition: any) => any }) => any;
   history?: any;
   routes?: any[];
   surfaceRuntime: any;
   surfaceMode?: string;
   fallbackRoute?: any;
   notFoundComponent?: any;
-  guard?: false | ((to: any) => any) | Record<string, any>;
+  guard?:
+    | false
+    | ((to: any) => any)
+    | {
+        webRootAllowed?: "yes" | "no";
+        guardEvaluatorKey?: string;
+        authenticatedPolicy?: string;
+        publicPolicy?: string;
+      };
+  /** Defaults to shellScrollBehavior; pass your own function, or false for none. */
+  scrollBehavior?: false | ((to: any, from: any, savedPosition: any) => any);
 }): Readonly<{
   router: any;
   activeRoutes: readonly any[];
@@ -112,6 +52,7 @@ export function bootstrapClientShellApp(options?: {
   appConfig?: Record<string, any>;
   appPlugins?: any[];
   pinia?: any;
+  queryClient?: any;
   router: any;
   bootClientModules: (context: any) => Promise<any>;
   surfaceRuntime: any;
@@ -119,6 +60,7 @@ export function bootstrapClientShellApp(options?: {
   env?: Record<string, any>;
   fallbackRoute?: any;
   logger?: ClientLogger;
+  /** Its isDebugEnabled decides whether bootstrap builds debug payloads; without it, a debug method means enabled. */
   createBootstrapLogger?: (options: {
     env?: Record<string, any>;
     logger?: ClientLogger;

package/client/index.js

@@ -8,6 +8,11 @@ export {
   isDynamicImportError,
   notifyAsyncModuleLoadError
 } from "./asyncModuleRecovery.js";
-export { normalizeIncomingAppUrl, registerMobileLaunchRouting } from "./mobileLaunchRouting.js";
-export { resolveClientBootstrapDebugEnabled, createSurfaceShellRouter as createShellRouter, bootstrapClientShellApp } from "./shellBootstrap.js";
+export {
+  resolveClientBootstrapDebugEnabled,
+  createSurfaceShellRouter as createShellRouter,
+  shellScrollBehavior,
+  bootstrapClientShellApp
+} from "./shellBootstrap.js";
+export { DEFAULT_GUARD_EVALUATOR_KEY } from "./shellRouting.js";
 export { createComponentInteractionEmitter } from "./componentInteraction.js";

package/client/logging.js

@@ -1,12 +1,17 @@
 import { isRecord } from "../shared/support/normalize.js";
 
+// isDebugEnabled tells callers whether debug output goes anywhere, so they
+// can skip building debug payloads. A logger may state it; otherwise it is
+// true exactly when the logger has its own debug method.
 function createStructuredLogger(logger = console) {
   if (isRecord(logger)) {
+    const hasDebug = typeof logger.debug === "function";
     return Object.freeze({
       info: typeof logger.info === "function" ? logger.info.bind(logger) : console.info.bind(console),
       warn: typeof logger.warn === "function" ? logger.warn.bind(logger) : console.warn.bind(console),
       error: typeof logger.error === "function" ? logger.error.bind(logger) : console.error.bind(console),
-      debug: typeof logger.debug === "function" ? logger.debug.bind(logger) : () => {}
+      debug: hasDebug ? logger.debug.bind(logger) : () => {},
+      isDebugEnabled: typeof logger.isDebugEnabled === "boolean" ? logger.isDebugEnabled : hasDebug
     });
   }
 
@@ -14,7 +19,8 @@ function createStructuredLogger(logger = console) {
     info: console.info.bind(console),
     warn: console.warn.bind(console),
     error: console.error.bind(console),
-    debug: () => {}
+    debug: () => {},
+    isDebugEnabled: false
   });
 }
 

package/client/moduleBootstrap.js

@@ -136,16 +136,18 @@ function registerClientModuleRoutes({
     surfaceMode
   });
   const log = createStructuredLogger(logger);
-  log.debug(
-    {
-      packageId: normalizedPackageId,
-      source,
-      surfaceMode: String(surfaceMode || "").trim(),
-      declaredRoutes: normalizedRoutes.map(toRouteSnapshot),
-      activeRoutes: activeRoutes.map(toRouteSnapshot)
-    },
-    "Client route registration analysis."
-  );
+  if (log.isDebugEnabled) {
+    log.debug(
+      {
+        packageId: normalizedPackageId,
+        source,
+        surfaceMode: String(surfaceMode || "").trim(),
+        declaredRoutes: normalizedRoutes.map(toRouteSnapshot),
+        activeRoutes: activeRoutes.map(toRouteSnapshot)
+      },
+      "Client route registration analysis."
+    );
+  }
 
   const declaredPaths = normalizedRoutes.map((route) => route.path);
   const activePaths = activeRoutes.map((route) => route.path);
@@ -167,14 +169,16 @@ function registerClientModuleRoutes({
 
     seenRoutePaths.add(normalizedPath);
     router.addRoute(toVueRouteRecord(route));
-    log.debug(
-      {
-        packageId: normalizedPackageId,
-        source,
-        route: toRouteSnapshot(route)
-      },
-      "Added client route to router."
-    );
+    if (log.isDebugEnabled) {
+      log.debug(
+        {
+          packageId: normalizedPackageId,
+          source,
+          route: toRouteSnapshot(route)
+        },
+        "Added client route to router."
+      );
+    }
     registeredCount += 1;
   }
 
@@ -560,14 +564,16 @@ async function bootClientModules({
       },
       "Registered client module routes."
     );
-    log.debug(
-      {
-        packageId,
-        source,
-        routerRoutes: summarizeRouterRoutes(router)
-      },
-      "Router route table after client route registration."
-    );
+    if (log.isDebugEnabled) {
+      log.debug(
+        {
+          packageId,
+          source,
+          routerRoutes: summarizeRouterRoutes(router)
+        },
+        "Router route table after client route registration."
+      );
+    }
     routeResults.push(result);
     return result;
   };
@@ -599,13 +605,15 @@ async function bootClientModules({
       },
       "Booted JSKIT client modules."
     );
-    log.debug(
-      {
-        routerRoutes: summarizeRouterRoutes(router),
-        currentPath: typeof window !== "undefined" ? String(window.location?.pathname || "") : ""
-      },
-      "JSKIT client bootstrap final route table."
-    );
+    if (log.isDebugEnabled) {
+      log.debug(
+        {
+          routerRoutes: summarizeRouterRoutes(router),
+          currentPath: typeof window !== "undefined" ? String(window.location?.pathname || "") : ""
+        },
+        "JSKIT client bootstrap final route table."
+      );
+    }
   }
 
   return Object.freeze({

package/client/moduleBootstrap.test.js

@@ -433,3 +433,38 @@ test("bootClientModules throws when packageMetadataClientProviders export is mis
     /packageMetadata provider export "MissingProvider" must be a capability provider/
   );
 });
+
+test("bootClientModules builds route debug payloads only when the logger's debug is enabled", async () => {
+  const surfaceRuntime = createSurfaceRuntimeFixture();
+  const clientModules = [
+    {
+      packageId: "@example/auth",
+      packageMetadataUiRoutes: [{ id: "auth.login", path: "/auth/login", scope: "global", autoRegister: false }],
+      module: {
+        clientRoutes: [{ id: "auth.login", name: "auth-login", path: "/auth/login", scope: "global", component: {} }]
+      }
+    }
+  ];
+
+  for (const isDebugEnabled of [false, true]) {
+    const router = createRouterStub();
+    let routeTableReads = 0;
+    router.getRoutes = () => {
+      routeTableReads += 1;
+      return [...router.routes];
+    };
+    const messages = [];
+    await bootClientModules({
+      clientModules,
+      router,
+      surfaceRuntime,
+      surfaceMode: "all",
+      logger: { info() {}, warn() {}, error() {}, debug: (_payload, message) => messages.push(message), isDebugEnabled }
+    });
+
+    assert.equal(router.routes.length, 1);
+    assert.equal(routeTableReads > 0, isDebugEnabled);
+    assert.equal(messages.includes("Added client route to router."), isDebugEnabled);
+    assert.equal(messages.includes("JSKIT client bootstrap final route table."), isDebugEnabled);
+  }
+});

package/client/shellBootstrap.js

@@ -56,6 +56,38 @@ function installAppPlugins(app, appPlugins = []) {
   }
 }
 
+function isSurfaceRootRecord(record) {
+  return Boolean(record?.meta?.jskit?.surface);
+}
+
+// A page that hosts tabs or sub-views keeps its own record above the changing
+// child, so the two locations share a non-leaf record below the surface root.
+function staysOnSamePage(to, from) {
+  if (to.path === from.path) {
+    return true;
+  }
+  const fromParents = new Set((from.matched || []).slice(0, -1));
+  return (to.matched || []).slice(0, -1).some((record) => fromParents.has(record) && !isSurfaceRootRecord(record));
+}
+
+/**
+ * JSKIT's default router scroll behaviour: Back/Forward restore the saved
+ * position, a new screen opens at the top (or at its hash target), and tab,
+ * query or hash changes within the same page keep the current position.
+ */
+function shellScrollBehavior(to, from, savedPosition) {
+  if (savedPosition) {
+    return savedPosition;
+  }
+  if (staysOnSamePage(to, from)) {
+    return false;
+  }
+  if (to.hash) {
+    return { el: to.hash, top: 0 };
+  }
+  return { top: 0 };
+}
+
 function createSurfaceShellRouter({
   createRouter,
   history,
@@ -64,7 +96,8 @@ function createSurfaceShellRouter({
   surfaceMode,
   fallbackRoute = null,
   notFoundComponent = null,
-  guard = false
+  guard = false,
+  scrollBehavior = shellScrollBehavior
 } = {}) {
   if (typeof createRouter !== "function") {
     throw new TypeError("createSurfaceShellRouter requires createRouter().");
@@ -79,7 +112,8 @@ function createSurfaceShellRouter({
   });
   const router = createRouter({
     history,
-    routes: activeRoutes
+    routes: activeRoutes,
+    ...(typeof scrollBehavior === "function" ? { scrollBehavior } : {})
   });
 
   if (guard !== false) {
@@ -170,14 +204,7 @@ async function bootstrapClientShellApp({
     logger: bootstrapLogger
   });
 
-  const isDebugEnabled =
-    typeof resolvedLogger?.isDebugEnabled === "boolean"
-      ? resolvedLogger.isDebugEnabled
-      : resolveClientBootstrapDebugEnabled({
-          env,
-          debugEnabled,
-          debugEnvKey
-        });
+  const { isDebugEnabled } = bootstrapLogger;
   if (isDebugEnabled) {
     bootstrapLogger.info(
       {
@@ -245,6 +272,7 @@ async function bootstrapClientShellApp({
 }
 
 export {
+  shellScrollBehavior,
   resolveClientBootstrapDebugEnabled,
   createClientBootstrapLogger,
   createSurfaceShellRouter,

package/client/shellBootstrap.test.js

@@ -4,7 +4,8 @@ import { createSurfaceRuntime } from "../shared/surface/runtime.js";
 import {
   bootstrapClientShellApp,
   createClientBootstrapLogger,
-  createSurfaceShellRouter
+  createSurfaceShellRouter,
+  shellScrollBehavior
 } from "./shellBootstrap.js";
 import { getClientAppConfig } from "./appConfig.js";
 
@@ -52,11 +53,6 @@ test("createSurfaceShellRouter builds active routes and installs a guard", () =>
     surfaceMode: "app",
     notFoundComponent: {},
     guard: {
-      surfaceDefinitions: {
-        app: { id: "app", pagesRoot: "app", requiresAuth: false },
-        admin: { id: "admin", pagesRoot: "admin", requiresAuth: false }
-      },
-      defaultSurfaceId: "app",
       webRootAllowed: "yes"
     }
   });
@@ -68,6 +64,57 @@ test("createSurfaceShellRouter builds active routes and installs a guard", () =>
   assert.equal(activeRoutes.some((route) => route.path === "/admin/home"), false);
   assert.equal(activeRoutes.some((route) => route.path === "/:pathMatch(.*)*"), true);
   assert.equal(fallbackRoute.path, "/:pathMatch(.*)*");
+  assert.equal(routerState.options.scrollBehavior, shellScrollBehavior);
+});
+
+test("createSurfaceShellRouter lets an app replace or disable the scroll behaviour", () => {
+  const surfaceRuntime = createSurfaceRuntimeFixture();
+  const custom = () => ({ top: 42 });
+  const seen = [];
+  for (const scrollBehavior of [custom, false]) {
+    createSurfaceShellRouter({
+      createRouter(options) {
+        seen.push(options);
+        return {};
+      },
+      routes: [],
+      surfaceRuntime,
+      surfaceMode: "app",
+      notFoundComponent: {},
+      scrollBehavior
+    });
+  }
+  assert.equal(seen[0].scrollBehavior, custom);
+  assert.equal(Object.hasOwn(seen[1], "scrollBehavior"), false);
+});
+
+test("shellScrollBehavior opens new screens at the top and keeps in-page changes still", () => {
+  const surface = { path: "/home", meta: { jskit: { surface: "home" } } };
+  const settings = { path: "/home/settings", meta: {} };
+  const general = { path: "/home/settings/general", meta: {} };
+  const profile = { path: "/home/settings/profile", meta: {} };
+  const contacts = { path: "/home/contacts", meta: {} };
+  const contact = { path: "/home/contacts/:id", meta: {} };
+  const at = (path, matched, extra = {}) => ({ path, matched, hash: "", ...extra });
+
+  const saved = { left: 0, top: 640 };
+  assert.equal(shellScrollBehavior(at("/home/contacts", [surface, contacts]), at("/home", [surface]), saved), saved);
+  assert.deepEqual(shellScrollBehavior(at("/home/contacts", [surface, contacts]), at("/home", [surface]), null), { top: 0 });
+  // Another record of the same screen type is still a new screen.
+  assert.deepEqual(
+    shellScrollBehavior(at("/home/contacts/2", [surface, contact]), at("/home/contacts/1", [surface, contact]), null),
+    { top: 0 }
+  );
+  // Query, hash or tab changes within one page keep the position.
+  assert.equal(shellScrollBehavior(at("/home/contacts", [surface, contacts]), at("/home/contacts", [surface, contacts]), null), false);
+  assert.equal(
+    shellScrollBehavior(at("/home/settings/profile", [surface, settings, profile]), at("/home/settings/general", [surface, settings, general]), null),
+    false
+  );
+  assert.deepEqual(
+    shellScrollBehavior(at("/home/contacts", [surface, contacts], { hash: "#recent" }), at("/home", [surface]), null),
+    { el: "#recent", top: 0 }
+  );
 });
 
 test("createClientBootstrapLogger enables debug from env flag", () => {
@@ -80,6 +127,38 @@ test("createClientBootstrapLogger enables debug from env flag", () => {
   assert.equal(logger.isDebugEnabled, true);
 });
 
+test("bootstrapClientShellApp hands hooks and modules one logger that carries its debug flag", async () => {
+  for (const debugEnabled of [false, true]) {
+    let routeTableReads = 0;
+    const seenLoggers = [];
+    const router = {
+      addRoute() {},
+      getRoutes() {
+        routeTableReads += 1;
+        return [];
+      },
+      async isReady() {}
+    };
+    const result = await bootstrapClientShellApp({
+      createApp: () => ({ use() {}, mount() {} }),
+      router,
+      surfaceRuntime: createSurfaceRuntimeFixture(),
+      logger: { info() {}, warn() {}, error() {} },
+      debugEnabled,
+      bootClientModules: async ({ logger }) => {
+        seenLoggers.push(logger);
+        return {};
+      },
+      onAfterRouterReady: ({ logger }) => seenLoggers.push(logger)
+    });
+
+    assert.equal(result.debugEnabled, debugEnabled);
+    assert.equal(result.logger.isDebugEnabled, debugEnabled);
+    assert.deepEqual(seenLoggers, [result.logger, result.logger]);
+    assert.equal(routeTableReads > 0, debugEnabled);
+  }
+});
+
 test("bootstrapClientShellApp boots modules, reinstalls fallback route, and mounts app", async () => {
   const calls = [];
   const logs = [];

package/client/shellRouting.js

@@ -1,4 +1,3 @@
-import { deriveSurfaceRouteBaseFromPagesRoot } from "../shared/surface/index.js";
 import { filterRoutesBySurface } from "../shared/surface/runtime.js";
 import { isExternalLinkTarget } from "../shared/support/linkPath.js";
 import { AUTH_POLICY_AUTHENTICATED, AUTH_POLICY_PUBLIC } from "../shared/support/policies.js";
@@ -101,20 +100,6 @@ function resolveSearchFromFullPath(fullPath) {
   return hashStart < 0 ? rawFullPath.slice(queryStart) : rawFullPath.slice(queryStart, hashStart);
 }
 
-function resolveSurfaceDefinition(surfaceDefinitions, surfaceId) {
-  const normalizedSurfaceId = String(surfaceId || "")
-    .trim()
-    .toLowerCase();
-  if (!normalizedSurfaceId) {
-    return null;
-  }
-  const definition = surfaceDefinitions[normalizedSurfaceId];
-  if (!definition || typeof definition !== "object") {
-    return null;
-  }
-  return definition;
-}
-
 function normalizeWebRootAllowed(value) {
   const normalizedValue = String(value || "")
     .trim()
@@ -125,27 +110,7 @@ function normalizeWebRootAllowed(value) {
   return WEB_ROOT_ALLOW_YES;
 }
 
-function resolveDefaultSurfaceRootPath({ surfaceDefinitions, defaultSurfaceId }) {
-  const defaultSurface = resolveSurfaceDefinition(surfaceDefinitions, defaultSurfaceId);
-  return String(
-    defaultSurface?.routeBase || deriveSurfaceRouteBaseFromPagesRoot(defaultSurface?.pagesRoot || "")
-  ).trim() || "/";
-}
-
-function resolveSurfaceRequiresAuth({ pathname, surfaceRuntime, surfaceDefinitions }) {
-  const normalizedPathname = String(pathname || "/").trim() || "/";
-  const surfaceId = surfaceRuntime.resolveSurfaceFromPathname(normalizedPathname);
-  const surfaceDefinition = resolveSurfaceDefinition(surfaceDefinitions, surfaceId);
-  return Boolean(surfaceDefinition?.requiresAuth);
-}
-
-function resolveEffectiveRouteGuard({
-  to,
-  surfaceRuntime,
-  surfaceDefinitions,
-  authenticatedPolicy = AUTH_POLICY_AUTHENTICATED,
-  publicPolicy = AUTH_POLICY_PUBLIC
-}) {
+function resolveEffectiveRouteGuard({ to, surfaceRuntime, authenticatedPolicy, publicPolicy }) {
   const routeGuard = resolveRouteGuard(to);
   const routePolicy = normalizeGuardPolicy(routeGuard?.policy);
   if (routePolicy) {
@@ -154,13 +119,8 @@ function resolveEffectiveRouteGuard({
     };
   }
 
-  if (
-    resolveSurfaceRequiresAuth({
-      pathname: to?.path || "/",
-      surfaceRuntime,
-      surfaceDefinitions
-    })
-  ) {
+  const surfaceId = surfaceRuntime.resolveSurfaceFromPathname(String(to?.path || "/").trim() || "/");
+  if (surfaceRuntime.getSurfaceDefinition(surfaceId)?.requiresAuth) {
     return {
       policy: authenticatedPolicy
     };
@@ -245,31 +205,27 @@ function evaluateShellGuard({ guard, to, guardEvaluatorKey }) {
 
 function createShellBeforeEachGuard({
   surfaceRuntime,
-  surfaceDefinitions,
-  defaultSurfaceId,
   webRootAllowed = WEB_ROOT_ALLOW_YES,
   guardEvaluatorKey = DEFAULT_GUARD_EVALUATOR_KEY,
   authenticatedPolicy = AUTH_POLICY_AUTHENTICATED,
   publicPolicy = AUTH_POLICY_PUBLIC
 } = {}) {
-  if (!surfaceRuntime || typeof surfaceRuntime.resolveSurfaceFromPathname !== "function") {
-    throw new TypeError("createShellBeforeEachGuard requires surfaceRuntime.resolveSurfaceFromPathname().");
-  }
-  if (!surfaceDefinitions || typeof surfaceDefinitions !== "object" || Array.isArray(surfaceDefinitions)) {
-    throw new TypeError("createShellBeforeEachGuard requires a surfaceDefinitions object.");
+  if (
+    !surfaceRuntime ||
+    typeof surfaceRuntime.resolveSurfaceFromPathname !== "function" ||
+    typeof surfaceRuntime.getSurfaceDefinition !== "function"
+  ) {
+    throw new TypeError(
+      "createShellBeforeEachGuard requires surfaceRuntime.resolveSurfaceFromPathname() and getSurfaceDefinition()."
+    );
   }
 
+  const defaultSurfaceRootPath =
+    surfaceRuntime.getSurfaceDefinition(surfaceRuntime.DEFAULT_SURFACE_ID)?.routeBase || "/";
+  const redirectWebRoot = normalizeWebRootAllowed(webRootAllowed) === WEB_ROOT_ALLOW_NO && defaultSurfaceRootPath !== "/";
+
   return (to) => {
-    const normalizedWebRootAllowed = normalizeWebRootAllowed(webRootAllowed);
-    const defaultSurfaceRootPath = resolveDefaultSurfaceRootPath({
-      surfaceDefinitions,
-      defaultSurfaceId
-    });
-    if (
-      normalizedWebRootAllowed === WEB_ROOT_ALLOW_NO &&
-      String(to?.path || "/").trim() === "/" &&
-      defaultSurfaceRootPath !== "/"
-    ) {
+    if (redirectWebRoot && String(to?.path || "/").trim() === "/") {
       const search = resolveSearchFromFullPath(to?.fullPath || "");
       const hash = String(to?.hash || "").trim();
       return `${defaultSurfaceRootPath}${search}${hash}`;
@@ -278,7 +234,6 @@ function createShellBeforeEachGuard({
     const guard = resolveEffectiveRouteGuard({
       to,
       surfaceRuntime,
-      surfaceDefinitions,
       authenticatedPolicy,
       publicPolicy
     });