akanjs 3.0.0-beta.2 → 3.0.0-beta.20

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;
 }
@@ -135,8 +130,6 @@ const getServerBasePath = (reqPathname: string, lang: string, headerBasePath: st
 
 declare global {
   var __AKAN_ROUTER__: Router | undefined;
-  var __AKAN_DEV_SYNC_NAVIGATION__: ((href: string, kind: "push" | "replace" | "back" | "pop") => void) | undefined;
-  var __AKAN_DEV_SYNC_NAVIGATION_APPLYING__: boolean | undefined;
 }
 
 export const getPathInfo = (requestUrl: string, lang: string, prefix: string) => {
@@ -163,15 +156,16 @@ class Router {
   #lang = parseAkanI18nEnv().defaultLocale;
   #routePaths = new Set<string>();
   #indexPath = "/";
+  #navigation: Promise<void> = Promise.resolve();
   #historyIdx = 0;
-  #instance: InternalRouterInstance = {
+  #instance: RouterInstance = {
     push: (href: string) => {
       const { href: fullHref } = this.#getPathInfo(href);
-      Logger.info(`push to:${fullHref}`);
+      Logger.warn(`router.push(${fullHref}) does not navigate on the server; use router.redirect() there`);
     },
     replace: (href: string) => {
-      const { pathname } = this.#getPathInfo(href);
-      Logger.info(`replace to:${pathname}`);
+      const { href: fullHref } = this.#getPathInfo(href);
+      Logger.warn(`router.replace(${fullHref}) does not navigate on the server; use router.redirect() there`);
     },
     back: () => {
       throw new Error("back is only available in client");
@@ -181,7 +175,6 @@ class Router {
     },
   };
   init(options: SsrClientRouterOption | SsrServerRouterOption | CSRClientRouterOption) {
-    
     this.#prefix = options.prefix ?? "";
     this.#lang = options.lang ?? parseAkanI18nEnv().defaultLocale;
     this.#routePaths = new Set(
@@ -196,29 +189,20 @@ class Router {
     }
     this.#ensureHistoryState();
     if (options.type === "csr") this.#initCsrClientRouter(options);
-    else if (options.side === "server") this.#initSsrServerRouter(options);
-    else this.#initSsrClientRouter(options);
+    else if (options.side === "client") this.#initSsrClientRouter(options);
     this.isInitialized = true;
     Logger.verbose("Router initialized");
   }
-  #initSsrServerRouter(options: SsrServerRouterOption) {
-  }
   #initSsrClientRouter(options: SsrClientRouterOption) {
+    const navigate = (method: "push" | "replace") => (href: string, routeOptions?: RouteOptions) => {
+      const pathInfo = this.#getPathInfo(href);
+      const navigationPathInfo = this.#getNavigationPathInfo(href);
+      this.#postPathChange(pathInfo);
+      return options.router[method](navigationPathInfo.href, routeOptions);
+    };
     this.#instance = {
-      push: (href: string, routeOptions) => {
-        const router = options.router;
-        const pathInfo = this.#getPathInfo(href);
-        const navigationPathInfo = this.#getNavigationPathInfo(href);
-        this.#postPathChange(pathInfo);
-        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 +222,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);
@@ -367,18 +351,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 +387,6 @@ class Router {
   }
   back(routeOptions?: RouteOptions) {
     if (getEnv().side === "server") throw new Error("back is only available in client side");
-    
     this.#checkInitialized();
     this.#instance.back(routeOptions);
     return undefined as never;
@@ -444,10 +437,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

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

package/client/sharedContext.ts

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

package/client/storage.ts

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

package/client/translator.ts

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

package/client/types.ts

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

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);
+  }
+}