akanjs 2.3.6-rc.2 → 2.3.6-rc.3

package/server/hmr/wsHub.ts

@@ -22,6 +22,7 @@ export type HmrMessage =
       routeIds?: string[];
     }
   | { type: "css-update"; cssAssets?: Record<string, { cssUrl: string; cssRelPath: string }> }
+  | { type: "sync-navigation"; clientId: string; href: string; kind?: "push" | "replace" | "back" | "pop" }
   | { type: "ok"; generation?: number }
   | {
       type: "build-status";
@@ -63,4 +64,32 @@ export class HmrWsHub {
     const payload = JSON.stringify(msg);
     this.#publish?.(HMR_WS_TOPIC, payload);
   }
+
+  handleMessage(message: string): void {
+    if (!isSyncNavigationEnabled()) return;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(message);
+    } catch {
+      return;
+    }
+    if (!isSyncNavigationMessage(parsed)) return;
+    this.broadcast(parsed);
+  }
 }
+
+const isSyncNavigationEnabled = () =>
+  process.env.AKAN_PUBLIC_SYNC_NAVIGATION === "true" ||
+  process.env.AKAN_PUBLIC_SYNC_NAVIGATION === "1" ||
+  process.env.SYNC_DOMAIN === "true" ||
+  process.env.SYNC_DOMAIN === "1";
+
+const isSyncNavigationMessage = (value: unknown): value is Extract<HmrMessage, { type: "sync-navigation" }> => {
+  if (!value || typeof value !== "object") return false;
+  const msg = value as Partial<Extract<HmrMessage, { type: "sync-navigation" }>>;
+  if (msg.type !== "sync-navigation") return false;
+  if (typeof msg.clientId !== "string" || msg.clientId.length === 0) return false;
+  if (typeof msg.href !== "string" || msg.href.length === 0) return false;
+  if (msg.kind === undefined) return true;
+  return msg.kind === "push" || msg.kind === "replace" || msg.kind === "back" || msg.kind === "pop";
+};

package/server/routeElementComposer.tsx

@@ -2,11 +2,13 @@ import type {
   Head,
   LayoutErrorRender,
   LayoutFallbackRoute,
+  PageConfig,
   LayoutNotFoundRender,
   PathRoute,
   ResolvedHead,
   RouteRender,
 } from "akanjs/client";
+import { getExplicitPageConfigKeys, resolvePageState } from "../client/frameConfig";
 import { Children, cloneElement, isValidElement, type ReactElement, type ReactNode, Suspense } from "react";
 import { resolveHeadResult } from "./metadata";
 import { type AkanRouteSegmentState, createAkanRouteSegments, createAkanSegmentOutletKey } from "./routeState";
@@ -14,6 +16,47 @@ import { isAkanRscPartialCommitEnabled } from "./rscPartialCommit";
 import { AkanSegmentOutletReference } from "./rscSegmentOutletReference";
 
 export class RouteElementComposer {
+  static async resolveSsrFramePathRoute({
+    pathRoute,
+    basePath,
+  }: {
+    pathRoute: PathRoute;
+    basePath?: string | null;
+  }): Promise<PathRoute> {
+    const pageConfigChain = await RouteElementComposer.#resolvePageConfigChain(pathRoute);
+    return {
+      ...pathRoute,
+      pageState: resolvePageState({
+        configChain: pageConfigChain,
+        path: pathRoute.path,
+        basePath: basePath ?? undefined,
+        platform: "web",
+        deviceSafeArea: { top: 0, bottom: 0 },
+        cssSafeArea: { top: 0, bottom: 0 },
+      }),
+      pageConfigChain,
+      explicitPageConfigKeys: getExplicitPageConfigKeys(pageConfigChain),
+    };
+  }
+
+  static async resolveSsrFallbackFrameState({
+    route,
+    basePath,
+  }: {
+    route: PathRoute | LayoutFallbackRoute;
+    basePath?: string | null;
+  }) {
+    const pageConfigChain = await RouteElementComposer.#resolveLayoutPageConfigChain(route);
+    return resolvePageState({
+      configChain: pageConfigChain,
+      path: route.path,
+      basePath: basePath ?? undefined,
+      platform: "web",
+      deviceSafeArea: { top: 0, bottom: 0 },
+      cssSafeArea: { top: 0, bottom: 0 },
+    });
+  }
+
   static compose({
     pathRoute,
     params,
@@ -231,6 +274,19 @@ export class RouteElementComposer {
     return [...pathRoute.renderRootLayouts, ...pathRoute.renderLayouts, pathRoute.renderPage];
   }
 
+  static async #resolveLayoutPageConfigChain(route: PathRoute | LayoutFallbackRoute): Promise<PageConfig[]> {
+    const configs = await Promise.all(
+      [...route.renderRootLayouts, ...route.renderLayouts].map((render) => render.getLayoutPageConfig?.()),
+    );
+    return configs.filter((config): config is PageConfig => Boolean(config));
+  }
+
+  static async #resolvePageConfigChain(pathRoute: PathRoute): Promise<PageConfig[]> {
+    const layoutConfigs = await RouteElementComposer.#resolveLayoutPageConfigChain(pathRoute);
+    const pageConfig = await pathRoute.renderPage.getPageConfig?.();
+    return [...layoutConfigs, ...(pageConfig ? [pageConfig] : [])];
+  }
+
   static #composeLoadingFallback(renders: RouteRender[], params: Record<string, string>): ReactNode {
     let element: ReactNode = null;
     for (let i = renders.length - 1; i >= 0; i--) {

package/server/routeTreeBuilder.ts

@@ -18,6 +18,7 @@ import {
   parseRouteModuleKey,
   routeSegmentToTreePath,
 } from "akanjs/common";
+import { validatePageConfig } from "../client/frameConfig";
 import { resolveHeadExport, resolveMetadataHead } from "./metadata";
 
 export type PagesContext = Record<string, () => Promise<RouteModule>>;
@@ -55,6 +56,7 @@ export class RouteTreeBuilder {
   ]);
   static readonly #rootLayoutExports = new Set([
     "default",
+    "pageConfig",
     "head",
     "metadata",
     "generateHead",
@@ -72,6 +74,7 @@ export class RouteTreeBuilder {
   ]);
   static readonly #layoutRouteExports = new Set([
     "default",
