akanjs 3.0.0-beta.8 → 3.0.0

package/base/baseEnv.ts

@@ -1,3 +1,5 @@
+import { DatabaseModes } from "./databaseModes";
+
 type ProcessEnvLike = { env?: Record<string, string | undefined> };
 
 const globalWithProcess = globalThis as unknown as { process?: ProcessEnvLike };
@@ -19,8 +21,6 @@ export type BackendEnv = {
   hostname?: string | null;
   port?: number;
   database?: {
-    mode?: DatabaseMode;
-    driver?: "sqlite" | "libsql" | "postgres";
     sqlite?: {
       filePath?: string;
       journalMode?: string;
@@ -41,6 +41,7 @@ export type BackendEnv = {
       database?: string;
       user?: string;
       password?: string;
+      insightUrl?: string;
     };
   };
   solid?: {
@@ -51,6 +52,7 @@ export type BackendEnv = {
     cleanupIntervalMs?: number;
     queuePollIntervalMs?: number;
     queueLeaseMs?: number;
+    queueFailedRetentionMs?: number;
   };
   onCleanup?: () => Promise<void>;
 };
@@ -79,7 +81,7 @@ type RoutePrefixOverride = { api?: string; ws?: string };
 
 const globalWithPrefix = globalThis as typeof globalThis & { __AKAN_PREFIX__?: RoutePrefixOverride };
 
-/** Leading slash, no trailing slash. A blank value — or a bare `/`, which would swallow every page route — is no prefix at all and falls through to the next source. */
+/** Leading slash, no trailing slash; a blank value or a bare `/` (it would swallow every page route) is no prefix. */
 export const normalizeRoutePrefix = (value: string | undefined | null): string | undefined => {
   const trimmed = value?.trim();
   if (!trimmed) return undefined;
@@ -88,12 +90,9 @@ export const normalizeRoutePrefix = (value: string | undefined | null): string |
 };
 
 /**
- * Three sources, narrowest first. The global is what a server-rendered page's bootstrap script writes, so the
- * browser follows the process that rendered it. `AKAN_API_PREFIX` is deliberately outside the `AKAN_PUBLIC_*`
- * namespace: only that namespace is inlined into client bundles at build time, so a name inside it could never
- * act as a runtime override. `AKAN_PUBLIC_API_PREFIX` is the build-time default, and the only one a prebuilt CSR
- * or mobile bundle can read. Written out rather than looked up by key — a computed `process.env[...]` is opaque
- * to the bundler's define pass, and the public value would stop being inlined.
+ * Narrowest first: the SSR bootstrap global, then `AKAN_API_PREFIX` (outside `AKAN_PUBLIC_*`, which is inlined at build
+ * time, so it can override at runtime), then the build-time default. Written out: a computed `process.env[...]` escapes
+ * the bundler's define pass.
  */
 export const getApiPrefix = (): string =>
   normalizeRoutePrefix(globalWithPrefix.__AKAN_PREFIX__?.api) ??
@@ -112,10 +111,36 @@ export const resetEnvCache = () => {
   cachedEnv = undefined;
 };
 
+const csrServerUrl = (): URL | null => {
+  const runtime = (globalThis as { __AKAN_NATIVE__?: { env?: Record<string, string | undefined> } }).__AKAN_NATIVE__
+    ?.env?.PUBLIC_AKAN_SERVER_URL;
+  const [key, value] = runtime
+    ? ["PUBLIC_AKAN_SERVER_URL", runtime]
+    : ["AKAN_PUBLIC_SERVER_URL", process.env.AKAN_PUBLIC_SERVER_URL];
+  if (!value) return null;
+  const url = new URL(value);
+  if (url.protocol !== "http:" && url.protocol !== "https:")
+    throw new Error(`${key} must be an http(s) URL, got "${value}".`);
+  return url;
+};
+
+const nativeDevGatewayOrigin = (): string | null =>
+  (globalThis as { __AKAN_NATIVE_DEV__?: { gateway?: string } }).__AKAN_NATIVE_DEV__?.gateway
+    ? `${window.location.protocol}//${window.location.host}`
+    : null;
+
+const devServerOrigin = () => `http://localhost:${process.env.AKAN_PUBLIC_SERVER_PORT ?? "8282"}`;
+
+const nativeDevServerUrl = (operationMode: BaseEnv["operationMode"]): URL | null => {
+  const platform = (globalThis as { __AKAN_NATIVE__?: { platform?: string } }).__AKAN_NATIVE__?.platform;
+  if (operationMode !== "local" || !platform || platform === "web") return null;
+  return new URL(devServerOrigin());
+};
+
 const missingPublicEnv = (key: string) =>
   `getEnv() cannot run at build time: akan build does not inject ${key}. Call it from a runtime function instead of at module scope (e.g. env(() => getEnv()) in adapt(), a method body, or a default thunk).`;
 
-/** Reads and caches Akan runtime environment values from process/browser environment settings. */
+/** Cached after the first call. */
 export const getEnv = (): ClientEnv => {
   if (cachedEnv) return cachedEnv;
   const appName = process.env.AKAN_PUBLIC_APP_NAME ?? "unknown";
@@ -133,7 +158,14 @@ export const getEnv = (): ClientEnv => {
     appName,
     environment,
     operationMode,
-    databaseMode: process.env.AKAN_DATABASE_MODE as DatabaseMode | undefined,
+    databaseMode:
+      typeof window === "undefined"
+        ? DatabaseModes.settle({
+            requested: process.env.AKAN_DATABASE_MODE,
+            declared: process.env.AKAN_DATABASE_MODES,
+            local: environment === "local" || operationMode === "local",
+          })
+        : undefined,
   } as const;
   const side = typeof window === "undefined" ? "server" : "client";
   const renderMode = (process.env.AKAN_PUBLIC_RENDER_ENV ?? "csr") as ClientEnv["renderMode"];
@@ -152,7 +184,15 @@ export const getEnv = (): ClientEnv => {
         ? "http:"
         : "https:";
   const clientHttpUri = `${clientHttpProtocol}//${clientHost}${clientPort === 443 ? "" : `:${clientPort}`}`;
+  const csrClient = side === "client" && renderMode === "csr";
+  const pinnedServerUrl = csrClient ? csrServerUrl() : null;
+  const pageOrigin = csrClient && !pinnedServerUrl ? nativeDevGatewayOrigin() : null;
+  const serverUrl = csrClient && !pageOrigin ? (pinnedServerUrl ?? nativeDevServerUrl(operationMode)) : null;
+  
+  const hostFromPage =
+    side === "client" && !serverUrl && (!!pageOrigin || operationMode === "local" || renderMode !== "csr");
   const serverHost =
+    (pageOrigin ? window.location.hostname : serverUrl?.hostname) ??
     process.env.SERVER_HOST ??
     (operationMode === "local"
       ? typeof window === "undefined"
@@ -168,9 +208,14 @@ export const getEnv = (): ClientEnv => {
   const serverPort =
     side === "server"
       ? parseInt(process.env.AKAN_PUBLIC_SERVER_PORT ?? selfServerPort ?? "8282")
-      : parseInt(window.location.port || (window.location.protocol === "https:" ? "443" : "80"));
+      : serverUrl
+        ? parseInt(serverUrl.port || (serverUrl.protocol === "https:" ? "443" : "80"))
+        : hostFromPage
+          ? parseInt(window.location.port || (window.location.protocol === "https:" ? "443" : "80"))
+          : 443;
 
   const serverHttpProtocol: "http:" | "https:" =
+    ((pageOrigin ? window.location.protocol : serverUrl?.protocol) as "http:" | "https:" | undefined) ??
     (process.env.SERVER_HTTP_PROTOCOL as "http:" | "https:" | undefined) ??
     (operationMode === "local"
       ? side === "client"
@@ -183,9 +228,14 @@ export const getEnv = (): ClientEnv => {
           : ("http:" as const));
   const apiPrefix = getApiPrefix();
   const wsPrefix = getWsPrefix();
-  const serverHttpUri = `${serverHttpProtocol}//${serverHost}${serverPort === 443 ? "" : `:${serverPort}`}${apiPrefix}`;
+  
+  const serverHttpUri = pageOrigin
+    ? `${pageOrigin}${apiPrefix}`
+    : `${serverHttpProtocol}//${serverHost}${serverPort === 443 ? "" : `:${serverPort}`}${apiPrefix}`;
   const serverWsProtocol = serverHttpProtocol === "http:" ? "ws:" : "wss:";
-  const serverWsUri = `${serverWsProtocol}//${serverHost}${serverPort === 443 ? "" : `:${serverPort}`}`;
+  const serverWsUri = pageOrigin
+    ? pageOrigin.replace(/^http/, "ws")
+    : `${serverWsProtocol}//${serverHost}${serverPort === 443 ? "" : `:${serverPort}`}`;
 
   const env: ClientEnv = {
     ...baseEnv,
@@ -208,3 +258,10 @@ export const getEnv = (): ClientEnv => {
   cachedEnv = env;
   return env;
 };
+
+export const getServerOrigin = (): string => {
+  const env = getEnv();
+  const behindGateway =
+    env.side === "client" && env.renderMode === "csr" && !csrServerUrl() && !!nativeDevGatewayOrigin();
+  return behindGateway ? devServerOrigin() : new URL(env.serverHttpUri).origin;
+};

package/base/databaseModes.ts

@@ -0,0 +1,75 @@
+import type { DatabaseMode } from "./baseEnv";
+
+export interface DatabaseModeRequest {
+  /** `AKAN_DATABASE_MODE`: the mode a deployment names. */
+  requested: string | undefined;
+  /** `AKAN_DATABASE_MODES`: what the build carries drivers for, first one the default. Unset allows any. */
+  declared: string | undefined;
+  /** A developer machine, which may leave the mode unnamed when the build carries several. */
+  local: boolean;
+}
+
+/** Shared by the CLI and the server. */
+export class DatabaseModes {
+  static readonly all = ["single", "multiple", "cluster"] as const satisfies readonly DatabaseMode[];
+  /** Packages a mode imports at runtime. A build carries them for every mode the app declares. */
+  static readonly drivers: { [mode in DatabaseMode]: readonly string[] } = {
+    single: [],
+    multiple: ["bullmq", "ioredis"],
+    cluster: ["bullmq", "ioredis", "postgres"],
+  };
+  static readonly #stores: { [mode in DatabaseMode]: string } = {
+    single: "sqlite · solid",
+    multiple: "sqlite · redis",
+    cluster: "postgres · redis",
+  };
+
+  static describe(mode: DatabaseMode) {
+    return `${mode} (${DatabaseModes.#stores[mode]})`;
+  }
+
+  static parse(value: string, source: string): DatabaseMode {
+    const mode = value.trim();
+    if ((DatabaseModes.all as readonly string[]).includes(mode)) return mode as DatabaseMode;
+    throw new Error(`${source} must be one of ${DatabaseModes.all.join(", ")}, not "${value}"`);
+  }
+
+  static parseList(value: string, source: string): DatabaseMode[] {
+    const modes = value
+      .split(",")
+      .filter((mode) => mode.trim())
+      .map((mode) => DatabaseModes.parse(mode, source));
+    if (!modes.length) throw new Error(`${source} names no database mode`);
+    return [...new Set(modes)];
+  }
+
+  /**
+   * Throws when a build carrying several modes names none: the fallback would be a SQLite file in each container,
+   * which a cluster deployment would discover only once its instances disagreed.
+   */
+  static resolve({ requested, declared, local }: DatabaseModeRequest): DatabaseMode {
+    const modes = declared?.trim() ? DatabaseModes.parseList(declared, "AKAN_DATABASE_MODES") : null;
+    if (requested?.trim()) {
+      const mode = DatabaseModes.parse(requested, "AKAN_DATABASE_MODE");
+      if (modes && !modes.includes(mode))
+        throw new Error(
+          `AKAN_DATABASE_MODE is ${mode}, but this build carries only ${modes.join(", ")}. Add "${mode}" to database.modes in akan.config.ts and rebuild.`,
+        );
+      return mode;
+    }
+    if (!modes) return "single";
+    if (modes.length === 1 || local) return modes[0] as DatabaseMode;
+    throw new Error(
+      `This build runs in ${modes.join(" or ")} mode, and AKAN_DATABASE_MODE names neither. Set it to say which this deployment is.`,
+    );
+  }
+
+  /** `resolve` for readers that cannot fail a boot; the boot itself resolves again and reports the reason. */
+  static settle(request: DatabaseModeRequest): DatabaseMode | undefined {
+    try {
+      return DatabaseModes.resolve(request);
+    } catch {
+      return undefined;
+    }
+  }
+}

package/base/index.ts

@@ -1,5 +1,6 @@
 export * from "./base";
 export * from "./baseEnv";
+export * from "./databaseModes";
 export * from "./primitiveRegistry";
 export * from "./symbols";
 export * from "./types";

package/base/primitiveRegistry.ts

@@ -4,19 +4,13 @@ import type { Cls } from "./types";
 
 export type { Dayjs };
 
-/** Shared dayjs factory re-export used by Akan documents, services, stores, and UI. */
 export const dayjs = dayjsLib;
 
-/** Registry that maps Akan primitive scalar names to their runtime scalar classes. */
 export class PrimitiveRegistry {
   static readonly #namePrimitiveMap = new Map<string, typeof PrimitiveScalar>();
   static readonly #primitiveNameMap = new Map<typeof PrimitiveScalar, string>();
-  static register(scalar: typeof PrimitiveScalar, { overwrite = false } = {}) {
-    if (
-      !overwrite &&
-      (PrimitiveRegistry.#namePrimitiveMap.has(scalar.refName) || PrimitiveRegistry.#primitiveNameMap.has(scalar))
-    )
-      throw new Error(`Scalar ${scalar.refName} already registered`);
+
+  static register(scalar: typeof PrimitiveScalar) {
     PrimitiveRegistry.#namePrimitiveMap.set(scalar.refName, scalar);
     PrimitiveRegistry.#primitiveNameMap.set(scalar, scalar.refName);
   }
@@ -42,9 +36,27 @@ export class PrimitiveRegistry {
   static getAll(): (typeof PrimitiveScalar)[] {
     return [...PrimitiveRegistry.#namePrimitiveMap.values()];
   }
+  /** The agent face `modelRef` declares, or null for anything that is not a registered primitive declaring one. */
+  static agentOf(modelRef: unknown): PrimitiveAgentFace | null {
+    if (!PrimitiveRegistry.#primitiveNameMap.has(modelRef as typeof PrimitiveScalar)) return null;
+    return (modelRef as typeof PrimitiveScalar).agent ?? null;
+  }
+}
+
+export interface PrimitiveJsonSchema {
+  [key: string]: unknown;
 }
 
-export type PrimitiveValue = string | number | boolean | Dayjs | Date | Uint8Array | null | undefined;
+/**
+ * How an agent sees a primitive whose stored shape is not the one a model should read: `schema` is its published shape
+ * and `read` maps a stored or wire value into it. No `write`: every input already runs through `parseValue`.
+ */
+export interface PrimitiveAgentFace<Value = unknown> {
+  schema: PrimitiveJsonSchema;
+  read(value: Value): unknown;
+}
+
+export type PrimitiveValue = string | number | boolean | Dayjs | Date | Uint8Array | object | null | undefined;
 export class PrimitiveScalar {
   static refName: string;
   static [SERVER_VALUE]: unknown;
@@ -52,6 +64,10 @@ export class PrimitiveScalar {
   static [DEFAULT_VALUE]: unknown = null;
   static [PURIFIED_VALUE]: unknown = null;
   static [EXAMPLE_VALUE]: unknown = null;
+  /** The wire shape, for a primitive the built-in schema table cannot know. Absent, it is published as a string. */
+  static jsonSchema?: PrimitiveJsonSchema;
+  /** Absent, an agent sees the wire shape. */
+  static agent?: PrimitiveAgentFace;
 
   static validate(value: PrimitiveValue): boolean {
     return true;
@@ -99,7 +115,7 @@ export class PrimitiveScalar {
   }
 }
 
-/** Integer primitive scalar. Accepts safe integer numbers after parsing. */
+/** Safe integers only. */
 export class Int extends PrimitiveScalar {
   static override refName: "Int" = "Int";
   static override [SERVER_VALUE]: number;
@@ -120,7 +136,7 @@ export class Int extends PrimitiveScalar {
 }
 PrimitiveRegistry.register(Int);
 
-/** Floating point primitive scalar. Accepts finite numbers after parsing. */
+/** Finite numbers only. */
 export class Float extends PrimitiveScalar {
   static override refName: "Float" = "Float";
   static override [SERVER_VALUE]: number;
@@ -141,7 +157,7 @@ export class Float extends PrimitiveScalar {
 }
 PrimitiveRegistry.register(Float);
 
-/** 24-character hexadecimal id primitive used by Akan document and signal models. */
+/** 24 hexadecimal characters. */
 export class ID extends PrimitiveScalar {
   static override refName: "ID" = "ID";
   static override [SERVER_VALUE]: string;
@@ -168,7 +184,7 @@ export class ID extends PrimitiveScalar {
 }
 PrimitiveRegistry.register(ID);
 
-/** Open object primitive for intentionally flexible payloads or metadata blobs. */
+/** An intentionally open payload. */
 export class Any extends PrimitiveScalar {
   static override refName: "Any" = "Any";
   static override [DEFAULT_VALUE]: object | null = null;
@@ -275,34 +291,20 @@ declare global {
   }
 }
 
+const isBlankOrInvalid = (refName: string, value: PrimitiveValue) =>
+  value === "" ||
+  (refName === "Date" && typeof value === "string" && Number.isNaN(new Date(value).getTime())) ||
+  (refName === "Date" && value instanceof Date && Number.isNaN(value.getTime())) ||
+  (!!value && typeof value === "object" && "isValid" in value && !(value as { isValid: () => boolean }).isValid());
+
 const scalarPrimitiveStatics = {
-  _parse(
-    this: typeof PrimitiveScalar,
-    input: PrimitiveValue,
-    { optional = false }: { optional?: boolean } = {},
-  ): PrimitiveValue {
-    if (optional && (input === null || input === undefined)) return undefined;
-    const value = this.parseValue(input);
-    this._checkValue(value, { optional });
-    return value;
-  },
+  _parse: PrimitiveScalar._parse,
   _serialize(
     this: typeof PrimitiveScalar,
     value: PrimitiveValue,
     { optional = false }: { optional?: boolean } = {},
   ): PrimitiveValue {
-    if (optional && value === "") return undefined;
-    if (this.refName === "Date" && optional && typeof value === "string" && Number.isNaN(new Date(value).getTime()))
-      return undefined;
-    if (this.refName === "Date" && optional && value instanceof Date && Number.isNaN(value.getTime())) return undefined;
-    if (
-      optional &&
-      value &&
-      typeof value === "object" &&
-      "isValid" in value &&
-      !(value as { isValid: () => boolean }).isValid()
-    )
-      return undefined;
+    if (optional && isBlankOrInvalid(this.refName, value)) return undefined;
     this._checkValue(value, { optional });
     if (value === null || value === undefined) return undefined;
     return this.serializeValue(value);
@@ -316,18 +318,7 @@ const scalarPrimitiveStatics = {
       if (optional) return;
       else throw new Error(`Required ${this.refName} value: ${value}`);
     }
-    if (optional && value === "") return;
-    if (this.refName === "Date" && optional && typeof value === "string" && Number.isNaN(new Date(value).getTime()))
-      return;
-    if (this.refName === "Date" && optional && value instanceof Date && Number.isNaN(value.getTime())) return;
-    if (
-      optional &&
-      value &&
-      typeof value === "object" &&
-      "isValid" in value &&
-      !(value as { isValid: () => boolean }).isValid()
-    )
-      return;
+    if (optional && isBlankOrInvalid(this.refName, value)) return;
     if (!this.validate(value)) throw new Error(`Invalid ${this.refName} value: ${value}`);
   },
 };

package/base/symbols.ts

@@ -13,7 +13,7 @@ export const STATE_META = Symbol.for("akan.state");
 export const STATE_INIT_META = Symbol.for("akan.state.init");
 export const STATE_DERIVED_META = Symbol.for("akan.state.derived");
 export const ACTION_META = Symbol.for("akan.action");
-/** Which module declared each action. See `ActionOwner`. */
+/** Which module declared each action. */
 export const ACTION_OWNER_META = Symbol.for("akan.action.owner");
 /** What a dispatcher does, carried on the function so a component handed one can annotate the DOM with it. */
 export const ACTION_TAG = Symbol.for("akan.action.tag");

package/base/types.ts

@@ -116,7 +116,7 @@ export type MergeAllDoubleKeyOfObjects<
     : MergeAllDoubleKeyOfObjects<Rest, Key, SubKey, Acc>
   : Acc;
 
-export type Primitive = string | number | boolean | null | undefined; 
+export type Primitive = string | number | boolean | null | undefined;
 
 export type NestedKeysWithAllowed<T, Allowed = Primitive> = T extends Primitive
   ? never

package/base/utils.ts

@@ -21,10 +21,7 @@ export const applyFnToArrayObjects = <Input, Fn extends (arg: never) => unknown>
   arraiedData: Input,
   fn: Fn,
 ): ApplyFnToArrayObjectsResult<Input, ReturnType<Fn>> => {
-  if (Array.isArray(arraiedData))
-    return arraiedData.map((data) => applyFnToArrayObjects(data, fn)) as ApplyFnToArrayObjectsResult<
-      Input,
-      ReturnType<Fn>
-    >;
-  return fn(arraiedData as never) as ApplyFnToArrayObjectsResult<Input, ReturnType<Fn>>;
+  type Result = ApplyFnToArrayObjectsResult<Input, ReturnType<Fn>>;
+  if (Array.isArray(arraiedData)) return arraiedData.map((data) => applyFnToArrayObjects(data, fn)) as Result;
+  return fn(arraiedData as never) as Result;
 };

package/client/cn.ts

@@ -1,11 +1,6 @@
 import { type ClassNameValue, extendTailwindMerge } from "tailwind-merge";
 
-/**
- * Akan's semantic color tokens beyond tailwind-merge's built-in Tailwind palette.
- * Registering them under `theme.color` teaches tailwind-merge that `bg-*`/`text-*`/
- * `border-*`/… built from these names belong to the same conflict group, so
- * `cn("bg-primary", "bg-open")` correctly resolves to `"bg-open"` instead of keeping both.
- */
+/** Registered with tailwind-merge so `cn("bg-primary", "bg-open")` resolves to `"bg-open"` instead of keeping both. */
 export const colorTokens = [
   "background",
   "foreground",
@@ -38,10 +33,7 @@ export const colorTokens = [
   "ring",
 ];
 
-/**
- * Akan's semantic radius tokens (`--radius-box` / `--radius-field` in ui/styles.css). Without them
- * `cn("rounded-field", "rounded-full")` keeps both classes and stylesheet order decides the winner.
- */
+/** `--radius-box` / `--radius-field`; unregistered, `cn("rounded-field", "rounded-full")` would keep both. */
 export const radiusTokens = ["box", "field"];
 
 const twMerge = extendTailwindMerge({
@@ -53,7 +45,5 @@ const twMerge = extendTailwindMerge({
   },
 });
 
-/** The one class-combining function: joins strings/arrays/conditional parts (`cond && "x"`) and
- *  resolves Tailwind conflicts with a shared tailwind-merge instance that knows Akan's semantic
- *  color tokens. clsx-style object syntax (`{ x: cond }`) is not supported — write `cond && "x"`. */
+/** Joins class parts and resolves Tailwind conflicts; object syntax (`{ x: cond }`) is unsupported — write `cond && "x"`. */
 export const cn = (...inputs: ClassNameValue[]) => twMerge(...inputs);

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;