akanjs 0.0.1 → 2.0.0-beta.1

package/client/device.ts

@@ -0,0 +1,147 @@
+"use client";
+import type { DeviceInfo } from "@capacitor/device";
+import type { KeyboardInfo } from "@capacitor/keyboard";
+import type { RefObject } from "react";
+import { isMobile } from "react-device-detect";
+import { loadCapacitorDevice, loadCapacitorHaptics, loadCapacitorKeyboard, loadCapacitorSafeArea } from "./capacitor";
+
+interface DeviceInitOption {
+  lang: string;
+  info: DeviceInfo;
+  topSafeArea: number;
+  bottomSafeArea: number;
+  keyboard: Awaited<ReturnType<typeof loadCapacitorKeyboard>>["Keyboard"];
+  haptics: Awaited<ReturnType<typeof loadCapacitorHaptics>>["Haptics"];
+  impactStyle: Awaited<ReturnType<typeof loadCapacitorHaptics>>["ImpactStyle"];
+}
+/** 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({
+    lang,
+    supportLanguages = [],
+  }: {
+    lang?: string;
+    supportLanguages?: string[] | readonly string[];
+  }) {
+    if (Device.instance) return Device.instance;
+    const [{ Device: CapacitorDevice }, { Keyboard }, { Haptics, ImpactStyle }, { SafeArea }] = await Promise.all([
+      loadCapacitorDevice(),
+      loadCapacitorKeyboard(),
+      loadCapacitorHaptics(),
+      loadCapacitorSafeArea(),
+    ]);
+    const [
+      info,
+      { value: languageCode },
+      {
+        insets: { top: topSafeArea, bottom: bottomSafeArea },
+      },
+    ] = await Promise.all([CapacitorDevice.getInfo(), CapacitorDevice.getLanguageCode(), SafeArea.getSafeAreaInsets()]);
+    const predefinedLangPath = window.location.pathname.split("/")[1]?.split("?")[0];
+    const predefinedLang = supportLanguages.find((language) => language === predefinedLangPath);
+    const device = new Device({
+      lang: lang ?? predefinedLang ?? languageCode,
+      info,
+      topSafeArea,
+      bottomSafeArea,
+      keyboard: Keyboard,
+      haptics: Haptics,
+      impactStyle: ImpactStyle,
+    });
+    Device.instance = device;
+    return device;
+  }
+  static getDevice() {
+    if (!Device.instance) throw new Error("Device is not loaded yet");
+    return Device.instance;
+  }
+
+  info: DeviceInfo;
+  lang: string;
+  topSafeArea: number;
+  bottomSafeArea: number;
+  isMobile = isMobile;
+  #keyboard: DeviceInitOption["keyboard"];
+  #haptics: DeviceInitOption["haptics"];
+  #impactStyle: DeviceInitOption["impactStyle"];
+  #pageContentRef: RefObject<HTMLDivElement | null> | null = null;
+
+  constructor({ lang, info, topSafeArea, bottomSafeArea, keyboard, haptics, impactStyle }: DeviceInitOption) {
+    this.info = info;
+    this.lang = lang;
+    this.topSafeArea = topSafeArea;
+    this.bottomSafeArea = bottomSafeArea;
+    this.#keyboard = keyboard;
+    this.#haptics = haptics;
+    this.#impactStyle = impactStyle;
+  }
+  setPageContentRef(pageContentRef: RefObject<HTMLDivElement | null>) {
+    this.#pageContentRef = pageContentRef;
+  }
+  async showKeyboard() {
+    if (this.info.platform === "web") return;
+    await this.#keyboard.show();
+  }
+  async hideKeyboard() {
+    if (this.info.platform === "web") return;
+    await this.#keyboard.hide();
+  }
+  listenKeyboardChanged(onKeyboardChanged: (height: number) => void) {
+    if (this.info.platform === "web") return;
+    void this.#keyboard.addListener("keyboardWillShow", (keyboard: KeyboardInfo) => {
+      onKeyboardChanged(keyboard.keyboardHeight);
+    });
+    void this.#keyboard.addListener("keyboardDidShow", (keyboard: KeyboardInfo) => {
+      onKeyboardChanged(keyboard.keyboardHeight);
+    });
+    void this.#keyboard.addListener("keyboardWillHide", () => {
+      onKeyboardChanged(0);
+    });
+    void this.#keyboard.addListener("keyboardDidHide", () => {
+      onKeyboardChanged(0);
+    });
+  }
+  unlistenKeyboardChanged() {
+    if (this.info.platform === "web") return;
+    void this.#keyboard.removeAllListeners();
+  }
+  async vibrate(type: "light" | "medium" | "heavy" | number = "medium") {
+    if (typeof type === "number") {
+      await this.#haptics.vibrate({ duration: type });
+      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();
+      },
+    };
+    await handleImpact[type]();
+  }
+  getScrollTop() {
+    if (this.info.platform === "web") return window.scrollY;
+    return this.#pageContentRef?.current?.scrollTop ?? 0;
+  }
+  setScrollTop(scrollTop: number) {
+    if (this.info.platform === "web") {
+      window.scrollTo({ top: scrollTop });
+      return;
+    }
+    return this.#pageContentRef?.current?.scrollTo({ top: scrollTop });
+  }
+}

package/client/fetch.ts

@@ -0,0 +1 @@
+export { fetch, sig } from "./clientRuntime";

package/client/index.ts

@@ -0,0 +1,15 @@
+export * from "./capacitor";
+export * from "./clientRuntime";
+export * from "./cookie";
+export * from "./createFont";
+export * from "./csrTypes";
+export * from "./decorators";
+export * from "./device";
+export * from "./locale";
+export * from "./makePageProto";
+export * from "./router";
+export * from "./rscNavigation";
+export * from "./storage";
+export * from "./translator";
+export * from "./types";
+export * from "./useClient";

package/client/locale.ts

@@ -0,0 +1,4 @@
+"use client";
+import { createContext } from "react";
+
+export const dictionaryContext = createContext<{ [key: string]: { [key: string]: string } }>({});

package/client/makePageProto.tsx

@@ -0,0 +1,178 @@
+import { getEnv } from "akanjs/base";
+import { parseAkanI18nEnv } from "akanjs/common";
+import { getRequest, headers } from "akanjs/fetch";
+import type { ReactNode } from "react";
+import { Translator } from "./translator";
+
+type TransMessage<Locale extends Record<string, unknown>> = {
+  [K in keyof Locale]-?: `${K & string}${Locale[K] extends Record<string, unknown> ? `.${keyof Locale[K] extends string ? keyof Locale[K] : never}` : ""}`;
+}[keyof Locale];
+
+interface ErrRestoreOption {
+  statusCode?: number;
+  details?: unknown;
+  path?: string;
+  timestamp?: string;
+}
+
+interface ErrPayload extends ErrRestoreOption {
+  error: string;
+  data?: Record<string, unknown>;
+}
+
+const getPageInfo = (): { locale: string; path: string } => {
+  const { defaultLocale, locales } = parseAkanI18nEnv();
+  const localeSet = new Set(locales);
+  if (getEnv().side !== "server") {
+    const [, firstSegment = "", ...rest] = window.location.pathname.split("/");
+    if (localeSet.has(firstSegment)) return { locale: firstSegment, path: `/${rest.join("/")}` };
+    return { locale: defaultLocale, path: window.location.pathname };
+  }
+  const h = headers();
+
+  const localeHeader = h.get("x-locale");
+  const pathHeader = h.get("x-path");
+  if (localeHeader && pathHeader) return { locale: localeHeader, path: pathHeader };
+  const req = getRequest();
+  if (req) {
+    const urlPath = new URL(req.url).pathname;
+    const [, firstSegment = "", ...rest] = urlPath.split("/");
+    if (!localeHeader && !localeSet.has(firstSegment)) return { locale: defaultLocale, path: pathHeader ?? urlPath };
+    return {
+      locale: localeHeader ?? (firstSegment || defaultLocale),
+      path: pathHeader ?? `/${rest.join("/")}`,
+    };
+  }
+  return { locale: localeHeader ?? defaultLocale, path: pathHeader ?? "/" };
+};
+
+export interface TransMessageOption {
+  key?: string;
+  duration?: number;
+  data?: Record<string, unknown>;
+}
+
+const msg = {
+  info: () => null,
+  success: () => null,
+  error: () => null,
+  warning: () => null,
+  loading: () => null,
+} as {
+  info: (key: TransMessage<any>, option?: TransMessageOption) => void;
+  success: (key: TransMessage<any>, option?: TransMessageOption) => void;
+  error: (key: TransMessage<any>, option?: TransMessageOption) => void;
+  warning: (key: TransMessage<any>, option?: TransMessageOption) => void;
+  loading: (key: TransMessage<any>, option?: TransMessageOption) => void;
+};
+
+export const makePageProto = <
+  Dict extends { __Dict_Key__: string; __Error_Key__: string },
+  DictKey extends Dict["__Dict_Key__"] = Dict["__Dict_Key__"],
+  ErrorKey extends Dict["__Error_Key__"] = Dict["__Error_Key__"],
+>(dictionary: {
+  [key: string]: { [key: string]: Record<string, unknown> };
+}) => {
+  const translator = new Translator(dictionary);
+  class Err extends Error {
+    readonly error: string;
+    readonly statusCode: number;
+    readonly details?: unknown;
+    readonly data?: Record<string, unknown>;
+    readonly path?: string;
+    readonly timestamp?: string;
+
+    constructor(key: ErrorKey, data?: Record<string, unknown>, option: ErrRestoreOption = {}) {
+      super(key);
+      this.name = this.constructor.name;
+      this.error = key;
+      this.statusCode = option.statusCode ?? 400;
+      this.details = option.details;
+      this.data = data;
+      this.path = option.path;
+      this.timestamp = option.timestamp;
+    }
+
+    toJSON() {
+      return {
+        error: this.message,
+        statusCode: this.statusCode,
+        ...(this.details !== undefined ? { details: this.details } : {}),
+        ...(this.data !== undefined ? { data: this.data } : {}),
+        ...(this.path !== undefined ? { path: this.path } : {}),
+        ...(this.timestamp !== undefined ? { timestamp: this.timestamp } : {}),
+      };
+    }
+
+    static fromJSON(payload: ErrPayload) {
+      return new Err(payload.error as ErrorKey, payload.data, payload);
+    }
+
+    static BadRequest = class BadRequestErr extends Err {
+      constructor(key: ErrorKey, data?: Record<string, unknown>, option: ErrRestoreOption = {}) {
+        super(key, data, { ...option, statusCode: 400 });
+      }
+    };
+
+    static Unauthorized = class UnauthorizedErr extends Err {
+      constructor(key: ErrorKey, data?: Record<string, unknown>, option: ErrRestoreOption = {}) {
+        super(key, data, { ...option, statusCode: 401 });
+      }
+    };
+
+    static Forbidden = class ForbiddenErr extends Err {
+      constructor(key: ErrorKey, data?: Record<string, unknown>, option: ErrRestoreOption = {}) {
+        super(key, data, { ...option, statusCode: 403 });
+      }
+    };
+
+    static NotFound = class NotFoundErr extends Err {
+      constructor(key: ErrorKey, data?: Record<string, unknown>, option: ErrRestoreOption = {}) {
+        super(key, data, { ...option, statusCode: 404 });
+      }
+    };
+
+    static Conflict = class ConflictErr extends Err {
+      constructor(key: ErrorKey, data?: Record<string, unknown>, option: ErrRestoreOption = {}) {
+        super(key, data, { ...option, statusCode: 409 });
+      }
+    };
+  }
+  return {
+    Err,
+    msg: msg as {
+      info: (key: DictKey, option?: TransMessageOption) => void;
+      success: (key: DictKey, option?: TransMessageOption) => void;
+      error: (key: DictKey | ErrorKey, option?: TransMessageOption) => void;
+      warning: (key: DictKey, option?: TransMessageOption) => void;
+      loading: (key: DictKey, option?: TransMessageOption) => void;
+    },
+    usePage: () => {
+      const { locale, path } = getPageInfo();
+      const lang = locale;
+      const l = (key: DictKey, param?: { [key: string]: string | number }) => translator.translate(lang, key, param);
+      l._ = (key: string, param?: { [key: string]: string | number }) => translator.translate(lang, key, param);
+      l.rich = (key: DictKey, param?: { [key: string]: string | number }) =>
+        (
+          <span
+            
+            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 => {
+        return (translation[lang as "en" | "ko" | (string & {})] ?? "unknown translation") as Returns extends string
+          ? string
+          : Returns;
+      };
+      return { path, l, lang };
+    },
+  };
+};

package/client/router.ts

@@ -0,0 +1,286 @@
+import { getEnv } from "akanjs/base";
+import { getBasePathFromPathname, Logger, parseAkanI18nEnv, parseBasePaths } from "akanjs/common";
+
+export interface RouteOptions {
+  scrollToTop?: boolean;
+}
+
+export interface RouterInstance {
+  push: (href: string, routeOptions?: RouteOptions) => void;
+  replace: (href: string, routeOptions?: RouteOptions) => void;
+  back: (routeOptions?: RouteOptions) => void;
+  refresh: () => void;
+}
+interface InternalRouterInstance {
+  push: (href: string, routeOptions?: RouteOptions) => void;
+  replace: (href: string, routeOptions?: RouteOptions) => void;
+  back: (routeOptions?: RouteOptions) => void;
+  refresh: () => void;
+}
+interface RouterOptions {
+  prefix?: string;
+  lang?: string;
+}
+interface SsrServerRouterOption extends RouterOptions {
+  type: "ssr";
+  side: "server";
+}
+interface SsrClientRouterOption extends RouterOptions {
+  type: "ssr";
+  side: "client";
+  router: RouterInstance;
+}
+interface CSRClientRouterOption extends RouterOptions {
+  type: "csr";
+  router: RouterInstance;
+}
+export type RedirectMethod = "replace" | "push";
+
+export class AkanRedirectError extends Error {
+  readonly digest = "AKAN_REDIRECT";
+  constructor(
+    readonly location: string,
+    readonly method: RedirectMethod = "replace",
+  ) {
+    super(`Redirect to ${location}`);
+    this.name = "AkanRedirectError";
+  }
+}
+
+export class AkanNotFoundError extends Error {
+  readonly digest = "AKAN_NOT_FOUND";
+  constructor() {
+    super("Not found");
+    this.name = "AkanNotFoundError";
+  }
+}
+
+function getServerRequestContext() {
+  const { getRequest, headers } = require("akanjs/fetch");
+  return { getRequest, headers } as { getRequest: () => Request; headers: () => Map<string, string> };
+}
+
+const getConfiguredBasePaths = () => new Set(parseBasePaths(process.env.AKAN_PUBLIC_BASE_PATHS));
+
+const getServerBasePath = (reqPathname: string, lang: string, headerBasePath: string | undefined, fallback: string) => {
+  return (
+    getBasePathFromPathname(reqPathname, {
+      basePaths: getConfiguredBasePaths(),
+      i18n: { locales: [lang], defaultLocale: lang },
+      headerBasePath,
+    }) ?? fallback
+  );
+};
+
+declare global {
+  var __AKAN_ROUTER__: Router | undefined;
+}
+
+export const getPathInfo = (requestUrl: string, lang: string, prefix: string) => {
+  const [urlWithoutHash, hash = ""] = requestUrl.split("#");
+  const [url, search = ""] = urlWithoutHash.split("?");
+  const langLength = lang.length + 1;
+  const pathWithSubRoute = url === `/${lang}` ? "/" : url.startsWith(`/${lang}/`) ? url.slice(langLength) : url;
+  const prefixLength = prefix ? prefix.length + 1 : 0;
+  const path = !prefixLength
+    ? pathWithSubRoute
+    : pathWithSubRoute === `/${prefix}`
+      ? "/"
+      : pathWithSubRoute.startsWith(`/${prefix}`)
+        ? pathWithSubRoute.slice(prefixLength)
+        : pathWithSubRoute;
+  const subRoute = prefix ? `/${prefix}` : "";
+  const pathname = path.startsWith("http") ? path : path === "/" ? `/${lang}${subRoute}` : `/${lang}${subRoute}${path}`;
+  const href = `${pathname}${search ? `?${search}` : ""}${hash ? `#${hash}` : ""}`;
+  return { path, pathname, hash, search, href };
+};
+class Router {
+  isInitialized = false;
+  #prefix = "";
+  #lang = parseAkanI18nEnv().defaultLocale;
+  #instance: InternalRouterInstance = {
+    push: (href: string) => {
+      const { href: fullHref } = this.#getPathInfo(href);
+      Logger.log(`push to:${fullHref}`);
+    },
+    replace: (href: string) => {
+      const { pathname } = this.#getPathInfo(href);
+      Logger.log(`replace to:${pathname}`);
+    },
+    back: () => {
+      throw new Error("back is only available in client");
+    },
+    refresh: () => {
+      throw new Error("refresh is only available in client");
+    },
+  };
+  init(options: SsrClientRouterOption | SsrServerRouterOption | CSRClientRouterOption) {
+    
+    this.#prefix = options.prefix ?? "";
+    this.#lang = options.lang ?? parseAkanI18nEnv().defaultLocale;
+    if (options.type === "csr") this.#initCsrClientRouter(options);
+    else if (options.side === "server") this.#initSsrServerRouter(options);
+    else this.#initSsrClientRouter(options);
+    this.isInitialized = true;
+    Logger.verbose("Router initialized");
+  }
+  #initSsrServerRouter(options: SsrServerRouterOption) {
+  }
+  #initSsrClientRouter(options: SsrClientRouterOption) {
+    this.#instance = {
+      push: (href: string, routeOptions) => {
+        const router = options.router;
+        const pathInfo = this.#getPathInfo(href);
+        this.#postPathChange(pathInfo);
+        router.push(pathInfo.href, routeOptions);
+      },
+      replace: (href: string, routeOptions) => {
+        const router = options.router;
+        const pathInfo = this.#getPathInfo(href);
+        this.#postPathChange(pathInfo);
+        router.replace(pathInfo.href, routeOptions);
+      },
+      back: () => {
+        const router = options.router;
+        const pathInfo = this.#getPathInfo(document.referrer);
+        this.#postPathChange(pathInfo);
+        router.back();
+      },
+      refresh: () => {
+        const router = options.router;
+        const pathInfo = this.#getPathInfo(location.pathname);
+        this.#postPathChange(pathInfo);
+        router.refresh();
+      },
+    };
+  }
+  #initCsrClientRouter(options: CSRClientRouterOption) {
+    this.#instance = {
+      push: (href: string, routeOptions) => {
+        const { path, pathname, hash, href: fullHref } = this.#getPathInfo(href);
+        this.#postPathChange({ path, pathname, hash });
+        options.router.push(fullHref, routeOptions);
+      },
+      replace: (href: string, routeOptions) => {
+        const { path, pathname, hash, href: fullHref } = this.#getPathInfo(href);
+        this.#postPathChange({ path, pathname, hash });
+        
+        setTimeout(() => {
+          options.router.replace(fullHref, routeOptions);
+        }, 0);
+      },
+      back: (routeOptions) => {
+        const { path, pathname, hash } = this.#getPathInfo(document.referrer);
+        this.#postPathChange({ path, pathname, hash });
+        options.router.back(routeOptions);
+      },
+      refresh: () => {
+        const { path, pathname, hash } = this.#getPathInfo(location.pathname);
+        this.#postPathChange({ path, pathname, hash });
+        options.router.refresh();
+      },
+    };
+  }
+  #checkInitialized() {
+    if (!this.isInitialized) throw new Error("Router is not initialized");
+  }
+
+  #getPathInfo(href: string, prefix = this.#prefix) {
+    return getPathInfo(href, this.#lang, prefix);
+  }
+  #postPathChange({ path, pathname, hash }: { path: string; pathname: string; hash: string }) {
+    Logger.log(`pathChange-start:${path}${hash ? `#${hash}` : ""}`);
+    window.parent.postMessage({ type: "pathChange", path, pathname, hash }, "*");
+  }
+  push(href: string, routeOptions?: RouteOptions) {
+    this.#checkInitialized();
+    this.#instance.push(href, routeOptions);
+    return undefined as never;
+  }
+  replace(href: string, routeOptions?: RouteOptions) {
+    this.#checkInitialized();
+    this.#instance.replace(href, routeOptions);
+    return undefined as never;
+  }
+  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;
+  }
+  refresh() {
+    if (getEnv().side === "server") throw new Error("refresh is only available in client side");
+    this.#checkInitialized();
+    this.#instance.refresh();
+    return undefined as never;
+  }
+  redirect(href: string): never {
+    if (getEnv().side === "server") {
+      const { getRequest, headers: requestHeaders } = getServerRequestContext();
+      const h = requestHeaders();
+      const req = getRequest();
+      const reqPathname = req ? new URL(req.url).pathname : "";
+      const langFromPath = reqPathname.split("/").filter(Boolean)[0];
+      const lang = (h.get("x-locale") ?? langFromPath ?? this.#lang) as string;
+      const basePath = getServerBasePath(reqPathname, lang, h.get("x-base-path") ?? undefined, this.#prefix);
+      const { pathname, href: fullHref } = getPathInfo(href, lang, basePath);
+      Logger.log(`redirect to:${pathname}`);
+      throw new AkanRedirectError(fullHref, "replace");
+    } else {
+      this.#instance.replace(href);
+    }
+    return undefined as never;
+  }
+  notFound(): never {
+    if (getEnv().side === "server") {
+      Logger.log(`redirect to:/404`);
+      throw new AkanNotFoundError();
+    }
+    this.#checkInitialized();
+    this.#instance.replace("/404");
+    return undefined as never;
+  }
+  setLang(lang: string) {
+    if (getEnv().side === "server") throw new Error("setLang is only available in client side");
+    this.#checkInitialized();
+    const { path } = getPathInfo(window.location.pathname, this.#lang, this.#prefix);
+    this.#lang = lang;
+    this.#instance.replace(`/${lang}${path}`);
+    return undefined as never;
+  }
+  getPath(pathname = window.location.pathname) {
+    if (getEnv().side === "server") throw new Error("getPath is only available in client side");
+    const { path } = getPathInfo(pathname, this.#lang, this.#prefix);
+    return path;
+  }
+  getFullPath(withLang = true) {
+    if (getEnv().side === "server") throw new Error("getPath is only available in client side");
+    return `${withLang ? `/${this.#lang}/` : ""}${this.#prefix}${this.getPath()}`;
+  }
+  getPrefix() {
+    return this.#prefix;
+  }
+  getPrefixedPath(path: string) {
+    return this.#prefix ? `${this.#lang ? `/${this.#lang}` : ""}/${this.#prefix}${path}` : path;
+  }
+}
+const browserRouter = () => {
+  if (!globalThis.__AKAN_ROUTER__) globalThis.__AKAN_ROUTER__ = new Router();
+  return globalThis.__AKAN_ROUTER__;
+};
+
+let serverRouter: Router | undefined;
+const getRouter = () => {
+  if (getEnv().side !== "server") return browserRouter();
+  serverRouter ??= new Router();
+  return serverRouter;
+};
+
+/** Akan navigation singleton that normalizes language/base-path prefixes before routing. */
+export const router = new Proxy({} as Router, {
+  get(_target, prop, receiver) {
+    const value = Reflect.get(getRouter(), prop, receiver);
+    return typeof value === "function" ? value.bind(getRouter()) : value;
+  },
+});

