akanjs 3.0.0-alpha.9 → 3.0.0-alpha.90

package/CHANGELOG.md

@@ -1,5 +1,108 @@
 # akanjs
 
+## 2.4.2
+
+### Minor Changes
+
+- 11aa655: feat(constant): remove a relation's target with its owner via `cascade: "remove"`
+
+  A relation field can now take its target down with it: `image: field(File, { cascade: "remove" })`, arrays
+  included. The removal runs through the **target's service**, so the target's own `_postRemove` runs with it —
+  that is how removing a model also deletes the file's stored blob or object, with no extra wiring in the owning
+  module.
+
+  Only a relation accepts the option. A `String`, an `ID`, a scalar, and a nested array each fail while the class
+  is being built, naming the field: none of them points at a document the framework could remove.
+
+  Target services resolve lazily, at removal time, so a cascade adds no boot-order edge between two services and a
+  cascade cycle cannot fail the boot. They resolve _before_ the parent is touched, so a model cascading into a
+  module the app never mounted fails with nothing half-removed.
+
+  Two limits worth knowing. Nothing checks whether another document still references the same target, so declaring
+  `cascade` asserts that the field owns its target exclusively. And query-level removal (`deleteManyByQuery` /
+  `updateManyByQuery`) stamps `removedAt` in one atomic update that fires no hooks and therefore no cascade —
+  remove documents one at a time when they cascade.
+
+- 11aa655: feat(store): invalidate sibling slices on create and refetch them in `Load.Units`
+
+  A model with more than one parent is listed by more than one slice, and a create could only ever be spliced
+  into the slice it was issued from. Creating a `bizDoc` from `bizDocInOrg` left `bizDocListInProject` without
+  it, and an RSC navigation back to that page replayed a cached payload whose server-stamped
+  `bizDocInitAtInProject` still satisfied `Load.Units`' cache check — so the new document stayed invisible until
+  a full reload.
+
+  `create<Model>` and `create<Model>InForm` now stamp a new per-slice `<model>StaleAt<Suffix>` on every slice
+  _except_ the one named by `sliceName`. Whether the new document belongs to a sibling slice is a server-side
+  filter decision, so the siblings are marked for revalidation rather than patched optimistically. `Load.Units`
+  refetches through `refresh<Model><Suffix>` when its slice's `StaleAt` is newer than its `InitAt`, and a
+  completed refresh restamps `InitAt` past `StaleAt` to end the stale state. The refetch is skipped while the
+  list is already loading, which also dedups several `Load.Units` mounted on one slice.
+
+  `Load.Units` also takes a `staleTime` prop, in milliseconds, for age-based revalidation independent of any
+  create: `staleTime={0}` always refetches on mount, `staleTime={30_000}` refetches only when the cached data is
+  older than 30s. Omitting it leaves the component purely invalidation-driven.
+
+  Update and remove are unchanged — they already walk every slice, because a document they touch is one the
+  cached lists can be searched for by id.
+
+- 11aa655: feat(server): add subRoute hosts at runtime with `AKAN_SUB_ROUTE_HOSTS`
+
+  An app resolved a request Host to a basePath through a map fixed at build time — the domains written into
+  `akan.config.ts` plus the generated `<basePath>-<branch>.<serveDomain>`. A platform that mints its hostnames when
+  a project is created cannot write either one into the repo, so its subRoute hosts fell through to the root app.
+
+  `AKAN_SUB_ROUTE_HOSTS` adds to that map at boot, in the same spirit as `AKAN_PUBLIC_BASE_PATHS`:
+
+  ```
+  AKAN_SUB_ROUTE_HOSTS="soft=soft-abc.try.akanjs.com,soft.acme.com;office=office-abc.try.akanjs.com"
+  ```
+
+  Hosts are matched lowercased and without a port, exactly as the built-in ones are. The env mapping is a union with
+  the built one, never a replacement, so a tenant's own domains keep working and removing the env restores the
+  previous behaviour byte for byte.
+
+  A basePath the build does not serve is dropped with a warning rather than honoured — the route tree is a build
+  output, so accepting one would answer every request under it with a 404 and nothing to explain why. A malformed
+  entry is skipped the same way: the value is rendered by a deployment platform, and one bad character must not turn
+  into a boot loop across every pod.
+
+  `x-base-path` is now checked against the basePaths the build serves before it is trusted, matching the check
+  `getBasePathFromPathname` already applied to it. An unrecognised value falls through to host matching instead of
+  selecting a basePath that resolves to nothing.
+
+- 25d5b15: feat(devkit): sync lib `page` trees into apps and honor `pageConfig.devOnly`
+
+  Apps can opt in with `syncPageLibs` (`true` / lib list) so `akan sync` links each lib's routes under
+  `page/(libs)/(<lib>)` — once per basePath when the app has subRoutes. The link is generated and
+  gitignored; the lib source stays the edit target. Collision on the resolved route pattern is a
+  sync-time error.
+
+  `pageConfig.devOnly: true` (literal only) keeps a route out of `akan build` while `akan start` still
+  serves it. On a `_layout` it excludes the whole subtree. Symlink-aware file ops avoid wiping a synced
+  lib when cleaning an app link, and dangling lib links no longer break `getApps`.
+
+- 25d5b15: feat(signal): refresh websocket credentials in-session and re-check pubsub rooms
+
+  Handshake credentials now live on `AppWsData` (headers/cookies only). Clients that hold the token in
+  memory send it with `fetch.setJwt(...)`, which forwards an `__auth` frame; the server swaps the
+  snapshot synchronously and re-runs each subscribed room's guards, unsubscribing the ones that fail.
+
+  Guards should read the caller with `context.get("account")` instead of branching on HTTP vs websocket
+  transport. Slice-level guards still only wrap generated query/mutation endpoints — a pubsub endpoint
+  needs its own `guards` if the room itself must be protected.
+
+### Patch Changes
+
+- 6d58c7e: add search feature for sqlit database with fts5
+- 25d5b15: fix(ui): refresh EditModal when the hydrated edit payload is stale
+
+  RSC navigation can replay a cached page tree, and an edit shell hydrated from that payload can show
+  arbitrarily old form data. EditModal now treats a cache replay (or a `modelViewAt` older than 60s) as
+  stale and refetches via `edit<Model>` while keeping the modal open on the last known id.
+
+- 42cf7a2: Normalize unsendable relayed WebSocket close codes to 1001 so Bun's global client WebSocket.close no longer throws InvalidAccessError at the gateway's client-to-upstream relay when a peer disappears without a close frame (code 1006). The upstream-to-client relay applies the same normalization defensively.
+- 04cb46d: Allow the documented wsConnect export during source validation for root layouts, including base-path and grouped root boundaries, while continuing to reject it on nested layouts.
+
 ## 2.4.1
 
 ### Patch Changes

