akanjs 3.0.0-beta.9 → 3.0.1

package/webkit/bootCsr.tsx

@@ -1,40 +1,11 @@
 "use client";
-import {
-  csrContext,
-  Device,
-  getExplicitPageConfigKeys,
-  getStoredAuthToken,
-  initAuth,
-  type LayoutModule,
-  type PageConfig,
-  type PathRoute,
-  type Route,
-  type RouteGuide,
-  type RouteModule,
-  type RouteModuleSource,
-  type RouteRender,
-  readCssSafeAreaInsets,
-  resolvePageState,
-  resolveRouteModule,
-  validatePageConfig,
-} from "akanjs/client";
-import {
-  assertUniqueRoutePatterns,
-  getRouteExports,
-  Logger,
-  parseAkanI18nEnv,
-  parseBasePaths,
-  parseRouteModuleKey,
-  routeSegmentToTreePath,
-} from "akanjs/common";
-import { createElement, memo, type ReactNode, useRef } from "react"; 
+import { csrContext, Device, getStoredAuthToken, initAuth } from "akanjs/client";
+import { Logger, parseAkanI18nEnv, parseBasePaths } from "akanjs/common";
+import { useSyncExternalStore } from "react";
 import * as ReactDOM from "react-dom/client";
+import { type CsrRouteContext, CsrRouteTable } from "./CsrRouteTable";
+import { RenderLayer } from "./RenderLayer";
 import { useCsrValues } from "./useCsrValues";
