@jskit-ai/kernel 0.1.62 → 0.1.64

package/client/appConfig.js

@@ -1,4 +1,4 @@
-import { isRecord } from "../shared/support/normalize.js";
+import { isRecord, normalizeMobileConfig } from "../shared/support/normalize.js";
 
 const CLIENT_APP_CONFIG_GLOBAL_KEY = "__JSKIT_CLIENT_APP_CONFIG__";
 const EMPTY_CLIENT_APP_CONFIG = Object.freeze({});
@@ -30,4 +30,18 @@ function getClientAppConfig() {
   return isRecord(appConfig) ? appConfig : EMPTY_CLIENT_APP_CONFIG;
 }
 
-export { CLIENT_APP_CONFIG_GLOBAL_KEY, setClientAppConfig, getClientAppConfig };
+function resolveMobileConfig(appConfig = getClientAppConfig()) {
+  return normalizeMobileConfig(isRecord(appConfig) ? appConfig.mobile : {});
+}
+
+function resolveClientAssetMode(appConfig = getClientAppConfig()) {
+  return resolveMobileConfig(appConfig).assetMode;
+}
+
+export {
+  CLIENT_APP_CONFIG_GLOBAL_KEY,
+  setClientAppConfig,
+  getClientAppConfig,
+  resolveMobileConfig,
+  resolveClientAssetMode
+};

package/client/appConfig.test.js

@@ -0,0 +1,71 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  CLIENT_APP_CONFIG_GLOBAL_KEY,
+  getClientAppConfig,
+  resolveClientAssetMode,
+  resolveMobileConfig,
+  setClientAppConfig
+} from "./appConfig.js";
+
+test("resolveMobileConfig and resolveClientAssetMode read normalized client mobile config", () => {
+  const previous = globalThis[CLIENT_APP_CONFIG_GLOBAL_KEY];
+
+  try {
+    setClientAppConfig({
+      mobile: {
+        enabled: true,
+        strategy: "capacitor",
+        assetMode: "dev_server",
+        auth: {
+          customScheme: "convict"
+        }
+      }
+    });
+
+    assert.equal(getClientAppConfig().mobile.enabled, true);
+    assert.deepEqual(resolveMobileConfig(), {
+      enabled: true,
+      strategy: "capacitor",
+      appId: "",
+      appName: "",
+      assetMode: "dev_server",
+      devServerUrl: "",
+      apiBaseUrl: "",
+      auth: {
+        callbackPath: "/auth/login",
+        customScheme: "convict",
+        appLinkDomains: []
+      },
+      android: {
+        packageName: "",
+        minSdk: 26,
+        targetSdk: 35,
+        versionCode: 1,
+        versionName: "1.0.0"
+      }
+    });
+    assert.equal(resolveClientAssetMode(), "dev_server");
+  } finally {
+    if (previous === undefined) {
+      delete globalThis[CLIENT_APP_CONFIG_GLOBAL_KEY];
+    } else {
+      globalThis[CLIENT_APP_CONFIG_GLOBAL_KEY] = previous;
+    }
+  }
+});
+
+test("resolveMobileConfig accepts explicit appConfig values", () => {
+  const mobileConfig = resolveMobileConfig({
+    mobile: {
+      enabled: true,
+      appId: "com.example.app",
+      appName: "Example App"
+    }
+  });
+
+  assert.equal(mobileConfig.enabled, true);
+  assert.equal(mobileConfig.appId, "com.example.app");
+  assert.equal(mobileConfig.appName, "Example App");
+  assert.equal(resolveClientAssetMode({}), "bundled");
+});

package/client/index.d.ts

@@ -7,6 +7,29 @@ export type ClientLogger = {
 };
 
 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>;
