akanjs 3.0.0-beta.19 → 3.0.0-beta.20

package/client/device.ts

@@ -6,16 +6,42 @@ import type {
   CapacitorKeyboardInfo,
   CapacitorKeyboardModule,
 } from "./capacitor";
-import { debugFrame } from "./frameDebug";
 
 type DeviceInfo = CapacitorDeviceInfo;
 type Keyboard = CapacitorKeyboardModule["Keyboard"];
 type Haptics = CapacitorHapticsModule["Haptics"];
 type ImpactStyle = CapacitorHapticsModule["ImpactStyle"];
 type ProcessEnvLike = { env?: Record<string, string | undefined> };
+type DebugPayload = Record<string, unknown>;
 
 const globalWithProcess = globalThis as typeof globalThis & { process?: ProcessEnvLike };
 
+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"
+  );
+};
+
+export function debugFrame(event: string, payload: DebugPayload = {}) {
+  if (!isFrameDebugEnabled()) 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));
+}
+
 interface DeviceInitOption {
   lang: string;
   info: DeviceInfo;
@@ -62,6 +88,11 @@ export const isMobileDevice = () => {
   return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
 };
 
+const langInPath = (pathname: string, supportLanguages: string[] | readonly string[]) => {
+  const predefinedLangPath = pathname.split("/")[1]?.split("?")[0];
+  return supportLanguages.find((language) => language === predefinedLangPath);
+};
+
 const createWebDevice = ({
   lang,
   supportLanguages,
@@ -70,10 +101,8 @@ const createWebDevice = ({
   supportLanguages: string[] | readonly string[];
 }) => {
   const pathname = typeof window === "undefined" ? "" : window.location.pathname;
-  const predefinedLangPath = pathname.split("/")[1]?.split("?")[0];
-  const predefinedLang = supportLanguages.find((language) => language === predefinedLangPath);
   return new Device({
-    lang: lang ?? predefinedLang ?? getBrowserLanguage(),
+    lang: lang ?? langInPath(pathname, supportLanguages) ?? getBrowserLanguage(),
     info: { platform: "web", isVirtual: false, osVersion: "" },
     topSafeArea: 0,
     bottomSafeArea: 0,
@@ -83,7 +112,6 @@ const createWebDevice = ({
   });
 };
 
-/** Capacitor-aware device helper for platform info, safe areas, keyboard, haptics, and scroll state. */
 export class Device {
   static instance: Device | null = null;
   static async load({
@@ -95,9 +123,8 @@ export class Device {
   }) {
     if (Device.instance) return Device.instance;
     if (getRenderMode() !== "csr" || !isNativeTarget()) {
-      const device = createWebDevice({ lang, supportLanguages });
-      Device.instance = device;
-      return device;
+      Device.instance = createWebDevice({ lang, supportLanguages });
+      return Device.instance;
     }
     const { loadCapacitorDevice, loadCapacitorHaptics, loadCapacitorKeyboard, loadCapacitorSafeArea } = await import(
       "./capacitor"
@@ -116,10 +143,8 @@ export class Device {
       },
     ] = await Promise.all([CapacitorDevice.getInfo(), CapacitorDevice.getLanguageCode(), SafeArea.getSafeAreaInsets()]);
     if (info.platform === "ios") await Keyboard.setResizeMode?.({ mode: "none" });
-    const predefinedLangPath = window.location.pathname.split("/")[1]?.split("?")[0];
-    const predefinedLang = supportLanguages.find((language) => language === predefinedLangPath);
-    const device = new Device({
-      lang: lang ?? predefinedLang ?? languageCode,
+    Device.instance = new Device({
+      lang: lang ?? langInPath(window.location.pathname, supportLanguages) ?? languageCode,
       info,
       topSafeArea,
       bottomSafeArea,
@@ -127,8 +152,7 @@ export class Device {
       haptics: Haptics,
       impactStyle: ImpactStyle,
     });
-    Device.instance = device;
-    return device;
+    return Device.instance;
   }
   static getDevice() {
     if (!Device.instance) throw new Error("Device is not loaded yet");
@@ -174,18 +198,14 @@ export class Device {
       currentHeight = height;
       onKeyboardChanged(height);
     };
-    void this.#keyboard.addListener("keyboardWillShow", (keyboard: CapacitorKeyboardInfo) => {
-      emitKeyboardHeight("keyboardWillShow", keyboard.keyboardHeight);
-    });
-    void this.#keyboard.addListener("keyboardDidShow", (keyboard: CapacitorKeyboardInfo) => {
-      emitKeyboardHeight("keyboardDidShow", keyboard.keyboardHeight);
-    });
-    void this.#keyboard.addListener("keyboardWillHide", () => {
-      emitKeyboardHeight("keyboardWillHide", 0);
-    });
-    void this.#keyboard.addListener("keyboardDidHide", () => {
-      emitKeyboardHeight("keyboardDidHide", 0);
-    });
+    for (const event of ["keyboardWillShow", "keyboardDidShow"])
+      void this.#keyboard.addListener(event, (keyboard: CapacitorKeyboardInfo) => {
+        emitKeyboardHeight(event, keyboard.keyboardHeight);
+      });
+    for (const event of ["keyboardWillHide", "keyboardDidHide"])
+      void this.#keyboard.addListener(event, () => {
+        emitKeyboardHeight(event, 0);
+      });
   }
   unlistenKeyboardChanged() {
     if (this.info.platform === "web") return;
@@ -197,24 +217,12 @@ export class Device {
       return;
     }
     const handleImpact = {
-      light: async () => {
-        await this.#haptics.impact({ style: this.#impactStyle.Light });
-      },
-      medium: async () => {
-        await this.#haptics.impact({ style: this.#impactStyle.Medium });
-      },
-      heavy: async () => {
-        await this.#haptics.impact({ style: this.#impactStyle.Heavy });
-      },
-      selectionStart: async () => {
-        await this.#haptics.selectionStart();
-      },
-      selectionChanged: async () => {
-        await this.#haptics.selectionChanged();
-      },
-      selectionEnd: async () => {
-        await this.#haptics.selectionEnd();
-      },
+      light: () => this.#haptics.impact({ style: this.#impactStyle.Light }),
+      medium: () => this.#haptics.impact({ style: this.#impactStyle.Medium }),
+      heavy: () => this.#haptics.impact({ style: this.#impactStyle.Heavy }),
+      selectionStart: () => this.#haptics.selectionStart(),
+      selectionChanged: () => this.#haptics.selectionChanged(),
+      selectionEnd: () => this.#haptics.selectionEnd(),
     };
     await handleImpact[type]();
   }