package/README.ko.md

@@ -26,7 +26,7 @@ generated reference가 같은 의도에서 이어집니다.
 
 ## 요구사항
 
-- [Bun](https://bun.sh) `>=1.3.13`
+- [Bun](https://bun.sh) `>=1.4.0`
 - TypeScript 중심의 애플리케이션 코드
 - React 기반 UI surface
 

package/README.md

@@ -25,7 +25,7 @@ server, app packaging, deployment artifacts, and generated references.
 
 ## Requirements
 
-- [Bun](https://bun.sh) `>=1.3.13`
+- [Bun](https://bun.sh) `>=1.4.0`
 - TypeScript-first application code
 - React-based UI surfaces
 

package/base/baseEnv.ts

@@ -15,7 +15,7 @@ export interface BaseEnv {
   operationMode: "local" | "edge" | "cloud" | "module";
   databaseMode?: DatabaseMode;
 }
-export type BackendEnv = BaseEnv & {
+export type BackendEnv = {
   hostname?: string | null;
   port?: number;
   database?: {
@@ -59,6 +59,8 @@ export type ClientEnv = BaseEnv & {
   side: "server" | "client";
   renderMode: "ssr" | "csr";
   websocket: boolean;
+  apiPrefix: string;
+  wsPrefix: string;
   clientHost: string;
   clientPort: number;
   clientHttpProtocol: "http:" | "https:";
@@ -73,15 +75,55 @@ export type ClientEnv = BaseEnv & {
 
 let cachedEnv: ClientEnv | undefined;
 
+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. */
+export const normalizeRoutePrefix = (value: string | undefined | null): string | undefined => {
+  const trimmed = value?.trim();
+  if (!trimmed) return undefined;
+  const normalized = `/${trimmed.replace(/^\/+|\/+$/g, "")}`;
+  return normalized === "/" ? undefined : normalized;
+};
+
+/**
+ * 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.
+ */
+export const getApiPrefix = (): string =>
+  normalizeRoutePrefix(globalWithPrefix.__AKAN_PREFIX__?.api) ??
+  normalizeRoutePrefix(process.env.AKAN_API_PREFIX) ??
+  normalizeRoutePrefix(process.env.AKAN_PUBLIC_API_PREFIX) ??
+  "/api";
+
+export const getWsPrefix = (): string =>
+  normalizeRoutePrefix(globalWithPrefix.__AKAN_PREFIX__?.ws) ??
+  normalizeRoutePrefix(process.env.AKAN_WS_PREFIX) ??
+  normalizeRoutePrefix(process.env.AKAN_PUBLIC_WS_PREFIX) ??
+  "/ws";
+
+/** `AkanApp` rewrites `process.env` for the replica it runs in-process, after this module may already have cached. */
+export const resetEnvCache = () => {
+  cachedEnv = undefined;
+};
+
+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. */
 export const getEnv = (): ClientEnv => {
   if (cachedEnv) return cachedEnv;
   const appName = process.env.AKAN_PUBLIC_APP_NAME ?? "unknown";
   const repoName = process.env.AKAN_PUBLIC_REPO_NAME ?? "unknown";
   const serveDomain = process.env.AKAN_PUBLIC_SERVE_DOMAIN ?? "unknown";
-  if (appName === "unknown") throw new Error("environment variable AKAN_PUBLIC_APP_NAME is required");
-  if (repoName === "unknown") throw new Error("environment variable AKAN_PUBLIC_REPO_NAME is required");
-  if (serveDomain === "unknown") throw new Error("environment variable AKAN_PUBLIC_SERVE_DOMAIN is required");
+  if (appName === "unknown") throw new Error(missingPublicEnv("AKAN_PUBLIC_APP_NAME"));
+  if (repoName === "unknown") throw new Error(missingPublicEnv("AKAN_PUBLIC_REPO_NAME"));
+  if (serveDomain === "unknown") throw new Error(missingPublicEnv("AKAN_PUBLIC_SERVE_DOMAIN"));
   const environment = (process.env.AKAN_PUBLIC_ENV ?? "debug") as BaseEnv["environment"];
   const operationMode = (process.env.AKAN_PUBLIC_OPERATION_MODE ??
     (environment === "local" ? "local" : "cloud")) as BaseEnv["operationMode"];
@@ -138,7 +180,9 @@ export const getEnv = (): ClientEnv => {
         : side === "client"
           ? (window.location.protocol as "http:" | "https:")
           : ("http:" as const));
-  const serverHttpUri = `${serverHttpProtocol}//${serverHost}${serverPort === 443 ? "" : `:${serverPort}`}/api`;
+  const apiPrefix = getApiPrefix();
+  const wsPrefix = getWsPrefix();
+  const serverHttpUri = `${serverHttpProtocol}//${serverHost}${serverPort === 443 ? "" : `:${serverPort}`}${apiPrefix}`;
   const serverWsProtocol = serverHttpProtocol === "http:" ? "ws:" : "wss:";
   const serverWsUri = `${serverWsProtocol}//${serverHost}${serverPort === 443 ? "" : `:${serverPort}`}`;
 
@@ -147,6 +191,8 @@ export const getEnv = (): ClientEnv => {
     side,
     renderMode,
     websocket: true,
+    apiPrefix,
+    wsPrefix,
     clientHost,
     clientPort,
     clientHttpProtocol,

package/base/primitiveRegistry.ts

@@ -44,7 +44,7 @@ export class PrimitiveRegistry {
   }
 }
 
-export type PrimitiveValue = string | number | boolean | Dayjs | Date | null | undefined;
+export type PrimitiveValue = string | number | boolean | Dayjs | Date | Uint8Array | null | undefined;
 export class PrimitiveScalar {
   static refName: string;
   static [SERVER_VALUE]: unknown;
@@ -176,6 +176,49 @@ export class Any extends PrimitiveScalar {
 }
 PrimitiveRegistry.register(Any);
 
+type NodeBuffer = Uint8Array & { toString(encoding: string): string };
+interface BufferCtor {
+  from(buffer: ArrayBufferLike, byteOffset: number, length: number): NodeBuffer;
+  from(text: string, encoding: string): NodeBuffer;
+}
+
+export class Binary extends PrimitiveScalar {
+  static override refName: "Binary" = "Binary";
+  static override [SERVER_VALUE]: Uint8Array;
+  static override [CLIENT_VALUE]: Uint8Array;
+  static override [DEFAULT_VALUE]: Uint8Array | null = null;
+  static override [PURIFIED_VALUE]: Uint8Array | null = null;
+  static override [EXAMPLE_VALUE]: string = "AAEC";
+
+  static override validate(value: Uint8Array | string): boolean {
+    return value instanceof Uint8Array || typeof value === "string";
+  }
+  static override parseValue(input: Uint8Array | string): Uint8Array {
+    return typeof input === "string" ? Binary.#fromBase64(input) : input;
+  }
+  static override serializeValue(value: Uint8Array | string): string {
+    return typeof value === "string" ? value : Binary.#toBase64(value);
+  }
+
+  static #toBase64(bytes: Uint8Array): string {
+    const buffer = (globalThis as { Buffer?: BufferCtor }).Buffer;
+    if (buffer) return buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
+    let binary = "";
+    for (let idx = 0; idx < bytes.length; idx += 0x8000)
+      binary += String.fromCharCode(...bytes.subarray(idx, idx + 0x8000));
+    return btoa(binary);
+  }
+  static #fromBase64(text: string): Uint8Array {
+    const buffer = (globalThis as { Buffer?: BufferCtor }).Buffer;
+    if (buffer) return buffer.from(text, "base64");
+    const binary = atob(text);
+    const bytes = new Uint8Array(binary.length);
+    for (let idx = 0; idx < binary.length; idx += 1) bytes[idx] = binary.charCodeAt(idx);
+    return bytes;
+  }
+}
+PrimitiveRegistry.register(Binary);
+
 export class Upload extends PrimitiveScalar {
   static override refName: "Upload" = "Upload";
   static override [SERVER_VALUE]: File;
@@ -209,12 +252,12 @@ declare global {
     [DEFAULT_VALUE]: boolean;
     [PURIFIED_VALUE]: boolean;
     [EXAMPLE_VALUE]: boolean;
-    validate(value: boolean | number): boolean;
-    parseValue(input: boolean | number): boolean | number;
-    serializeValue(value: boolean | number): boolean | number;
-    _parse(input: boolean | number): boolean;
-    _serialize(value: boolean | number): boolean;
-    _checkValue(value: boolean | number): void;
+    validate(value: boolean | number | string): boolean;
+    parseValue(input: boolean | number | string): boolean | number | string;
+    serializeValue(value: boolean | number | string): boolean | number | string;
+    _parse(input: boolean | number | string): boolean;
+    _serialize(value: boolean | number | string): boolean;
+    _checkValue(value: boolean | number | string): void;
   }
   interface DateConstructor {
     refName: "Date";
@@ -305,10 +348,14 @@ Object.assign(String, scalarPrimitiveStatics, {
 });
 PrimitiveRegistry.register(String);
 
-const normalizeBooleanPrimitiveValue = (value: boolean | number): boolean | null => {
+const normalizeBooleanPrimitiveValue = (value: boolean | number | string): boolean | null => {
   if (typeof value === "boolean") return value;
   if (value === 1) return true;
   if (value === 0) return false;
+  if (typeof value !== "string") return null;
+  const text = value.trim().toLowerCase();
+  if (text === "true" || text === "1") return true;
+  if (text === "false" || text === "0") return false;
   return null;
 };
 
@@ -317,13 +364,13 @@ Object.assign(Boolean, {
   refName: "Boolean",
   [DEFAULT_VALUE]: false,
   [EXAMPLE_VALUE]: true,
-  validate(value: boolean | number) {
+  validate(value: boolean | number | string) {
     return normalizeBooleanPrimitiveValue(value) !== null;
   },
-  parseValue(input: boolean | number) {
+  parseValue(input: boolean | number | string) {
     return normalizeBooleanPrimitiveValue(input) ?? input;
   },
-  serializeValue(value: boolean | number) {
+  serializeValue(value: boolean | number | string) {
     return normalizeBooleanPrimitiveValue(value) ?? value;
   },
 });
@@ -350,4 +397,4 @@ Object.assign(Date, {
 });
 PrimitiveRegistry.register(Date);
 
-export type DefaultPrimitiveName = "String" | "Boolean" | "Date" | "Int" | "Float" | "ID" | "Any" | "Upload";
+export type DefaultPrimitiveName = "String" | "Boolean" | "Date" | "Int" | "Float" | "ID" | "Any" | "Binary" | "Upload";

package/base/symbols.ts

@@ -13,6 +13,10 @@ 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`. */
+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");
 export const SERVER_VALUE = Symbol.for("akan.value.server");
 export const CLIENT_VALUE = Symbol.for("akan.value.client");
 export const DEFAULT_VALUE = Symbol.for("akan.value.default");

package/client/capacitor.ts

@@ -46,6 +46,28 @@ export type CapacitorContactsModule = {
   };
 };
 
+export type CapacitorSpeechRecognitionModule = {
+  SpeechRecognition: {
+    available: () => Promise<{ available: boolean }>;
+    checkPermissions: () => Promise<{ speechRecognition: CapacitorPermissionState }>;
+    requestPermissions: () => Promise<{ speechRecognition: CapacitorPermissionState }>;
+    start: (options: Record<string, unknown>) => Promise<{ matches?: string[] }>;
+    stop: () => Promise<void>;
+    removeAllListeners: () => Promise<void> | void;
+    addListener: (
+      eventName: string,
+      listenerFunc: (data: { matches?: string[] }) => void,
+    ) => Promise<{ remove: () => Promise<void> | void }> | { remove: () => Promise<void> | void };
+  };
+};
+
+export type CapacitorTextToSpeechModule = {
+  TextToSpeech: {
+    speak: (options: { text: string; lang?: string; rate?: number }) => Promise<void>;
+    stop: () => Promise<void>;
+  };
+};
+
 export type CapacitorCoreModule = {
   CapacitorCookies: {
     setCookie: (options: { key: string; value: string; path?: string }) => Promise<void> | void;
@@ -155,6 +177,8 @@ type CapacitorModuleMap = {
   preferences: CapacitorPreferencesModule;
   pushNotifications: CapacitorPushNotificationsModule;
   safeArea: CapacitorSafeAreaModule;
+  speechRecognition: CapacitorSpeechRecognitionModule;
+  textToSpeech: CapacitorTextToSpeechModule;
   updater: CapacitorUpdaterModule;
 };
 
@@ -257,6 +281,16 @@ export const loadCapacitorSafeArea = () =>
     SafeArea: getCapacitorPlugin<CapacitorSafeAreaModule["SafeArea"]>("SafeArea"),
   }));
 
+export const loadCapacitorSpeechRecognition = () =>
+  loadCapacitorModule("speechRecognition", async () => ({
+    SpeechRecognition: getCapacitorPlugin<CapacitorSpeechRecognitionModule["SpeechRecognition"]>("SpeechRecognition"),
+  }));
+
+export const loadCapacitorTextToSpeech = () =>
+  loadCapacitorModule("textToSpeech", async () => ({
+    TextToSpeech: getCapacitorPlugin<CapacitorTextToSpeechModule["TextToSpeech"]>("TextToSpeech"),
+  }));
+
 export const loadCapacitorUpdater = () =>
   loadCapacitorModule("updater", async () => ({
     CapacitorUpdater: getCapacitorPlugin<CapacitorUpdaterModule["CapacitorUpdater"]>("CapacitorUpdater"),

package/client/clientRuntime.ts

@@ -1,4 +1,5 @@
 import type { SliceMeta } from "akanjs/fetch";
+import type { SerializedArg } from "akanjs/signal";
 import type { ReactNode } from "react";
 import type { TransMessageOption } from "./makePageProto";
 
@@ -47,6 +48,10 @@ type RuntimeFetch = typeof globalThis.fetch & {
   serializedSignal: Record<string, unknown>;
   setJwt: (jwt: string | null) => void;
   slice: Record<string, SliceMeta>;
+  /** Sort keys per model refName, registered from each serialized signal's filter. */
+  sortKeyMap?: Map<string, string[]>;
+  /** Filter queries per model refName, with the args each one takes — what the root slice picks from. */
+  filterQueryMap?: Map<string, { [queryKey: string]: SerializedArg[] }>;
   ws: RuntimeWs;
   [key: string]: unknown;
 };

package/client/cookie.ts

@@ -1,7 +1,14 @@
 import { getEnv } from "akanjs/base";
-import { decodeJwtPayload, Logger } from "akanjs/common";
+import {
+  authTokenKey,
+  decodeJwtPayload,
+  isOwnAuthToken,
+  Logger,
+  legacyAuthTokenKey,
+  readAuthToken,
+} from "akanjs/common";
 import type { Account } from "akanjs/fetch";
-import { cookies as serverCookies, headers as serverHeaders } from "akanjs/fetch";
+import { parseCookieHeader, cookies as serverCookies, headers as serverHeaders } from "akanjs/fetch";
 import { loadCapacitorCore } from "./capacitor";
 import { storage } from "./storage";
 import { fetch } from "./useClient";
@@ -12,23 +19,6 @@ interface CookieOptions {
   secure?: boolean;
 }
 
-function parseCookieHeader(cookieHeader: string): Map<string, { name: string; value: string }> {
-  const entries = cookieHeader
-    .split(";")
-    .map((c) => c.trim())
-    .filter(Boolean)
-    .map((c) => {
-      const eqIdx = c.indexOf("=");
-      if (eqIdx === -1) return null;
-      const name = c.slice(0, eqIdx).trim();
-      const raw = c.slice(eqIdx + 1).trim();
-      const value = typeof raw === "string" && raw.startsWith("j:") ? (JSON.parse(raw.slice(2)) as string) : raw;
-      return [name, { name, value }] as const;
-    })
-    .filter((e): e is NonNullable<typeof e> => e !== null);
-  return new Map(entries);
-}
-
 export const cookies = (): Map<string, { name: string; value: string }> => {
   if (getEnv().side === "server") return serverCookies();
   return parseCookieHeader(document.cookie);
@@ -53,21 +43,18 @@ export const setCookie = (
     .catch(() => undefined);
 };
 
-export const getCookie = (key: string): string | undefined => {
-  if (getEnv().side === "server") return cookies().get(key)?.value;
-  else
-    return document.cookie
-      .split(";")
-      .find((c) => c.trim().startsWith(`${key}=`))
-      ?.split("=")[1];
-};
+/**
+ * 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.
+ */
+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 cookies().delete(key);
-  else {
-    
-    document.cookie = `${key}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;`;
-  }
+
+  if (getEnv().side === "server") return;
+  
+  document.cookie = `${key}=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=${options.path};`;
 };
 export const headers = (): Map<string, string> => {
   if (getEnv().side !== "server") return new Map();
@@ -77,9 +64,29 @@ export const headers = (): Map<string, string> => {
 export const getHeader = (key: string): string | undefined => {
   return headers().get(key);
 };
-/** Decodes the current JWT into account data when it belongs to this app/environment. */
+
+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);
+
+/** The auth token this app holds in client storage — localStorage under SSR, Capacitor Preferences on CSR. */
+export const getStoredAuthToken = async (): Promise<string | undefined> => {
+  const scoped = await storage.getItem(authTokenKey());
+  if (scoped) return scoped;
+  const legacy = await storage.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.
+ */
 export const getAccount = <AddData = unknown>(): Account<AddData> => {
-  const jwt = getCookie("jwt") ?? getHeader("jwt");
+  const jwt = getAuthToken() ?? getHeader("authorization")?.replace(/^Bearer\s+/i, "");
   const defaultAccount = { appName: getEnv().appName, environment: getEnv().environment } as Account<AddData>;
   if (!jwt) return defaultAccount;
   const account = decodeJwtPayload<Account<AddData>>(jwt);
@@ -95,21 +102,34 @@ interface SetAuthOption {
 /** Sets the active auth token on fetch, cookie storage, and client storage. */
 export const setAuth = ({ jwt }: SetAuthOption) => {
   fetch.setJwt(jwt);
-  setCookie("jwt", jwt);
-  void storage.setItem("jwt", jwt);
+  setCookie(authTokenKey(), jwt);
+  void storage.setItem(authTokenKey(), jwt);
+
+  removeCookie(legacyAuthTokenKey);
+  void storage.removeItem(legacyAuthTokenKey);
 };
 
 interface InitAuthOption {
   jwt?: string;
 }
 export const initAuth = ({ jwt }: InitAuthOption = {}) => {
-  const token = jwt ?? cookies().get("jwt")?.value;
+  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;
+  }
   if (token) setAuth({ jwt: token });
-  Logger.verbose(`JWT set from cookie: ${token}`);
+  
+  Logger.verbose(`JWT ${token ? "restored from cookie" : "not found in cookie"}`);
 };
 
 export const resetAuth = () => {
   fetch.setJwt(null);
-  removeCookie("jwt");
-  void storage.removeItem("jwt");
+  removeCookie(authTokenKey());
+  removeCookie(legacyAuthTokenKey);
+  void storage.removeItem(authTokenKey());
+  void storage.removeItem(legacyAuthTokenKey);
 };

package/client/csrTypes.ts

@@ -1,9 +1,10 @@
 "use client";
 import type { ReactDOMAttributes } from "@use-gesture/react/dist/declarations/src/types";
 import type { PromiseOrObject } from "akanjs/base";
-import { createContext, type ForwardRefExoticComponent, type ReactNode, type RefObject, useContext } from "react";
+import { type ForwardRefExoticComponent, type ReactNode, type RefObject, useContext } from "react";
 import type { AnimatedComponent, AnimatedProps, Interpolation, SpringValue } from "react-spring";
 import type { RouterInstance } from "./router";
+import { sharedContext } from "./sharedContext";
 import type { ReactFont } from "./types";
 
 export type TransitionType = "none" | "fade" | "bottomUp" | "stack" | "scaleOut";
@@ -261,18 +262,6 @@ export type PageState = CsrState & {
   topInset: number;
   bottomInset: number;
 };
-export const defaultPageState: PageState = {
-  transition: "none",
-  topSafeArea: 0,
-  bottomSafeArea: 0,
-  topInset: 0,
-  bottomInset: 0,
-  gesture: true,
-  cache: false,
-  ssr: "stream",
-  topSafeAreaColor: "var(--color-background, Canvas)",
-  bottomSafeAreaColor: "var(--color-background, Canvas)",
-};
 
 export interface Location {
   href: string;
@@ -349,7 +338,7 @@ export type UseCsrTransition = CsrTransitionStyles & {
 };
 
 export type CsrContextType = RouteState & UseCsrTransition;
-export const csrContext = createContext<CsrContextType>({} as unknown as CsrContextType);
+export const csrContext = sharedContext<CsrContextType>("csr", {} as unknown as CsrContextType);
 export const useCsr = () => {
   const contextValues = useContext(csrContext);
   return contextValues;
@@ -363,7 +352,7 @@ export interface PathContextType {
   setGestureEnabled: (enabled: boolean) => void;
   registerFrameSlot: (slot: FrameSlotRegistration) => () => void;
 }
-export const pathContext = createContext<PathContextType>({} as unknown as PathContextType);
+export const pathContext = sharedContext<PathContextType>("path", {} as unknown as PathContextType);
 export const usePathCtx = () => {
   const contextValues = useContext(pathContext);
   return contextValues;

package/client/frameConfig.ts

@@ -120,6 +120,19 @@ export function getExplicitPageConfigKeys(configChain: PageConfig[] = []): Parti
   return explicitKeys;
 }
 
+export const defaultPageState: PageState = {
+  transition: "none",
+  topSafeArea: 0,
+  bottomSafeArea: 0,
+  topInset: 0,
+  bottomInset: 0,
+  gesture: true,
+  cache: false,
+  ssr: "stream",
+  topSafeAreaColor: "var(--color-background, Canvas)",
+  bottomSafeAreaColor: "var(--color-background, Canvas)",
+};
+
 export function resolvePageState({
   configChain = [],
   path,

package/client/index.ts

@@ -11,6 +11,7 @@ export * from "./locale";
 export * from "./makePageProto";
 export * from "./router";
 export * from "./rscNavigation";
+export * from "./sharedContext";
 export * from "./storage";
 export * from "./translator";
 export * from "./types";

package/client/locale.ts

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