akanjs 3.1.2-rc.3 → 3.1.2-rc.4

package/README.ko.md

@@ -62,11 +62,22 @@ URL이라면, 코딩 에이전트는 묻지 않고 아래대로 진행하면 됩
 - **정해진 URL:** 페이지는 기본적으로 `/<locale>/…` 아래에 있습니다. 기본 로케일을 프리픽스 없는 경로
   (`/pokemon/deoxys`)로 내보내려면 `akan.config.ts`에 `i18n: { defaultLocale: "en", locales: ["en"], localePrefix:
   "as-needed" }`를 두세요. `<Link>`도 따라갑니다.
-- **Node와 npm만 있는 호스트:** `npm install -g bun`으로 생성기를 실행할 런타임을 받으세요. 호스트에도 설치되도록
-  워크스페이스의 `dependencies`에 `bun`을 두고, package script에서는 `devDependencies`의 `@akanjs/cli`로 `akan`을
-  부르세요. 전역 설치 뒤 `akan`을 찾지 못하면 `bun pm bin -g`가 출력하는 폴더를 `PATH`에 더하세요.
-- **Docker 없이 프로덕션 빌드 실행:** `akan build <app>` 뒤 `cd dist/apps/<app> && PORT=3000 bun main.js`. 빌드에
-  필요한 env가 함께 들어 있습니다.
+- **Node와 npm만 있는 호스트:** 생성기를 npx로 실행하세요. 전역에 아무것도 쓰지 않습니다:
+  `npx -y bun@1.4.4 x create-akan-workspace@latest . --app <app> --dir <folder> --sample false`. 호스트에도
+  설치되도록 워크스페이스의 `dependencies`에 `bun`을 두고, package script에서는 `devDependencies`의 `@akanjs/cli`로
+  `akan`을 부르세요. 전역 설치 뒤 `akan`을 찾지 못하면 `bun pm bin -g`가 출력하는 폴더를 `PATH`에 더하세요.
+- **Docker 없이 빌드하고 실행하기:** 아래 package script를 두고 `npm run build` 뒤 `PORT=3000 npm start`로 띄웁니다.
+
+  ```json
+  "build": "akan build <app>",
+  "start": "cd dist/apps/<app> && bun main.js"
+  ```
+
+  새로 clone한 사본도 그대로 빌드됩니다. env 파일은 gitignore된 채로 두면 `akan`이 없는 것을 만들어 주므로 커밋할
+  필요가 없습니다. 빌드에 필요한 env가 함께 들어 있고, 실행할 때 지정한 변수가 그 값을 덮어씁니다.
+- **실행할 곳에 맞게 빌드하기.** `.env`가 없으면 `akan build`는 `local`로 빌드합니다. 내 컴퓨터나 테스트 러너에서는
+  이대로 맞지만, dev 라우트를 누구에게나 엽니다. 다른 사람이 접속하는 호스트라면 `AKAN_PUBLIC_ENV=main`,
+  `AKAN_PUBLIC_REPO_NAME`, `AKAN_PUBLIC_SERVE_DOMAIN`(서비스할 도메인)을 셸이나 워크스페이스 `.env`에 지정하세요.
 
 ## 이 모든 게 한 줄입니다
 

package/README.md

@@ -61,11 +61,23 @@ Node and npm, or URLs given by a spec, a coding agent needs these, and nothing h
 - **Exact URLs:** pages live under `/<locale>/…`. To serve the default locale at the bare path (`/pokemon/deoxys`),
   set `i18n: { defaultLocale: "en", locales: ["en"], localePrefix: "as-needed" }` in `akan.config.ts`; `<Link>`
   follows.
