akanjs 3.0.0-beta.3 → 3.0.0-beta.31

package/client/cookie.ts

@@ -9,8 +9,7 @@ import {
 } from "akanjs/common";
 import type { Account } from "akanjs/fetch";
 import { parseCookieHeader, cookies as serverCookies, headers as serverHeaders } from "akanjs/fetch";
-import { loadCapacitorCore } from "./capacitor";
-import { storage } from "./storage";
+import { secretStorage } from "./storage";
 import { fetch } from "./useClient";
 
 interface CookieOptions {
@@ -19,8 +18,28 @@ interface CookieOptions {
   secure?: boolean;
 }
 
+const isCsrClient = () => {
+  const env = getEnv();
+  return env.side === "client" && env.renderMode === "csr";
+};
+
+const cookieJarKey = "akan:cookies";
+const pageKeepsCookies = () => (globalThis as { location?: Location }).location?.protocol !== "app:";
+const readCookieJar = (): Record<string, string> => {
+  try {
+    return JSON.parse(localStorage.getItem(cookieJarKey) ?? "{}") as Record<string, string>;
+  } catch {
+    return {};
+  }
+};
+const writeCookieJar = (jar: Record<string, string>) => {
+  localStorage.setItem(cookieJarKey, JSON.stringify(jar));
+};
+
 export const cookies = (): Map<string, { name: string; value: string }> => {
   if (getEnv().side === "server") return serverCookies();
+  if (!pageKeepsCookies())
+    return new Map(Object.entries(readCookieJar()).map(([name, value]) => [name, { name, value }]));
   return parseCookieHeader(document.cookie);
 };
 
@@ -29,30 +48,30 @@ export const setCookie = (
   value: string,
   options: CookieOptions = { path: "/", sameSite: "none", secure: true },
 ) => {
-  const env = getEnv();
-  if (env.side === "server") return;
+  if (getEnv().side === "server") return;
+  if (!pageKeepsCookies()) {
+    writeCookieJar({ ...readCookieJar(), [key]: value });
+    return;
+  }
   const encoded = `${key}=${value}`;
   const path = options.path ? `; path=${options.path}` : "";
   const sameSite = options.sameSite ? `; SameSite=${options.sameSite}` : "";
   const secure = options.secure ? "; Secure" : "";
   
   document.cookie = `${encoded}${path}${sameSite}${secure}`;
-  if (env.renderMode !== "csr") return;
-  void loadCapacitorCore()
-    .then(({ CapacitorCookies }) => CapacitorCookies.setCookie({ key, value, path: options.path }))
-    .catch(() => undefined);
 };
 
-/**
- * Reads through `cookies()` on both sides, which is the only way the two agree: a hand-rolled
- * `split("=")[1]` truncates a value at its first `=` (base64 padding) and never decodes the `j:` form the
- * server branch does. Capacitor's own docs say to read `document.cookie`, and `cookies()` does.
- */
+/** Reads through `cookies()` on both sides: a hand-rolled `split("=")` cuts base64 padding and skips the `j:` form. */
 export const getCookie = (key: string): string | undefined => cookies().get(key)?.value;
 
 export const removeCookie = (key: string, options: { path: string } = { path: "/" }) => {
-
+  
   if (getEnv().side === "server") return;
+  if (!pageKeepsCookies()) {
+    const { [key]: _removed, ...rest } = readCookieJar();
+    writeCookieJar(rest);
+    return;
+  }
   
   document.cookie = `${key}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=${options.path};`;
 };
@@ -67,24 +86,31 @@ export const getHeader = (key: string): string | undefined => {
 
 export { authTokenKey };
 
-/** The auth token this app holds in the cookie jar, under the app-scoped key or a legacy global one. */
-export const getAuthToken = (): string | undefined => readAuthToken(getCookie);
+const sentAuthToken = (): string | undefined => {
+  try {
+    return (fetch.instance as { jwt?: string | null } | undefined)?.jwt ?? undefined;
+  } catch {
+    
+    return undefined;
+  }
+};
 
-/** The auth token this app holds in client storage — localStorage under SSR, Capacitor Preferences on CSR. */
+/** The auth token this app holds: on a CSR client the one `fetch` sends first, since a native shell's page keeps no
+ * session cookie; then the cookie jar, under the app-scoped key or a legacy global one. */
+export const getAuthToken = (): string | undefined =>
+  (isCsrClient() ? sentAuthToken() : undefined) ?? readAuthToken(getCookie);
+
+/** The auth token this app holds in client storage — the OS credential store in a native app, localStorage elsewhere. */
 export const getStoredAuthToken = async (): Promise<string | undefined> => {
-  const scoped = await storage.getItem(authTokenKey());
+  const scoped = await secretStorage.getItem(authTokenKey());
   if (scoped) return scoped;
-  const legacy = await storage.getItem(legacyAuthTokenKey);
+  const legacy = await secretStorage.getItem(legacyAuthTokenKey);
   return legacy && isOwnAuthToken(legacy) ? legacy : undefined;
 };
 
-/**
- * Decodes the current JWT into account data when it belongs to this app/environment.
- *
- * The two credentials read here are exactly the two the server honours — the app-scoped auth cookie and
- * `Authorization: Bearer` (`AccountMiddleware`). It used to fall back to a bare `jwt` *header*, which nothing
- * sends and no guard accepts, so a request carrying one read as signed in here and anonymous at the endpoint.
- */
+/** The current JWT's account when minted for this app and environment. Reads only the two credentials the server
+ * honours — the app-scoped auth cookie (a CSR client's bearer token) and `Authorization: Bearer` — so the two never
+ * disagree on who is signed in. */
 export const getAccount = <AddData = unknown>(): Account<AddData> => {
   const jwt = getAuthToken() ?? getHeader("authorization")?.replace(/^Bearer\s+/i, "");
   const defaultAccount = { appName: getEnv().appName, environment: getEnv().environment } as Account<AddData>;
@@ -99,14 +125,15 @@ export interface GetOption {
 interface SetAuthOption {
   jwt: string;
 }
-/** Sets the active auth token on fetch, cookie storage, and client storage. */
+/** Sets the active auth token on fetch, the cookie jar (except on a CSR client), and client storage. */
 export const setAuth = ({ jwt }: SetAuthOption) => {
   fetch.setJwt(jwt);
-  setCookie(authTokenKey(), jwt);
-  void storage.setItem(authTokenKey(), jwt);
-
+  
+  if (!isCsrClient()) setCookie(authTokenKey(), jwt);
+  void secretStorage.setItem(authTokenKey(), jwt);
+  
   removeCookie(legacyAuthTokenKey);
-  void storage.removeItem(legacyAuthTokenKey);
+  void secretStorage.removeItem(legacyAuthTokenKey);
 };
 
 interface InitAuthOption {
@@ -116,7 +143,7 @@ export const initAuth = ({ jwt }: InitAuthOption = {}) => {
   const stored = getAuthToken();
   const token = jwt ?? stored;
   if (token && !isOwnAuthToken(token)) {
-
+    
     Logger.warn("JWT ignored: it was minted for another app or environment");
     if (token === stored) resetAuth();
     return;
@@ -130,6 +157,6 @@ export const resetAuth = () => {
   fetch.setJwt(null);
   removeCookie(authTokenKey());
   removeCookie(legacyAuthTokenKey);
-  void storage.removeItem(authTokenKey());
-  void storage.removeItem(legacyAuthTokenKey);
+  void secretStorage.removeItem(authTokenKey());
+  void secretStorage.removeItem(legacyAuthTokenKey);
 };

package/client/createFont.ts

@@ -1,5 +1,3 @@
-
-
 export const createFont = (_data: unknown) => null;
 export default createFont;
 export const Nanum_Gothic_Coding = createFont;

package/client/csrTypes.ts

@@ -18,21 +18,10 @@ export type PageSafeAreaConfig =
       bottom?: boolean;
       android?: "auto" | "edge-to-edge" | "none";
     };
-/**
- * Server-render strategy for the initial full-document SSR pass.
- * - `"stream"` (default): flush the shell — including any `Loading` Suspense
- *   fallback — as soon as it is ready, then stream the resolved page. Redirects
- *   decided in the shell still become real HTTP redirects; redirects thrown
- *   inside suspended content degrade to soft (client) redirects.
- * - `"block"`: buffer the whole document until every Suspense boundary resolves
- *   before sending a byte. The `Loading` fallback never reaches the browser, but
- *   a non-redirect error thrown in slow content can still yield a clean error
- *   page. Use only for routes that need that guarantee and do not care about SEO
- *   or first-paint of the fallback.
- */
+/** `"stream"` flushes the shell (`Loading` included) then streams; a redirect in suspended content becomes a client one.
+ * `"block"` buffers the whole document, so an error in slow content can still render a clean error page. */
 export type SsrRenderMode = "stream" | "block";
 
-/** Per-page CSR configuration for transition, safe-area, and gesture behavior. */
 export interface PageConfig {
   transition?: TransitionType;
   safeArea?: PageSafeAreaConfig;
@@ -44,20 +33,12 @@ export interface PageConfig {
   cache?: boolean;
   /** Initial full-document SSR strategy. Defaults to `"stream"`. */
   ssr?: SsrRenderMode;
-  /**
-   * Opt in to guarded RSC page suffix commits when the page does not require
-   * head/metadata updates and the retained route chain head is invariant for
-   * sibling navigations under the same layout.
-   */
+  /** Opt-in suffix-only RSC commits, for a page needing no head update under a layout head its siblings share. */
   rscPatchHeadSafe?: boolean;
   topSafeAreaColor?: string;
   bottomSafeAreaColor?: string;
-  /**
-   * Keeps the route out of `akan build`. The route still serves under `akan start`, but nothing about it
-   * reaches production: no bundle, no manifest entry, no URL. On a `_layout`, every route under that
-   * directory is excluded with it. Must be written as a literal `true`/`false` — the build reads it from
-   * the source without evaluating the module.
-   */
+  /** Keeps the route (on a `_layout`, its whole directory) out of `akan build` while `akan start` serves it. Write a
+   * literal `true`/`false`: the build reads it off the source without evaluating the module. */
   devOnly?: boolean;
 }
 
@@ -79,7 +60,6 @@ export interface PageProps {
   params: { [key: string]: string };
   searchParams: { [key: string]: string | string[] };
 }
-/** Props passed to Akan layout route modules. */
 export interface LayoutProps extends PageProps {
   children: ReactNode;
 }
@@ -109,7 +89,6 @@ export interface AkanHeadSnapshotV1 {
 }
 export interface ResolvedHead {
   node: Head | null | undefined;
-  hasExplicitLanguageAlternates: boolean;
   headSnapshot?: AkanHeadSnapshotV1;
 }
 export type ResolveHeadResult = Head | ResolvedHead | null | undefined;
@@ -124,9 +103,11 @@ export type LayoutErrorRender = (props: LayoutErrorProps) => PromiseOrObject<Rea
 export interface RouteRender {
   render: LayoutRender | PageRender;
   isAsync?: boolean;
+  /** CSR: a page's render reads the query; a layout's reads only the params of its own path (`paramNames`). */
+  kind?: "page" | "layout";
+  paramNames?: string[];
   Loading?: LayoutLoadingRender | PageLoadingRender;
-  /** Loads the module and populates `Loading` without running `render`/`resolveHead`.
-   * Used by the patch (suffix) compose path, which never calls `resolveHead`. */
+  /** Loads the module and fills `Loading` without running `render`/`resolveHead` (the suffix compose path). */
   resolveLoading?: () => void | Promise<void>;
   NotFound?: LayoutNotFoundRender;
   Error?: LayoutErrorRender;
@@ -163,53 +144,24 @@ export interface WebAppManifest {
   screenshots?: WebAppManifestIcon[];
   [key: string]: unknown;
 }
-export interface AkanMetadata {
-  title?: string;
-  description?: string;
-  robots?: string;
-  openGraph?: {
-    title?: string;
-    description?: string;
-    type?: string;
-    url?: string;
-    siteName?: string;
-    images?: string | string[];
-  };
-  twitter?: {
-    card?: "summary" | "summary_large_image" | "app" | "player" | (string & {});
-    title?: string;
-    description?: string;
-    images?: string | string[];
-  };
-  alternates?: {
-    canonical?: string;
-    languages?: Record<string, string>;
-  };
-}
-export type GenerateMetadata = (props: PageProps) => PromiseOrObject<AkanMetadata | null | undefined>;
 export interface PageModule {
   default?: PageRender;
   pageConfig?: PageConfig;
   head?: Head;
-  metadata?: AkanMetadata;
   generateHead?: GenerateHead;
-  generateMetadata?: GenerateMetadata;
   Loading?: PageLoadingRender;
 }
 export interface LayoutModule {
   default?: LayoutRender;
   pageConfig?: PageConfig;
   head?: Head;
-  metadata?: AkanMetadata;
   generateHead?: GenerateHead;
-  generateMetadata?: GenerateMetadata;
   fonts?: ReactFont[];
   manifest?: WebAppManifest;
   theme?: string;
   reconnect?: boolean;
   wsConnect?: boolean;
   layoutStyle?: "mobile" | "web";
-  gaTrackingId?: string;
   Loading?: LayoutLoadingRender;
   NotFound?: LayoutNotFoundRender;
   Error?: LayoutErrorRender;
@@ -222,16 +174,16 @@ 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;
   isSpecialRoute?: boolean;
-
   loader?: () => unknown;
   pageState?: PageState;
   pageConfigChain?: PageConfig[];
   explicitPageConfigKeys?: Partial<Record<keyof PageConfig, boolean>>;
-
   children: Map<string, Route>;
 }
 
@@ -274,6 +226,7 @@ export interface Location {
   searchParams: { [key: string]: string | string[] };
   pathRoute: PathRoute;
   hash: string;
+  entryId?: string; 
 }
 export type CsrNavigationPhase = "idle" | "preparing" | "transitioning";
 export type CsrNavigationKind = "push" | "replace" | "back" | "popForward" | "popBack";
@@ -300,6 +253,7 @@ export interface History {
   idxMap: Map<string, number>;
   cachedLocationMap: Map<string, Location>;
   idx: number;
+  dormant?: Set<string>; 
 }
 
 export interface RouterProps {
@@ -309,14 +263,24 @@ export interface RouterProps {
   back: () => void | Promise<void>;
 }
 
+export type CsrPageType = "current" | "prev" | "pending" | "cached";
+export interface CsrStackEntry {
+  key: string; 
+  location: Location;
+  pageType: CsrPageType;
+  zIndex: number;
+}
+
 export interface RouteState {
   clientWidth: number;
   clientHeight: number;
   location: Location;
   prevLocation: Location | null;
   pendingLocation: Location | null;
+  stackEntries: CsrStackEntry[];
   navigationIntent: NavigationIntent | null;
   phase: CsrNavigationPhase;
+  isBackgrounded: boolean;
   history: RefObject<History>;
   topSafeAreaRef: RefObject<HTMLDivElement | null>;
   bottomSafeAreaRef: RefObject<HTMLDivElement | null>;
@@ -341,14 +305,24 @@ export type UseCsrTransition = CsrTransitionStyles & {
 };
 
 export type CsrContextType = RouteState & UseCsrTransition;
-export const csrContext = sharedContext<CsrContextType>("csr", {} as unknown as CsrContextType);
+
+export const csrContext = sharedContext<CsrContextType>("csr", {
+  history: { current: null },
+  topSafeAreaRef: { current: null },
+  bottomSafeAreaRef: { current: null },
+  prevPageContentRef: { current: null },
+  pageContentRef: { current: null },
+  frameRootRef: { current: null },
+  onBack: { current: {} },
+} as unknown as CsrContextType);
 export const useCsr = () => {
   const contextValues = useContext(csrContext);
   return contextValues;
 };
 
 export interface PathContextType {
-  pageType: "current" | "prev" | "cached" | "pending";
+  pageType: CsrPageType;
+  pageKey?: string;
   location: Location;
   prefix?: string;
   gestureEnabled: boolean;
@@ -361,6 +335,16 @@ export const usePathCtx = () => {
   return contextValues;
 };
 
+export type PageActivity = "current" | "prev" | "pending" | "hidden";
+export interface PageActivityState {
+  activity: PageActivity;
+  focused: boolean;
+}
+export const pageActivityContext = sharedContext<PageActivityState>("pageActivity", {
+  activity: "current",
+  focused: true,
+});
+
 export interface PathRoute {
   path: string;
   pathSegments: string[];

package/client/decorators.ts

@@ -5,7 +5,7 @@ interface ToastProps {
   root?: string;
   duration?: number;
 }
-/** Decorates async actions with loading/success/error toast messages from `msg`. */
+/** Toasts `<root>.<key>-loading` / `-success` around the method; an error is toasted and logged, not rethrown. */
 export const Toast = ({ root, duration = 3 }: ToastProps = {}) => {
   return (target: any, key: string, descriptor: PropertyDescriptor) => {
     const originMethod = descriptor.value as (...args: any[]) => Promise<void>;