akanjs 3.0.0-beta.26 → 3.0.0-beta.28

package/base/baseEnv.ts

@@ -112,11 +112,15 @@ export const resetEnvCache = () => {
 };
 
 const csrServerUrl = (): URL | null => {
-  const value = process.env.AKAN_PUBLIC_SERVER_URL;
+  const runtime = (globalThis as { __AKAN_NATIVE__?: { env?: Record<string, string | undefined> } }).__AKAN_NATIVE__
+    ?.env?.PUBLIC_AKAN_SERVER_URL;
+  const [key, value] = runtime
+    ? ["PUBLIC_AKAN_SERVER_URL", runtime]
+    : ["AKAN_PUBLIC_SERVER_URL", process.env.AKAN_PUBLIC_SERVER_URL];
   if (!value) return null;
   const url = new URL(value);
   if (url.protocol !== "http:" && url.protocol !== "https:")
-    throw new Error(`AKAN_PUBLIC_SERVER_URL must be an http(s) URL, got "${value}".`);
+    throw new Error(`${key} must be an http(s) URL, got "${value}".`);
   return url;
 };
 
@@ -125,10 +129,12 @@ const nativeDevGatewayOrigin = (): string | null =>
     ? `${window.location.protocol}//${window.location.host}`
     : null;
 
+const devServerOrigin = () => `http://localhost:${process.env.AKAN_PUBLIC_SERVER_PORT ?? "8282"}`;
+
 const nativeDevServerUrl = (operationMode: BaseEnv["operationMode"]): URL | null => {
   const platform = (globalThis as { __AKAN_NATIVE__?: { platform?: string } }).__AKAN_NATIVE__?.platform;
   if (operationMode !== "local" || !platform || platform === "web") return null;
-  return new URL(`http://localhost:${process.env.AKAN_PUBLIC_SERVER_PORT ?? "8282"}`);
+  return new URL(devServerOrigin());
 };
 
 const missingPublicEnv = (key: string) =>