@@ -52,6 +75,7 @@ export function bootstrapClientShellApp(options?: {
   debugEnvKey?: string;
   debugMessage?: string;
   onAfterModulesBootstrapped?: (context: any) => void | Promise<void>;
+  onAfterRouterReady?: (context: any) => void | Promise<void>;
   mountSelector?: string;
 }): Promise<
   Readonly<{

package/client/index.js

@@ -1,3 +1,4 @@
-export { getClientAppConfig } from "./appConfig.js";
+export { getClientAppConfig, resolveMobileConfig, resolveClientAssetMode } from "./appConfig.js";
+export { normalizeIncomingAppUrl, registerMobileLaunchRouting } from "./mobileLaunchRouting.js";
 export { resolveClientBootstrapDebugEnabled, createSurfaceShellRouter as createShellRouter, bootstrapClientShellApp } from "./shellBootstrap.js";
 export { createComponentInteractionEmitter } from "./componentInteraction.js";

package/client/mobileLaunchRouting.js

@@ -0,0 +1,231 @@
+import { normalizePathname } from "../shared/surface/paths.js";
+import { normalizeText } from "../shared/support/normalize.js";
+import { resolveMobileConfig } from "./appConfig.js";
+
+function buildNormalizedRoutePath(pathname = "/", search = "", hash = "") {
+  const normalizedPathname = normalizePathname(pathname);
+  const normalizedSearch = String(search || "").trim().replace(/^\?+/, "");
+  const normalizedHash = String(hash || "").trim();
+
+  return `${normalizedPathname}${normalizedSearch ? `?${normalizedSearch}` : ""}${normalizedHash}`;
+}
+
+function normalizeResolvedRoutePath(value = "", fallback = "") {
+  const normalizedValue = normalizeText(value);
+  if (!normalizedValue) {
+    return fallback;
+  }
+
+  try {
+    const parsed = new URL(normalizedValue, "https://jskit.invalid");
+    return buildNormalizedRoutePath(parsed.pathname, parsed.search, parsed.hash);
+  } catch {
+    return fallback;
+  }
+}
+
+function normalizeAllowedHttpOrigins({ mobileConfig = {}, currentOrigin = "", allowedHttpOrigins = [] } = {}) {
+  const origins = new Set();
+
+  const maybeAddOrigin = (value = "") => {
+    const normalizedValue = normalizeText(value);
+    if (!normalizedValue) {
+      return;
+    }
+
+    try {
+      const parsed = new URL(normalizedValue);
+      const protocol = String(parsed.protocol || "").toLowerCase();
+      if (protocol !== "http:" && protocol !== "https:") {
+        return;
+      }
+      origins.add(String(parsed.origin || "").trim().toLowerCase());
+    } catch {}
+  };
+
+  maybeAddOrigin(currentOrigin);
+
+  const explicitOrigins = Array.isArray(allowedHttpOrigins) ? allowedHttpOrigins : [allowedHttpOrigins];
+  for (const entry of explicitOrigins) {
+    maybeAddOrigin(entry);
+  }
+
+  const appLinkDomains = Array.isArray(mobileConfig?.auth?.appLinkDomains) ? mobileConfig.auth.appLinkDomains : [];
+  for (const domain of appLinkDomains) {
+    const normalizedDomain = normalizeText(domain).toLowerCase();
+    if (!normalizedDomain) {
+      continue;
+    }
+    maybeAddOrigin(`https://${normalizedDomain}`);
+  }
+
+  return origins;
+}
+
+function normalizeCustomSchemeRoutePath(parsedUrl) {
+  const host = normalizeText(parsedUrl?.host);
+  const pathname = normalizePathname(parsedUrl?.pathname || "/");
+
+  if (!host) {
+    return pathname;
+  }
+
+  if (pathname === "/") {
+    return `/${host}`;
+  }
+
+  return normalizePathname(`/${host}${pathname}`);
+}
+
+function normalizeIncomingAppUrl(url = "", mobileConfig = {}, { currentOrigin = "", allowedHttpOrigins = [] } = {}) {
+  const normalizedUrl = normalizeText(url);
+  if (!normalizedUrl) {
+    return "";
+  }
+
+  if (normalizedUrl.startsWith("/")) {
+    try {
+      const parsed = new URL(normalizedUrl, "https://jskit.invalid");
+      return buildNormalizedRoutePath(parsed.pathname, parsed.search, parsed.hash);
+    } catch {
+      return "";
+    }
+  }
+
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(normalizedUrl);
+  } catch {
+    return "";
+  }
+
+  const resolvedMobileConfig = resolveMobileConfig({
+    mobile: mobileConfig
+  });
+  const allowedOrigins = normalizeAllowedHttpOrigins({
+    mobileConfig: resolvedMobileConfig,
+    currentOrigin,
+    allowedHttpOrigins
+  });
+  const protocol = String(parsedUrl.protocol || "").toLowerCase();
+  const customScheme = normalizeText(resolvedMobileConfig.auth.customScheme).toLowerCase();
+
+  if (customScheme && protocol === `${customScheme}:`) {
+    return buildNormalizedRoutePath(
+      normalizeCustomSchemeRoutePath(parsedUrl),
+      parsedUrl.search,
+      parsedUrl.hash
+    );
+  }
+
+  if ((protocol === "http:" || protocol === "https:") && allowedOrigins.has(String(parsedUrl.origin || "").toLowerCase())) {
+    return buildNormalizedRoutePath(parsedUrl.pathname, parsedUrl.search, parsedUrl.hash);
+  }
+
+  return "";
+}
+
+function registerMobileLaunchRouting({
+  router,
+  mobileConfig = {},
+  getInitialLaunchUrl = async () => "",
+  subscribeToLaunchUrls = () => () => {},
+  resolveTargetPath = null,
+  currentOrigin = typeof window === "object" && window?.location ? String(window.location.origin || "") : "",
+  allowedHttpOrigins = [],
+  logger = null
+} = {}) {
+  if (!router || typeof router.replace !== "function") {
+    throw new TypeError("registerMobileLaunchRouting requires router.replace().");
+  }
+
+  const resolvedMobileConfig = resolveMobileConfig({
+    mobile: mobileConfig
+  });
+  const runtimeLogger =
+    logger && typeof logger === "object"
+      ? logger
+      : {
+          info() {},
+          warn() {},
+          error() {}
+        };
+
+  async function applyIncomingUrl(url = "", reason = "manual") {
+    const normalizedTargetPath = normalizeIncomingAppUrl(url, resolvedMobileConfig, {
+      currentOrigin,
+      allowedHttpOrigins
+    });
+    if (!normalizedTargetPath) {
+      return "";
+    }
+
+    let resolvedTargetPath = normalizedTargetPath;
+    if (typeof resolveTargetPath === "function") {
+      const nextTargetPath = await resolveTargetPath(
+        Object.freeze({
+          originalUrl: String(url || ""),
+          normalizedTargetPath,
+          reason,
+          mobileConfig: resolvedMobileConfig,
+          router
+        })
+      );
+      resolvedTargetPath = normalizeResolvedRoutePath(nextTargetPath, normalizedTargetPath);
+    }
+
+    const currentFullPath = String(router.currentRoute?.value?.fullPath || "").trim();
+    if (currentFullPath === resolvedTargetPath) {
+      return resolvedTargetPath;
+    }
+
+    await router.replace(resolvedTargetPath);
+    if (typeof runtimeLogger.info === "function") {
+      runtimeLogger.info(
+        {
+          reason,
+          targetPath: resolvedTargetPath
+        },
+        "Mobile launch routing applied incoming app URL."
+      );
+    }
+    return resolvedTargetPath;
+  }
+
+  async function initialize() {
+    if (resolvedMobileConfig.enabled !== true) {
+      return "";
+    }
+
+    const initialLaunchUrl = await getInitialLaunchUrl();
+    return applyIncomingUrl(initialLaunchUrl, "initial-launch");
+  }
+
+  const unsubscribe =
+    resolvedMobileConfig.enabled === true
+      ? subscribeToLaunchUrls((nextUrl) => {
+          Promise.resolve(applyIncomingUrl(nextUrl, "launch-event")).catch((error) => {
+            if (typeof runtimeLogger.warn === "function") {
+              runtimeLogger.warn(
+                {
+                  error: String(error?.message || error || "unknown error")
+                },
+                "Mobile launch routing failed to apply incoming app URL."
+              );
+            }
+          });
+        })
+      : () => {};
+
+  return Object.freeze({
+    initialize,
+    dispose() {
+      if (typeof unsubscribe === "function") {
+        unsubscribe();
+      }
+    },
+    applyIncomingUrl
+  });
+}
+
+export { normalizeIncomingAppUrl, registerMobileLaunchRouting };