package/client/frameConfig.ts

@@ -1,3 +1,4 @@
+import { isRecord } from "akanjs/common";
 import type { PageConfig, PageSafeAreaConfig, PageState, SsrRenderMode, TransitionType } from "./csrTypes";
 
 export type DevicePlatform = "ios" | "android" | "web" | (string & {});
@@ -30,9 +31,6 @@ const transitionTypes = new Set<TransitionType>(["none", "fade", "bottomUp", "st
 const ssrRenderModes = new Set<SsrRenderMode>(["stream", "block"]);
 const DEFAULT_BOOLEAN_INSET = 48;
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === "object" && value !== null && !Array.isArray(value);
-
 const hasOwn = <Key extends PropertyKey>(value: object, key: Key) => Object.hasOwn(value, key);
 
 export function validatePageConfig(routeKey: string, config?: PageConfig) {
@@ -53,15 +51,11 @@ export function validatePageConfig(routeKey: string, config?: PageConfig) {
   if (pageConfig.ssr !== undefined && !ssrRenderModes.has(pageConfig.ssr)) {
     throw new Error(`[route-convention] unsupported pageConfig.ssr "${pageConfig.ssr}" in ${routeKey}`);
   }
-  if (pageConfig.topInset !== undefined && !isValidInsetValue(pageConfig.topInset)) {
-    throw new Error(
-      `[route-convention] pageConfig.topInset in ${routeKey} must be a boolean or non-negative px number.`,
-    );
-  }
-  if (pageConfig.bottomInset !== undefined && !isValidInsetValue(pageConfig.bottomInset)) {
-    throw new Error(
-      `[route-convention] pageConfig.bottomInset in ${routeKey} must be a boolean or non-negative px number.`,
-    );
+  for (const key of ["topInset", "bottomInset"] as const) {
+    if (pageConfig[key] !== undefined && !isValidInsetValue(pageConfig[key]))
+      throw new Error(
+        `[route-convention] pageConfig.${key} in ${routeKey} must be a boolean or non-negative px number.`,
+      );
   }
   validateSafeAreaConfig(routeKey, pageConfig.safeArea);
 }
@@ -78,11 +72,9 @@ function validateSafeAreaConfig(routeKey: string, safeArea?: PageSafeAreaConfig)
       throw new Error(`[route-convention] unsupported pageConfig.safeArea option "${key}" in ${routeKey}`);
     }
   }
-  if (safeArea.top !== undefined && typeof safeArea.top !== "boolean") {
-    throw new Error(`[route-convention] pageConfig.safeArea.top in ${routeKey} must be a boolean.`);
-  }
-  if (safeArea.bottom !== undefined && typeof safeArea.bottom !== "boolean") {
-    throw new Error(`[route-convention] pageConfig.safeArea.bottom in ${routeKey} must be a boolean.`);
+  for (const side of ["top", "bottom"] as const) {
+    if (safeArea[side] !== undefined && typeof safeArea[side] !== "boolean")
+      throw new Error(`[route-convention] pageConfig.safeArea.${side} in ${routeKey} must be a boolean.`);
   }
   if (
     safeArea.android !== undefined &&
@@ -208,14 +200,11 @@ function resolveSafeArea({
   cssSafeArea?: SafeAreaInsets;
 }): SafeAreaInsets {
   if (safeArea === false) return { top: 0, bottom: 0 };
-  const topEnabled =
-    safeArea === true ||
-    safeArea === "top" ||
-    (isRecord(safeArea) ? safeArea.top !== false : safeArea === undefined && platform !== "web");
-  const bottomEnabled =
+  const enabledAt = (side: "top" | "bottom") =>
     safeArea === true ||
-    safeArea === "bottom" ||
-    (isRecord(safeArea) ? safeArea.bottom !== false : safeArea === undefined && platform !== "web");
+    safeArea === side ||
+    (isRecord(safeArea) ? safeArea[side] !== false : safeArea === undefined && platform !== "web");
+  const [topEnabled, bottomEnabled] = [enabledAt("top"), enabledAt("bottom")];
   if (platform === "android") {
     const androidMode = isRecord(safeArea)
       ? (safeArea.android as "auto" | "edge-to-edge" | "none" | undefined)

package/client/index.ts

@@ -6,7 +6,6 @@ export * from "./csrTypes";
 export * from "./decorators";
 export * from "./device";
 export * from "./frameConfig";
-export * from "./frameDebug";
 export * from "./locale";
 export * from "./makePageProto";
 export * from "./route";

package/client/makePageProto.tsx

@@ -29,12 +29,12 @@ const getPageInfo = (): { locale: string; path: string } => {
   if (getEnv().side !== "server") {
     const [, firstSegment = "", ...rest] = window.location.pathname.split("/");
     const hasLocalePrefix = localeSet.has(firstSegment);
-
+    
     const locale = activeLocale ?? (hasLocalePrefix ? firstSegment : defaultLocale);
     return { locale, path: activePath ?? (hasLocalePrefix ? `/${rest.join("/")}` : window.location.pathname) };
   }
   const h = untrackedHeaders();
-
+  
   const localeHeader = h.get("x-locale");
   const pathHeader = h.get("x-path");
   if (localeHeader && pathHeader) return { locale: localeHeader, path: pathHeader };
@@ -164,13 +164,12 @@ export const makePageProto = <
             dangerouslySetInnerHTML={{
               __html: translator.translate(lang, key, {
                 ...param,
-
                 br: `<br />`,
               }),
             }}
           />
         ) as ReactNode;
-
+      
       l.trans = <Returns extends ReactNode>(
         translation: Record<"en" | "ko" | (string & {}), Returns>,
       ): Returns extends string ? string : Returns => {

package/client/route/RouteDefinition.ts

@@ -31,10 +31,7 @@ export interface RouteArgResolveOption {
   strict?: boolean;
 }
 
-/**
- * What a route file declares in place of named exports. The chain is the only surface — the module exports the
- * finished definition and the loader turns it back into the module shape every renderer already reads.
- */
+/** What a route file declares in place of named exports; the loader turns it back into the module shape. */
 export abstract class RouteDefinition<
   Args extends RouteArgsShape = Record<never, never>,
   Extra extends object = Record<never, never>,
@@ -77,11 +74,7 @@ export abstract class RouteDefinition<
     this.args.push(arg);
   }
 
-  /**
-   * Typed values out of the URL halves the router matched. A path value the declared type refuses is a URL that
-   * matched the pattern and nothing under it, so a page answers not-found; a search value that fails is dropped
-   * the way an absent one is. Under `strict` both are refused by name, which is what a prompt caller can act on.
-   */
+  /** A path value the type refuses answers not-found; a failing search value is dropped. `strict` refuses both by name. */
   resolveArgs(input: RouteArgInput, { strict = false }: RouteArgResolveOption = {}): Record<string, unknown> {
     const resolved: Record<string, unknown> = {};
     for (const arg of this.args) {
@@ -101,10 +94,7 @@ export abstract class RouteDefinition<
     return resolved;
   }
 
-  /**
-   * The `[x]` segments of the file's path against the `.param()` stages. A page must name every segment it sits
-   * under, so nothing reaches its body undeclared; a layout may name a subset, since most read none of them.
-   */
+  /** A page must declare every `[x]` segment it sits under with `.param()`; a layout may declare a subset. */
   assertPattern(pattern: string, key: string) {
     const inPath = pattern
       .split("/")
@@ -160,10 +150,7 @@ export abstract class RouteDefinition<
     return (this.kind === "page" ? args : { ...args, children: props.children }) as RouteBaseArgs & Args & Extra;
   }
 
-  /**
-   * A single value where a list was declared is a one-item list: the URL spells `?tags=a` for one tag. A prompt
-   * argument is one string whatever it holds, so under `strict` a list is read comma-separated.
-   */
+  /** One value where a list was declared is a one-item list (`?tags=a`); under `strict` a list is comma-separated. */
   static #lift(arg: RouteArgInfo, raw: string | string[], strict: boolean): unknown {
     if (!arg.list) return Array.isArray(raw) ? raw[0] : raw;
     if (Array.isArray(raw)) return raw;

package/client/route/resolveRouteModule.ts

@@ -20,11 +20,7 @@ export interface ResolvedRouteModule {
 export const isRouteDefinition = (value: unknown): value is RouteDefinition =>
   typeof value === "object" && value !== null && (value as Record<symbol, unknown>)[routeDefinitionMarker] === true;
 
-/**
- * Every loader — the RSC worker, the CSR boot, the generated root layout — reads route modules by their named
- * exports. A chain module has one export, so it is unfolded into that shape here and nothing downstream learns
- * which of the two it was reading; a legacy module passes through untouched.
- */
+/** Unfolds a chain module into the named-export shape every loader reads; a legacy module passes through untouched. */
 export const resolveRouteModule = (
   mod: RouteModuleSource,
   key: string,

package/client/router.ts

@@ -20,12 +20,6 @@ export interface RouterInstance {
   back: (routeOptions?: RouteOptions) => void;
   refresh: () => void;
 }
-interface InternalRouterInstance {
-  push: (href: string, routeOptions?: RouteOptions) => void | Promise<void>;
-  replace: (href: string, routeOptions?: RouteOptions) => void | Promise<void>;
-  back: (routeOptions?: RouteOptions) => void;
-  refresh: () => void;
-}
 interface RouterOptions {
   prefix?: string;
   lang?: string;
@@ -136,8 +130,6 @@ const getServerBasePath = (reqPathname: string, lang: string, headerBasePath: st
 
 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 const getPathInfo = (requestUrl: string, lang: string, prefix: string) => {
@@ -166,14 +158,14 @@ class Router {
   #indexPath = "/";
   #navigation: Promise<void> = Promise.resolve();
   #historyIdx = 0;
-  #instance: InternalRouterInstance = {
+  #instance: RouterInstance = {
     push: (href: string) => {
       const { href: fullHref } = this.#getPathInfo(href);
-      Logger.info(`push to:${fullHref}`);
+      Logger.warn(`router.push(${fullHref}) does not navigate on the server; use router.redirect() there`);
     },
     replace: (href: string) => {
-      const { pathname } = this.#getPathInfo(href);
-      Logger.info(`replace to:${pathname}`);
+      const { href: fullHref } = this.#getPathInfo(href);
+      Logger.warn(`router.replace(${fullHref}) does not navigate on the server; use router.redirect() there`);
     },
     back: () => {
       throw new Error("back is only available in client");
@@ -183,7 +175,6 @@ class Router {
     },
   };
   init(options: SsrClientRouterOption | SsrServerRouterOption | CSRClientRouterOption) {
-    
     this.#prefix = options.prefix ?? "";
     this.#lang = options.lang ?? parseAkanI18nEnv().defaultLocale;
     this.#routePaths = new Set(
@@ -198,29 +189,20 @@ class Router {
     }
     this.#ensureHistoryState();
     if (options.type === "csr") this.#initCsrClientRouter(options);
-    else if (options.side === "server") this.#initSsrServerRouter(options);
-    else this.#initSsrClientRouter(options);
+    else if (options.side === "client") this.#initSsrClientRouter(options);
     this.isInitialized = true;
     Logger.verbose("Router initialized");
   }
-  #initSsrServerRouter(options: SsrServerRouterOption) {
-  }
   #initSsrClientRouter(options: SsrClientRouterOption) {
+    const navigate = (method: "push" | "replace") => (href: string, routeOptions?: RouteOptions) => {
+      const pathInfo = this.#getPathInfo(href);
+      const navigationPathInfo = this.#getNavigationPathInfo(href);
+      this.#postPathChange(pathInfo);
+      return options.router[method](navigationPathInfo.href, routeOptions);
+    };
     this.#instance = {
-      push: (href: string, routeOptions) => {
-        const router = options.router;
-        const pathInfo = this.#getPathInfo(href);
-        const navigationPathInfo = this.#getNavigationPathInfo(href);
-        this.#postPathChange(pathInfo);
-        return router.push(navigationPathInfo.href, routeOptions);
-      },
-      replace: (href: string, routeOptions) => {
-        const router = options.router;
-        const pathInfo = this.#getPathInfo(href);
-        const navigationPathInfo = this.#getNavigationPathInfo(href);
-        this.#postPathChange(pathInfo);
-        return router.replace(navigationPathInfo.href, routeOptions);
-      },
+      push: navigate("push"),
+      replace: navigate("replace"),
       back: () => {
         const router = options.router;
         const pathInfo = this.#getPathInfo(document.referrer);
@@ -381,14 +363,8 @@ class Router {
     this.#postDevSyncNavigation("replace", href);
     return undefined as never;
   }
-  /**
-   * The navigation `push` / `replace` last started, for a caller that has to know whether it landed. **Rejects
-   * when the route refused to move** — a target that resolves to nothing leaves the page where it was instead of
-   * replacing it, and `push` returns long before that is known, so this is the only place it can be reported.
-   *
-   * A method rather than a getter: `router` is a Proxy that binds functions to the real instance, and a getter
-   * reached through it would run with the Proxy as `this` and fail on the private field.
-   */
+  /** The last `push`/`replace`; rejects when the route refused to move. A method, not a getter: through the `router`
+   * Proxy a getter would run with the Proxy as `this` and fail on the private field. */
   navigation(): Promise<void> {
     return this.#navigation;
   }
@@ -411,7 +387,6 @@ class Router {
   }
   back(routeOptions?: RouteOptions) {
     if (getEnv().side === "server") throw new Error("back is only available in client side");
-    
     this.#checkInitialized();
     this.#instance.back(routeOptions);
     return undefined as never;
@@ -462,11 +437,7 @@ class Router {
     this.#instance.replace(`${path}${search ? `?${search}` : ""}${hash ? `#${hash}` : ""}`);
     return undefined as never;
   }
-  /**
-   * A pathname with the locale and base-path segments taken off — the app-internal route it names, which is what
-   * a tool argument and a `<a href>` have in common. Unguarded, unlike `getPath`, whose default argument is the
-   * one thing in it that needs a browser.
-   */
+  /** A pathname without its locale and base-path segments; unlike `getPath`, it needs no browser. */
   routeOf(pathname: string) {
     return getPathInfo(pathname, this.#lang, this.#prefix).path;
   }

package/client/rscNavigation.ts

@@ -4,17 +4,16 @@ declare global {
   var __AKAN_RSC_NAVIGATE__:
     | ((href: string, options?: { replace?: boolean; scrollToTop?: boolean }) => Promise<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;
 }
 
 export const clearRscNavigationCache = () => {
   globalThis.__AKAN_RSC_CLEAR_CACHE__?.();
 };
 
-/**
- * True when the page tree currently on screen was replayed from the RSC navigation cache instead of
- * fetched from the server. Data hydrated out of such a payload can be arbitrarily old, so anything
- * that must show current values should refetch.
- */
+/** True when the page on screen was replayed from the RSC navigation cache, so its hydrated data may be stale. */
 export const isRscNavigationFromCache = () => globalThis.__AKAN_RSC_IS_FROM_CACHE__?.() ?? false;
 
 export const navigateRsc = (href: string, options?: { replace?: boolean; scrollToTop?: boolean }) => {

package/client/sharedContext.ts

@@ -1,25 +1,8 @@
 "use client";
 import { type Context, createContext } from "react";
 
-/**
- * A React context interned on `globalThis`, which is how every context this framework owns must be made.
- *
- * An akan build does not give an app one copy of `akanjs`: it inlines each reachable module into every client
- * chunk that reaches it — four copies of the agent runtime in this repo's own docs app. A context is identified
- * by object identity, so a Provider mounted from one copy is invisible to a consumer holding another, and the
- * consumer silently reads the context's default instead.
- *
- * Silently is the whole problem. `UiOverrideContext` was a plain `createContext`, so a route's `_overrides.tsx`
- * bound its slots in the chunk holding the generated provider and every overridable component in another chunk
- * kept rendering the framework default — no throw, no warning, and only *some* slots affected, which reads like
- * a bug in the app's own component. The same shape cost a zone every tool it declared.
- *
- * The rule is therefore mechanical rather than case-by-case: a context whose Provider and consumers can be
- * bundled apart is every context worth having, so all of them go through here. A test fails if one does not.
- *
- * `use-agentic` carries its own twin under a `useAgentic.` prefix, deliberately — it ships as a standalone
- * package and cannot import this one. The prefixes keep the two namespaces from ever meeting.
- */
+/** Every framework context is made here: a build inlines modules into each client chunk, so a plain `createContext`
+ * copy silently misses a Provider from another chunk. `use-agentic` keeps its own `useAgentic.`-prefixed twin. */
 export const sharedContext = <T>(name: string, initial: T): Context<T> => {
   const key = Symbol.for(`akanjs.context.${name}`);
   const holder = globalThis as typeof globalThis & { [slot: symbol]: Context<T> | undefined };

package/client/storage.ts

@@ -1,56 +1,47 @@
 import { getEnv } from "akanjs/base";
-import { loadCapacitorPreferences } from "./capacitor";
+import { type CapacitorPreferencesModule, loadCapacitorPreferences } from "./capacitor";
 
-const getLocalStorageItem = (key: string) => localStorage.getItem(key);
+type Preferences = CapacitorPreferencesModule["Preferences"];
 
-const setLocalStorageItem = (key: string, value: string) => {
-  localStorage.setItem(key, value);
-};
-
-const removeLocalStorageItem = (key: string) => {
-  localStorage.removeItem(key);
+const inStorage = async <T>(native: (preferences: Preferences) => Promise<T>, local: () => T) => {
+  const env = getEnv();
+  if (env.side === "server") return;
+  if (env.renderMode === "ssr") return local();
+  try {
+    const { Preferences } = await loadCapacitorPreferences();
+    return await native(Preferences);
+  } catch {
+    return local();
+  }
 };
 
 export const storage = {
-  getItem: async (key: string) => {
-    const env = getEnv();
-    if (env.side === "server") return;
-    if (env.renderMode === "ssr") return getLocalStorageItem(key);
-    try {
-      const { Preferences } = await loadCapacitorPreferences();
-      return (await Preferences.get({ key })).value;
-    } catch {
-      return getLocalStorageItem(key);
-    }
-  },
-  setItem: async (key: string, value: string) => {
-    const env = getEnv();
-    if (env.side === "server") return;
-    if (env.renderMode === "ssr") {
-      setLocalStorageItem(key, value);
-      return;
-    }
-    try {
-      const { Preferences } = await loadCapacitorPreferences();
-      await Preferences.set({ key, value });
-      return;
-    } catch {
-      setLocalStorageItem(key, value);
-      return;
-    }
-  },
+  getItem: (key: string) =>
+    inStorage(
+      async (preferences) => (await preferences.get({ key })).value,
+      () => localStorage.getItem(key),
+    ),
+  setItem: (key: string, value: string) =>
+    inStorage(
+      async (preferences) => {
+        await preferences.set({ key, value });
+      },
+      () => {
+        localStorage.setItem(key, value);
+      },
+    ),
   removeItem: async (key: string) => {
     const env = getEnv();
     if (env.side === "server") return;
     if (env.renderMode === "ssr") {
-      removeLocalStorageItem(key);
+      localStorage.removeItem(key);
       return;
     }
     try {
       const { Preferences } = await loadCapacitorPreferences();
-      return Preferences.remove({ key });
+      return await Preferences.remove({ key });
     } catch {
-      removeLocalStorageItem(key);
+      localStorage.removeItem(key);
       return;
     }
   },

package/client/translator.ts

@@ -11,13 +11,12 @@ export interface AllDictionary {
 
 interface TranslatorState {
   langDictionaryMap: Map<string, Dictionary>;
-
+  
   seededDicts: WeakSet<object>;
-
   replacedDicts: WeakSet<object>;
-
+  
   activeLocale?: string;
-
+  
   activePath?: string;
 }
 
@@ -70,12 +69,12 @@ export class Translator {
     const node = pathGetLoose(key, dictionary, ".") as { t?: unknown } | null;
     return typeof node?.t === "string" ? node.t : undefined;
   }
-
+  
   static #lookupDefault(lang: string, key: string) {
     const { defaultLocale } = parseAkanI18nEnv();
     return defaultLocale === lang ? undefined : Translator.#lookup(defaultLocale, key);
   }
-
+  
   static seed(lang: string, dict: Dictionary | undefined) {
     if (!dict) return;
     const state = getTranslatorState();

package/client/types.ts

@@ -105,7 +105,6 @@ const slugFontPart = (value: string) =>
     .replace(/[^a-z0-9]+/g, "-")
     .replace(/^-+|-+$/g, "") || "font";
 
-/** Common props for list/zone components that render many model records. */
 export interface ModelsProps<M extends { id: string }> {
   className?: string;
   slice?: SliceMeta;
@@ -114,7 +113,6 @@ export interface ModelsProps<M extends { id: string }> {
   onClickItem?: (model: M) => unknown;
 }
 
-/** Common props for unit/view components that render one named model record. */
 export type ModelProps<T extends string, L extends { id: string }> = { [key in T]: L } & {
   className?: string;
   slice?: SliceMeta;
@@ -213,7 +211,6 @@ export interface ReactFont {
   optimize?: boolean;
 }
 
-/** Font declaration consumed by Akan layout modules and font optimization. */
 export type Font = ReactFont;
 
 export interface RootLayoutProps {