@jskit-ai/kernel 0.1.244 → 0.1.245

package/client/index.d.ts

@@ -91,8 +91,10 @@ export function resolveClientBootstrapDebugEnabled(options?: {
   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;
@@ -100,6 +102,8 @@ export function createShellRouter(options?: {
   fallbackRoute?: any;
   notFoundComponent?: any;
   guard?: false | ((to: any) => any) | Record<string, any>;
+  /** 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[];

package/client/index.js

@@ -9,5 +9,10 @@ export {
   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 { createComponentInteractionEmitter } from "./componentInteraction.js";

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) {
@@ -245,6 +279,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";
 
@@ -68,6 +69,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", () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.244",
+  "version": "0.1.245",
   "type": "module",
   "dependencies": {
     "json-rest-schema": "^1.0.17"

package/shared/support/returnToPath.js

@@ -1,5 +1,17 @@
 import { normalizePathname } from "../surface/paths.js";
 
+const SAME_ORIGIN_PROBE = "http://return-to.invalid";
+
+// Browsers read "/\\host" and "/<tab>/host" as another site, so a path counts
+// only if it resolves on the page's own origin.
+function staysOnSameOrigin(path) {
+  try {
+    return new URL(path, SAME_ORIGIN_PROBE).origin === SAME_ORIGIN_PROBE;
+  } catch {
+    return false;
+  }
+}
+
 function normalizeHttpOrigin(value = "") {
   const rawValue = String(value || "").trim();
   if (!rawValue) {
@@ -113,6 +125,9 @@ function normalizeReturnToPath(
   const normalizedBlockedPathnames = normalizeBlockedPathnames(blockedPathnames);
 
   if (rawValue.startsWith("/") && !rawValue.startsWith("//")) {
+    if (!staysOnSameOrigin(rawValue)) {
+      return fallback;
+    }
     const normalizedPathname = normalizePathname(rawValue);
     if (normalizedBlockedPathnames.includes(normalizedPathname)) {
       return fallback;

package/shared/support/returnToPath.test.js

@@ -121,3 +121,10 @@ test("resolveAllowedOriginsFromPlacementContext collects current and surface ori
     }
   }
 });
+
+test("normalizeReturnToPath refuses paths a browser reads as another site", () => {
+  for (const value of ["/\\evil.example", "/\\/evil.example/x", "/\t/evil.example", "/\n/evil.example", "\\\\evil.example"]) {
+    assert.equal(normalizeReturnToPath(value, { fallback: "/home" }), "/home", JSON.stringify(value));
+  }
+  assert.equal(normalizeReturnToPath("/a/b?c=1#d", { fallback: "/home" }), "/a/b?c=1#d");
+});

package/test/barrelExposure.test.js

@@ -117,7 +117,8 @@ const BARREL_EXPECTATIONS = Object.freeze([
       "notifyAsyncModuleLoadError",
       "registerMobileLaunchRouting",
       "resolveMobileConfig",
-      "resolveClientBootstrapDebugEnabled"
+      "resolveClientBootstrapDebugEnabled",
+      "shellScrollBehavior"
     ])
   }),
   Object.freeze({