akanjs 3.0.0-beta.9 → 3.0.1

package/client/router.ts

@@ -14,14 +14,9 @@ export interface DeepLinkOptions extends RouteOptions {
 const DEEP_LINK_STACK_STEP_DELAY = 450;
 
 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;
+  /** May answer a promise that rejects when the route refused to move — see `Router.navigation`. */
+  push: (href: string, routeOptions?: RouteOptions) => void | Promise<void>;
+  replace: (href: string, routeOptions?: RouteOptions) => void | Promise<void>;
   back: (routeOptions?: RouteOptions) => void;
   refresh: () => void;
 }
@@ -116,6 +111,8 @@ export const normalizeDeepLinkHref = (
   href: string,
   origin = globalThis.window?.location?.origin ?? "http://localhost",
 ) => {
+  
+  if (href.startsWith("/") && !href.startsWith("//")) return normalizeRoutePath(href) ?? "/";
   const url = new URL(href, origin);
   if (url.protocol === "http:" || url.protocol === "https:") return `${url.pathname}${url.search}${url.hash}`;
   const hostPath = url.hostname ? `/${url.hostname}` : "";
@@ -135,8 +132,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) => {
@@ -163,15 +158,17 @@ class Router {
   #lang = parseAkanI18nEnv().defaultLocale;
   #routePaths = new Set<string>();
   #indexPath = "/";
+  #navigation: Promise<void> = Promise.resolve();
   #historyIdx = 0;
-  #instance: InternalRouterInstance = {
+  #redirects = 0;
+  #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");
@@ -181,7 +178,6 @@ class Router {
     },
   };
   init(options: SsrClientRouterOption | SsrServerRouterOption | CSRClientRouterOption) {
-    
     this.#prefix = options.prefix ?? "";
     this.#lang = options.lang ?? parseAkanI18nEnv().defaultLocale;
     this.#routePaths = new Set(
@@ -196,29 +192,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);
-        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);
-        router.replace(navigationPathInfo.href, routeOptions);
-      },
+      push: navigate("push"),
+      replace: navigate("replace"),
       back: () => {
         const router = options.router;
         const pathInfo = this.#getPathInfo(document.referrer);
@@ -238,7 +225,7 @@ class Router {
       push: (href: string, routeOptions) => {
         const { path, pathname, hash, href: fullHref } = this.#getPathInfo(href);
         this.#postPathChange({ path, pathname, hash });
-        options.router.push(this.#withCsrRuntimeSearchParams(fullHref), routeOptions);
+        return options.router.push(this.#withCsrRuntimeSearchParams(fullHref), routeOptions);
       },
       replace: (href: string, routeOptions) => {
         const { path, pathname, hash, href: fullHref } = this.#getPathInfo(href);
@@ -333,10 +320,18 @@ class Router {
       .map((_, index) => `/${segments.slice(0, index + 1).join("/")}`)
       .filter((candidate) => this.#routePaths.has(candidate));
   }
+  
+  #routePathOfLink(path: string) {
+    const segments = path.split("/").filter(Boolean);
+    if (segments[0] && (parseAkanI18nEnv().locales as readonly string[]).includes(segments[0])) segments.shift();
+    if (this.#prefix && segments[0] === this.#prefix) segments.shift();
+    return segments.length ? `/${segments.join("/")}` : "/";
+  }
   resolveDeepLinkStack(href: string) {
     this.#checkInitialized();
     const normalizedHref = normalizeDeepLinkHref(href);
-    const { path, search, hash } = splitHref(normalizedHref);
+    const { path: linkPath, search, hash } = splitHref(normalizedHref);
+    const path = this.#routePathOfLink(linkPath);
     if (this.#routePaths.size > 0 && !this.#routePaths.has(path)) {
       Logger.info(`[router] deep link target '${path}' was not found in route manifest.`);
       return [];
@@ -367,18 +362,28 @@ class Router {
   }
   push(href: string, routeOptions?: RouteOptions) {
     this.#checkInitialized();
-    this.#instance.push(href, routeOptions);
+    this.#track(this.#instance.push(href, routeOptions));
     this.#rememberHistoryState("push");
     this.#postDevSyncNavigation("push", href);
     return undefined as never;
   }
   replace(href: string, routeOptions?: RouteOptions) {
     this.#checkInitialized();
-    this.#instance.replace(href, routeOptions);
+    this.#track(this.#instance.replace(href, routeOptions));
     this.#rememberHistoryState("replace");
     this.#postDevSyncNavigation("replace", href);
     return undefined as never;
   }
+  /** 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;
+  }
+  #track(result: void | Promise<void>) {
+    this.#navigation = Promise.resolve(result);
+    
+    void this.#navigation.catch(() => undefined);
+  }
   canGoBack() {
     if (getEnv().side === "server") return false;
     return this.#historyIdx > 0;
@@ -393,7 +398,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;
@@ -404,6 +408,11 @@ class Router {
     this.#instance.refresh();
     return undefined as never;
   }
+  /** Client-side redirects so far: a render that saw this change while it ran redirected instead of drawing. A method
+   * for the reason `navigation()` is one. */
+  redirectCount(): number {
+    return this.#redirects;
+  }
   redirect(href: string, options: RedirectOptions = {}): never {
     const method = options.method ?? "replace";
     const status = options.status ?? 307;
@@ -419,6 +428,7 @@ class Router {
       Logger.info(`redirect to:${pathname}`);
       throw new AkanRedirectError(fullHref, method, status);
     } else {
+      this.#redirects += 1;
       this.#instance[method](href);
     }
     return undefined as never;
@@ -429,6 +439,7 @@ class Router {
       throw new AkanNotFoundError();
     }
     this.#checkInitialized();
+    this.#redirects += 1;
     this.#instance.replace("/404");
     return undefined as never;
   }
@@ -444,10 +455,13 @@ class Router {
     this.#instance.replace(`${path}${search ? `?${search}` : ""}${hash ? `#${hash}` : ""}`);
     return undefined as never;
   }
+  /** 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;
+  }
   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;
+    return this.routeOf(pathname);
   }
   getFullPath(withLang = true) {
     if (getEnv().side === "server") throw new Error("getPath is only available in client side");

package/client/rscNavigation.ts

@@ -1,26 +1,30 @@
 declare global {
   var __AKAN_RSC_CLEAR_CACHE__: (() => void) | undefined;
   var __AKAN_RSC_IS_FROM_CACHE__: (() => boolean) | undefined;
+  var __AKAN_RSC_REFRESH__: ((options?: { buildId?: number }) => Promise<void>) | undefined;
   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 }) => {
   return globalThis.__AKAN_RSC_NAVIGATE__?.(href, options);
 };
 
+export const refreshRsc = () => {
+  return globalThis.__AKAN_RSC_REFRESH__?.();
+};
+
 export const useRscNavigation = () => ({
   clearCache: clearRscNavigationCache,
   isFromCache: isRscNavigationFromCache,

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,57 +1,77 @@
 import { getEnv } from "akanjs/base";
-import { loadCapacitorPreferences } from "./capacitor";
 
-const getLocalStorageItem = (key: string) => localStorage.getItem(key);
+type NativeModule = typeof import("./native");
 
-const setLocalStorageItem = (key: string, value: string) => {
-  localStorage.setItem(key, value);
+interface ClientStore {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  remove(key: string): Promise<void>;
+}
+
+const localStore: ClientStore = {
+  get: async (key) => localStorage.getItem(key),
+  set: async (key, value) => localStorage.setItem(key, value),
+  remove: async (key) => localStorage.removeItem(key),
 };
 
-const removeLocalStorageItem = (key: string) => {
-  localStorage.removeItem(key);
+const nativeApp = async (): Promise<NativeModule | null> => {
+  const native = await import("./native");
+  return native.isNativeApp() ? native : null;
 };
 
-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);
-    }
+const inClient = async <T>(
+  run: (store: ClientStore) => Promise<T>,
+  nativeStore: (native: NativeModule) => ClientStore,
+) => {
+  const env = getEnv();
+  if (env.side === "server") return;
+  const native = env.renderMode === "csr" ? await nativeApp() : null;
+  return await run(native ? nativeStore(native) : localStore);
+};
+
+const preferencesOf = ({ preferences }: NativeModule): ClientStore => ({
+  get: async (key) => (await preferences.get({ key })).value,
+  set: (key, value) => preferences.set({ key, value }),
+  remove: (key) => preferences.remove({ key }),
+});
+
+const installMarkerKey = "akan:installed";
+let freshInstall: Promise<void> | null = null;
+const clearedOnReinstall = (native: NativeModule) =>
+  (freshInstall ??= (async () => {
+    if ((await native.preferences.get({ key: installMarkerKey })).value) return;
+    await native.secureStorage.clear();
+    await native.preferences.set({ key: installMarkerKey, value: "1" });
+  })().catch((error: unknown) => {
+    freshInstall = null;
+    throw error;
+  }));
+
+const secureStorageOf = (native: NativeModule): ClientStore => ({
+  get: async (key) => {
+    await clearedOnReinstall(native);
+    return (await native.secureStorage.get({ key })).value;
   },
-  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;
-    }
+  set: async (key, value) => {
+    await clearedOnReinstall(native);
+    await native.secureStorage.set({ key, value });
   },
-  removeItem: async (key: string) => {
-    const env = getEnv();
-    if (env.side === "server") return;
-    if (env.renderMode === "ssr") {
-      removeLocalStorageItem(key);
-      return;
-    }
-    try {
-      const { Preferences } = await loadCapacitorPreferences();
-      return Preferences.remove({ key });
-    } catch {
-      removeLocalStorageItem(key);
-      return;
-    }
+  remove: async (key) => {
+    await clearedOnReinstall(native);
+    await native.secureStorage.remove({ key });
   },
+});
+
+/** Client key-value storage: the shell's preferences in a native app, localStorage in a browser. */
+export const storage = {
+  getItem: (key: string) => inClient((store) => store.get(key), preferencesOf),
+  setItem: (key: string, value: string) => inClient((store) => store.set(key, value), preferencesOf),
+  removeItem: (key: string) => inClient((store) => store.remove(key), preferencesOf),
+};
+
+/** Tokens: the OS credential store in a native app; a browser has none, so localStorage there. */
+export const secretStorage = {
+  getItem: (key: string) => inClient((store) => store.get(key), secureStorageOf),
+  setItem: (key: string, value: string) => inClient((store) => store.set(key, value), secureStorageOf),
+  removeItem: (key: string) => inClient((store) => store.remove(key), secureStorageOf),
 };

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;
 }
 
@@ -35,6 +34,7 @@ const getTranslatorState = (): TranslatorState => {
 };
 
 export class Translator {
+  static readonly #filledDicts = new WeakMap<AllDictionary, Map<string, Dictionary>>();
   constructor(dictionary: Record<string, Record<string, Record<string, unknown>>>) {
     Object.entries(dictionary).forEach(([lang, dict]) => {
       Translator.seed(lang, dict as Dictionary);
@@ -70,12 +70,37 @@ 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 withDefaultLocale(allDictionary: AllDictionary, lang: string): Dictionary | undefined {
+    const { defaultLocale } = parseAkanI18nEnv();
+    const fallback = allDictionary[defaultLocale];
+    if (lang === defaultLocale || !fallback) return allDictionary[lang];
+    const filledByLocale = Translator.#filledDicts.get(allDictionary) ?? new Map<string, Dictionary>();
+    Translator.#filledDicts.set(allDictionary, filledByLocale);
+    const filled =
+      filledByLocale.get(lang) ?? (Translator.#fillGaps(allDictionary[lang] ?? {}, fallback) as Dictionary);
+    filledByLocale.set(lang, filled);
+    return filled;
+  }
+  static #fillGaps(own: Record<string, unknown>, fallback: Record<string, unknown>): Record<string, unknown> {
+    const filled = { ...own };
+    for (const [key, value] of Object.entries(fallback)) {
+      const ownValue = filled[key];
+      if (ownValue === undefined) filled[key] = value;
+      else if (Translator.#isNode(ownValue) && Translator.#isNode(value))
+        filled[key] = Translator.#fillGaps(ownValue, value);
+    }
+    return filled;
+  }
+  static #isNode(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+  
   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 {

package/common/CodeAgentClient.ts

@@ -0,0 +1,91 @@
+import {
+  type CodeAgentCommand,
+  type CodeAgentEvent,
+  type CodeAgentFrame,
+  type CodeAgentRequest,
+  isCodeAgentReply,
+} from "./codeAgentWire";
+
+export interface CodeAgentTransport {
+  send(line: string): void | Promise<void>;
+  /** Called once with a handler that receives whole lines. */
+  onLine(handler: (line: string) => void): void;
+  close?(): void | Promise<void>;
+}
+
+export class CodeAgentClient {
+  readonly #transport: CodeAgentTransport;
+  readonly #pending = new Map<string, { resolve: (data: unknown) => void; reject: (error: Error) => void }>();
+  readonly #listeners = new Set<(event: CodeAgentEvent) => void>();
+  #nextId = 0;
+  #lastSeq = 0;
+  #buffer = "";
+
+  constructor(transport: CodeAgentTransport) {
+    this.#transport = transport;
+    this.#transport.onLine((line) => this.#receive(line));
+  }
+
+  /** The highest sequence accepted; a reconnecting host replays from here. */
+  get lastSeq() {
+    return this.#lastSeq;
+  }
+
+  /** Call on a new session, which restarts the sequence. */
+  resetSeq() {
+    this.#lastSeq = 0;
+  }
+
+  on(listener: (event: CodeAgentEvent) => void) {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+
+  async send(command: CodeAgentCommand): Promise<unknown> {
+    this.#nextId += 1;
+    const id = `c${this.#nextId}`;
+    const request: CodeAgentRequest = { id, command };
+    const promise = new Promise<unknown>((resolve, reject) => this.#pending.set(id, { resolve, reject }));
+    await this.#transport.send(`${JSON.stringify(request)}\n`);
+    return await promise;
+  }
+
+  async close() {
+    for (const pending of this.#pending.values()) pending.reject(new Error("code agent transport closed"));
+    this.#pending.clear();
+    await this.#transport.close?.();
+  }
+
+  /** Feed raw chunks when the transport is byte-oriented rather than line-oriented. */
+  push(chunk: string) {
+    this.#buffer += chunk;
+    let index = this.#buffer.indexOf("\n");
+    while (index >= 0) {
+      const line = this.#buffer.slice(0, index);
+      this.#buffer = this.#buffer.slice(index + 1);
+      if (line.trim()) this.#receive(line);
+      index = this.#buffer.indexOf("\n");
+    }
+  }
+
+  #receive(line: string) {
+    let frame: CodeAgentFrame;
+    try {
+      frame = JSON.parse(line) as CodeAgentFrame;
+    } catch {
+      return;
+    }
+    if (isCodeAgentReply(frame)) {
+      const pending = this.#pending.get(frame.id);
+      if (!pending) return;
+      this.#pending.delete(frame.id);
+      if (frame.ok) pending.resolve(frame.data);
+      else pending.reject(new Error(frame.error ?? "code agent command failed"));
+      return;
+    }
+    if (frame.type !== "event") return;
+    if (frame.event.seq <= this.#lastSeq) return;
+    this.#lastSeq = frame.event.seq;
+    for (const listener of this.#listeners) listener(frame.event);
+  }
+}