akanjs 2.2.8 → 2.2.9

package/client/clientRuntime.ts

@@ -96,6 +96,9 @@ export const msg = new Proxy({} as ClientRuntime["msg"], {
   get(_target, prop, receiver) {
     return Reflect.get(getClientRuntime().msg, prop, receiver);
   },
+  set(_target, prop, value) {
+    return Reflect.set(getClientRuntime().msg, prop, value);
+  },
 });
 
 const ErrTarget = function AkanClientRuntimeErr(...args: ConstructorParameters<RuntimeErr>) {

package/client/csrTypes.ts

@@ -119,6 +119,7 @@ export interface LayoutModule {
   manifest?: WebAppManifest;
   theme?: string;
   reconnect?: boolean;
+  wsConnect?: boolean;
   layoutStyle?: "mobile" | "web";
   gaTrackingId?: string;
   Loading?: LayoutLoadingRender;

package/client/translator.ts

@@ -44,6 +44,12 @@ export class Translator {
   static getActiveLocale(): string | undefined {
     return getTranslatorState().activeLocale;
   }
+  static translateByLocale(lang: string, key: string, param?: Record<string, string | number>): string {
+    const dictionary = getTranslatorState().langDictionaryMap.get(lang);
+    if (!dictionary) return key;
+    const msg = (pathGet(key, dictionary, ".", { t: key }) as { t: string }).t;
+    return param ? msg.replace(/{([^}]+)}/g, (_, key: string) => param[key] as string) : msg;
+  }
 
   static seed(lang: string, dict: Dictionary | undefined) {
     if (!dict) return;
@@ -58,10 +64,7 @@ export class Translator {
     state.langDictionaryMap.set(lang, existingDictionary);
   }
   translate(lang: string, key: string, param?: Record<string, string | number>): string {
-    const dictionary = getTranslatorState().langDictionaryMap.get(lang);
-    if (!dictionary) return key;
-    const msg = (pathGet(key, dictionary, ".", { t: key }) as { t: string }).t;
-    return param ? msg.replace(/{([^}]+)}/g, (_, key: string) => param[key] as string) : msg;
+    return Translator.translateByLocale(lang, key, param);
   }
   async getDictionary(lang: string) {
     const dictionary = getTranslatorState().langDictionaryMap.get(lang);

package/dictionary/base.dictionary.ts

@@ -20,7 +20,6 @@ export const baseDictionary = serviceDictionary(["en", "ko"])
       .arg((t) => ({
         id: t(["ID", "아이디"]),
       })),
-    cleanup: fn(["Cleanup", "Cleanup"]).desc(["Cleanup operation", "정리 작업"]),
     wsPing: fn(["Socket.io Ping", "Socket.io Ping"])
       .desc(["Socket.io Ping test", "Socket.io Ping 테스트"])
       .arg((t) => ({

package/fetch/client/fetchClient.ts

@@ -173,6 +173,10 @@ export class FetchClient {
     if (!handler) throw new Error(`${owner} requires fetch handler "${key}", but it is not registered`);
     return handler as T;
   }
+  #setHandlerFactory(key: string, factory: FetchHandlerFactory) {
+    this.#handlerFactory.set(key, factory);
+    delete this.#handlerStore[key];
+  }
   connect() {
     this.ws.connect();
   }
@@ -256,15 +260,15 @@ export class FetchClient {
   #registerEndpoint(key: string, endpoint: SerializedEndpoint, prefix?: string) {
     switch (endpoint.type) {
       case "query": {
-        this.#handlerFactory.set(key, () => this.#makeHttpFn(key, endpoint, prefix));
+        this.#setHandlerFactory(key, () => this.#makeHttpFn(key, endpoint, prefix));
         return;
       }
       case "mutation": {
-        this.#handlerFactory.set(key, () => this.#makeHttpFn(key, endpoint, prefix));
+        this.#setHandlerFactory(key, () => this.#makeHttpFn(key, endpoint, prefix));
         return;
       }
       case "pubsub": {
-        this.#handlerFactory.set(`subscribe${capitalize(key)}`, () => {
+        this.#setHandlerFactory(`subscribe${capitalize(key)}`, () => {
           const roomArgs = endpoint.args.filter((arg) => arg.type === "room");
           const roomArgLength = roomArgs.length;
           const serializerMap = this.#makeArgSerializer(endpoint.args);
@@ -292,7 +296,7 @@ export class FetchClient {
         return;
       }
       case "message": {
-        this.#handlerFactory.set(key, () => {
+        this.#setHandlerFactory(key, () => {
           const msgArgs = endpoint.args.filter((arg) => arg.type === "msg");
           const msgArgLength = msgArgs.length;
           const serializerMap = this.#makeArgSerializer(endpoint.args);
@@ -302,7 +306,7 @@ export class FetchClient {
             this.ws.emit(key, data);
           };
         });
-        this.#handlerFactory.set(`listen${capitalize(key)}`, () => {
+        this.#setHandlerFactory(`listen${capitalize(key)}`, () => {
           const parseReturn = this.#makeReturnParser(endpoint.returns);
           const wrappedListeners = new WeakMap<(data: unknown) => void, (data: unknown) => void>();
           return ((handleEvent: (data: unknown) => void, fetchPolicy: FetchPolicy = {}) => {
@@ -407,11 +411,11 @@ export class FetchClient {
     };
     const endpoint = FetchClient.getBaseEndpoint(refName, signal);
     Object.entries(endpoint).forEach(([key, value]) => {
-      this.#handlerFactory.set(key, () => this.#makeHttpFn(key, value, signal.prefix));
+      this.#setHandlerFactory(key, () => this.#makeHttpFn(key, value, signal.prefix));
     });
 
     if (signal.cruGuards) {
-      this.#handlerFactory.set(
+      this.#setHandlerFactory(
         names.viewModel,
         () =>
           (async (id: string, option?: FetchPolicy) => {
@@ -425,7 +429,7 @@ export class FetchClient {
             };
           }) as FetchHandler,
       );
-      this.#handlerFactory.set(
+      this.#setHandlerFactory(
         names.getModelView,
         () =>
           (async (id: string, option?: FetchPolicy) => {
@@ -434,7 +438,7 @@ export class FetchClient {
             return { refName, [`${refName}Obj`]: modelObj, [`${refName}ViewAt`]: new Date() };
           }) as FetchHandler,
       );
-      this.#handlerFactory.set(
+      this.#setHandlerFactory(
         names.editModel,
         () =>
           (async (id: string, option?: FetchPolicy) => {
@@ -448,7 +452,7 @@ export class FetchClient {
             };
           }) as FetchHandler,
       );
-      this.#handlerFactory.set(
+      this.#setHandlerFactory(
         names.getModelEdit,
         () =>
           (async (id: string, option?: FetchPolicy) => {
@@ -457,7 +461,7 @@ export class FetchClient {
             return { refName, [`${refName}Obj`]: modelObj, [`${refName}ViewAt`]: new Date() };
           }) as FetchHandler,
       );
-      this.#handlerFactory.set(
+      this.#setHandlerFactory(
         names.mergeModel,
         () =>
           (async (modelOrId: string | { id: string }, data: UnknownRecord, option?: FetchPolicy) => {
@@ -468,7 +472,7 @@ export class FetchClient {
       );
     }
 
-    this.#handlerFactory.set(
+    this.#setHandlerFactory(
       names.addModelFiles,
       () =>
         (async (fileList: FileList, parentId?: string, option?: FetchPolicy) => {
@@ -529,12 +533,12 @@ export class FetchClient {
 
     const endpoint = FetchClient.getEndpointFromSlice(refName, suffix, slice);
     Object.entries(endpoint).forEach(([key, value]) => {
-      this.#handlerFactory.set(key, () => this.#makeHttpFn(key, value, prefix));
+      this.#setHandlerFactory(key, () => this.#makeHttpFn(key, value, prefix));
     });
 
     const argLength = slice.args.length;
     this.slice[sliceName] = { refName, sliceName, argLength };
-    this.#handlerFactory.set(names.init, () => async (...argData: unknown[]) => {
+    this.#setHandlerFactory(names.init, () => async (...argData: unknown[]) => {
       const cnst = ConstantRegistry.getDatabase(refName);
       const queryArgs = normalizeQueryArgs(
         Array.from({ length: Math.min(argData.length, argLength) }, (_, idx) => argData[idx]),
@@ -576,7 +580,7 @@ export class FetchClient {
         [`${refName}Insight${capSuffix}`]: modelInsight,
       };
     });
-    this.#handlerFactory.set(names.getInit, () => async (...args: unknown[]) => {
+    this.#setHandlerFactory(names.getInit, () => async (...args: unknown[]) => {
       const initFn = this.#requireHandler<(...args: unknown[]) => Promise<Record<string, unknown>>>(
         names.init,
         names.getInit,

package/fetch/client/wsClient.ts

@@ -53,6 +53,7 @@ export class WsClient {
   }
 
   connect() {
+    if (this.#ws && this.#ws.readyState !== WebSocket.CLOSED) return;
     this.logger.debug(`Connecting to ${this.url}`);
     this.#destroyed = false;
     this.#reconnectAttempts = 0;
@@ -201,9 +202,15 @@ export class WsClient {
     const hasRoom = roomSub ? roomSub.listener.size > 0 : false;
     return hasGeneric || hasRoom;
   }
+  #warnNotConnected(action: "emit" | "subscribe", key: string) {
+    console.warn(
+      `[akanjs] WebSocket is not connected. Call fetch.instance.connect() or enable root layout "wsConnect" before ${action} "${key}".`,
+    );
+  }
   emit(key: string, data: WsRequestPayload) {
     if (this.#ws?.readyState !== WebSocket.OPEN) {
       this.logger.warn("WebSocket not connected");
+      this.#warnNotConnected("emit", key);
       return this;
     }
     const payload: WebsocketReqData = { key, data: Array.isArray(data) ? data : [data] };
@@ -212,6 +219,7 @@ export class WsClient {
   }
   subscribe(option: { key: string; data: unknown[]; handleEvent: (data: unknown) => void }) {
     const roomId = WsClient.makeRoomId(option.key, option.data);
+    if (!this.#ws) this.#warnNotConnected("subscribe", option.key);
     if (!this.#roomSubscribeMap.has(roomId)) {
       this.#roomSubscribeMap.set(roomId, { key: option.key, data: option.data, listener: new Set() });
       if (this.#ws?.readyState === WebSocket.OPEN) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "2.2.8",
+  "version": "2.2.9",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {

package/server/hmr/devHmrController.ts

@@ -362,6 +362,7 @@ export class DevHmrController {
       `${path.sep}pkgs${path.sep}akanjs${path.sep}server${path.sep}src${path.sep}ssrFromRscRenderer.tsx`,
     ];
     if (files.some((file) => runtimeRoots.some((needle) => path.resolve(file).includes(needle)))) return true;
+    if (files.some((file) => path.basename(file).endsWith(".signal.ts"))) return true;
 
     return (
       routeIds === undefined &&

package/server/routeTreeBuilder.ts

@@ -53,6 +53,7 @@ export class RouteTreeBuilder {
     "manifest",
     "theme",
     "reconnect",
+    "wsConnect",
     "layoutStyle",
     "gaTrackingId",
     "Loading",

package/server/ssrFromRscRenderer.tsx

@@ -69,7 +69,6 @@ export class SsrFromRscRenderer {
 
     const renderHtml = () =>
       renderToReadableStream(<Root />, {
-        bootstrapModules: input.bootstrapModules,
         bootstrapScriptContent: bootstrap,
       });
     const htmlStream =
@@ -77,6 +76,7 @@ export class SsrFromRscRenderer {
 
     const withHeadScripts = SsrFromRscRenderer.#injectHeadScriptsIntoHead(htmlStream, {
       importmap: input.importmap,
+      bootstrapModules: input.bootstrapModules,
       theme: input.theme,
       injectThemeInitScript: input.injectThemeInitScript,
     });
@@ -84,6 +84,7 @@ export class SsrFromRscRenderer {
     return SsrFromRscRenderer.#appendRscScriptsAfterHtml(
       withHeadScripts,
       SsrFromRscRenderer.#sanitizeFlightForClient(rscForClient),
+      input.bootstrapModules,
       input.request,
     );
   }
@@ -124,32 +125,35 @@ export class SsrFromRscRenderer {
    * tag in the outgoing HTML stream.
    *
    * We do this as a stream transform (rather than as a React child inside
-   * `<head>`) because React 19's Float pipeline hoists
-   * `<link rel="modulepreload">` for every entry in `bootstrapModules` to the
-   * top of `<head>`. An importmap rendered via JSX ends up *after* those
-   * hoisted preloads, which — per the HTML spec — is too late: once the
-   * browser starts a module script fetch for a preload, the document's
-   * "allow-import-maps" bit flips to false and no further importmap can be
-   * acquired. By writing the importmap before any of React's own `<head>`
-   * output reaches the wire, we guarantee the browser sees it first.
+   * `<head>`) so importmaps are acquired before any modulepreload can start.
+   * The spec is strict: once the browser starts a module script fetch for a
+   * preload, the document's "allow-import-maps" bit flips to false and no
+   * further importmap can be acquired.
    *
    * The transform operates on UTF-8 bytes until it has spliced the tag, then
    * becomes a pure passthrough to avoid any further per-chunk overhead.
    */
   static #injectHeadScriptsIntoHead(
     stream: ReadableStream<Uint8Array>,
-    options: { importmap?: Record<string, string>; theme?: AkanTheme; injectThemeInitScript?: boolean },
+    options: {
+      importmap?: Record<string, string>;
+      bootstrapModules?: string[];
+      theme?: AkanTheme;
+      injectThemeInitScript?: boolean;
+    },
   ): ReadableStream<Uint8Array> {
     const encoder = new TextEncoder();
     const decoder = new TextDecoder();
-    const { importmap, theme, injectThemeInitScript } = options;
+    const { importmap, bootstrapModules, theme, injectThemeInitScript } = options;
     const htmlTheme = theme && theme !== "css" && theme !== "system" ? theme : undefined;
     const importmapTag =
       importmap && Object.keys(importmap).length > 0
         ? `<script type="importmap">${JSON.stringify({ imports: importmap })}</script>`
         : "";
+    const modulePreloadTags = SsrFromRscRenderer.#createBootstrapModulePreloadTags(bootstrapModules);
     const shouldInjectThemeScript = theme === "system" || (theme === undefined && injectThemeInitScript);
-    const tags = `${shouldInjectThemeScript ? SsrFromRscRenderer.#themeInitScript : ""}${importmapTag}`;
+    const themeInitTag = shouldInjectThemeScript ? SsrFromRscRenderer.#themeInitScript : "";
+    const tags = `${themeInitTag}${importmapTag}${modulePreloadTags}`;
     if (!tags && !htmlTheme) return stream;
     const htmlOpenRe = /<html(\s[^>]*)?>/i;
     const headOpenRe = /<head(\s[^>]*)?>/i;
@@ -200,6 +204,20 @@ export class SsrFromRscRenderer {
     return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
   }
 
+  static #createBootstrapModulePreloadTags(bootstrapModules?: string[]): string {
+    if (!bootstrapModules?.length) return "";
+    return bootstrapModules
+      .map((src) => `<link rel="modulepreload" href="${SsrFromRscRenderer.#escapeHtmlAttr(src)}">`)
+      .join("");
+  }
+
+  static #createBootstrapModuleScriptTags(bootstrapModules?: string[]): string {
+    if (!bootstrapModules?.length) return "";
+    return bootstrapModules
+      .map((src) => `<script type="module" src="${SsrFromRscRenderer.#escapeHtmlAttr(src)}"></script>`)
+      .join("");
+  }
+
   static #sanitizeFlightForClient(stream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array> {
     const decoder = new TextDecoder();
     const encoder = new TextEncoder();
@@ -227,9 +245,11 @@ export class SsrFromRscRenderer {
   static #appendRscScriptsAfterHtml(
     htmlStream: ReadableStream<Uint8Array>,
     rscClientStream: ReadableStream<Uint8Array>,
+    bootstrapModules?: string[],
     request?: Request,
   ): ReadableStream<Uint8Array> {
     const encoder = new TextEncoder();
+    const bootstrapModuleScripts = SsrFromRscRenderer.#createBootstrapModuleScriptTags(bootstrapModules);
 
     return new ReadableStream<Uint8Array>({
       start(controller) {
@@ -253,6 +273,8 @@ export class SsrFromRscRenderer {
             reader.releaseLock();
           }
 
+          if (bootstrapModuleScripts && !errored) controller.enqueue(encoder.encode(bootstrapModuleScripts));
+
           const rscReader = rscClientStream.getReader();
           try {
             while (true) {

package/server/ssrTypes.ts

@@ -35,12 +35,11 @@ export interface SsrFromRscInput {
    * guaranteeing one React instance across rscClient and every route
    * chunk.
    *
-   * Injection happens via a stream transform, not React children, because
-   * React Fizz hoists `<link rel="modulepreload">` (generated from
-   * `bootstrapModules`) to the top of `<head>`, which would otherwise sit
-   * before any importmap rendered via JSX. The spec is strict: import maps
-   * must be acquired before any module script fetch starts, including
-   * modulepreload.
+   * Injection happens via a stream transform, not React children, because the
+   * spec is strict: import maps must be acquired before any module script fetch
+   * starts, including modulepreload. Akan writes bootstrap module preloads
+   * directly after this importmap and delays the executable module script until
+   * the Fizz HTML stream has completed.
    */
   importmap?: Record<string, string>;
   theme?: AkanTheme;

package/service/base.service.ts

@@ -9,10 +9,6 @@ export class BaseService extends serve("base" as const, ({ env, signal, memory }
   publishPing() {
     this.baseSignal.pubsubPing("ping");
   }
-  async cleanup() {
-    if (!this.onCleanup) throw new Error("onCleanup is not defined");
-    await this.onCleanup();
-  }
 }
 
 export const srv = { base: new ServiceModel(BaseService) };

package/signal/base.signal.ts

@@ -18,11 +18,6 @@ export class BaseEndpoint extends endpoint(srv.base, ({ query, mutation, message
   pingQuery: query(String, { nullable: true })
     .search("id", String)
     .exec((id) => `pingQuery: ${id}`),
-  cleanup: mutation(Boolean).exec(async function () {
-    if (process.env.NODE_ENV !== "test") throw new Error("cleanup is only available in test environment");
-    await this.baseService.cleanup();
-    return true;
-  }),
   wsPing: message(String)
     .msg("data", String, { nullable: true })
     .exec((data) => `wsPing: ${data}`),

package/store/storeInstance.ts

@@ -1,5 +1,6 @@
 import { ACTION_META, STATE_DERIVED_META, STATE_INIT_META } from "akanjs/base";
-import { capitalize, Logger } from "akanjs/common";
+import { Translator } from "akanjs/client/translator";
+import { capitalize, Logger, parseAkanI18nEnv } from "akanjs/common";
 import { produce } from "immer";
 import type { RefObject } from "react";
 import { useEffect, useRef, useSyncExternalStore } from "./hooks";
@@ -9,6 +10,7 @@ import { evaluateInitializers, type SearchParamsState, type StateDerivedMeta } f
 
 type StoreStateRecord = Record<string, unknown>;
 type StoreAction = (...args: unknown[]) => unknown;
+type TranslationParam = Record<string, string | number>;
 
 type SliceActionKey =
   | "initModel"
@@ -20,6 +22,27 @@ type SliceActionKey =
   | "setQueryArgsOfModel"
   | "setSortOfModel";
 
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value && typeof value === "object" && !Array.isArray(value));
+
+const getActionErrorKey = (error: unknown) => {
+  if (typeof error === "string") return error;
+  if (!isRecord(error)) return String(error);
+  if (typeof error.error === "string") return error.error;
+  if (typeof error.message === "string") return error.message;
+  return String(error);
+};
+
+const getActionErrorData = (error: unknown): TranslationParam | undefined => {
+  if (!isRecord(error) || !isRecord(error.data)) return undefined;
+  const data = Object.fromEntries(
+    Object.entries(error.data).filter((entry): entry is [string, string | number] =>
+      ["string", "number"].includes(typeof entry[1]),
+    ),
+  );
+  return Object.keys(data).length ? data : undefined;
+};
+
 export type ReactAPI = {
   useSyncExternalStore: <T>(
     subscribe: (onStoreChange: () => void) => () => void,
@@ -190,12 +213,36 @@ export class StoreInstance {
       this.do[k] = async (...args: unknown[]) => {
         Logger.verbose(`${k} action loading...`);
         const start = Date.now();
-        await (this.#ctx[k] as StoreAction)(...args);
-        Logger.verbose(`=> ${k} action dispatched (${Date.now() - start}ms)`);
+        try {
+          const result = await (this.#ctx[k] as StoreAction)(...args);
+          Logger.verbose(`=> ${k} action dispatched (${Date.now() - start}ms)`);
+          return result;
+        } catch (error) {
+          this.#showActionErrorMessage(k, error);
+          Logger.error(`${k} action error return: ${error instanceof Error ? error.message : String(error)}`);
+          throw error;
+        }
       };
     }
   }
 
+  #showActionErrorMessage(actionKey: string, error: unknown) {
+    const showMessage = this.#ctx.showMessage;
+    if (typeof showMessage !== "function") return;
+    try {
+      const lang = Translator.getActiveLocale() ?? parseAkanI18nEnv().defaultLocale;
+      const errorKey = getActionErrorKey(error);
+      const content = Translator.translateByLocale(lang, errorKey, getActionErrorData(error));
+      showMessage({ type: "error", key: actionKey, duration: 3, content });
+    } catch (messageError) {
+      Logger.warn(
+        `Failed to show ${actionKey} action error message: ${
+          messageError instanceof Error ? messageError.message : String(messageError)
+        }`,
+      );
+    }
+  }
+
   #buildSlices(store: RootStoreCls) {
     Object.entries(store.slice).forEach(([refName, sliceObj]) => {
       Object.entries(sliceObj).forEach(([suffix, serializedSlice]) => {

package/types/client/csrTypes.d.ts

@@ -122,6 +122,7 @@ export interface LayoutModule {
     manifest?: WebAppManifest;
     theme?: string;
     reconnect?: boolean;
+    wsConnect?: boolean;
     layoutStyle?: "mobile" | "web";
     gaTrackingId?: string;
     Loading?: LayoutLoadingRender;

package/types/client/translator.d.ts

@@ -11,6 +11,7 @@ export declare class Translator {
     hasDictionary(lang: string): boolean;
     static setActiveLocale(lang: string | undefined): void;
     static getActiveLocale(): string | undefined;
+    static translateByLocale(lang: string, key: string, param?: Record<string, string | number>): string;
     static seed(lang: string, dict: Dictionary | undefined): void;
     translate(lang: string, key: string, param?: Record<string, string | number>): string;
     getDictionary(lang: string): Promise<Dictionary>;

package/types/server/ssrTypes.d.ts

@@ -34,12 +34,11 @@ export interface SsrFromRscInput {
      * guaranteeing one React instance across rscClient and every route
      * chunk.
      *
-     * Injection happens via a stream transform, not React children, because
-     * React Fizz hoists `<link rel="modulepreload">` (generated from
-     * `bootstrapModules`) to the top of `<head>`, which would otherwise sit
-     * before any importmap rendered via JSX. The spec is strict: import maps
-     * must be acquired before any module script fetch starts, including
-     * modulepreload.
+     * Injection happens via a stream transform, not React children, because the
+     * spec is strict: import maps must be acquired before any module script fetch
+     * starts, including modulepreload. Akan writes bootstrap module preloads
+     * directly after this importmap and delays the executable module script until
+     * the Fizz HTML stream has completed.
      */
     importmap?: Record<string, string>;
     theme?: AkanTheme;

package/types/service/base.service.d.ts

@@ -8,7 +8,6 @@ declare const BaseService_base: import("./serve.d.ts").ServiceCls<"base", {}, {
 }>;
 export declare class BaseService extends BaseService_base {
     publishPing(): void;
-    cleanup(): Promise<void>;
 }
 export declare const srv: {
     base: ServiceModel<typeof BaseService, any, any, {

package/types/signal/base.signal.d.ts

@@ -18,9 +18,6 @@ declare const BaseEndpoint_base: import("./endpoint.d.ts").EndpointCls<import("a
     pingQuery: import("./endpointInfo.d.ts").EndpointInfo<"query", {
         baseService: import("akanjs/service").BaseService;
     }, [string], [arg?: string | null | undefined], [], [arg: string | undefined], StringConstructor, string, string, true>;
-    cleanup: import("./endpointInfo.d.ts").EndpointInfo<"mutation", {
-        baseService: import("akanjs/service").BaseService;
-    }, [], [], [], [], BooleanConstructor, boolean, Promise<boolean>, false>;
     wsPing: import("./endpointInfo.d.ts").EndpointInfo<"message", {
         baseService: import("akanjs/service").BaseService;
     }, [string], [arg?: string | null | undefined], [], [arg: string | undefined], StringConstructor, string, string, false>;

package/types/ui/System/CSR.d.ts

@@ -5,7 +5,7 @@ export declare const CSR: {
     ({ children }: {
         children: ReactNode;
     }): import("react/jsx-runtime").JSX.Element;
-    Provider: ({ className, appName, params, head, manifest, env, theme, prefix, children, gaTrackingId, fonts, layoutStyle, reconnect, of, }: CSRProviderProps) => import("react/jsx-runtime").JSX.Element;
+    Provider: ({ className, appName, params, head, manifest, env, theme, prefix, children, gaTrackingId, fonts, layoutStyle, reconnect, wsConnect, of, }: CSRProviderProps) => import("react/jsx-runtime").JSX.Element;
     Wrapper: ({ children, lang, head, manifest, fonts, appName, className, prefix, layoutStyle, }: CSRWrapperProps) => import("react/jsx-runtime").JSX.Element;
     Inner: () => import("react/jsx-runtime").JSX.Element;
     Bridge: ({ lang, prefix }: CSRBridgeProps) => null;
@@ -13,7 +13,7 @@ export declare const CSR: {
 export type CSRProviderProps = ProviderProps & {
     fonts: ReactFont[];
 };
-declare const CSRProvider: ({ className, appName, params, head, manifest, env, theme, prefix, children, gaTrackingId, fonts, layoutStyle, reconnect, of, }: CSRProviderProps) => import("react/jsx-runtime").JSX.Element;
+declare const CSRProvider: ({ className, appName, params, head, manifest, env, theme, prefix, children, gaTrackingId, fonts, layoutStyle, reconnect, wsConnect, of, }: CSRProviderProps) => import("react/jsx-runtime").JSX.Element;
 interface CSRWrapperProps {
     className?: string;
     appName: string;

package/types/ui/System/Client.d.ts

@@ -6,7 +6,7 @@ import { type HTMLAttributes, type ReactNode, type RefObject } from "react";
 export declare const Client: {
     (): import("react/jsx-runtime").JSX.Element;
     Wrapper: ({ children, theme, lang, dictionary, signals, reconnect, }: ClientWrapperProps) => import("react/jsx-runtime").JSX.Element;
-    Bridge: ({ env, lang, theme, prefix, gaTrackingId }: ClientBridgeProps) => "" | import("react/jsx-runtime").JSX.Element | undefined;
+    Bridge: ({ env, lang, theme, prefix, gaTrackingId, wsConnect }: ClientBridgeProps) => "" | import("react/jsx-runtime").JSX.Element | undefined;
     Inner: () => import("react/jsx-runtime").JSX.Element;
     SsrBridge: ({ lang, prefix }: ClientSsrBridgeProps) => null;
 };
@@ -36,8 +36,9 @@ interface ClientBridgeProps {
     theme?: AkanTheme;
     prefix?: string;
     gaTrackingId?: string;
+    wsConnect?: boolean;
 }
-export declare const ClientBridge: ({ env, lang, theme, prefix, gaTrackingId }: ClientBridgeProps) => "" | import("react/jsx-runtime").JSX.Element | undefined;
+export declare const ClientBridge: ({ env, lang, theme, prefix, gaTrackingId, wsConnect }: ClientBridgeProps) => "" | import("react/jsx-runtime").JSX.Element | undefined;
 export declare const ClientInner: () => import("react/jsx-runtime").JSX.Element;
 interface ClientSsrBridgeProps {
     lang: string;

package/types/ui/System/Common.d.ts

@@ -28,6 +28,8 @@ export interface ProviderProps {
     layoutStyle?: "mobile" | "web";
     /** Enable reconnect helper. Defaults to local operation mode in CSR. */
     reconnect?: boolean;
+    /** Connect the client WebSocket runtime after the browser loads. */
+    wsConnect?: boolean;
     /** Active-locale dictionary injected by the server (SSR only) to seed the client Translator. */
     dictionary?: Record<string, Record<string, unknown>>;
     /**

package/types/ui/System/SSR.d.ts

@@ -3,13 +3,13 @@ import { type ReactNode } from "react";
 import { type ProviderProps } from "./Common.d.ts";
 export declare const SSR: {
     (): import("react/jsx-runtime").JSX.Element;
-    Provider: ({ className, appName, params, head, manifest, env, gaTrackingId, children, theme, prefix, fonts, layoutStyle, reconnect, dictionary, allDictionary, of, }: SSRProviderProps) => import("react/jsx-runtime").JSX.Element;
+    Provider: ({ className, appName, params, head, manifest, env, gaTrackingId, children, theme, prefix, fonts, layoutStyle, reconnect, wsConnect, dictionary, allDictionary, of, }: SSRProviderProps) => import("react/jsx-runtime").JSX.Element;
     Wrapper: ({ children, head, manifest, fonts, className, prefix, layoutStyle, }: SSRWrapperProps) => import("react/jsx-runtime").JSX.Element;
 };
 export type SSRProviderProps = ProviderProps & {
     fonts?: ReactFont[];
 };
-declare const SSRProvider: ({ className, appName, params, head, manifest, env, gaTrackingId, children, theme, prefix, fonts, layoutStyle, reconnect, dictionary, allDictionary, of, }: SSRProviderProps) => import("react/jsx-runtime").JSX.Element;
+declare const SSRProvider: ({ className, appName, params, head, manifest, env, gaTrackingId, children, theme, prefix, fonts, layoutStyle, reconnect, wsConnect, dictionary, allDictionary, of, }: SSRProviderProps) => import("react/jsx-runtime").JSX.Element;
 interface SSRWrapperProps {
     className?: string;
     appName: string;

package/ui/System/CSR.tsx

@@ -45,6 +45,7 @@ const CSRProvider = ({
   fonts,
   layoutStyle = "web",
   reconnect = getEnv().operationMode === "local",
+  wsConnect = true,
   of,
 }: CSRProviderProps) => {
   return (
@@ -72,7 +73,14 @@ const CSRProvider = ({
           </Client.Wrapper>
           <Client.Inner />
           <CSRInner />
-          <Client.Bridge lang={lang} env={env} theme={theme} prefix={prefix} gaTrackingId={gaTrackingId} />
+          <Client.Bridge
+            lang={lang}
+            env={env}
+            theme={theme}
+            prefix={prefix}
+            gaTrackingId={gaTrackingId}
+            wsConnect={wsConnect}
+          />
           <CSRBridge lang={lang} prefix={prefix} />
         </>
       )}

package/ui/System/Client.tsx

@@ -5,6 +5,7 @@ import {
   clsx,
   Device,
   defaultPageState,
+  fetch,
   getPathInfo,
   initAuth,
   type Location,
@@ -152,9 +153,10 @@ interface ClientBridgeProps {
   theme?: AkanTheme;
   prefix?: string;
   gaTrackingId?: string;
+  wsConnect?: boolean;
 }
 
-export const ClientBridge = ({ env, lang, theme, prefix, gaTrackingId }: ClientBridgeProps) => {
+export const ClientBridge = ({ env, lang, theme, prefix, gaTrackingId, wsConnect = true }: ClientBridgeProps) => {
   const uiOperation = st.use.uiOperation();
   const pathname = st.use.pathname();
   const params = st.use.params();
@@ -174,6 +176,11 @@ export const ClientBridge = ({ env, lang, theme, prefix, gaTrackingId }: ClientB
     }, 2000);
   }, []);
 
+  useEffect(() => {
+    if (!wsConnect) return;
+    (fetch.instance as { connect: () => void }).connect();
+  }, [wsConnect]);
+
   useEffect(() => {
     if (getThemeCookie() !== undefined) return;
     applyThemePolicy(theme ?? "system");

package/ui/System/Common.tsx

@@ -30,6 +30,8 @@ export interface ProviderProps {
   layoutStyle?: "mobile" | "web";
   /** Enable reconnect helper. Defaults to local operation mode in CSR. */
   reconnect?: boolean;
+  /** Connect the client WebSocket runtime after the browser loads. */
+  wsConnect?: boolean;
   /** Active-locale dictionary injected by the server (SSR only) to seed the client Translator. */
   dictionary?: Record<string, Record<string, unknown>>;
   /**

package/ui/System/SSR.tsx

@@ -29,6 +29,7 @@ const SSRProvider = ({
   fonts,
   layoutStyle = "web",
   reconnect = getEnv().operationMode === "local",
+  wsConnect = true,
   dictionary,
   allDictionary,
   of,
@@ -65,7 +66,14 @@ const SSRProvider = ({
               <ClientInner />
             </Suspense>
             <Suspense key="client-bridge" fallback={null}>
-              <ClientBridge key="bridge" env={env} theme={theme} prefix={prefix} gaTrackingId={gaTrackingId} />
+              <ClientBridge
+                key="bridge"
+                env={env}
+                theme={theme}
+                prefix={prefix}
+                gaTrackingId={gaTrackingId}
+                wsConnect={wsConnect}
+              />
               <ClientSsrBridge key="ssr-bridge" lang={lang} prefix={prefix} />
             </Suspense>
           </ClientWrapper>

package/webkit/bootCsr.tsx

@@ -293,6 +293,7 @@ function validateRouteModuleExports(key: string, mod: RouteModule) {
             "manifest",
             "theme",
             "reconnect",
+            "wsConnect",
             "layoutStyle",
             "gaTrackingId",
             "Loading",