package/client/rscNavigation.ts

@@ -0,0 +1,19 @@
+declare global {
+  var __AKAN_RSC_CLEAR_CACHE__: (() => void) | undefined;
+  var __AKAN_RSC_NAVIGATE__:
+    | ((href: string, options?: { replace?: boolean; scrollToTop?: boolean }) => Promise<void>)
+    | undefined;
+}
+
+export const clearRscNavigationCache = () => {
+  globalThis.__AKAN_RSC_CLEAR_CACHE__?.();
+};
+
+export const navigateRsc = (href: string, options?: { replace?: boolean; scrollToTop?: boolean }) => {
+  return globalThis.__AKAN_RSC_NAVIGATE__?.(href, options);
+};
+
+export const useRscNavigation = () => ({
+  clearCache: clearRscNavigationCache,
+  navigate: navigateRsc,
+});

package/client/storage.ts

@@ -0,0 +1,33 @@
+import { getEnv } from "akanjs/base";
+
+export const storage = {
+  getItem: async (key: string) => {
+    if (getEnv().side === "server") return;
+    if (getEnv().renderMode === "ssr") return localStorage.getItem(key);
+    else {
+      const { Preferences } = await import("@capacitor/preferences");
+      return (await Preferences.get({ key })).value;
+    }
+  },
+  setItem: async (key: string, value: string) => {
+    if (getEnv().side === "server") return;
+    if (getEnv().renderMode === "ssr") {
+      localStorage.setItem(key, value);
+      return;
+    } else {
+      const { Preferences } = await import("@capacitor/preferences");
+      await Preferences.set({ key, value });
+      return;
+    }
+  },
+  removeItem: async (key: string) => {
+    if (getEnv().side === "server") return;
+    if (getEnv().renderMode === "ssr") {
+      localStorage.removeItem(key);
+      return;
+    } else {
+      const { Preferences } = await import("@capacitor/preferences");
+      return Preferences.remove({ key });
+    }
+  },
+};