@@ -179,8 +185,9 @@ export const getEnv = (): ClientEnv => {
         : "https:";
   const clientHttpUri = `${clientHttpProtocol}//${clientHost}${clientPort === 443 ? "" : `:${clientPort}`}`;
   const csrClient = side === "client" && renderMode === "csr";
-  const pageOrigin = csrClient && !process.env.AKAN_PUBLIC_SERVER_URL ? nativeDevGatewayOrigin() : null;
-  const serverUrl = csrClient && !pageOrigin ? (csrServerUrl() ?? nativeDevServerUrl(operationMode)) : null;
+  const pinnedServerUrl = csrClient ? csrServerUrl() : null;
+  const pageOrigin = csrClient && !pinnedServerUrl ? nativeDevGatewayOrigin() : null;
+  const serverUrl = csrClient && !pageOrigin ? (pinnedServerUrl ?? nativeDevServerUrl(operationMode)) : null;
   
   const hostFromPage =
     side === "client" && !serverUrl && (!!pageOrigin || operationMode === "local" || renderMode !== "csr");
@@ -251,3 +258,10 @@ export const getEnv = (): ClientEnv => {
   cachedEnv = env;
   return env;
 };
+
+export const getServerOrigin = (): string => {
+  const env = getEnv();
+  const behindGateway =
+    env.side === "client" && env.renderMode === "csr" && !csrServerUrl() && !!nativeDevGatewayOrigin();
+  return behindGateway ? devServerOrigin() : new URL(env.serverHttpUri).origin;
+};

package/client/csrTypes.ts

@@ -174,6 +174,8 @@ export interface Route {
   path: string;
   renderPage?: RouteRender;
   renderLayout?: RouteRender;
+  /** `renderLayout` is a generated `__root_layout`: a root boundary the page generator found. */
+  isRootLayout?: boolean;
   /** Synthetic layout render from a `_overrides.tsx` at this node; wraps the subtree in a UI-override provider. */
   renderOverrides?: RouteRender;
   pageIncludesOwnLayout?: boolean;

package/client/device.ts

@@ -13,27 +13,43 @@ const globalWithProcess = globalThis as typeof globalThis & { process?: ProcessE
 const debugSessionId = Math.random().toString(36).slice(2, 8);
 let debugSeq = 0;
 
-const isFrameDebugEnabled = () => {
-  if (typeof window === "undefined") return false;
-  const windowWithTarget = window as typeof window & { __AKAN_MOBILE_TARGET__?: unknown };
-  const search = new URLSearchParams(window.location.search);
-  return (
-    Boolean(windowWithTarget.__AKAN_MOBILE_TARGET__) ||
-    search.has("akanMobileTarget") ||
-    search.get("akanFrameDebug") === "1" ||
-    window.localStorage.getItem("akan:debug:frame") === "1"
-  );
+const FRAME_TRACE_LIMIT = 2000;
+const frameTrace: { seq: number; event: string; details: DebugPayload }[] = [];
+
+const readFrameDebugFlag = () => {
+  const fromSearch = new URLSearchParams(window.location.search).get("akanFrameDebug");
+  if (fromSearch) return fromSearch;
+  try {
+    return window.localStorage.getItem("akan:debug:frame");
+  } catch {
+    
+    return null;
+  }
+};
+
+const frameDebugMode = (): "console" | "memory" | null => {
+  if (typeof window === "undefined") return null;
+  const flag = readFrameDebugFlag();
+  return flag === "1" ? "console" : flag === "memory" ? "memory" : null;
 };
 
 export function debugFrame(event: string, payload: DebugPayload = {}) {
-  if (!isFrameDebugEnabled()) return;
+  const mode = frameDebugMode();
+  if (!mode) return;
   debugSeq += 1;
   const details = {
     href: window.location.href,
     now: Math.round(performance.now()),
     ...payload,
   };
-  console.info(`[akan:frame:${debugSessionId}:${debugSeq}] ${event}`, details, JSON.stringify(details));
+  if (mode === "memory") {
+    frameTrace.push({ seq: debugSeq, event, details });
+    if (frameTrace.length > FRAME_TRACE_LIMIT) frameTrace.splice(0, frameTrace.length - FRAME_TRACE_LIMIT);
+    (window as { __AKAN_FRAME_TRACE__?: typeof frameTrace }).__AKAN_FRAME_TRACE__ = frameTrace;
+    return;
+  }
+  
+  console.debug(`[akan:frame:${debugSessionId}:${debugSeq}] ${event}`, details);
 }
 
 interface DeviceInitOption {

package/client/index.ts

@@ -8,6 +8,7 @@ export * from "./device";
 export * from "./frameConfig";
 export * from "./locale";
 export * from "./makePageProto";
+export * from "./resolveServerUrl";
 export * from "./route";
 export * from "./router";
 export * from "./rscNavigation";

package/client/native/accessibility.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/accessibility/src/index.ts";

package/client/native/app-state.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/app-state/src/index.ts";

package/client/native/app.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/app/src/index.ts";

package/client/native/appearance.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/appearance/src/index.ts";

package/client/native/auth-session.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/auth-session/src/index.ts";

package/client/native/autostart.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/autostart/src/index.ts";

package/client/native/badge.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/badge/src/index.ts";

package/client/native/biometric.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/biometric/src/index.ts";

package/client/native/browser.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/browser/src/index.ts";

package/client/native/camera.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/camera/src/index.ts";

package/client/native/clipboard.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/clipboard/src/index.ts";

package/client/native/contacts.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/contacts/src/index.ts";

package/client/native/device.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/device/src/index.ts";

package/client/native/dialog.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/dialog/src/index.ts";

package/client/native/dock.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/dock/src/index.ts";

package/client/native/file-picker.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/file-picker/src/index.ts";

package/client/native/filesystem.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/filesystem/src/index.ts";

package/client/native/geolocation.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/geolocation/src/index.ts";

package/client/native/global-shortcut.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/global-shortcut/src/index.ts";

package/client/native/haptics.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/haptics/src/index.ts";

package/client/native/http.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/http/src/index.ts";

package/client/native/iap.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/iap/src/index.ts";

package/client/native/keep-awake.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/keep-awake/src/index.ts";

package/client/native/keyboard.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/keyboard/src/index.ts";

package/client/native/local-notifications.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/local-notifications/src/index.ts";

package/client/native/menu.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/menu/src/index.ts";

package/client/native/network.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/network/src/index.ts";

package/client/native/opener.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/opener/src/index.ts";

package/client/native/preferences.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/preferences/src/index.ts";

package/client/native/push.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/push/src/index.ts";

package/client/native/screen-orientation.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/screen-orientation/src/index.ts";

package/client/native/screen.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/screen/src/index.ts";

package/client/native/secure-storage.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/secure-storage/src/index.ts";

package/client/native/share.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/share/src/index.ts";

package/client/native/single-instance.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/single-instance/src/index.ts";

package/client/native/splash-screen.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/splash-screen/src/index.ts";

package/client/native/sqlite.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/sqlite/src/index.ts";

package/client/native/toast.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/toast/src/index.ts";

package/client/native/tray.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/tray/src/index.ts";

package/client/native/updates.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/updates/src/index.ts";

package/client/native/volume.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/volume/src/index.ts";

package/client/native/window-state.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/window-state/src/index.ts";

package/client/native/window.ts

@@ -0,0 +1 @@
+export * from "../../vendor/@akanjs/native/plugins/window/src/index.ts";

package/client/native.ts

@@ -2,14 +2,36 @@ import { isNative, platform } from "../vendor/@akanjs/native/packages/core/src/i
 import { browser } from "../vendor/@akanjs/native/plugins/browser/src/index.ts";
 import { opener } from "../vendor/@akanjs/native/plugins/opener/src/index.ts";
 
-export { AkanNativeError, fileBlob, releaseFile } from "../vendor/@akanjs/native/packages/core/src/index.ts";
+export type { LiveValue, Plugin } from "../vendor/@akanjs/native/packages/core/src/index.ts";
+export {
+  AkanNativeError,
+  createLiveValue,
+  definePlugin,
+  defineWebPlugin,
+  fileBlob,
+  isAkanNativeError,
+  releaseFile,
+  shallowEqual,
+} from "../vendor/@akanjs/native/packages/core/src/index.ts";
 export { app } from "../vendor/@akanjs/native/plugins/app/src/index.ts";
 export { appState } from "../vendor/@akanjs/native/plugins/app-state/src/index.ts";
+export type { AuthSessionApi } from "../vendor/@akanjs/native/plugins/auth-session/src/index.ts";
+export { authSession } from "../vendor/@akanjs/native/plugins/auth-session/src/index.ts";
 export type { Photo } from "../vendor/@akanjs/native/plugins/camera/src/index.ts";
 export type { Contact } from "../vendor/@akanjs/native/plugins/contacts/src/index.ts";
 export type { DeviceInfo } from "../vendor/@akanjs/native/plugins/device/src/index.ts";
 export { device } from "../vendor/@akanjs/native/plugins/device/src/index.ts";
 export { dialog } from "../vendor/@akanjs/native/plugins/dialog/src/index.ts";
+export type {
+  DirectoryFile,
+  PickDirectoryOptions,
+  PickDirectoryResult,
+  PickedFile,
+  PickFilesOptions,
+  SaveFileOptions,
+  SaveFileResult,
+} from "../vendor/@akanjs/native/plugins/file-picker/src/index.ts";
+export { filePicker } from "../vendor/@akanjs/native/plugins/file-picker/src/index.ts";
 export type { Position } from "../vendor/@akanjs/native/plugins/geolocation/src/index.ts";
 export { haptics } from "../vendor/@akanjs/native/plugins/haptics/src/index.ts";
 export type { IapProduct, IapTransaction } from "../vendor/@akanjs/native/plugins/iap/src/index.ts";
@@ -23,6 +45,11 @@ export type {
 } from "../vendor/@akanjs/native/plugins/push/src/index.ts";
 export { push } from "../vendor/@akanjs/native/plugins/push/src/index.ts";
 export { secureStorage } from "../vendor/@akanjs/native/plugins/secure-storage/src/index.ts";
+export type { UpdateCheck, UpdateProgress, UpdateState } from "../vendor/@akanjs/native/plugins/updates/src/index.ts";
+export { markReady, updates, useUpdateState } from "../vendor/@akanjs/native/plugins/updates/src/index.ts";
+export type { VolumeState } from "../vendor/@akanjs/native/plugins/volume/src/index.ts";
+export { volume } from "../vendor/@akanjs/native/plugins/volume/src/index.ts";
+export { useLiveValue, usePluginEvent } from "../vendor/@akanjs/native/packages/react/src/index.ts";
 export { browser, opener };
 
 export const loadCamera = () => import("../vendor/@akanjs/native/plugins/camera/src/index.ts");
@@ -33,6 +60,9 @@ export const loadIap = () => import("../vendor/@akanjs/native/plugins/iap/src/in
 /** Inside an iOS or Android shell of the native runtime; a mobile target opened in a browser is not. */
 export const isNativeApp = () => isNative && (platform === "ios" || platform === "android");
 
+/** Inside any shell of the native runtime, desktop included. */
+export const isNativeShell = () => isNative;
+
 export const nativePlatform = () => (isNativeApp() ? (platform as "ios" | "android") : null);
 
 export const desktopPlatform = () =>

package/client/resolveServerUrl.ts

@@ -0,0 +1,11 @@
+import { getEnv } from "akanjs/base";
+
+export const resolveServerUrl = (url: string): string => {
+  if (!url.startsWith("/") || url.startsWith("//")) return url;
+  const env = getEnv();
+  if (env.side !== "client" || env.renderMode !== "csr") return url;
+  if (url !== env.apiPrefix && !url.startsWith(`${env.apiPrefix}/`)) return url;
+  const server = new URL(env.serverHttpUri);
+  const serverOrigin = `${server.protocol}//${server.host}`;
+  return serverOrigin === `${window.location.protocol}//${window.location.host}` ? url : `${serverOrigin}${url}`;
+};

package/client/router.ts

@@ -160,6 +160,7 @@ class Router {
   #indexPath = "/";
   #navigation: Promise<void> = Promise.resolve();
   #historyIdx = 0;
+  #redirects = 0;
   #instance: RouterInstance = {
     push: (href: string) => {
       const { href: fullHref } = this.#getPathInfo(href);
@@ -407,6 +408,11 @@ class Router {
     this.#instance.refresh();
     return undefined as never;
   }
+  /** Client-side redirects so far: a render that saw this change while it ran redirected instead of drawing. A method
+   * for the reason `navigation()` is one. */
+  redirectCount(): number {
+    return this.#redirects;
+  }
   redirect(href: string, options: RedirectOptions = {}): never {
     const method = options.method ?? "replace";
     const status = options.status ?? 307;
@@ -422,6 +428,7 @@ class Router {
       Logger.info(`redirect to:${pathname}`);
       throw new AkanRedirectError(fullHref, method, status);
     } else {
+      this.#redirects += 1;
       this.#instance[method](href);
     }
     return undefined as never;
@@ -432,6 +439,7 @@ class Router {
       throw new AkanNotFoundError();
     }
     this.#checkInitialized();
+    this.#redirects += 1;
     this.#instance.replace("/404");
     return undefined as never;
   }

package/common/Logger.ts

@@ -77,6 +77,15 @@ const colorizeMap: { [key in LogLevel]: (text: string) => string } = {
   error: clc.red,
 };
 
+const consoleMethodMap = {
+  trace: "debug",
+  verbose: "debug",
+  debug: "debug",
+  info: "info",
+  warn: "warn",
+  error: "error",
+} as const satisfies { [key in LogLevel]: "debug" | "info" | "warn" | "error" };
+
 const ansiPattern = new RegExp(`${String.fromCharCode(27)}\\[[0-?]*[ -/]*[@-~]`, "g");
 
 const redactedAttrKey = /password|passwd|token|jwt|authorization|cookie|secret|api[-_]?key|private[-_]?key/i;
@@ -332,7 +341,22 @@ export class Logger {
     if (!Logger.consoleOutput) return;
     if (typeof window === "undefined")
       (process[entry.stream] as unknown as NodeJS.WriteStream | undefined)?.write(entry.message);
-    else console.log(entry.message);
+    else Logger.#writeBrowserConsole(entry.record, entry.message);
+  }
+
+  static #writeBrowserConsole(record: LogRecord, rendered: string) {
+    const level = record.level ?? "info";
+    const context = record.context ? `[${record.context}] ` : "";
+    const attrs = record.attrs ? ` ${Logger.formatAttrs(record.attrs)}` : "";
+    const text = Logger.#inNativeShell()
+      ? `[${record.name}] ${context}${record.message}${attrs}`
+      : rendered.replace(/\n+$/, "");
+    
+    console[consoleMethodMap[level]](text);
+  }
+  static #inNativeShell() {
+    const platform = (globalThis as { __AKAN_NATIVE__?: { platform?: string } }).__AKAN_NATIVE__?.platform;
+    return platform !== undefined && platform !== "web";
   }
   static #write(name: string | undefined, message: string, context: string, logLevel: LogLevel, attrs?: LogAttrs) {
     const stream = logLevel === "error" ? "stderr" : "stdout";
@@ -367,7 +391,7 @@ export class Logger {
     if (!Logger.consoleOutput) return;
     if (typeof window === "undefined" && method !== "console" && (process as unknown as NodeJS.Process | undefined))
       process[stream].write(msg);
-    else console[outputStream === "error" ? "error" : "log"](msg.trim());
+    else console[outputStream === "error" ? "error" : Logger.#inNativeShell() ? "debug" : "log"](msg.trim());
   }
   static {
     if (envValue("AKAN_PUBLIC_LOG_LEVEL") === "log" && typeof window === "undefined")

package/common/RouteLayering.ts

@@ -0,0 +1,52 @@
+interface LayeredRoute<Render> {
+  /** The tree segment: `/`, `/:lang`, `/(group)`, `/foo`. */
+  path: string;
+  renderLayout?: Render;
+  /** A generated `__root_layout`: one of the root boundaries the page generator found. */
+  isRootLayout?: boolean;
+  renderOverrides?: Render;
+  /** `false` for a named page file, which sits beside its directory's layout rather than under it. */
+  pageIncludesOwnLayout?: boolean;
+}
+
+export interface RouteLayer<Render> {
+  /** The URL pattern down to this node; a route group adds nothing to it. */
+  path: string;
+  pathSegments: string[];
+  isRoot: boolean;
+  /** The root layout above or at this node, overrides left out: once there is one, nothing below is a root. */
+  rootLayouts: Render[];
+  renderRootLayouts: Render[];
+  renderLayouts: Render[];
+  /** What a page file at this node renders inside: without this node's layout for a named page file. */
+  pageRenderRootLayouts: Render[];
+  pageRenderLayouts: Render[];
+}
+
+export class RouteLayering {
+  static readonly #group = /^\/\(.*\)$/;
+
+  static of<Render>(route: LayeredRoute<Render>, parent: RouteLayer<Render> | null): RouteLayer<Render> {
+    const parentSegments = parent?.pathSegments ?? [];
+    const parentRootLayouts = parent?.rootLayouts ?? [];
+    const parentRootRenders = parent?.renderRootLayouts ?? [];
+    const parentLayouts = parent?.renderLayouts ?? [];
+    const segment = RouteLayering.#group.test(route.path) ? "" : route.path;
+    const path = parentSegments.filter((part) => part !== "/").join("") + segment;
+    const isRoot = parentRootLayouts.length === 0 && (route.isRootLayout === true || !route.renderLayout);
+    const overrideRenders = route.renderOverrides ? [route.renderOverrides] : [];
+
+    const nodeRenders = [...overrideRenders, ...(route.renderLayout ? [route.renderLayout] : [])];
+    const pageNodeRenders = route.pageIncludesOwnLayout === false ? overrideRenders : nodeRenders;
+    return {
+      path,
+      pathSegments: [...parentSegments, ...(segment ? [segment] : [])],
+      isRoot,
+      rootLayouts: isRoot && route.renderLayout ? [...parentRootLayouts, route.renderLayout] : parentRootLayouts,
+      renderRootLayouts: isRoot ? [...parentRootRenders, ...nodeRenders] : parentRootRenders,
+      renderLayouts: isRoot ? parentLayouts : [...parentLayouts, ...nodeRenders],
+      pageRenderRootLayouts: isRoot ? [...parentRootRenders, ...pageNodeRenders] : parentRootRenders,
+      pageRenderLayouts: isRoot ? parentLayouts : [...parentLayouts, ...pageNodeRenders],
+    };
+  }
+}

package/common/index.ts

@@ -128,6 +128,7 @@ export {
 export { deepObjectify, objectify, plainFieldsOf } from "./objectify";
 export { pathGet, pathGetLoose, pathSet, toPathSegments } from "./objectPath";
 export { formatPhone, isPhoneNumber } from "./phone";
+export { type RouteLayer, RouteLayering } from "./RouteLayering";
 export { randomPick, randomPicks } from "./randomPick";
 export { hostFromRequest, isJsonContentType, originFromRequest } from "./requestOrigin";
 export { RestClient, type RestClientOptions, type RestRequestOptions } from "./restClient";