package/client/mobileLaunchRouting.test.js

@@ -0,0 +1,230 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { normalizeIncomingAppUrl, registerMobileLaunchRouting } from "./mobileLaunchRouting.js";
+
+test("normalizeIncomingAppUrl normalizes custom-scheme auth callback routes into router paths", () => {
+  const normalized = normalizeIncomingAppUrl("convict://auth/login?code=abc&oauthProvider=google", {
+    enabled: true,
+    auth: {
+      customScheme: "convict"
+    }
+  });
+
+  assert.equal(normalized, "/auth/login?code=abc&oauthProvider=google");
+});
+
+test("normalizeIncomingAppUrl normalizes custom-scheme workspace routes", () => {
+  const normalized = normalizeIncomingAppUrl("convict://w/acme/workouts/2026-05-07?tab=today", {
+    enabled: true,
+    auth: {
+      customScheme: "convict"
+    }
+  });
+
+  assert.equal(normalized, "/w/acme/workouts/2026-05-07?tab=today");
+});
+
+test("normalizeIncomingAppUrl normalizes allowed HTTPS app links", () => {
+  const normalized = normalizeIncomingAppUrl("https://app.example.com/auth/login?code=abc", {
+    enabled: true,
+    auth: {
+      appLinkDomains: ["app.example.com"]
+    }
+  });
+
+  assert.equal(normalized, "/auth/login?code=abc");
+});
+
+test("normalizeIncomingAppUrl accepts same-origin HTTP URLs when explicitly allowed", () => {
+  const normalized = normalizeIncomingAppUrl(
+    "http://192.168.1.10:5173/w/acme",
+    {
+      enabled: true
+    },
+    {
+      allowedHttpOrigins: ["http://192.168.1.10:5173"]
+    }
+  );
+
+  assert.equal(normalized, "/w/acme");
+});
+
+test("normalizeIncomingAppUrl rejects unowned schemes and domains", () => {
+  assert.equal(
+    normalizeIncomingAppUrl("otherapp://auth/login?code=abc", {
+      enabled: true,
+      auth: {
+        customScheme: "convict"
+      }
+    }),
+    ""
+  );
+
+  assert.equal(
+    normalizeIncomingAppUrl("https://evil.example.com/auth/login?code=abc", {
+      enabled: true,
+      auth: {
+        appLinkDomains: ["app.example.com"]
+      }
+    }),
+    ""
+  );
+});
+
+test("registerMobileLaunchRouting initializes and applies the initial launch URL", async () => {
+  const replaceCalls = [];
+  const runtime = registerMobileLaunchRouting({
+    router: {
+      currentRoute: {
+        value: {
+          fullPath: "/home"
+        }
+      },
+      async replace(target) {
+        replaceCalls.push(target);
+      }
+    },
+    mobileConfig: {
+      enabled: true,
+      auth: {
+        customScheme: "convict"
+      }
+    },
+    getInitialLaunchUrl: async () => "convict://auth/login?code=abc"
+  });
+
+  const targetPath = await runtime.initialize();
+
+  assert.equal(targetPath, "/auth/login?code=abc");
+  assert.deepEqual(replaceCalls, ["/auth/login?code=abc"]);
+});
+
+test("registerMobileLaunchRouting subscribes to later launch URLs and routes them", async () => {
+  const replaceCalls = [];
+  let listener = null;
+  const runtime = registerMobileLaunchRouting({
+    router: {
+      currentRoute: {
+        value: {
+          fullPath: "/home"
+        }
+      },
+      async replace(target) {
+        replaceCalls.push(target);
+      }
+    },
+    mobileConfig: {
+      enabled: true,
+      auth: {
+        customScheme: "convict"
+      }
+    },
+    subscribeToLaunchUrls(handler) {
+      listener = handler;
+      return () => {
+        listener = null;
+      };
+    }
+  });
+
+  assert.equal(typeof listener, "function");
+  listener("convict://w/acme");
+  await Promise.resolve();
+  await Promise.resolve();
+  assert.deepEqual(replaceCalls, ["/w/acme"]);
+
+  runtime.dispose();
+  assert.equal(listener, null);
+});
+
+test("registerMobileLaunchRouting lets a resolver override the final route target", async () => {
+  const replaceCalls = [];
+  const runtime = registerMobileLaunchRouting({
+    router: {
+      currentRoute: {
+        value: {
+          fullPath: "/home"
+        }
+      },
+      async replace(target) {
+        replaceCalls.push(target);
+      }
+    },
+    mobileConfig: {
+      enabled: true,
+      auth: {
+        customScheme: "convict"
+      }
+    },
+    getInitialLaunchUrl: async () => "convict://auth/login?code=abc",
+    resolveTargetPath({ originalUrl, normalizedTargetPath, reason }) {
+      assert.equal(originalUrl, "convict://auth/login?code=abc");
+      assert.equal(normalizedTargetPath, "/auth/login?code=abc");
+      assert.equal(reason, "initial-launch");
+      return "/w/acme";
+    }
+  });
+
+  const targetPath = await runtime.initialize();
+
+  assert.equal(targetPath, "/w/acme");
+  assert.deepEqual(replaceCalls, ["/w/acme"]);
+});
+
+test("registerMobileLaunchRouting forwards unknown deep-link paths to the normal router", async () => {
+  const replaceCalls = [];
+  const runtime = registerMobileLaunchRouting({
+    router: {
+      currentRoute: {
+        value: {
+          fullPath: "/home"
+        }
+      },
+      async replace(target) {
+        replaceCalls.push(target);
+      }
+    },
+    mobileConfig: {
+      enabled: true,
+      auth: {
+        customScheme: "convict"
+      }
+    },
+    getInitialLaunchUrl: async () => "convict://w/acme/does-not-exist"
+  });
+
+  const targetPath = await runtime.initialize();
+
+  assert.equal(targetPath, "/w/acme/does-not-exist");
+  assert.deepEqual(replaceCalls, ["/w/acme/does-not-exist"]);
+});
+
+test("registerMobileLaunchRouting no-ops when mobile config is disabled", async () => {
+  const replaceCalls = [];
+  const runtime = registerMobileLaunchRouting({
+    router: {
+      currentRoute: {
+        value: {
+          fullPath: "/home"
+        }
+      },
+      async replace(target) {
+        replaceCalls.push(target);
+      }
+    },
+    mobileConfig: {
+      enabled: false,
+      auth: {
+        customScheme: "convict"
+      }
+    },
+    getInitialLaunchUrl: async () => "convict://auth/login?code=abc",
+    subscribeToLaunchUrls() {
+      throw new Error("subscribeToLaunchUrls should not be called when mobile is disabled");
+    }
+  });
+
+  const targetPath = await runtime.initialize();
+  assert.equal(targetPath, "");
+  assert.deepEqual(replaceCalls, []);
+});