-- **A host with only Node and npm:** `npm install -g bun` gives the creator its runtime. Put `bun` in the workspace's
-  `dependencies` so the host installs it too, and let the package scripts call `akan` from the `@akanjs/cli` in
-  `devDependencies`. If `akan` is not found after a global install, add the folder `bun pm bin -g` prints to `PATH`.
-- **Run the production build without Docker:** `akan build <app>`, then `cd dist/apps/<app> && PORT=3000 bun main.js`.
-  The build carries the env it needs.
+- **A host with only Node and npm:** run the creator through npx, which writes nothing global:
+  `npx -y bun@1.4.4 x create-akan-workspace@latest . --app <app> --dir <folder> --sample false`. Put `bun` in the
+  workspace's `dependencies` so the host installs it too, and let the package scripts call `akan` from the
+  `@akanjs/cli` in `devDependencies`. If `akan` is not found after a global install, add the folder `bun pm bin -g`
+  prints to `PATH`.
+- **Build and run without Docker** through these package scripts; `npm run build`, then `PORT=3000 npm start`:
+
+  ```json
+  "build": "akan build <app>",
+  "start": "cd dist/apps/<app> && bun main.js"
+  ```
+
+  A fresh clone builds as is: the env files stay gitignored and `akan` writes the ones it lacks, so commit none. The
+  build carries the env it needs, and a variable set at start overrides it.
+- **Build for where it runs.** Without a `.env`, `akan build` builds for `local`, right for your own machine or a test
+  runner but serving the dev routes to every caller. For a host others can reach, set `AKAN_PUBLIC_ENV=main`,
+  `AKAN_PUBLIC_REPO_NAME` and `AKAN_PUBLIC_SERVE_DOMAIN` (the domain it serves) in the shell or the workspace `.env`.
 
 ## All Of It Is One Line
 

package/client/makePageProto.tsx

@@ -1,5 +1,5 @@
 import { getEnv } from "akanjs/base";
-import { parseAkanI18nEnv, RequestLocale } from "akanjs/common";
+import { hasErrKey, parseAkanI18nEnv, RequestLocale } from "akanjs/common";
 import { untrackedHeaders, untrackedRequest } from "akanjs/fetch";
 import type { ReactNode } from "react";
 import { csrLocation } from "./csrLocation";
@@ -118,6 +118,10 @@ export const makePageProto = <
       return new Err(payload.error as ErrorKey, payload.data, payload);
     }
 