-import { useFetch } from "./useFetch";
-
-type RouteModuleWithConfig = RouteModule & { pageConfig?: PageConfig };
-type CsrRouteModuleLoader = () => Promise<RouteModuleSource>;
-type CsrRouteModuleEntry = CsrRouteModuleLoader | { loader: CsrRouteModuleLoader; isAsyncDefault?: boolean };
 
 declare global {
   interface Window {
@@ -42,54 +13,23 @@ declare global {
   }
 }
 
-interface RootRenderLayerProps {
-  renders: RouteRender[];
-  index: number;
-  params: Record<string, string>;
-  searchParams: Record<string, string | string[]>;
-}
-const RootRenderLayer = memo(({ renders, index, params, searchParams }: RootRenderLayerProps) => {
-  const isLast = index >= renders.length - 1;
-  const children = isLast ? null : (
-    <RootRenderLayer renders={renders} index={index + 1} params={params} searchParams={searchParams} />
-  );
-  const routeRender = renders[index];
-  const isAsyncRender = isAsyncRouteRender(routeRender);
-  const resultRef = useRef<ReactNode | Promise<ReactNode> | null>(null);
-  if (isAsyncRender && resultRef.current === null) {
-    resultRef.current = routeRender?.render({ children, params, searchParams } as never) ?? null;
-  }
-  const { fulfilled, value: Layout } = useFetch(resultRef.current);
-  if (!routeRender) return null;
-  if (!isAsyncRender) return createElement(routeRender.render as never, { children, params, searchParams } as never);
-  if (!fulfilled || !Layout) return <>{composeLoadingFallback(renders.slice(index), params)}</>;
-  return Layout;
-});
-
-function isAsyncRouteRender(routeRender?: RouteRender): boolean {
-  return Boolean(routeRender?.isAsync || routeRender?.render.constructor.name === "AsyncFunction");
-}
-
-function composeLoadingFallback(renders: RouteRender[], params: Record<string, string>): ReactNode {
-  let element: ReactNode = null;
-  for (let i = renders.length - 1; i >= 0; i--) {
-    const Loading = renders[i]?.Loading;
-    if (!Loading) continue;
-    element = Loading({ params, children: element } as never) as ReactNode;
-  }
-  return element;
-}
-
-export const bootCsr = async (context: Record<string, CsrRouteModuleEntry>) => {
+export const bootCsr = async (context: CsrRouteContext) => {
   const i18n = parseAkanI18nEnv();
   window.document.body.style.overflow = "hidden";
   initializeMobileTargetFromSearch();
-  const mobileBasePath = window.__AKAN_MOBILE_TARGET__?.basePath?.replace(/^\/+|\/+$/g, "");
-  const pathname = mobileBasePath && window.location.pathname === "/" ? `/${mobileBasePath}` : window.location.pathname;
-  if (pathname === "/404") return;
+  if (window.location.pathname === "/404") return;
 
   const [device, jwt] = await Promise.all([Device.load({ supportLanguages: i18n.locales }), getStoredAuthToken()]);
-  if (!window.__AKAN_MOBILE_TARGET__ && !pathname.startsWith(`/${device.lang}`))
+  const mobileTarget = window.__AKAN_MOBILE_TARGET__;
+  
+  if (mobileTarget && window.location.pathname === "/")
+    window.history.replaceState(
+      window.history.state,
+      "",
+      `${mobileHomePath(device.lang, mobileTarget)}${window.location.search}${window.location.hash}`,
+    );
+  const pathname = window.location.pathname;
+  if (!mobileTarget && !pathname.startsWith(`/${device.lang}`))
     window.location.replace(`/${device.lang}${pathname}${window.location.search}${window.location.hash}`);
 
   if (jwt) initAuth({ jwt });
@@ -99,190 +39,25 @@ export const bootCsr = async (context: Record<string, CsrRouteModuleEntry>) => {
   const currentBasePath = basePaths ? pathname.split("/")[2] : undefined;
   if (currentBasePath && basePaths && !basePaths.includes(currentBasePath))
     throw new Error(`Invalid path: ${pathname}`);
-  const baseLayoutPaths = ["/", "/:lang", ...(currentBasePath ? [`/:lang/${currentBasePath}`] : [])];
-  const otherBasePaths = basePaths?.filter((path) => path !== currentBasePath) ?? [];
-
-  const pages: { [key: string]: RouteModule } = {};
-  const asyncDefaultMap: { [key: string]: boolean | undefined } = {};
-  await Promise.all(
-    Object.entries(context).map(async ([key, value]) => {
-      const parsed = parseRouteModuleKey(key);
-      if (basePaths) {
-        const pageBasePath = parsed.sourceRouteSegments.find((segment) => !/^\(.+\)$/.test(segment));
-        if (pageBasePath && otherBasePaths.includes(pageBasePath)) return; 
-      }
-      const entry = typeof value === "function" ? { loader: value } : value;
-      const loaded = await entry.loader();
-      const pageContent =
-        parsed.kind === "overrides"
-          ? (loaded as RouteModule)
-          : resolveRouteModule(loaded, key, { kind: parsed.kind, pattern: parsed.pattern }).module;
-      validateRouteModuleExports(key, pageContent);
-      validatePageConfig(key, (pageContent as RouteModuleWithConfig).pageConfig);
-      asyncDefaultMap[key] = entry.isAsyncDefault;
-      
-      if (pageContent.default || parsed.kind === "overrides") pages[key] = pageContent;
-    }),
-  );
-  const cssSafeArea = readCssSafeAreaInsets();
-
-  const routeMap = new Map<string, Route>();
-  routeMap.set("/", { path: "/", children: new Map() });
-  const pagePatterns: { key: string; pattern: string }[] = [];
-  for (const filePath of Object.keys(pages)) {
-    const parsed = parseRouteModuleKey(filePath);
-    if (parsed.kind === "page") pagePatterns.push({ key: filePath, pattern: parsed.pattern });
-    const pathSegments = ["/", ...parsed.routeSegments.map(routeSegmentToTreePath)];
-
-    const targetRouteMap = pathSegments.slice(0, -1).reduce((rMap: Map<string, Route>, path: string) => {
-      if (!rMap.has(path)) rMap.set(path, { path, children: new Map() });
-      const children = rMap.get(path)?.children;
-      if (!children) throw new Error("No children");
-      return children;
-    }, routeMap);
-    if (!targetRouteMap) continue;
 
-    const targetPath = pathSegments[pathSegments.length - 1];
-    if (!targetPath) continue;
-    const page = pages[filePath];
-    if (!page) continue;
-    if (parsed.kind === "overrides") {
-      
-      const overridesRender: RouteRender = {
-        render: page.default as never,
-        isAsync: asyncDefaultMap[filePath] || page.default?.constructor.name === "AsyncFunction",
-      };
-      targetRouteMap.set(targetPath, {
-        ...(targetRouteMap.get(targetPath) ?? { path: targetPath, children: new Map<string, Route>() }),
-        renderOverrides: overridesRender,
-      } as Route);
-      continue;
-    }
-    const layoutPage = parsed.kind === "layout" ? (page as LayoutModule) : null;
-    const routeRender: RouteRender = {
-      render: page.default as never,
-      isAsync: asyncDefaultMap[filePath] || page.default?.constructor.name === "AsyncFunction",
-      Loading: page.Loading as never,
-      NotFound: layoutPage?.NotFound,
-      Error: layoutPage?.Error,
-      resolveNotFound: layoutPage ? () => layoutPage.NotFound : undefined,
-      resolveError: layoutPage ? () => layoutPage.Error : undefined,
-    };
-    targetRouteMap.set(targetPath, {
-
-      ...(targetRouteMap.get(targetPath) ?? { path: targetPath, children: new Map<string, Route>() }),
-      ...(parsed.kind === "layout"
-        ? { renderLayout: routeRender, layoutPageConfig: (page as RouteModuleWithConfig).pageConfig }
-        : {
-            renderPage: routeRender,
-            pageIncludesOwnLayout: parsed.leaf === "_index",
-            isSpecialRoute: parsed.isSpecialRoute,
-            pageConfig: (page as RouteModuleWithConfig).pageConfig,
-            PageConfig: (page as RouteModuleWithConfig).pageConfig,
-          }),
-    } as Route);
-  }
-  assertUniqueRoutePatterns(pagePatterns);
-  const getPathRoutes = (
-    route: Route,
-    parentRootLayouts: RouteRender[] = [],
-    parentLayouts: RouteRender[] = [],
-    parentPaths: string[] = [],
-    parentPageConfigChain: PageConfig[] = [],
-    parentOverrides: RouteRender[] = [],
-  ): PathRoute[] => {
-    const parentPath = parentPaths.filter((path) => path !== "/").join("");
-    const isRouteGroup = /^\/\(.*\)$/.test(route.path);
-    const currentPathSegment = isRouteGroup ? "" : route.path;
-    const path = parentPath + currentPathSegment;
-    const isRoot = !isRouteGroup && baseLayoutPaths.includes(path);
-    const pathSegments = [...parentPaths, ...(currentPathSegment ? [currentPathSegment] : [])];
-    const currentRootLayout = isRoot && route.renderLayout ? route.renderLayout : null;
-    const currentLayout = !isRoot && route.renderLayout ? route.renderLayout : null;
-    const currentLayoutConfig = route.renderLayout && route.layoutPageConfig ? route.layoutPageConfig : null;
-
-    const currentOverrideRenders = route.renderOverrides ? [route.renderOverrides] : [];
-    const overrideRenders = [...parentOverrides, ...currentOverrideRenders];
-    const rootLayoutStack = [...parentRootLayouts, ...(currentRootLayout ? [currentRootLayout] : [])];
-    const renderRootLayouts = [...overrideRenders, ...rootLayoutStack];
-    const renderLayouts = [...parentLayouts, ...(currentLayout ? [currentLayout] : [])];
-    const pageConfigChain = [
-      ...parentPageConfigChain,
-      ...(currentRootLayout || currentLayout ? (currentLayoutConfig ? [currentLayoutConfig] : []) : []),
-    ];
-    const pageRenderRootLayouts =
-      route.pageIncludesOwnLayout === false && currentRootLayout
-        ? [...overrideRenders, ...parentRootLayouts]
-        : renderRootLayouts;
-    const pageRenderLayouts = route.pageIncludesOwnLayout === false && currentLayout ? parentLayouts : renderLayouts;
-    const pageRenderConfigChain =
-      route.pageIncludesOwnLayout === false && (currentRootLayout || currentLayout)
-        ? parentPageConfigChain
-        : pageConfigChain;
-    const ownPageConfig = route.renderPage && route.pageConfig ? route.pageConfig : null;
-    const finalPageConfigChain = [...pageRenderConfigChain, ...(ownPageConfig ? [ownPageConfig] : [])];
-    const pageState = resolvePageState({
-      configChain: finalPageConfigChain,
-      path,
-      basePath: currentBasePath,
-      platform: device.info.platform,
-      deviceSafeArea: { top: device.topSafeArea, bottom: device.bottomSafeArea },
-      cssSafeArea,
-    });
-    return [
-      ...(route.renderPage
-        ? [
-            {
-              path,
-              pathSegments,
-              renderPage: route.renderPage,
-              renderRootLayouts: pageRenderRootLayouts,
-              renderLayouts: pageRenderLayouts,
-              isSpecialRoute: route.isSpecialRoute,
-              pageState: route.pageState ?? pageState,
-              pageConfigChain: finalPageConfigChain,
-              explicitPageConfigKeys: getExplicitPageConfigKeys(finalPageConfigChain),
-            },
-          ]
-        : []),
-      ...(route.children.size
-        ? [...route.children.values()].flatMap((child) =>
-            getPathRoutes(child, rootLayoutStack, renderLayouts, pathSegments, pageConfigChain, overrideRenders),
-          )
-        : []),
-    ];
-  };
-  const rootRoute = routeMap.get("/");
-  if (!rootRoute) throw new Error("No root route");
-  const pathRoutes = getPathRoutes(rootRoute);
-  const routeGuide: RouteGuide = { pathSegment: "/", children: {} };
-  pathRoutes.forEach((pathRoute) => {
-    const pathSegments = pathRoute.pathSegments.slice(1);
-    pathSegments.reduce((routeGuide: RouteGuide, pathSegment: string, index: number) => {
-      const child = routeGuide.children[pathSegment] as RouteGuide | undefined;
-      const next: RouteGuide = {
-        ...(child ?? {}),
-        pathSegment,
-        ...(index === pathSegments.length - 1 ? { pathRoute } : {}),
-        children: (child?.children as { [key: string]: RouteGuide } | undefined) ?? {},
-      } as RouteGuide;
-      routeGuide.children[pathSegment] = next;
-      return next;
-    }, routeGuide);
-  });
+  const table = await CsrRouteTable.boot(context, { device, basePaths, currentBasePath });
   const RouterProvider = () => {
+    const { pathRoutes, routeGuide } = useSyncExternalStore(table.subscribe, table.snapshot);
     const csrValues = useCsrValues(routeGuide, pathRoutes);
     const { location } = csrValues;
+
+    if (location.pathRoute.renderRootLayouts.length === 0)
+      throw new Error(
+        `[csr] no root layout for ${location.pathRoute.path}: the route table put none of its layouts at the root`,
+      );
     return (
       <csrContext.Provider value={csrValues}>
-        {location.pathRoute.renderRootLayouts.length > 0 ? (
-          <RootRenderLayer
-            renders={location.pathRoute.renderRootLayouts}
-            index={0}
-            params={location.params}
-            searchParams={location.searchParams}
-          />
-        ) : null}
+        <RenderLayer
+          renders={location.pathRoute.renderRootLayouts}
+          index={0}
+          params={location.params}
+          searchParams={location.searchParams}
+        />
       </csrContext.Provider>
     );
   };
@@ -293,6 +68,12 @@ export const bootCsr = async (context: Record<string, CsrRouteModuleEntry>) => {
   root.render(<RouterProvider />);
 };
 
+/**
+ * Swaps the route modules of a running CSR bundle — what a dev server calls when a page, layout or overrides module
+ * changed. History, mounted pages and stores stay; `false` means the set of routes changed and the page must reload.
+ */
+export const replacePages = async (context: CsrRouteContext) => (await CsrRouteTable.active?.replace(context)) ?? false;
+
 function initializeMobileTargetFromSearch() {
   if (window.__AKAN_MOBILE_TARGET__) return;
 
@@ -305,32 +86,9 @@ function initializeMobileTargetFromSearch() {
   window.__AKAN_MOBILE_TARGET__ = { name, basePath, ...(indexPath ? { indexPath } : {}) };
 }
 
-function validateRouteModuleExports(key: string, mod: RouteModule) {
-  const parsed = parseRouteModuleKey(key);
-  if (parsed.kind === "overrides") {
-    
-    if (!mod.default) throw new Error(`[route-convention] ${key} generated override wrapper has no default export`);
-    return;
-  }
-  const allowed = getRouteExports(parsed.kind, { rootLayout: parsed.isInternalRootLayout });
-  for (const exportName of Object.keys(mod)) {
-    if (!allowed.has(exportName)) {
-      throw new Error(`[route-convention] unsupported export "${exportName}" in ${key}`);
-    }
-  }
-  if ("head" in mod && "generateHead" in mod) {
-    throw new Error(`[route-convention] head and generateHead cannot both be exported in ${key}`);
-  }
-  if (
-    !parsed.isInternalRootLayout &&
-    ("head" in mod || "generateHead" in mod) &&
-    ("metadata" in mod || "generateMetadata" in mod)
-  ) {
-    throw new Error(
-      `[route-convention] head/generateHead and metadata/generateMetadata cannot both be exported in ${key}`,
-    );
-  }
-  if ("metadata" in mod && "generateMetadata" in mod) {
-    throw new Error(`[route-convention] metadata and generateMetadata cannot both be exported in ${key}`);
-  }
+function mobileHomePath(lang: string, target: { basePath?: string; indexPath?: string }) {
+  const segments = [lang, target.basePath, target.indexPath]
+    .flatMap((part) => (part ?? "").split("/"))
+    .filter((segment) => segment.length > 0);
+  return `/${segments.join("/")}`;
 }

package/webkit/csrFrameDump.ts

@@ -0,0 +1,67 @@
+"use client";
+
+interface LayerRecord {
+  layer: string;
+  status: "pending" | "settled" | "failed";
+  startedAt: number;
+  settledAt: number | null;
+  /** A mounted layer is waiting on this render's promise; false once it unmounts or its Activity hides. */
+  subscribed: boolean;
+  /** The layer has drawn this render's value. */
+  delivered: boolean;
+}
+
+interface FrameState {
+  phase: string;
+  location: string;
+  prevLocation: string | null;
+  pendingLocation: string | null;
+  stack: { key: string; path: string; pageType: string }[];
+}
+
+export class CsrFrameDump {
+  static readonly limit = 300;
+  static readonly #layers: LayerRecord[] = [];
+  static #frame: (() => FrameState) | null = null;
+
+  static track(layer: string, result: Promise<unknown>): LayerRecord {
+    const record: LayerRecord = {
+      layer,
+      status: "pending",
+      startedAt: Math.round(performance.now()),
+      settledAt: null,
+      subscribed: false,
+      delivered: false,
+    };
+    CsrFrameDump.#layers.push(record);
+    if (CsrFrameDump.#layers.length > CsrFrameDump.limit) CsrFrameDump.#layers.shift();
+    const settle = (status: LayerRecord["status"]) => {
+      record.status = status;
+      record.settledAt = Math.round(performance.now());
+    };
+    result.then(
+      () => settle("settled"),
+      () => settle("failed"),
+    );
+    CsrFrameDump.#install();
+    return record;
+  }
+
+  static watchFrame(read: () => FrameState) {
+    CsrFrameDump.#frame = read;
+    CsrFrameDump.#install();
+  }
+
+  static dump() {
+    return {
+      now: Math.round(performance.now()),
+      frame: CsrFrameDump.#frame?.() ?? null,
+      layers: CsrFrameDump.#layers.map((record) => ({ ...record })),
+    };
+  }
+
+  static #install() {
+    if (typeof window === "undefined") return;
+    (window as { __AKAN_DUMP_FRAME__?: () => unknown }).__AKAN_DUMP_FRAME__ = CsrFrameDump.dump;
+  }
+}

package/webkit/index.ts

@@ -1,12 +1,9 @@
-export { bootCsr } from "./bootCsr";
-export { createRobotPage } from "./createRobotPage";
-export { createSitemapPage } from "./createSitemapPage";
+export { bootCsr, replacePages } from "./bootCsr";
 export { lazy } from "./lazy";
+export { createRobotPage, createSitemapPage } from "./seoPages";
 export type * from "./types";
 export { useBodyScrollLock } from "./useBodyScrollLock";
 export { useCamera } from "./useCamera";
-export { useCodepush } from "./useCodepush";
-export { useContact } from "./useContact";
 export { useCsrValues } from "./useCsrValues";
 export { useDebounce } from "./useDebounce";
 export { useEscapeKey } from "./useEscapeKey";
@@ -15,6 +12,9 @@ export { useGeoLocation } from "./useGeoLocation";
 export { useHistory } from "./useHistory";
 export { useInterval } from "./useInterval";
 export { useLocation } from "./useLocation";
+export { usePageActivity } from "./usePageActivity";
+export { usePageFocusEffect } from "./usePageFocusEffect";
+export { usePageLocation } from "./usePageLocation";
 export { usePageTool } from "./usePageTool";
 export type { ScreenScopeItem } from "./useScreenScope";
 export { useScreenScope } from "./useScreenScope";

package/webkit/lazy.tsx

@@ -5,17 +5,8 @@ import { forwardRef, lazy as reactLazy } from "react";
 
 const isServer = typeof window === "undefined";
 
-/**
- * `suspense` puts a Suspense boundary around the lazy component, so a chunk that resolves *after* the
- * page is painted — a modal body, a dropdown menu — suspends only itself. Without one the suspension
- * travels up to the nearest boundary, which is the route (`server/routeElementComposer.tsx`), and the
- * whole page repaints as its loading fallback on the first open.
- *
- * It is opt-in rather than the default because a boundary also changes server rendering: under the
- * default `renderMode: "stream"` the boundary's subtree leaves the shell as `loading` and arrives later
- * in the stream. That is fine for an interaction shell and wrong for a page body, which SEO snapshots,
- * prerendering and pre-hydration E2E read out of the shell.
- */
+/** `suspense`: a late chunk suspends only itself, not the route. Opt-in: under streaming the boundary's subtree
+ * leaves the shell, which SEO snapshots, prerendering and pre-hydration E2E read. */
 type LazyOption = { ssr?: boolean; suspense?: boolean; loading?: () => ReactNode };
 type LazyProps = Record<string, unknown>;
 type LoadedOf<Loaded> = Loaded extends { default: infer T } ? T : Loaded;
@@ -26,7 +17,7 @@ const normalizeLazyModule = <Loaded,>(loaded: Loaded): LazyModule => {
   return { default: loaded as ComponentType<LazyProps> };
 };
 
-/** React lazy wrapper with Akan's `ssr: false` server stub and client mount gate. */
+/** `ssr: false` renders `loading` on the server and mounts the component only after hydration. */
 export const lazy = <Loaded,>(loader: () => Promise<Loaded>, option?: LazyOption): LoadedOf<Loaded> => {
   const ssrFalse = option?.ssr === false;
   const renderFallback = (): ReactNode => (option?.loading ? option.loading() : null);
@@ -38,7 +29,6 @@ export const lazy = <Loaded,>(loader: () => Promise<Loaded>, option?: LazyOption
   const LazyInner = reactLazy(async () => normalizeLazyModule(await loader()));
 
   if (!ssrFalse) {
-
     const Wrapper = forwardRef<unknown, LazyProps>((props, ref) =>
       option?.suspense ? (
         <React.Suspense fallback={renderFallback()}>