package/client/shellBootstrap.js

@@ -121,6 +121,7 @@ async function bootstrapClientShellApp({
   debugEnvKey = "VITE_JSKIT_CLIENT_DEBUG",
   debugMessage = "Client modules bootstrapped before router install.",
   onAfterModulesBootstrapped = null,
+  onAfterRouterReady = null,
   mountSelector = "#app"
 } = {}) {
   if (typeof createApp !== "function") {
@@ -216,6 +217,20 @@ async function bootstrapClientShellApp({
   if (typeof router.isReady === "function") {
     await router.isReady();
   }
+  if (typeof onAfterRouterReady === "function") {
+    await onAfterRouterReady(
+      Object.freeze({
+        app,
+        router,
+        clientBootstrap,
+        surfaceRuntime,
+        surfaceMode,
+        env: isRecord(env) ? { ...env } : {},
+        logger: bootstrapLogger,
+        debugEnabled: isDebugEnabled
+      })
+    );
+  }
   app.mount(mountSelector);
 
   return Object.freeze({

package/client/shellBootstrap.test.js

@@ -168,6 +168,9 @@ test("bootstrapClientShellApp boots modules, reinstalls fallback route, and moun
     },
     onAfterModulesBootstrapped(context) {
       calls.push(`after:${context.clientBootstrap.routeCount}`);
+    },
+    onAfterRouterReady(context) {
+      calls.push(`router-ready:${context.clientBootstrap.routeCount}`);
     }
   });
 
@@ -185,4 +188,5 @@ test("bootstrapClientShellApp boots modules, reinstalls fallback route, and moun
   assert.equal(calls.includes("add:not-found"), true);
   assert.equal(calls.includes("isReady"), true);
   assert.equal(calls.includes("after:3"), true);
+  assert.equal(calls.includes("router-ready:3"), true);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/kernel",
-  "version": "0.1.62",
+  "version": "0.1.64",
   "type": "module",
   "dependencies": {
     "json-rest-schema": "1.x.x"