+    static is<Key extends ErrorKey>(error: unknown, ...keys: Key[]): error is Err & { readonly error: Key } {
+      return hasErrKey(error, keys);
+    }
+
     static BadRequest = class BadRequestErr extends Err {
       constructor(key: ErrorKey, data?: Record<string, unknown>, option: ErrRestoreOption = {}) {
         super(key, data, { ...option, statusCode: 400 });

package/client/route/RouteHead.ts

@@ -37,6 +37,29 @@ export class RouteHead {
     return RouteHead.merge([RouteHead.#withoutPageIdentity(layouts), page]);
   }
 
+  /** The tags at the top of `node` that a head merges by identity, apart from the rest, which is `node` if none. */
+  static split(node: ReactNode): { tags: ReactNode[]; rest: ReactNode } {
+    const children = RouteHead.#flatten(node);
+    const tags = children.filter((child) => RouteHead.#keyOfNode(child) !== null);
+    if (!tags.length) return { tags, rest: node };
+    const rest = children.filter((child) => RouteHead.#keyOfNode(child) === null);
+    return { tags, rest: createElement(Fragment, null, ...rest) };
+  }
+
+  /** A `robots` meta that adds `noindex` to the directives of the last `robots` meta at the top of `node`. */
+  static noindexOver(node: ReactNode): ReactElement {
+    const robots = RouteHead.#flatten(node).findLast((child) => RouteHead.#keyOfNode(child) === "meta:name:robots");
+    const content = isValidElement(robots) ? (robots.props as TagProps).content : undefined;
+    const kept =
+      typeof content === "string"
+        ? content
+            .split(",")
+            .map((directive) => directive.trim())
+            .filter((directive) => directive && !/^(?:index|noindex|all)$/i.test(directive))
+        : [];
+    return createElement("meta", { key: "robots", name: "robots", content: ["noindex", ...kept].join(", ") });
+  }
+
   /** What makes two tags the same tag; `null` for one that never replaces another. */
   static keyOf(tag: string, props: TagProps): string | null {
     if (tag === "title" || tag === "base") return tag;

package/common/akanGraph.ts

@@ -12,6 +12,8 @@ export type AkanGraphNodeKind =
 
 export type AkanGraphEdgeKind = "field" | "guard" | "calls" | "fetches" | "uses";
 
+export type AkanGraphChange = "added" | "removed" | "changed";
+
 export interface AkanGraphLocation {
   file: string;
   line: number;
@@ -26,6 +28,8 @@ export interface AkanGraphField {
   ref: string | null;
   declaredIn: string;
   at: AkanGraphLocation;
+  digest?: string;
+  change?: AkanGraphChange;
 }
 
 export interface AkanGraphNode {
@@ -39,6 +43,8 @@ export interface AkanGraphNode {
   at: AkanGraphLocation | null;
   fields?: AkanGraphField[];
   values?: string[];
+  digest?: string;
+  change?: AkanGraphChange;
 }
 
 export interface AkanGraphEdge {
@@ -48,6 +54,7 @@ export interface AkanGraphEdge {
   label: string | null;
   count: number;
   at: AkanGraphLocation | null;
+  change?: Exclude<AkanGraphChange, "changed">;
 }
 
 export interface AkanGraph {
@@ -55,3 +62,14 @@ export interface AkanGraph {
   nodes: AkanGraphNode[];
   edges: AkanGraphEdge[];
 }
+
+export interface AkanChangedFile {
+  file: string;
+  change: AkanGraphChange;
+}
+
+export interface AkanChangeMap extends AkanGraph {
+  since: string;
+  summary: { [change in AkanGraphChange]: number };
+  unmapped: AkanChangedFile[];
+}

package/common/appHosts.ts

@@ -1,4 +1,5 @@
 import { getEnv } from "akanjs/base";
+import { IpLiteral } from "./IpLiteral";
 
 export class AppHosts {
   static readonly #declared = new Set<string>();
@@ -24,6 +25,12 @@ export class AppHosts {
     return listed.some((entry) => AppHosts.nameOf(entry) === name);
   }
 
+  static isRebindSafe(host: string): boolean {
+    const name = AppHosts.nameOf(host);
+    if (!name) return false;
+    return !!IpLiteral.parse(host) || name === "localhost" || name.endsWith(".localhost") || AppHosts.allows(host);
+  }
+
   static nameOf(host: string): string | null {
     const url = URL.parse(`http://${host.trim()}`);
     if (!url || url.href !== `${url.origin}/`) return null;

package/common/hasErrKey.ts

@@ -0,0 +1,8 @@
+export const hasErrKey = <Key extends string>(
+  error: unknown,
+  keys: readonly Key[],
+): error is { readonly error: Key } => {
+  if (typeof error !== "object" || error === null) return false;
+  const key = (error as { error?: unknown }).error;
+  return typeof key === "string" && (!keys.length || (keys as readonly string[]).includes(key));
+};

package/common/index.ts

@@ -1,5 +1,8 @@
 export type {
+  AkanChangedFile,
+  AkanChangeMap,
   AkanGraph,
+  AkanGraphChange,
   AkanGraphEdge,
   AkanGraphEdgeKind,
   AkanGraphField,
@@ -99,6 +102,7 @@ export {
   resolveFileUploadCapability,
 } from "./fileUpload";
 export { formatNumber } from "./formatNumber";
+export { hasErrKey } from "./hasErrKey";
 export { type AkanHmrPhase, getAkanHmrPhase, isAkanHmrApplying } from "./hmrPhase";
 export { IpLiteral } from "./IpLiteral";
 export { interpolateTranslation } from "./interpolateTranslation";
@@ -270,5 +274,6 @@ export {
   type WebsocketHeartbeatRequest,
   websocketAuthContract,
   websocketBinaryFrameContract,
+  websocketCredentialContract,
   websocketHeartbeatContract,
 } from "./websocketContract";

package/common/tunnelWire.ts

@@ -98,8 +98,9 @@ export interface TunnelOpenFrame {
   /** `http` and `websocket`: path plus query, already percent-encoded. */
   path?: string;
   /**
-   * `http` and `websocket`, replayed verbatim: the gateway strips every `forwardedHeaderNames` entry the caller sent
-   * (else Host header injection) and writes `x-forwarded-host` as the tunnel hostname (else CSRF refuses mutations).
+   * `http` and `websocket`, replayed verbatim but for `host`, which the agent dials as the origin's own: the gateway
+   * strips every `forwardedHeaderNames` entry the caller sent (else Host header injection) and writes
+   * `x-forwarded-host` as the tunnel hostname (else CSRF refuses mutations).
    */
   headers?: TunnelHeaderList;
   /** `tcp`: the port on the local origin to dial. */

package/common/websocketContract.ts

@@ -1,3 +1,5 @@
+import { decodeJwtPayload } from "./jwtDecode";
+
 export interface WebsocketAuthRequest {
   key: string;
   data: [string | null];
@@ -27,6 +29,19 @@ export interface WebsocketHeartbeatAckData {
   type: "pong";
 }
 
+export const websocketCredentialContract = {
+  expiredCode: 4401,
+  expiredReason: "credential expired",
+  expiresAtOf: (jwt: string): number | null => {
+    try {
+      const { exp } = decodeJwtPayload<{ exp?: unknown }>(jwt);
+      return typeof exp === "number" && Number.isFinite(exp) ? exp * 1000 : null;
+    } catch {
+      return null;
+    }
+  },
+} as const;
+
 export const websocketHeartbeatContract = {
   key: "__ping",
   /** Under the 60s idle timeout nginx and most CDNs ship with. */

package/dictionary/trans.ts

@@ -1,5 +1,5 @@
 import type { GetStateObject, ObjectAssign, Prettify } from "akanjs/base";
-import { interpolateTranslation, Logger, parseAkanI18nEnv, pathGetLoose } from "akanjs/common";
+import { hasErrKey, interpolateTranslation, Logger, parseAkanI18nEnv, pathGetLoose } from "akanjs/common";
 
 import { DictionaryRegistry } from "./dictionaryRegistry";
 import type { DictModule } from "./locale";
@@ -153,9 +153,7 @@ export const makeTrans = <
 
     /** An Akan error, and one of `keys` when any are named; read off `error`, so a restored remote one passes too. */
     static is<Key extends _ErrorKey>(error: unknown, ...keys: Key[]): error is ErrInstance & { readonly error: Key } {
-      if (typeof error !== "object" || error === null) return false;
-      const key = (error as { error?: unknown }).error;
-      return typeof key === "string" && (!keys.length || (keys as string[]).includes(key));
+      return hasErrKey(error, keys);
     }
 
     static BadRequest = class BadRequestErr extends Err {

package/document/dataLoader.ts

@@ -11,10 +11,12 @@ type BatchLoadFn<Key, Value> = (
   keys: readonly Key[],
 ) => PromiseLike<ReadonlyArray<Value | Error>> | ReadonlyArray<Value | Error>;
 
-interface DataLoaderOptions<Key, CacheKey> {
+interface DataLoaderOptions<Key, Value, CacheKey> {
   /** `false` (default) keeps nothing past its batch, a number keeps a key that many ms, `true` for its whole life. */
   cache?: boolean | number;
   cacheKeyFn?: (key: Key) => CacheKey;
+  /** What a caller gets in place of a value another caller already holds: a repeated key's, or a kept key's. */
+  copy?: (value: Value) => Value;
   batch?: boolean;
   batchScheduleFn?: (callback: () => void) => void;
   maxBatchSize?: number;
@@ -36,12 +38,13 @@ export class DataLoader<Key, Value, CacheKey = Key> {
   readonly #batch: boolean;
   readonly #batchScheduleFn: (callback: () => void) => void;
   readonly #maxBatchSize: number;
+  readonly #copy: ((value: Value) => Value) | null;
   readonly #promiseCache = new Map<CacheKey, { promise: Promise<Value>; expiresAt: number }>();
   #sweepAt = DataLoader.#minSweepSize;
   #queue: BatchItem<Key, Value>[] = [];
   #scheduled = false;
 
-  constructor(batchLoadFn: BatchLoadFn<Key, Value>, options: DataLoaderOptions<Key, CacheKey> = {}) {
+  constructor(batchLoadFn: BatchLoadFn<Key, Value>, options: DataLoaderOptions<Key, Value, CacheKey> = {}) {
     this.#batchLoadFn = batchLoadFn;
     this.#ttl =
       options.cache === true
@@ -53,13 +56,14 @@ export class DataLoader<Key, Value, CacheKey = Key> {
     this.#batch = options.batch !== false;
     this.#batchScheduleFn = options.batchScheduleFn ?? ((callback) => queueMicrotask(callback));
     this.#maxBatchSize = options.maxBatchSize ?? Number.POSITIVE_INFINITY;
+    this.#copy = options.copy ?? null;
     this.name = options.name;
   }
 
   load(key: Key): Promise<Value> {
     const cacheKey = this.#cacheKeyFn(key);
     const cached = this.#cached(cacheKey);
-    if (cached) return cached;
+    if (cached) return this.#copy ? cached.then(this.#copy) : cached;
 
     const promise = new Promise<Value>((resolve, reject) => {
       this.#queue.push({ key, resolve, reject });
@@ -135,9 +139,20 @@ export class DataLoader<Key, Value, CacheKey = Key> {
           for (const { reject } of batch) reject(error);
           return;
         }
+        const handedOut = new Set<Value | Error>();
         values.forEach((value, index) => {
-          if (value instanceof Error) batch[index]?.reject(value);
-          else batch[index]?.resolve(value as Value);
+          const item = batch[index];
+          if (value instanceof Error) item?.reject(value);
+          else if (this.#copy && handedOut.has(value)) {
+            try {
+              item?.resolve(this.#copy(value as Value));
+            } catch (error) {
+              item?.reject(error);
+            }
+          } else {
+            handedOut.add(value);
+            item?.resolve(value as Value);
+          }
         });
       },
       (error) => {

package/fetch/client/fetchClient.ts

@@ -455,7 +455,7 @@ export class FetchClient {
   #makeHttpFn(key: string, endpoint: SerializedEndpoint, prefix?: string) {
     const argLength = endpoint.args.length;
     const serializerMap = this.#makeArgSerializer(endpoint.args);
-    const parseReturn = this.#makeReturnParser(endpoint.returns);
+    const parseReturn = FetchClient.#refusingUndeclaredNull(key, endpoint, this.#makeReturnParser(endpoint.returns));
     const { bodyArgs, uploadArgs } = FetchClient.classifyHttpArgs(endpoint.args);
     const requestOf = (argData: unknown[]) => {
       const args = argData.slice(0, argLength);
@@ -527,7 +527,6 @@ export class FetchClient {
           const roomArgLength = roomArgs.length;
           const serializerMap = this.#makeArgSerializer(endpoint.args);
           const parseReturn = this.#makeReturnParser(endpoint.returns);
-          const wrappedListeners = new WeakMap<(data: unknown) => void, (data: unknown) => void>();
           return (...argData: unknown[]) => {
             this.#refuseInApp(key);
             
@@ -540,17 +539,10 @@ export class FetchClient {
               const parsedReturn = parseReturn(data, { crystalize: fetchPolicy?.crystalize ?? true });
               handleEvent(parsedReturn);
             };
-            wrappedListeners.set(handleEvent, wrapped);
             const ws = this.#resolveWs(fetchPolicy?.origin);
             const handleResync = fetchPolicy?.onResync;
             ws.subscribe({ key, data, handleEvent: wrapped, handleResync });
-            return () =>
-              ws.unsubscribe({
-                key,
-                data,
-                handleEvent: wrappedListeners.get(handleEvent) ?? handleEvent,
-                handleResync,
-              });
+            return () => ws.unsubscribe({ key, data, handleEvent: wrapped, handleResync });
           };
         });
         return;
@@ -572,16 +564,14 @@ export class FetchClient {
         });
         this.#setHandlerFactory(endpointNames(key).listen, () => {
           const parseReturn = this.#makeReturnParser(endpoint.returns);
-          const wrappedListeners = new WeakMap<(data: unknown) => void, (data: unknown) => void>();
           return ((handleEvent: (data: unknown) => void, fetchPolicy: FetchPolicy = {}) => {
             const wrapped = (data: unknown) => {
               const parsedReturn = parseReturn(data, { crystalize: fetchPolicy?.crystalize ?? true });
               handleEvent(parsedReturn);
             };
-            wrappedListeners.set(handleEvent, wrapped);
             const ws = this.#resolveWs(fetchPolicy.origin);
             ws.on(key, wrapped);
-            return () => ws.off(key, wrappedListeners.get(handleEvent) ?? handleEvent);
+            return () => ws.off(key, wrapped);
           }) as FetchHandler;
         });
         return;
@@ -976,6 +966,20 @@ export class FetchClient {
     );
     return serializerMap;
   }
+  static #refusingUndeclaredNull<Parse extends (value: unknown, option?: { crystalize?: boolean }) => unknown>(
+    key: string,
+    endpoint: SerializedEndpoint,
+    parse: Parse,
+  ): Parse {
+    if (endpoint.returns.nullable) return parse;
+    return ((value: unknown, option?: { crystalize?: boolean }) => {
+      if (value === null || value === undefined)
+        throw new Error(
+          `${endpoint.type} ${key} answered ${value}, but its return is not nullable: answer a value, or declare { nullable: true } and answer null`,
+        );
+      return parse(value, option);
+    }) as Parse;
+  }
   #makeReturnParser(returns: SerializedReturns) {
     if (returns.modelType) {
       const returnRef = ConstantRegistry.getModelRef(returns.refName, returns.modelType);

package/fetch/client/wsClient.ts

@@ -6,6 +6,7 @@ import {
   type WebsocketHeartbeatAckData,
   websocketAuthContract,
   websocketBinaryFrameContract,
+  websocketCredentialContract,
   websocketHeartbeatContract,
 } from "akanjs/common";
 import type {
@@ -37,6 +38,11 @@ export interface WsClientOptions {
   onRevoked?: (roomId: string) => void;
   /** A frame the server answered with an error, and the subscribe or message key it answered. */
   onError?: (error: unknown, key?: string) => void;
+  /**
+   * Awaited, up to `WsClient.renewTimeoutMs`, before the reconnect that follows the server closing the socket at its
+   * credential's expiry: renew the session cookie, or call `setJwt`, so the new handshake carries a live credential.
+   */
+  onCredentialExpired?: () => unknown;
 }
 
 interface SubscribeOption {
@@ -68,6 +74,7 @@ export class WsClient {
     return websocketRoomContract.idOf(key, args);
   }
   static readonly stableMs = 5_000;
+  static renewTimeoutMs = 10_000;
 
   readonly logger = new Logger("WsClient");
   readonly url: string;
@@ -91,6 +98,7 @@ export class WsClient {
   #outbox: string[] = [];
   #unconnectedWarnTimers = new Map<string, ReturnType<typeof setTimeout>>();
   #jwt: string | null = null;
+  #renewing: Promise<unknown> | null = null;
   #heartbeatTimer: ReturnType<typeof setInterval> | null = null;
   #lastInboundAt = 0;
   #options: WsClientOptions = {};
@@ -268,7 +276,8 @@ export class WsClient {
       
       if (openedAt && Date.now() - openedAt >= WsClient.stableMs) this.#reconnectAttempts = 0;
       if (this.#destroyed) return;
-      this.#closed();
+      if (event.code === websocketCredentialContract.expiredCode) this.#renewThenReconnect();
+      else this.#closed();
       
       this.#handleMessage("disconnect", { code: event.code, reason: event.reason });
     };
@@ -293,6 +302,28 @@ export class WsClient {
     this.#scheduleReconnect();
   }
 
+  #renewThenReconnect() {
+    this.#reconnectAttempts = 0;
+    this.#setState("closed");
+    const renewing = Promise.race([
+      Promise.resolve()
+        .then(() => this.#options.onCredentialExpired?.())
+        .catch((error: unknown) => {
+          this.logger.warn(`WebSocket credential renewal failed: ${error instanceof Error ? error.message : error}`);
+        }),
+      new Promise<void>((resolve) => {
+        setTimeout(resolve, WsClient.renewTimeoutMs).unref?.();
+      }),
+    ]);
+    this.#renewing = renewing;
+    void renewing.then(() => {
+      if (this.#renewing !== renewing) return;
+      this.#renewing = null;
+      if (this.#destroyed || this.#ws || this.#reconnectTimer) return;
+      this.#connect();
+    });
+  }
+
   #startHeartbeat() {
     this.#stopHeartbeat();
     this.#lastInboundAt = Date.now();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.1.2-rc.3",
+  "version": "3.1.2-rc.4",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/akanApp.ts

@@ -26,6 +26,7 @@ import type { OpsRoute } from "./ops/opsRoute";
 import { StatusAccess } from "./ops/statusAccess";
 import { ProcessMetricsCollector } from "./processMetricsCollector";
 import { HostAllowlist } from "./routing/hostAllowlist";
+import { RouteHosts } from "./routing/routeHosts";
 import { ServerLimits } from "./routing/serverLimits";
 import { WsUpgrade } from "./routing/wsUpgrade";
 import { SelfExec } from "./selfExec";
@@ -615,6 +616,8 @@ export class AkanApp {
   }
 
   #listen() {
+    
+    if (this.#hostAllowlist?.devDefault) RouteHosts.declare(this.#artifactDir);
     this.#server = Bun.serve({
       idleTimeout: this.#limits.idleTimeout,
       maxRequestBodySize: this.#limits.uploadBodyBytes,
@@ -643,6 +646,8 @@ export class AkanApp {
     const url = new URL(req.url);
     if (url.pathname === "/_akan/app/health")
       return this.#statusAccess.health(req, () => this.#getHealthStatus(), AkanApp.#clientOf(req, server));
+    if (url.pathname === "/_akan/app/ready")
+      return this.#statusAccess.ready(req, () => this.#getReadyStatus(), AkanApp.#clientOf(req, server));
     if (url.pathname === "/_akan/app/metrics")
       return this.#statusAccess.metrics(req, () => this.#getMetricsStatus(), AkanApp.#clientOf(req, server));
     if (url.pathname === LogStreamRoute.path && this.#logStream)
@@ -815,6 +820,20 @@ export class AkanApp {
     };
   }
 
+  #getReadyStatus() {
+    return {
+      ready: this.#isReady(),
+      pid: process.pid,
+      children: [...this.#children.values()].map(({ idx, role, status, ready }) => ({ idx, role, status, ready })),
+    };
+  }
+
+  #isReady() {
+    if (this.#stopping) return false;
+    if (this.#replica.federation + this.#replica.all > 0) return this.#federationCandidates().length > 0;
+    return [...this.#children.values()].some((child) => child.ready && !this.#isChildUnavailable(child));
+  }
+
   #getMetricsStatus() {
     return {
       rooms: this.#roomChildren.size,
@@ -1073,17 +1092,19 @@ export class AkanApp {
     return await encodedFileResponse(req, filePath, options.contentType, assetHeaders(options));
   }
 
+  #federationCandidates() {
+    this.#federationChildCache ??= [...this.#children.values()].filter(
+      (child) =>
+        (child.role === "federation" || child.role === "all") &&
+        child.ready &&
+        child.status !== "unhealthy" &&
+        !this.#isChildUnavailable(child),
+    );
+    return this.#federationChildCache;
+  }
+
   #pickFederationChild() {
-    const candidates =
-      this.#federationChildCache ??
-      [...this.#children.values()].filter(
-        (child) =>
-          (child.role === "federation" || child.role === "all") &&
-          child.ready &&
-          child.status !== "unhealthy" &&
-          !this.#isChildUnavailable(child),
-      );
-    this.#federationChildCache = candidates;
+    const candidates = this.#federationCandidates();
     if (candidates.length === 0) return null;
     const child = candidates[this.#rrIdx % candidates.length];
     this.#rrIdx++;

package/server/akanOption.ts

@@ -12,6 +12,7 @@ import type {
 import type { McpServerOption } from "./akanServer";
 import type { WebProxyRegistration } from "./proxy";
 import { HostBasePathWebProxy, LocaleWebProxy } from "./proxy";
+import type { SessionRefreshHook } from "./sessionRefresh";
 
 export interface AdaptorOverride {
   role: AdaptorCls;
@@ -32,6 +33,7 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
   #agentQuota: AgentQuotaHook | null | undefined;
   #crossSite: CrossSiteOption | undefined;
   #getRateLimit: ((env: Env) => RateLimitSetting | false) | undefined;
+  #sessionRefresh: SessionRefreshHook | null | undefined;
   use(fnOrObject: ((env: Env) => Record<string, PromiseOrObject<unknown>>) | Record<string, PromiseOrObject<unknown>>) {
     if (typeof fnOrObject === "function")
       this.#getUses.push(fnOrObject as (env: Env) => Record<string, PromiseOrObject<unknown>>);
@@ -92,6 +94,15 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
     this.#getRateLimit = typeof settingOrFn === "function" ? settingOrFn : () => settingOrFn;
     return this;
   }
+  /**
+   * Runs before a page or RSC navigation renders, with the request as the browser sent it, and returns `Set-Cookie`
+   * values (or none). The render reads the cookies they set and the response carries them, so a session whose access
+   * token expired is renewed before a guard sees it. The app's wins over its libs'; `null` clears a lib's.
+   */
+  setSessionRefresh(hook: SessionRefreshHook | null) {
+    this.#sessionRefresh = hook;
+    return this;
+  }
   /** Injected into the `LlmAdaptorRole` adaptor as the `llmOption` use; merged in mount order, the app's last. */
   setLlm<Option extends LlmOption>(llmOrFn: Option | ((env: Env) => Option)) {
     if (typeof llmOrFn === "function") this.#getLlms.push(llmOrFn);
@@ -151,6 +162,9 @@ export class AkanOption<Env extends BackendEnv = BackendEnv> {
   getRateLimit(env: Env): RateLimitSetting | false | undefined {
     return this.#getRateLimit?.(env);
   }
+  getSessionRefresh(): SessionRefreshHook | null | undefined {
+    return this.#sessionRefresh;
+  }
   getLlm(env: Env): LlmOption {
     return Object.assign({}, ...this.#getLlms.map((fn) => fn(env)));
   }

package/server/akanServer.ts

@@ -51,6 +51,7 @@ import { RoomReplay } from "./routing/roomReplay";
 import { RouteHosts } from "./routing/routeHosts";
 import { ServerLimits } from "./routing/serverLimits";
 import { createSoloAppRoutes } from "./routing/soloAppRoutes";
+import { SessionRefresh } from "./sessionRefresh";
 import {
   getWebConfigFromEnv,
   type HttpRoutes,
@@ -223,6 +224,7 @@ export class AkanServer {
     this.openapi = options?.openapi ?? this.openapi;
     
     EndpointRateLimit.reset();
+    SessionRefresh.use(null);
     libs.forEach((lib) => {
       const mcp = lib.option.getMcp(this.env);
       if (mcp !== undefined) this.setMcp(mcp);
@@ -236,6 +238,8 @@ export class AkanServer {
       if (crossSite !== undefined) CrossSiteGuard.configure(crossSite);
       const rateLimit = lib.option.getRateLimit(this.env);
       if (rateLimit !== undefined) EndpointRateLimit.configure(rateLimit);
+      const sessionRefresh = lib.option.getSessionRefresh();
+      if (sessionRefresh !== undefined) SessionRefresh.use(sessionRefresh);
     });
     EndpointRateLimit.applyEnv(process.env.AKAN_RATE_LIMIT, getEnv().environment);
     this.setMcp(options?.mcp ?? this.mcp);
@@ -763,6 +767,7 @@ export class AkanServer {
             running: this.status === "running",
             status: this.status,
             port: this.#server?.port ?? null,
+            rscWorker: webRouter?.rscWorkerStatus ?? null,
             metrics: this.#lastMetrics,
           }),
           this.#logStream,
@@ -783,6 +788,7 @@ export class AkanServer {
       openapi: this.openapi,
       getStatus: () => this.status,
       buildGraph: webRouter ? () => webRouter.buildGraph() : undefined,
+      buildChanges: webRouter ? (since) => webRouter.buildChanges(since) : undefined,
     }).createRoutes();
     return { ...openapiRoutes, ...mcpRoutes, ...devtoolsRoutes, ...soloRoutes };
   }