+    "pageConfig",
     "head",
     "metadata",
     "generateHead",
@@ -271,6 +274,7 @@ export class RouteTreeBuilder {
       RouteTreeBuilder.#moduleCacheStats.cacheMisses += 1;
       const mod = await loader();
       RouteTreeBuilder.#validateRouteModuleExports(key, kind, mod);
+      validatePageConfig(key, "pageConfig" in mod ? mod.pageConfig : undefined);
       if (!loaded) {
         RouteTreeBuilder.#moduleCacheStats.loadedModuleCount += 1;
         RouteTreeBuilder.#moduleCacheStats.loadedModuleKeys.push(key);
@@ -354,6 +358,10 @@ export class RouteTreeBuilder {
         return "pageConfig" in mod ? mod.pageConfig : undefined;
       };
     } else {
+      routeRender.getLayoutPageConfig = async () => {
+        const mod = await loadModule();
+        return "pageConfig" in mod ? mod.pageConfig : undefined;
+      };
       routeRender.resolveNotFound = async () => {
         const mod = (await loadModule()) as LayoutModule;
         routeRender.NotFound = mod.NotFound;

package/server/routing/apiRouter.ts

@@ -130,7 +130,10 @@ export class ApiRouter {
       },
       message: async (ws, message) => {
         const data = ws.data as WsTaggedData | undefined;
-        if (data?.kind === "akan-hmr") return; 
+        if (data?.kind === "akan-hmr") {
+          if (typeof message === "string" && typeof hmrHub?.handleMessage === "function") hmrHub.handleMessage(message);
+          return;
+        }
         try {
           if (typeof message === "string") {
             const msg = JSON.parse(message) as WebsocketReqData;

package/server/rscClient.tsx

@@ -47,6 +47,9 @@ declare global {
     | undefined;
   var __AKAN_RSC_REFRESH__: ((options?: { buildId?: number }) => Promise<void>) | undefined;
   var __AKAN_RSC_CLEAR_CACHE__: (() => void) | undefined;
+  var __AKAN_DEV_SYNC_NAVIGATION__: ((href: string, kind: "push" | "replace" | "back" | "pop") => void) | undefined;
+  var __AKAN_DEV_SYNC_NAVIGATION_APPLYING__: boolean | undefined;
+  var __AKAN_GET_SYNC_ROUTE_HREF__: ((href: string) => string) | undefined;
 }
 
 function decodeBase64(b64: string): Uint8Array {
@@ -514,6 +517,11 @@ function Root(): ReactNode {
 
 window.addEventListener("popstate", () => {
   void globalThis.__AKAN_RSC_NAVIGATE__?.(window.location.href, { replace: true, scrollToTop: false });
+  window.setTimeout(() => {
+    if (globalThis.__AKAN_DEV_SYNC_NAVIGATION_APPLYING__) return;
+    const href = globalThis.__AKAN_GET_SYNC_ROUTE_HREF__?.(window.location.href) ?? window.location.href;
+    globalThis.__AKAN_DEV_SYNC_NAVIGATION__?.(href, "pop");
+  }, 0);
 });
 
 const hydrate = () => hydrateRoot(document, createElement(Root));

package/server/rscWorker.tsx

@@ -12,6 +12,7 @@ import {
   getRequestPolicy,
   getRequestTheme,
   requestStorage,
+  setRequestFrameState,
   untrackedCookies,
   untrackedRequest,
   updateRequestPolicy,
@@ -1164,6 +1165,12 @@ export class RscRenderer {
     error?: unknown;
     digest?: string;
   }): Promise<ReactNode | null> {
+    setRequestFrameState(
+      await RouteElementComposer.resolveSsrFallbackFrameState({
+        route,
+        basePath: this.#getBasePath(url),
+      }),
+    );
     const body = await RouteElementComposer.composeFallback({
       kind,
       route,
@@ -1218,17 +1225,22 @@ export class RscRenderer {
     this.#logger.verbose(
       `composing route element pathname=${url.pathname} search=${url.search || "(none)"} params=${JSON.stringify(match.params)}`,
     );
-    const routeHead = await RouteElementComposer.resolveHeadWithMetadata({
+    const pathRoute = await RouteElementComposer.resolveSsrFramePathRoute({
       pathRoute: match.pathRoute,
+      basePath: this.#getBasePath(url),
+    });
+    setRequestFrameState(pathRoute.pageState);
+    const routeHead = await RouteElementComposer.resolveHeadWithMetadata({
+      pathRoute,
       params: match.params,
       searchParams,
     });
     const routeHeadSnapshot = this.#createRouteHeadSnapshot(url, routeHead, {
-      isSpecialRoute: match.pathRoute.isSpecialRoute,
+      isSpecialRoute: pathRoute.isSpecialRoute,
       hasExplicitLanguageAlternates: routeHead.hasExplicitLanguageAlternates,
     });
     const body = RouteElementComposer.compose({
-      pathRoute: match.pathRoute,
+      pathRoute,
       params: match.params,
       searchParams,
     });
@@ -1245,7 +1257,7 @@ export class RscRenderer {
             : (routeHead.node ?? this.#renderDefaultHead())}
           {!routeHeadSnapshot &&
           shouldRenderLocaleAlternates({
-            isSpecialRoute: match.pathRoute.isSpecialRoute,
+            isSpecialRoute: pathRoute.isSpecialRoute,
             hasExplicitLanguageAlternates: routeHead.hasExplicitLanguageAlternates,
           })
             ? this.#renderLocaleAlternates(url)
@@ -1266,8 +1278,13 @@ export class RscRenderer {
     this.#logger.verbose(
       `composing route suffix pathname=${url.pathname} start=${patchStartIndex} params=${JSON.stringify(match.params)}`,
     );
-    return RouteElementComposer.composeSuffix({
+    const pathRoute = await RouteElementComposer.resolveSsrFramePathRoute({
       pathRoute: match.pathRoute,
+      basePath: this.#getBasePath(url),
+    });
+    setRequestFrameState(pathRoute.pageState);
+    return RouteElementComposer.composeSuffix({
+      pathRoute,
       params: match.params,
       searchParams,
       patchStartIndex,
@@ -1315,6 +1332,14 @@ export class RscRenderer {
     return <title key="title">{process.env.AKAN_PUBLIC_APP_NAME ?? "Akan App"}</title>;
   }
 
+  #getBasePath(url: URL): string | null {
+    return getBasePathFromPathname(url.pathname, {
+      basePaths: this.#basePaths,
+      i18n: this.#i18n,
+      headerBasePath: untrackedRequest()?.headers.get("x-base-path"),
+    });
+  }
+
   async #resolveRouteHeadSnapshot(
     url: URL,
     match: { pathRoute: PathRoute; params: Record<string, string> },

package/store/baseSt.ts

@@ -44,8 +44,8 @@ export class BaseStore extends store("base" as const, () => ({
     bottomInset: 0,
     gesture: true,
     cache: false,
-    topSafeAreaColor: "transparent",
-    bottomSafeAreaColor: "transparent",
+    topSafeAreaColor: "var(--color-base-100, Canvas)",
+    bottomSafeAreaColor: "var(--color-base-100, Canvas)",
   } as PageState,
   devMode: false,
   deviceToken: "" as string,

package/types/client/capacitor.d.ts

@@ -12,6 +12,7 @@ export type CapacitorAppModule = {
     App: {
         addListener: (eventName: string, listenerFunc: (...args: unknown[]) => void) => Promise<unknown> | unknown;
         removeAllListeners: () => Promise<void> | void;
+        exitApp?: () => Promise<void> | void;
         getInfo: () => Promise<{
             id: string;
             version: string;
@@ -128,6 +129,9 @@ export type CapacitorKeyboardModule = {
     Keyboard: {
         show: () => Promise<void> | void;
         hide: () => Promise<void> | void;
+        setResizeMode?: (options: {
+            mode: "body" | "ionic" | "native" | "none";
+        }) => Promise<void> | void;
         addListener: (eventName: string, listenerFunc: (info: CapacitorKeyboardInfo) => void) => Promise<unknown> | unknown;
         removeAllListeners: () => Promise<void> | void;
     };

package/types/client/csrTypes.d.ts

@@ -5,15 +5,19 @@ import type { AnimatedComponent, AnimatedProps, Interpolation, SpringValue } fro
 import type { RouterInstance } from "./router.d.ts";
 import type { ReactFont } from "./types.d.ts";
 export type TransitionType = "none" | "fade" | "bottomUp" | "stack" | "scaleOut";
+export type PageSafeAreaConfig = boolean | "top" | "bottom" | {
+    top?: boolean;
+    bottom?: boolean;
+    android?: "auto" | "edge-to-edge" | "none";
+};
 /** Per-page CSR configuration for transition, safe-area, and gesture behavior. */
 export interface PageConfig {
     transition?: TransitionType;
-    safeArea?: boolean | "top" | "bottom";
-    topInset?: boolean | number;
-    /**
-     * @default 48px
-     */
-    bottomInset?: boolean | number;
+    safeArea?: PageSafeAreaConfig;
+    /** Top chrome reservation in px. Use 0 or omit for no reservation. */
+    topInset?: number;
+    /** Bottom chrome reservation in px. Use 0 or omit for no reservation. */
+    bottomInset?: number;
     gesture?: boolean;
     cache?: boolean;
     /**
@@ -100,6 +104,7 @@ export interface RouteRender {
     resolveError?: () => PromiseOrObject<LayoutErrorRender | undefined>;
     resolveHead?: ResolveHead;
     getPageConfig?: () => PromiseOrObject<PageConfig | undefined>;
+    getLayoutPageConfig?: () => PromiseOrObject<PageConfig | undefined>;
 }
 export interface WebAppManifestIcon {
     src: string;
@@ -161,6 +166,7 @@ export interface PageModule {
 }
 export interface LayoutModule {
     default?: LayoutRender;
+    pageConfig?: PageConfig;
     head?: Head;
     metadata?: AkanMetadata;
     generateHead?: GenerateHead;
@@ -179,6 +185,8 @@ export interface LayoutModule {
 export type RouteModule = PageModule | LayoutModule;
 export interface Route {
     PageConfig?: PageConfig;
+    pageConfig?: PageConfig;
+    layoutPageConfig?: PageConfig;
     path: string;
     renderPage?: RouteRender;
     renderLayout?: RouteRender;
@@ -186,6 +194,8 @@ export interface Route {
     isSpecialRoute?: boolean;
     loader?: () => unknown;
     pageState?: PageState;
+    pageConfigChain?: PageConfig[];
+    explicitPageConfigKeys?: Partial<Record<keyof PageConfig, boolean>>;
     children: Map<string, Route>;
 }
 export type AnimatedDivProps = AnimatedComponent<"div"> extends ForwardRefExoticComponent<AnimatedProps<infer P>> ? P : never;
@@ -229,9 +239,23 @@ export interface Location {
     pathRoute: PathRoute;
     hash: string;
 }
+export type CsrNavigationPhase = "idle" | "preparing" | "transitioning";
+export type CsrNavigationKind = "push" | "replace" | "back" | "popForward" | "popBack";
+export interface NavigationIntent {
+    id: number;
+    kind: CsrNavigationKind;
+    from: Location;
+    to: Location;
+    scrollTop: number;
+    scrollToTop?: boolean;
+    createdAt: number;
+}
 export interface LocationState {
     location: Location;
     prevLocation: Location | null;
+    pendingLocation?: Location | null;
+    navigationIntent?: NavigationIntent | null;
+    phase: CsrNavigationPhase;
 }
 export interface History {
     type: "initial" | "forward" | "back";
@@ -252,6 +276,9 @@ export interface RouteState {
     clientHeight: number;
     location: Location;
     prevLocation: Location | null;
+    pendingLocation: Location | null;
+    navigationIntent: NavigationIntent | null;
+    phase: CsrNavigationPhase;
     history: RefObject<History>;
     topSafeAreaRef: RefObject<HTMLDivElement | null>;
     bottomSafeAreaRef: RefObject<HTMLDivElement | null>;
@@ -263,6 +290,8 @@ export interface RouteState {
     }>;
     router: RouterInstance;
     pathRoutes: PathRoute[];
+    registerFrameSlot: (path: string, slot: FrameSlotRegistration, bucket?: FrameSlotBucket) => () => void;
+    frameLayout: FrameLayoutState;
 }
 export type UseCsrTransition = CsrTransitionStyles & {
     pageBind: (...args: unknown[]) => ReactDOMAttributes;
@@ -277,11 +306,12 @@ export type CsrContextType = RouteState & UseCsrTransition;
 export declare const csrContext: import("react").Context<CsrContextType>;
 export declare const useCsr: () => CsrContextType;
 export interface PathContextType {
-    pageType: "current" | "prev" | "cached";
+    pageType: "current" | "prev" | "cached" | "pending";
     location: Location;
     prefix?: string;
     gestureEnabled: boolean;
     setGestureEnabled: (enabled: boolean) => void;
+    registerFrameSlot: (slot: FrameSlotRegistration) => () => void;
 }
 export declare const pathContext: import("react").Context<PathContextType>;
 export declare const usePathCtx: () => PathContextType;
@@ -290,11 +320,99 @@ export interface PathRoute {
     pathSegments: string[];
     renderPage: RouteRender;
     pageState: PageState;
+    pageConfigChain?: PageConfig[];
+    explicitPageConfigKeys?: Partial<Record<keyof PageConfig, boolean>>;
     renderRootLayouts: RouteRender[];
     renderLayouts: RouteRender[];
     resolveHead?: ResolveHead;
     isSpecialRoute?: boolean;
 }
+export type FrameSlotScope = "page" | "layout";
+export type FrameSlotType = "topInset" | "bottomInset";
+export type FrameSlotBucket = "active" | "pending";
+export type FrameLayer = "page" | "topChrome" | "bottomChrome" | "keyboard" | "overlay";
+export type FrameSlotRole = "topChrome" | "bottomChrome" | "keyboardAccessory";
+export type FramePlatformProfile = "ios" | "android" | "web" | "mobileWeb";
+export interface FrameViewportState {
+    width: number;
+    height: number;
+    visualWidth: number;
+    visualHeight: number;
+    visualOffsetTop: number;
+}
+export interface KeyboardFrameState {
+    height: number;
+    offset: number;
+    visible: boolean;
+    sticky: boolean;
+    frozen?: boolean;
+    source?: "native" | "visualViewport" | "fallback";
+    animationDuration?: number;
+    animationEasing?: string;
+}
+export interface FrameContentViewportState {
+    top: number;
+    bottom: number;
+    height: number;
+}
+export interface KeyboardAccessoryFrameState {
+    top: number;
+    bottom: number;
+    height: number;
+    visible: boolean;
+    slotHeight: number;
+}
+export interface FrameSnapshot {
+    location: Location;
+    pageState: PageState;
+    viewport: FrameViewportState;
+    frameSlots: FrameSlotRegistration[];
+    measuredAt: number;
+}
+export interface TransitionActionContext {
+    plan: TransitionPlan;
+}
+export interface TransitionAction {
+    type: "page" | "topChrome" | "bottomChrome" | "keyboard" | "safeArea" | (string & {});
+    run: (ctx: TransitionActionContext) => Promise<void> | void;
+}
+export interface TransitionPlan {
+    id: number;
+    intent: NavigationIntent;
+    type: TransitionType;
+    direction: "forward" | "back";
+    fromFrame: FrameSnapshot;
+    toFrame: FrameSnapshot;
+    actions: TransitionAction[];
+    duration: number;
+}
+export interface FrameLayerZIndex {
+    page: number;
+    previousPage: number;
+    cachedPage: number;
+    topChrome: number;
+    bottomChrome: number;
+    keyboard: number;
+    overlay: number;
+}
+export interface FrameLayoutState {
+    viewport: FrameViewportState;
+    keyboard: KeyboardFrameState;
+    contentViewport: FrameContentViewportState;
+    keyboardAccessory: KeyboardAccessoryFrameState;
+    platformProfile: FramePlatformProfile;
+    zIndex: FrameLayerZIndex;
+    pageStateByPath: Map<string, PageState>;
+}
+export interface FrameSlotRegistration {
+    scope?: FrameSlotScope;
+    type: FrameSlotType;
+    role?: FrameSlotRole;
+    height?: number;
+    estimatedHeight?: number;
+    source?: "navbar" | "topInset" | "bottomInset" | "bottomTab" | (string & {});
+    cache?: boolean;
+}
 export interface LayoutFallbackRoute {
     path: string;
     pathSegments: string[];

package/types/client/frameConfig.d.ts

@@ -0,0 +1,19 @@
+import type { PageConfig, PageState } from "./csrTypes.d.ts";
+export type DevicePlatform = "ios" | "android" | "web" | (string & {});
+export type SafeAreaInsets = {
+    top: number;
+    bottom: number;
+};
+export interface ResolvePageStateOptions {
+    configChain?: PageConfig[];
+    path: string;
+    basePath?: string;
+    platform: DevicePlatform;
+    deviceSafeArea: SafeAreaInsets;
+    cssSafeArea?: SafeAreaInsets;
+}
+export declare function validatePageConfig(routeKey: string, config?: PageConfig): void;
+export declare function mergePageConfigs(configChain?: PageConfig[]): PageConfig;
+export declare function getExplicitPageConfigKeys(configChain?: PageConfig[]): Partial<Record<keyof PageConfig, boolean>>;
+export declare function resolvePageState({ configChain, path, basePath, platform, deviceSafeArea, cssSafeArea, }: ResolvePageStateOptions): PageState;
+export declare function readCssSafeAreaInsets(): SafeAreaInsets;

package/types/client/frameDebug.d.ts

@@ -0,0 +1,3 @@
+type DebugPayload = Record<string, unknown>;
+export declare function debugFrame(event: string, payload?: DebugPayload): void;
+export {};

package/types/client/index.d.ts

@@ -4,6 +4,8 @@ export * from "./createFont.d.ts";
 export * from "./csrTypes.d.ts";
 export * from "./decorators.d.ts";
 export * from "./device.d.ts";
+export * from "./frameConfig.d.ts";
+export * from "./frameDebug.d.ts";
 export * from "./locale.d.ts";
 export * from "./makePageProto.d.ts";
 export * from "./router.d.ts";

package/types/client/router.d.ts

@@ -43,6 +43,8 @@ export declare class AkanNotFoundError extends Error {
 }
 declare global {
     var __AKAN_ROUTER__: Router | undefined;
+    var __AKAN_DEV_SYNC_NAVIGATION__: ((href: string, kind: "push" | "replace" | "back" | "pop") => void) | undefined;
+    var __AKAN_DEV_SYNC_NAVIGATION_APPLYING__: boolean | undefined;
 }
 export declare const getPathInfo: (requestUrl: string, lang: string, prefix: string) => {
     path: string;

package/types/fetch/requestStorage.d.ts

@@ -12,6 +12,7 @@ export interface AkanDynamicUsage {
 export interface AkanRequestStore {
     request: Request;
     theme?: AkanTheme;
+    frameState?: unknown;
     queryCache: Map<string, Promise<unknown>>;
     policy: AkanRequestPolicy;
     dynamicUsage: AkanDynamicUsage;
@@ -29,6 +30,8 @@ export declare function createRequestStore(request: Request, policy?: Partial<Om
 /** Stores theme preference on the active request when server rendering. */
 export declare function setRequestTheme(theme: AkanTheme | undefined): void;
 export declare function getRequestTheme(): AkanTheme | undefined;
+export declare function setRequestFrameState(frameState: unknown): void;
+export declare function getRequestFrameState<FrameState = unknown>(): FrameState | undefined;
 export declare function pushRequestFallback(storeOrRequest: Request | AkanRequestStore): () => void;
 /** Returns the active server request store from AsyncLocalStorage or the fallback stack. */
 export declare function getRequestStore(): AkanRequestStore | undefined;

package/types/server/hmr/clientScript.d.ts

@@ -1 +1 @@
-export declare const HMR_CLIENT_SCRIPT = "(function(){\n  if (self.__AKAN_HMR_INSTALLED__) return;\n  self.__AKAN_HMR_INSTALLED__ = true;\n  var proto = location.protocol === \"https:\" ? \"wss:\" : \"ws:\";\n  var url = proto + \"//\" + location.host + \"/_akan/hmr\";\n  var attempts = 0;\n  var socket = null;\n  var lastBuildId = null;\n  var refreshRuntimePromise = null;\n  var refreshRuntime = null;\n  var pendingRefreshRegistrations = [];\n  var refreshQueue = Promise.resolve();\n  var overlayEl = null;\n  var overlayLabelEl = null;\n  var overlayDetailEl = null;\n  var overlayStyleEl = null;\n  var overlayTimer = null;\n  var overlayHideTimer = null;\n  var overlayNextToken = 1;\n  var overlayJobs = {};\n  var buildErrorStates = {};\n  self.__AKAN_HMR_PHASE__ = null;\n\n  // Bun's React Fast Refresh transform can emit top-level calls to these globals\n  // even when we fall back to full reload instead of applying React Refresh.\n  self.$RefreshReg$ = self.$RefreshReg$ || function(type, id){\n    if (refreshRuntime) refreshRuntime.register(type, id);\n    else pendingRefreshRegistrations.push([type, id]);\n  };\n  self.$RefreshSig$ = self.$RefreshSig$ || function(){ return function(type){ return type; }; };\n  // Start installing React Refresh before the application module graph loads.\n  // Injecting the runtime only on the first update is too late for React's renderer hook.\n  ensureRefreshRuntime().catch(function(err){\n    console.warn(\"[akan-hmr] React Refresh runtime preload failed\", err);\n  });\n\n  function connect(){\n    try { socket = new WebSocket(url); }\n    catch(e){ console.error(\"[akan-hmr] ws init failed\", e); schedule(); return; }\n    socket.addEventListener(\"open\", function(){ attempts = 0; });\n    socket.addEventListener(\"message\", function(ev){\n      var msg;\n      try { msg = JSON.parse(ev.data); } catch (e){ return; }\n      if (!msg || typeof msg.type !== \"string\") return;\n      if (msg.type === \"hello\") {\n        if (lastBuildId !== null && msg.buildId !== lastBuildId) {\n          location.reload();\n          return;\n        }\n        lastBuildId = msg.buildId;\n        return;\n      }\n      if (msg.type === \"reload\") {\n        beginHmrOverlay(\"Reloading...\", true);\n        try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}\n        setTimeout(function(){ location.reload(); }, 30);\n        return;\n      }\n      if (msg.type === \"rsc-refresh\") {\n        refreshRsc(msg);\n        return;\n      }\n      if (msg.type === \"client-refresh\") {\n        refreshClient(msg);\n        return;\n      }\n      if (msg.type === \"css-update\") {\n        var cssUrl = selectCssUrl(msg.cssAssets);\n        if (cssUrl) swapCss(cssUrl);\n        else {\n          beginHmrOverlay(\"Reloading...\", true);\n          location.reload();\n        }\n        return;\n      }\n      if (msg.type === \"build-status\") { handleBuildStatus(msg); return; }\n      if (msg.type === \"ok\") {\n        clearBuildErrorOverlay({\n          phase: \"build\",\n          generation: typeof msg.generation === \"number\" ? msg.generation : Number.MAX_SAFE_INTEGER,\n          files: 0\n        });\n        return;\n      }\n      if (msg.type === \"error\") {\n        console.error(\"[akan-hmr]\", msg.message);\n        showBuildErrorOverlay({ phase: \"build\", generation: 0, message: msg.message, files: 0 });\n        return;\n      }\n    });\n    socket.addEventListener(\"close\", function(){ socket = null; schedule(); });\n    socket.addEventListener(\"error\", function(){ try { socket && socket.close(); } catch(e){} });\n  }\n\n  function schedule(){\n    attempts = Math.min(attempts + 1, 6);\n    var delay = Math.min(30000, 250 * Math.pow(2, attempts - 1));\n    setTimeout(connect, delay);\n  }\n\n  function ensureOverlay(){\n    if (overlayEl && overlayLabelEl) return overlayEl;\n    if (!overlayStyleEl) {\n      overlayStyleEl = document.createElement(\"style\");\n      overlayStyleEl.textContent =\n        \"@keyframes akan-hmr-spin{to{transform:rotate(360deg)}}\" +\n        \".__akan_hmr_overlay{position:fixed;left:16px;bottom:16px;z-index:2147483647;display:flex;align-items:flex-start;gap:9px;max-width:min(420px,calc(100vw - 32px));padding:10px 12px;border-radius:16px;background:rgba(17,24,39,.94);color:#fff;font:500 13px/1.25 ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;box-shadow:0 10px 28px rgba(0,0,0,.28);pointer-events:none;opacity:0;transform:translateY(6px);transition:opacity .15s ease,transform .15s ease;backdrop-filter:blur(8px)}\" +\n        \".__akan_hmr_overlay[data-show=true]{opacity:1;transform:translateY(0)}\" +\n        \".__akan_hmr_overlay[data-status=error]{background:rgba(127,29,29,.96);border:1px solid rgba(252,165,165,.55)}\" +\n        \".__akan_hmr_overlay[data-status=ok]{background:rgba(6,95,70,.94);border:1px solid rgba(110,231,183,.45)}\" +\n        \".__akan_hmr_spinner{width:14px;height:14px;margin-top:1px;border:2px solid rgba(255,255,255,.32);border-top-color:#fff;border-radius:999px;animation:akan-hmr-spin .75s linear infinite;flex:none}\" +\n        \".__akan_hmr_overlay[data-status=error] .__akan_hmr_spinner,.__akan_hmr_overlay[data-status=ok] .__akan_hmr_spinner{animation:none;border-color:rgba(255,255,255,.72);border-top-color:rgba(255,255,255,.72)}\" +\n        \".__akan_hmr_body{display:flex;flex-direction:column;gap:3px;min-width:0}\" +\n        \".__akan_hmr_detail{font:400 12px/1.35 ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;color:rgba(255,255,255,.82);white-space:pre-wrap;overflow-wrap:anywhere}\" +\n        \"@media (prefers-reduced-motion:reduce){.__akan_hmr_overlay{transition:none}.__akan_hmr_spinner{animation:none}}\";\n      document.head.appendChild(overlayStyleEl);\n    }\n    overlayEl = document.createElement(\"div\");\n    overlayEl.className = \"__akan_hmr_overlay\";\n    overlayEl.setAttribute(\"data-status\", \"updating\");\n    overlayEl.setAttribute(\"role\", \"status\");\n    overlayEl.setAttribute(\"aria-live\", \"polite\");\n    overlayEl.innerHTML = '<span class=\"__akan_hmr_spinner\" aria-hidden=\"true\"></span><span class=\"__akan_hmr_body\"><span data-akan-hmr-label>Updating...</span><span class=\"__akan_hmr_detail\" data-akan-hmr-detail></span></span>';\n    overlayLabelEl = overlayEl.querySelector(\"[data-akan-hmr-label]\");\n    overlayDetailEl = overlayEl.querySelector(\"[data-akan-hmr-detail]\");\n    (document.body || document.documentElement).appendChild(overlayEl);\n    return overlayEl;\n  }\n\n  function activeOverlayTokens(){\n    return Object.keys(overlayJobs);\n  }\n\n  function latestOverlayLabel(){\n    var keys = activeOverlayTokens();\n    if (keys.length === 0) return \"Updating...\";\n    return overlayJobs[keys[keys.length - 1]] || \"Updating...\";\n  }\n\n  function showOverlayNow(){\n    overlayTimer = null;\n    if (activeOverlayTokens().length === 0) return;\n    if (hasBuildErrors()) {\n      renderBuildErrorOverlay();\n      return;\n    }\n    var el = ensureOverlay();\n    el.setAttribute(\"data-status\", \"updating\");\n    if (overlayHideTimer) {\n      clearTimeout(overlayHideTimer);\n      overlayHideTimer = null;\n    }\n    if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n    if (overlayDetailEl) overlayDetailEl.textContent = \"\";\n    requestAnimationFrame(function(){ el.setAttribute(\"data-show\", \"true\"); });\n  }\n\n  function beginHmrOverlay(label, immediate){\n    var token = overlayNextToken++;\n    overlayJobs[token] = label || \"Updating...\";\n    if (!hasBuildErrors() && overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n    if (overlayHideTimer) {\n      clearTimeout(overlayHideTimer);\n      overlayHideTimer = null;\n    }\n    if (immediate) {\n      if (overlayTimer) clearTimeout(overlayTimer);\n      showOverlayNow();\n    } else if (!overlayTimer && (!overlayEl || overlayEl.getAttribute(\"data-show\") !== \"true\")) {\n      overlayTimer = setTimeout(showOverlayNow, 120);\n    }\n    return token;\n  }\n\n  function setHmrOverlayLabel(token, label){\n    if (!overlayJobs[token]) return;\n    overlayJobs[token] = label || \"Updating...\";\n    if (!hasBuildErrors() && overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n  }\n\n  function endHmrOverlay(token){\n    delete overlayJobs[token];\n    if (hasBuildErrors()) {\n      renderBuildErrorOverlay();\n      return;\n    }\n    if (activeOverlayTokens().length > 0) {\n      if (overlayLabelEl) overlayLabelEl.textContent = latestOverlayLabel();\n      return;\n    }\n    if (overlayTimer) {\n      clearTimeout(overlayTimer);\n      overlayTimer = null;\n    }\n    if (!overlayEl) return;\n    overlayEl.setAttribute(\"data-show\", \"false\");\n    if (overlayHideTimer) clearTimeout(overlayHideTimer);\n    overlayHideTimer = setTimeout(function(){\n      if (overlayEl && activeOverlayTokens().length === 0 && overlayEl.parentNode) {\n        overlayEl.parentNode.removeChild(overlayEl);\n        overlayEl = null;\n        overlayLabelEl = null;\n        overlayDetailEl = null;\n      }\n    }, 180);\n  }\n\n  function handleBuildStatus(msg){\n    if (msg.status === \"error\") {\n      showBuildErrorOverlay(msg);\n      return;\n    }\n    if (msg.status === \"ok\") clearBuildErrorOverlay(msg);\n  }\n\n  function showBuildErrorOverlay(msg){\n    var phase = msg.phase || \"build\";\n    var generation = typeof msg.generation === \"number\" ? msg.generation : 0;\n    var previous = buildErrorStates[phase];\n    if (previous && generation < previous.generation) return;\n    buildErrorStates[phase] = {\n      phase: msg.phase || \"build\",\n      generation: generation,\n      message: msg.message || \"Build failed\",\n      files: typeof msg.files === \"number\" ? msg.files : 0\n    };\n    console.error(\"[akan-hmr] build failed\", buildErrorStates[phase]);\n    renderBuildErrorOverlay();\n  }\n\n  function renderBuildErrorOverlay(){\n    if (!hasBuildErrors()) return;\n    if (overlayTimer) {\n      clearTimeout(overlayTimer);\n      overlayTimer = null;\n    }\n    if (overlayHideTimer) {\n      clearTimeout(overlayHideTimer);\n      overlayHideTimer = null;\n    }\n    var el = ensureOverlay();\n    var phases = buildErrorPhases();\n    var latest = latestBuildErrorState();\n    el.setAttribute(\"data-status\", \"error\");\n    if (overlayLabelEl) overlayLabelEl.textContent = \"Build failed: \" + phases.join(\", \");\n    if (overlayDetailEl) overlayDetailEl.textContent = formatBuildStatusDetail(latest, phases.length);\n    requestAnimationFrame(function(){ el.setAttribute(\"data-show\", \"true\"); });\n  }\n\n  function clearBuildErrorOverlay(msg){\n    var phase = msg.phase || \"build\";\n    var current = buildErrorStates[phase];\n    if (!current) return;\n    var generation = typeof msg.generation === \"number\" ? msg.generation : 0;\n    var recovered = phase === \"backend\" ? generation >= current.generation : generation > current.generation;\n    if (!recovered) return;\n    delete buildErrorStates[phase];\n    if (hasBuildErrors()) {\n      renderBuildErrorOverlay();\n      return;\n    }\n    if (overlayHideTimer) clearTimeout(overlayHideTimer);\n    var el = ensureOverlay();\n    el.setAttribute(\"data-status\", \"ok\");\n    if (overlayLabelEl) overlayLabelEl.textContent = \"Build recovered\";\n    if (overlayDetailEl) overlayDetailEl.textContent = formatBuildStatusDetail(msg);\n    requestAnimationFrame(function(){ el.setAttribute(\"data-show\", \"true\"); });\n    overlayHideTimer = setTimeout(function(){\n      if (activeOverlayTokens().length > 0) {\n        showOverlayNow();\n        return;\n      }\n      if (!overlayEl) return;\n      overlayEl.setAttribute(\"data-show\", \"false\");\n      overlayHideTimer = setTimeout(function(){\n        if (overlayEl && activeOverlayTokens().length === 0 && !hasBuildErrors() && overlayEl.parentNode) {\n          overlayEl.parentNode.removeChild(overlayEl);\n          overlayEl = null;\n          overlayLabelEl = null;\n          overlayDetailEl = null;\n        }\n      }, 180);\n    }, 900);\n  }\n\n  function hasBuildErrors(){\n    return Object.keys(buildErrorStates).length > 0;\n  }\n\n  function buildErrorPhases(){\n    return Object.keys(buildErrorStates).sort();\n  }\n\n  function latestBuildErrorState(){\n    var phases = buildErrorPhases();\n    var latest = buildErrorStates[phases[0]];\n    for (var i = 1; i < phases.length; i++) {\n      var next = buildErrorStates[phases[i]];\n      if (!latest || next.generation >= latest.generation) latest = next;\n    }\n    return latest;\n  }\n\n  function formatBuildStatusDetail(msg, failedPhaseCount){\n    var parts = [];\n    if (typeof msg.generation === \"number\" && msg.generation > 0) parts.push(\"generation \" + msg.generation);\n    if (typeof msg.files === \"number\") parts.push(msg.files + \" file\" + (msg.files === 1 ? \"\" : \"s\"));\n    if (failedPhaseCount > 1) parts.push(failedPhaseCount + \" failed phases\");\n    var prefix = parts.length > 0 ? parts.join(\" \u00B7 \") : \"\";\n    if (!msg.message) return prefix;\n    return prefix ? prefix + \"\\n\" + msg.message : msg.message;\n  }\n\n  function refreshRsc(msg){\n    var started = performance.now();\n    var overlayToken = beginHmrOverlay(\"Refreshing page...\");\n    try { self.__AKAN_RSC_CLEAR_CACHE__ && self.__AKAN_RSC_CLEAR_CACHE__(); } catch(e){}\n    if (!self.__AKAN_RSC_REFRESH__) {\n      console.warn(\"[akan-hmr] RSC refresh API unavailable, falling back to full reload\");\n      setHmrOverlayLabel(overlayToken, \"Reloading...\");\n      setTimeout(function(){ location.reload(); }, 30);\n      return;\n    }\n    Promise.resolve(self.__AKAN_RSC_REFRESH__({ buildId: msg.buildId })).then(function(){\n      lastBuildId = msg.buildId;\n      endHmrOverlay(overlayToken);\n      console.debug && console.debug(\"[akan-hmr] RSC refreshed\", {\n        buildId: msg.buildId,\n        generation: msg.generation,\n        routeIds: msg.routeIds,\n        changedFiles: msg.changedFiles && msg.changedFiles.length,\n        durationMs: Math.round(performance.now() - started)\n      });\n    }, function(err){\n      console.error(\"[akan-hmr] RSC refresh failed, falling back to full reload\", err);\n      setHmrOverlayLabel(overlayToken, \"Update failed, reloading...\");\n      setTimeout(function(){ location.reload(); }, 250);\n    });\n  }\n\n  function ensureRefreshRuntime(){\n    if (refreshRuntimePromise) return refreshRuntimePromise;\n    refreshRuntimePromise = import(\"react-refresh/runtime\").then(function(mod){\n      var runtime = mod.default || mod;\n      if (!self.__AKAN_REACT_REFRESH_READY__) {\n        refreshRuntime = runtime;\n        runtime.injectIntoGlobalHook(self);\n        self.$RefreshReg$ = function(type, id){ runtime.register(type, id); };\n        self.$RefreshSig$ = runtime.createSignatureFunctionForTransform;\n        for (var i = 0; i < pendingRefreshRegistrations.length; i++) {\n          self.$RefreshReg$(pendingRefreshRegistrations[i][0], pendingRefreshRegistrations[i][1]);\n        }\n        pendingRefreshRegistrations = [];\n        self.__AKAN_REACT_REFRESH_READY__ = true;\n        self.__AKAN_REACT_REFRESH_RUNTIME__ = runtime;\n      }\n      return runtime;\n    });\n    return refreshRuntimePromise;\n  }\n\n  function refreshClient(msg){\n    refreshQueue = refreshQueue.then(function(){ return doRefreshClient(msg); }, function(){ return doRefreshClient(msg); });\n  }\n\n  function setHmrPhase(phase){\n    self.__AKAN_HMR_PHASE__ = phase;\n  }\n\n  function doRefreshClient(msg){\n    var started = performance.now();\n    var metadataAt = started;\n    var importAt = started;\n    var refreshAt = started;\n    var overlayToken = beginHmrOverlay(\"Updating...\");\n    var fallbackToRsc = false;\n    return ensureRefreshRuntime().then(function(runtime){\n      setHmrOverlayLabel(overlayToken, \"Fetching update...\");\n      var endpoint = new URL(\"/_akan/hmr/client-refresh\", location.origin);\n      endpoint.searchParams.set(\"url\", location.href);\n      if (msg.buildId != null) endpoint.searchParams.set(\"buildId\", String(msg.buildId));\n      return fetch(endpoint, { credentials: \"same-origin\", cache: \"no-store\" })\n        .then(function(res){\n          if (!res.ok) throw new Error(\"client-refresh metadata failed \" + res.status + \" \" + res.statusText);\n          return res.json();\n        })\n        .then(function(info){\n          metadataAt = performance.now();\n          var chunks = Array.isArray(info.chunks) ? info.chunks : [];\n          if (chunks.length === 0) throw new Error(\"no client chunks returned\");\n          setHmrPhase(\"refresh-import\");\n          setHmrOverlayLabel(overlayToken, \"Importing update...\");\n          return Promise.all(chunks.map(function(chunk){ return import(chunk); })).then(function(){\n            importAt = performance.now();\n            setHmrPhase(\"react-refresh\");\n            setHmrOverlayLabel(overlayToken, \"Applying update...\");\n            try {\n              runtime.performReactRefresh();\n            } finally {\n              setHmrPhase(null);\n            }\n            refreshAt = performance.now();\n            lastBuildId = msg.buildId;\n            console.debug && console.debug(\"[akan-hmr] React Fast Refresh applied\", {\n              buildId: msg.buildId,\n              generation: msg.generation,\n              chunks: chunks.length,\n              routeIds: info.routeIds || msg.routeIds,\n              changedFiles: msg.changedFiles && msg.changedFiles.length,\n              metadataMs: Math.round(metadataAt - started),\n              importMs: Math.round(importAt - metadataAt),\n              refreshMs: Math.round(refreshAt - importAt),\n              durationMs: Math.round(refreshAt - started)\n            });\n            endHmrOverlay(overlayToken);\n          }, function(err){\n            setHmrPhase(null);\n            throw err;\n          });\n        });\n    }).catch(function(err){\n      console.warn(\"[akan-hmr] React Fast Refresh failed, falling back to RSC refresh\", err);\n      fallbackToRsc = true;\n      endHmrOverlay(overlayToken);\n      refreshRsc(msg);\n    }).finally(function(){\n      if (!fallbackToRsc) endHmrOverlay(overlayToken);\n    });\n  }\n\n  function swapCss(href){\n    var overlayToken = beginHmrOverlay(\"Updating styles...\");\n    var link = document.createElement(\"link\");\n    link.rel = \"stylesheet\";\n    link.href = href;\n    link.setAttribute(\"data-akan-css\", \"pending\");\n    link.addEventListener(\"load\", function(){\n      var prev = document.querySelectorAll(\"link[data-akan-css=active]\");\n      for (var i = 0; i < prev.length; i++) prev[i].parentNode && prev[i].parentNode.removeChild(prev[i]);\n      link.setAttribute(\"data-akan-css\", \"active\");\n      endHmrOverlay(overlayToken);\n    });\n    link.addEventListener(\"error\", function(){\n      if (link.parentNode) link.parentNode.removeChild(link);\n      endHmrOverlay(overlayToken);\n    });\n    document.head.appendChild(link);\n  }\n\n  function selectCssUrl(cssAssets){\n    if (!cssAssets || typeof cssAssets !== \"object\") return null;\n    var parts = location.pathname.split(\"/\").filter(Boolean);\n    for (var i = 0; i < parts.length; i++) {\n      var asset = cssAssets[parts[i]];\n      if (asset && asset.cssUrl) return asset.cssUrl;\n    }\n    return cssAssets[\"\"] && cssAssets[\"\"].cssUrl ? cssAssets[\"\"].cssUrl : null;\n  }\n\n  connect();\n})();";
+export declare const HMR_CLIENT_SCRIPT: string;

package/types/server/hmr/wsHub.d.ts

@@ -31,6 +31,11 @@ export type HmrMessage = {
         cssUrl: string;
         cssRelPath: string;
     }>;
+} | {
+    type: "sync-navigation";
+    clientId: string;
+    href: string;
+    kind?: "push" | "replace" | "back" | "pop";
 } | {
     type: "ok";
     generation?: number;
@@ -53,4 +58,5 @@ export declare class HmrWsHub {
     attach(ws: Bun.ServerWebSocket<HmrWsData>): void;
     detach(ws: Bun.ServerWebSocket<HmrWsData>): void;
     broadcast(msg: HmrMessage): void;
+    handleMessage(message: string): void;
 }