@nice-code/action 0.4.5 → 0.4.7

package/README.md

@@ -154,7 +154,9 @@ export const clientCoord = RuntimeCoordinate.env("frontend");
 export const serverCoord = RuntimeCoordinate.env("backend");
 
 // Transport definitions are plain, reusable objects you construct once.
-const serverHttp = new HttpTransport({ url: "https://api.example.com/resolve_action" });
+const serverHttp = HttpTransport.create({
+  createRequest: () => ({ url: "https://api.example.com/resolve_action" }),
+});
 
 const serverHandler = new ActionExternalClientHandler({
   runtimeCoordinate: serverCoord,
@@ -218,7 +220,10 @@ function RenameUser() {
 ```ts
 import { WebSocketTransport } from "@nice-code/action";
 
-const serverWs = new WebSocketTransport({ url: "wss://api.example.com/resolve_action/ws" });
+const serverWs = WebSocketTransport.create({
+  createWebSocket: () => new WebSocket("wss://api.example.com/resolve_action/ws"),
+  getTransportCacheKey: () => ["wss://api.example.com/resolve_action/ws"],
+});
 
 const serverHandler = new ActionExternalClientHandler({
   runtimeCoordinate: serverCoord,
@@ -226,12 +231,15 @@ const serverHandler = new ActionExternalClientHandler({
 }).forDomain(userDomain);
 ```
 
-The socket is opened lazily and reused across actions to the same endpoint. Multiple transports can
-be registered; the runtime picks the best available one (WebSocket preferred for lower latency, HTTP
-as fallback). For channels nice-action doesn't model natively, use `CustomTransport`.
+The socket is opened lazily and reused across actions sharing a `getTransportCacheKey`. Multiple
+transports can be registered; the runtime picks the best available one (WebSocket preferred for lower
+latency, HTTP as fallback). For channels nice-action doesn't model natively, use `CustomTransport`.
 
-For advanced cases, `HttpTransport` / `WebSocketTransport` accept functions to derive the URL or
-headers per action (e.g. `new HttpTransport({ url: (input) => \`/api/${input.action.id}\` })`).
+Each transport takes a single creation function so you decide how simple or complex it should be —
+derive the request per action straight from the params (e.g.
+`HttpTransport.create({ createRequest: (input) => ({ url: \`/api/${input.action.id}\` }) })`). For full
+control over readiness (support detection, async init), `WebSocketTransport` / `CustomTransport` also
+offer `.createAdvanced({ getTransport })`.
 
 ---
 

package/build/devtools/browser/index.js

@@ -4502,6 +4502,7 @@ var ActionInputAndOutputChip = ({
 
 // src/devtools/browser/components/action_list/ActionEntryRow.tsx
 import { jsxDEV as jsxDEV19, Fragment as Fragment10 } from "react/jsx-dev-runtime";
+var MAX_GROUP_DOTS = 5;
 function getLatestChipColor(status) {
   if (status === "failed")
     return "failed" /* failed */;
@@ -4822,15 +4823,29 @@ function ActionEntryRow({
           paddingLeft: "4.6em",
           paddingBottom: "2px"
         },
-        children: groupEntries.map((e, i) => /* @__PURE__ */ jsxDEV19(GroupDot, {
-          entry: e,
-          index: i,
-          total: groupEntries.length,
-          refTime: groupEntries[0].startTime,
-          isActive: selectedGroupCuid === e.cuid,
-          onSelect: () => onSelectGroupEntry?.(e.cuid)
-        }, e.cuid, false, undefined, this))
-      }, undefined, false, undefined, this)
+        children: [
+          groupEntries.slice(0, MAX_GROUP_DOTS).map((e, i) => /* @__PURE__ */ jsxDEV19(GroupDot, {
+            entry: e,
+            index: i,
+            total: groupEntries.length,
+            refTime: groupEntries[0].startTime,
+            isActive: selectedGroupCuid === e.cuid,
+            onSelect: () => onSelectGroupEntry?.(e.cuid)
+          }, e.cuid, false, undefined, this)),
+          groupEntries.length > MAX_GROUP_DOTS && /* @__PURE__ */ jsxDEV19("span", {
+            style: {
+              fontSize: "0.7em",
+              opacity: 0.5,
+              flexShrink: 0,
+              lineHeight: 1
+            },
+            children: [
+              "+ ",
+              groupEntries.length - MAX_GROUP_DOTS
+            ]
+          }, undefined, true, undefined, this)
+        ]
+      }, undefined, true, undefined, this)
     ]
   }, undefined, true, undefined, this);
 }

package/build/index.js

@@ -1993,7 +1993,7 @@ class ActionExternalClientHandler extends ActionHandler {
       client: this.externalClient,
       transOrd: transport.transOrd,
       transType: transport.type,
-      transInfo: transport.definition?.getRouteInfo(input)
+      transInfo: transport.getRouteInfo(input)
     };
   }
   clearTransportCache() {
@@ -2053,6 +2053,9 @@ class TransportConnection {
     this.type = def.type;
     this.initialized = def.initialize();
   }
+  getRouteInfo(input) {
+    return this.definition?.getRouteInfo(input);
+  }
   _getCacheKey(input) {
     const parts = this.initialized.getTransportCacheKey?.(input);
     if (parts == null)
@@ -2121,20 +2124,32 @@ class CustomTransport extends Transport {
     super();
     this.options = options;
   }
+  static create(options) {
+    return new CustomTransport({ ...options, mode: "send" });
+  }
+  static createAdvanced(options) {
+    return new CustomTransport({ ...options, mode: "advanced" });
+  }
   _createConnection(_ctx) {
     const options = this.options;
+    let getTransport;
+    if (options.mode === "advanced") {
+      getTransport = options.getTransport;
+    } else {
+      getTransport = () => ({
+        status: "ready" /* ready */,
+        readyData: {
+          sendActionData: options.sendActionData,
+          sendReturnData: options.sendReturnData,
+          updateRunConfig: options.updateRunConfig,
+          closeTransport: options.closeTransport ?? (() => {})
+        }
+      });
+    }
     return new CustomConnection({
       initialize: () => ({
         getTransportCacheKey: options.getTransportCacheKey,
-        getTransport: options.getTransport ?? (() => ({
-          status: "ready" /* ready */,
-          readyData: {
-            sendActionData: options.sendActionData,
-            sendReturnData: options.sendReturnData,
-            updateRunConfig: options.updateRunConfig,
-            closeTransport: options.closeTransport ?? (() => {})
-          }
-        }))
+        getTransport
       })
     });
   }
@@ -2282,9 +2297,6 @@ class HttpConnection extends TransportConnection {
 }
 
 // src/ActionRuntime/Handler/ExternalClient/Transport/Http/HttpTransport.ts
-function resolveMaybe(value, input) {
-  return typeof value === "function" ? value(input) : value;
-}
 function shortPath(url) {
   try {
     return new URL(url).pathname || url;
@@ -2300,13 +2312,8 @@ class HttpTransport extends Transport {
     super();
     this.options = options;
   }
-  _resolveRequest(input) {
-    if (this.options.createRequest != null)
-      return this.options.createRequest(input);
-    return {
-      url: resolveMaybe(this.options.url, input),
-      headers: this.options.headers != null ? resolveMaybe(this.options.headers, input) : undefined
-    };
+  static create(options) {
+    return new HttpTransport(options);
   }
   _createConnection(_ctx) {
     return new HttpConnection({
@@ -2315,7 +2322,7 @@ class HttpTransport extends Transport {
         getTransport: () => ({
           status: "ready" /* ready */,
           readyData: {
-            createRequest: (input) => this._resolveRequest(input),
+            createRequest: this.options.createRequest,
             updateRunConfig: this.options.updateRunConfig
           }
         })
@@ -2323,7 +2330,7 @@ class HttpTransport extends Transport {
     });
   }
   getRouteInfo(input) {
-    const { url } = this._resolveRequest(input);
+    const { url } = this.options.createRequest(input);
     return {
       type: "http" /* http */,
       method: "POST",
@@ -2339,10 +2346,21 @@ var createUnsetTransportResolvers = (type) => ({
   }
 });
 
+// src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/ws_util.ts
+function shortWs(url) {
+  try {
+    const u = new URL(url);
+    return `${u.host}${u.pathname}`;
+  } catch {
+    return url;
+  }
+}
+
 // src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/WebSocketConnection.ts
 class WebSocketConnection extends TransportConnection {
   resolvers;
   _abortSet = new Set;
+  _liveSocketUrl;
   constructor(def, resolvers) {
     super({ ...def, type: "ws" /* ws */ });
     this.resolvers = resolvers ?? createUnsetTransportResolvers("ws" /* ws */);
@@ -2403,9 +2421,22 @@ class WebSocketConnection extends TransportConnection {
       readyData: this._finalizeTransportMethods(transportStatusInfo.readyData)
     };
   }
+  getRouteInfo(input) {
+    const base = this.definition?.getRouteInfo(input);
+    if (base?.url != null || this._liveSocketUrl == null)
+      return base;
+    return {
+      type: "ws" /* ws */,
+      ...base,
+      url: this._liveSocketUrl,
+      summary: `ws ${shortWs(this._liveSocketUrl)}`
+    };
+  }
   _finalizeTransportMethods(wsData) {
     const ws = wsData.ws;
     const disconnectListeners = [];
+    if (ws.url != null && ws.url !== "")
+      this._liveSocketUrl = ws.url;
     const sendActionData = (inputs) => {
       const { action, runningAction, timeout } = inputs;
       if (action.type === "request" /* request */) {
@@ -2475,18 +2506,6 @@ class WebSocketConnection extends TransportConnection {
 }
 
 // src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/WebSocketTransport.ts
-function resolveMaybe2(value, input) {
-  return typeof value === "function" ? value(input) : value;
-}
-function shortWs(url) {
-  try {
-    const u = new URL(url);
-    return `${u.host}${u.pathname}`;
-  } catch {
-    return url;
-  }
-}
-
 class WebSocketTransport extends Transport {
   options;
   type = "ws" /* ws */;
@@ -2494,32 +2513,40 @@ class WebSocketTransport extends Transport {
     super();
     this.options = options;
   }
-  _createSocket(input) {
-    if (this.options.createWebSocket != null)
-      return this.options.createWebSocket(input);
-    return new WebSocket(resolveMaybe2(this.options.url, input));
+  static create(options) {
+    return new WebSocketTransport({ ...options, mode: "socket" });
+  }
+  static createAdvanced(options) {
+    return new WebSocketTransport({ ...options, mode: "advanced" });
   }
   _createConnection(ctx) {
+    const options = this.options;
+    let getTransport;
+    if (options.mode === "advanced") {
+      getTransport = options.getTransport;
+    } else {
+      getTransport = (input) => ({
+        status: "ready" /* ready */,
+        readyData: {
+          ws: options.createWebSocket(input),
+          formatMessage: options.formatMessage,
+          updateRunConfig: options.updateRunConfig
+        }
+      });
+    }
     return new WebSocketConnection({
       initialize: () => ({
-        getTransportCacheKey: this.options.getTransportCacheKey ?? ((input) => [resolveMaybe2(this.options.url, input)]),
-        getTransport: (input) => ({
-          status: "ready" /* ready */,
-          readyData: {
-            ws: this._createSocket(input),
-            formatMessage: this.options.formatMessage,
-            updateRunConfig: this.options.updateRunConfig
-          }
-        })
+        getTransportCacheKey: options.getTransportCacheKey,
+        getTransport
       })
     }, ctx.resolvers);
   }
   getRouteInfo(input) {
-    const url = resolveMaybe2(this.options.url, input);
+    if (this.options.getRouteInfo != null)
+      return this.options.getRouteInfo(input);
     return {
       type: "ws" /* ws */,
-      url,
-      summary: `ws ${shortWs(url)}`
+      summary: "ws"
     };
   }
 }

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/Custom/CustomConnection.d.ts

@@ -1,5 +1,5 @@
-import { TransportConnection } from "../TransportConnection";
 import { ETransportType, type IActionTransportReadyData_Methods, type ITransportRouteActionParams } from "../Transport.types";
+import { TransportConnection } from "../TransportConnection";
 import type { IActionTransportDef_Custom, IActionTransportInitialized_Custom, IActionTransportReadyData_Custom, TActionTransportDef_Custom_NoType } from "./TransportCustom.types";
 export declare class CustomConnection extends TransportConnection<ETransportType.custom, ITransportRouteActionParams, IActionTransportReadyData_Custom, IActionTransportInitialized_Custom, IActionTransportDef_Custom> {
     constructor(def: TActionTransportDef_Custom_NoType);

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/Custom/CustomTransport.d.ts

@@ -1,33 +1,43 @@
-import { Transport, type ITransportConnectionContext } from "../Transport";
+import { type ITransportConnectionContext, Transport } from "../Transport";
 import { ETransportType, type ITransportMethod_SendActionData_Input, type ITransportRouteActionParams, type ITransportRouteInfo, type TSendReturnDataMethod, type TUpdateActionRunConfig } from "../Transport.types";
 import { CustomConnection } from "./CustomConnection";
 import type { IActionTransportInitialized_Custom } from "./TransportCustom.types";
-export interface ICustomTransportOptions {
-    /** Send a request/progress payload to the external client. */
-    sendActionData: (input: ITransportMethod_SendActionData_Input) => void;
-    /** Optional return-path dispatch for bidirectional channels. */
-    sendReturnData?: TSendReturnDataMethod;
-    closeTransport?: (input?: ITransportRouteActionParams) => void;
+interface ICustomTransportSharedOptions {
     updateRunConfig?: TUpdateActionRunConfig;
     getTransportCacheKey?: (input: ITransportRouteActionParams) => string[];
-    /**
-     * Advanced escape hatch — full control over readiness/initialization. When provided, the simple
-     * `sendActionData` / `sendReturnData` / `closeTransport` fields are ignored.
-     */
-    getTransport?: IActionTransportInitialized_Custom["getTransport"];
     /** Short label shown in the devtools chip (defaults to "custom"). */
     label?: string;
     /** Override the devtools route info for a specific action. */
     getRouteInfo?: (input: ITransportRouteActionParams) => ITransportRouteInfo;
 }
+export interface ICustomTransportSendOptions extends ICustomTransportSharedOptions {
+    /** Send a request/progress payload to the external client. */
+    sendActionData: (input: ITransportMethod_SendActionData_Input) => void;
+    /** Optional return-path dispatch for bidirectional channels. */
+    sendReturnData?: TSendReturnDataMethod;
+    closeTransport?: (input?: ITransportRouteActionParams) => void;
+}
+export interface ICustomTransportAdvancedOptions extends ICustomTransportSharedOptions {
+    /** Full control over readiness/initialization for the custom channel. */
+    getTransport: IActionTransportInitialized_Custom["getTransport"];
+}
+export type TCustomTransportOptions = (ICustomTransportSendOptions & {
+    mode: "send";
+}) | (ICustomTransportAdvancedOptions & {
+    mode: "advanced";
+});
 /**
- * Reusable custom transport definition for channels nice-action doesn't model natively. Provide
- * `sendActionData` for the simple case, or `getTransport` for full control over the lifecycle.
+ * Reusable custom transport definition for channels nice-action doesn't model natively. Create one
+ * with `CustomTransport.create({ sendActionData })` for the simple case, or
+ * `CustomTransport.createAdvanced({ getTransport })` for full control over the lifecycle.
  */
 export declare class CustomTransport extends Transport<ETransportType.custom> {
     private readonly options;
     readonly type = ETransportType.custom;
-    constructor(options: ICustomTransportOptions);
+    constructor(options: TCustomTransportOptions);
+    static create(options: ICustomTransportSendOptions): CustomTransport;
+    static createAdvanced(options: ICustomTransportAdvancedOptions): CustomTransport;
     _createConnection(_ctx: ITransportConnectionContext): CustomConnection;
     getRouteInfo(input: ITransportRouteActionParams): ITransportRouteInfo;
 }
+export {};

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/Http/HttpConnection.d.ts

@@ -1,5 +1,5 @@
-import { TransportConnection } from "../TransportConnection";
 import { ETransportType, type IActionTransportReadyData_Methods, type ITransportDispatchAction, type ITransportRouteActionParams } from "../Transport.types";
+import { TransportConnection } from "../TransportConnection";
 import type { IActionTransportDef_Http, IActionTransportInitialized_Http, IActionTransportReadyData_Http, IActionTransportReadyParams_Http } from "./TransportHttp.types";
 export declare class HttpConnection extends TransportConnection<ETransportType.http, ITransportRouteActionParams, IActionTransportReadyData_Http, IActionTransportInitialized_Http, IActionTransportDef_Http> {
     constructor(def: Omit<IActionTransportDef_Http, "type">);

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/Http/HttpTransport.d.ts

@@ -1,28 +1,26 @@
-import { Transport, type ITransportConnectionContext } from "../Transport";
+import { type ITransportConnectionContext, Transport } from "../Transport";
 import { ETransportType, type ITransportRouteActionParams, type ITransportRouteInfo, type TUpdateActionRunConfig } from "../Transport.types";
 import { HttpConnection } from "./HttpConnection";
 import type { IHttpRequestParams } from "./TransportHttp.types";
-type TMaybeResolved<T> = T | ((input: ITransportRouteActionParams) => T);
 export interface IHttpTransportOptions {
-    /** Endpoint URL, either static or derived per action. */
-    url: TMaybeResolved<string>;
-    /** Optional extra headers, either static or derived per action. */
-    headers?: TMaybeResolved<Record<string, string>>;
-    /** Advanced escape hatch — full control over the request. Overrides `url` / `headers`. */
-    createRequest?: (input: ITransportRouteActionParams) => IHttpRequestParams;
+    /**
+     * Build the HTTP request for an action. Return a static request for the simple case, or derive the
+     * url / headers / body from the action params for full control.
+     */
+    createRequest: (input: ITransportRouteActionParams) => IHttpRequestParams;
     updateRunConfig?: TUpdateActionRunConfig;
     getTransportCacheKey?: (input: ITransportRouteActionParams) => string[];
 }
 /**
- * Reusable HTTP transport definition. Common case is just `new HttpTransport({ url })`; pass
- * functions for `url` / `headers` to derive them per action, or `createRequest` for full control.
+ * Reusable HTTP transport definition. Create one with `HttpTransport.create({ createRequest })` — the
+ * single `createRequest` function lets you keep it simple (`() => ({ url })`) or derive the request
+ * per action.
  */
 export declare class HttpTransport extends Transport<ETransportType.http> {
     private readonly options;
     readonly type = ETransportType.http;
     constructor(options: IHttpTransportOptions);
-    private _resolveRequest;
+    static create(options: IHttpTransportOptions): HttpTransport;
     _createConnection(_ctx: ITransportConnectionContext): HttpConnection;
     getRouteInfo(input: ITransportRouteActionParams): ITransportRouteInfo;
 }
-export {};

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/Transport.d.ts

@@ -9,8 +9,9 @@ export interface ITransportConnectionContext {
     resolvers?: IActionTransportResolvers;
 }
 /**
- * Reusable transport definition. Devs construct these (`new HttpTransport({ url })`,
- * `new WebSocketTransport({ url })`, …) and pass them to an `ActionExternalClientHandler`. A single
+ * Reusable transport definition. Devs construct these (`HttpTransport.create({ createRequest })`,
+ * `WebSocketTransport.create({ createWebSocket })`, …) and pass them to an
+ * `ActionExternalClientHandler`. A single
  * definition can be shared across multiple handlers — each handler builds its own live
  * {@link TransportConnection} via {@link TransportConnection._createConnection}.
  */

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/TransportConnection.d.ts

@@ -1,5 +1,5 @@
 import type { Transport } from "./Transport";
-import { type ETransportType, type IActionTransportDef, type IActionTransportInitialized, type IActionTransportReadyData_Base, type IActionTransportReadyData_Methods, type ITransportRouteActionParams, type TTransportStatusInfo } from "./Transport.types";
+import { type ETransportType, type IActionTransportDef, type IActionTransportInitialized, type IActionTransportReadyData_Base, type IActionTransportReadyData_Methods, type ITransportRouteActionParams, type ITransportRouteInfo, type TTransportStatusInfo } from "./Transport.types";
 /**
  * Live, per-handler transport runtime built from a reusable {@link Transport} definition. Holds the
  * connection-scoped state (ordinal, initialized config, sockets / abort sets) that must not be shared
@@ -13,6 +13,12 @@ export declare abstract class TransportConnection<T extends ETransportType = ETr
     /** Backref to the public definition that created this connection (used for devtools route info). */
     definition?: Transport<T>;
     constructor(def: DEF);
+    /**
+     * Devtools route info for an action routed through this live connection. Defaults to the stateless
+     * {@link definition}'s info; connections override to enrich it from live state (e.g. the actual
+     * resolved socket URL) when the definition couldn't resolve it on its own.
+     */
+    getRouteInfo(input: RP): ITransportRouteInfo | undefined;
     protected abstract _finalizeTransportMethods(inputs: RD): IActionTransportReadyData_Methods;
     protected _getCacheKey(input: RP): string | null;
     getCacheKey(input: RP): string | null;

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/WebSocketConnection.d.ts

@@ -1,12 +1,15 @@
+import { ETransportType, type IActionTransportReadyData_Methods, type IActionTransportResolvers, type ITransportRouteActionParams, type ITransportRouteInfo, type TTransportStatusInfo } from "../Transport.types";
 import { TransportConnection } from "../TransportConnection";
-import { ETransportType, type IActionTransportReadyData_Methods, type IActionTransportResolvers, type ITransportRouteActionParams, type TTransportStatusInfo } from "../Transport.types";
 import type { IActionTransportDef_Ws, IActionTransportInitialized_Ws, IActionTransportReadyData_Ws } from "./TransportWebSocket.types";
 export declare class WebSocketConnection extends TransportConnection<ETransportType.ws, ITransportRouteActionParams, IActionTransportReadyData_Ws, IActionTransportInitialized_Ws, IActionTransportDef_Ws> {
     private resolvers;
     private _abortSet;
+    /** URL of the most recently resolved live socket — surfaced to devtools when the definition can't. */
+    private _liveSocketUrl?;
     constructor(def: Omit<IActionTransportDef_Ws, "type">, resolvers?: IActionTransportResolvers);
     protected _getCacheKey(_input: ITransportRouteActionParams): string;
     protected _processTransportStatus(input: ITransportRouteActionParams): TTransportStatusInfo<IActionTransportReadyData_Methods>;
+    getRouteInfo(input: ITransportRouteActionParams): ITransportRouteInfo | undefined;
     _finalizeTransportMethods(wsData: IActionTransportReadyData_Ws): IActionTransportReadyData_Methods;
     private _parseActionMessage;
     private _abortAll;

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/WebSocketTransport.d.ts

@@ -1,31 +1,48 @@
-import { Transport, type ITransportConnectionContext } from "../Transport";
+import { type ITransportConnectionContext, Transport } from "../Transport";
 import { ETransportType, type ITransportRouteActionParams, type ITransportRouteInfo, type TUpdateActionRunConfig } from "../Transport.types";
-import type { IActionTransportReadyData_Ws } from "./TransportWebSocket.types";
+import type { IActionTransportInitialized_Ws, IActionTransportReadyData_Ws } from "./TransportWebSocket.types";
 import { WebSocketConnection } from "./WebSocketConnection";
-type TMaybeResolved<T> = T | ((input: ITransportRouteActionParams) => T);
-export interface IWebSocketTransportOptions {
-    /** WebSocket endpoint URL, either static or derived per action. */
-    url: TMaybeResolved<string>;
-    /** Advanced escape hatch — provide your own socket (e.g. with sub-protocols). Overrides `url`. */
-    createWebSocket?: (input: ITransportRouteActionParams) => WebSocket;
+interface IWebSocketTransportSharedOptions {
     /** Custom (de)serialization of action payloads on the wire. */
     formatMessage?: IActionTransportReadyData_Ws["formatMessage"];
     updateRunConfig?: TUpdateActionRunConfig;
     /**
-     * Keys that identify a reusable socket. Defaults to the resolved url, so a single socket is shared
-     * across actions to the same endpoint instead of opening one per action.
+     * Keys that identify a reusable socket, so a single socket is shared across actions to the same
+     * endpoint instead of opening one per action.
      */
     getTransportCacheKey?: (input: ITransportRouteActionParams) => string[];
+    /** Override the devtools route info for a specific action. */
+    getRouteInfo?: (input: ITransportRouteActionParams) => ITransportRouteInfo;
 }
+export interface IWebSocketTransportSocketOptions extends IWebSocketTransportSharedOptions {
+    /** Open (or reuse) the WebSocket for an action — keep it simple or derive it per action. */
+    createWebSocket: (input: ITransportRouteActionParams) => WebSocket;
+}
+export interface IWebSocketTransportAdvancedOptions extends IWebSocketTransportSharedOptions {
+    /**
+     * Full control over readiness/initialization. Use this for contextual support detection (return
+     * `{ status: ETransportStatus.unsupported }` when the socket shouldn't be used) or async url
+     * building (return `{ status: ETransportStatus.initializing, initializationPromise }` that resolves
+     * to a `ready` socket).
+     */
+    getTransport: IActionTransportInitialized_Ws["getTransport"];
+}
+export type TWebSocketTransportOptions = (IWebSocketTransportSocketOptions & {
+    mode: "socket";
+}) | (IWebSocketTransportAdvancedOptions & {
+    mode: "advanced";
+});
 /**
- * Reusable WebSocket transport definition. Common case is just `new WebSocketTransport({ url })`. The
- * underlying socket is cached (by url, by default) and reused across actions to the same endpoint.
+ * Reusable WebSocket transport definition. Create one with `WebSocketTransport.create({ createWebSocket })`
+ * for the common case, or `WebSocketTransport.createAdvanced({ getTransport })` for full control over
+ * readiness. The underlying socket is cached (via `getTransportCacheKey`) and reused across actions.
  */
 export declare class WebSocketTransport extends Transport<ETransportType.ws> {
     private readonly options;
     readonly type = ETransportType.ws;
-    constructor(options: IWebSocketTransportOptions);
-    private _createSocket;
+    constructor(options: TWebSocketTransportOptions);
+    static create(options: IWebSocketTransportSocketOptions): WebSocketTransport;
+    static createAdvanced(options: IWebSocketTransportAdvancedOptions): WebSocketTransport;
     _createConnection(ctx: ITransportConnectionContext): WebSocketConnection;
     getRouteInfo(input: ITransportRouteActionParams): ITransportRouteInfo;
 }

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/ws_util.d.ts

@@ -0,0 +1,2 @@
+/** Compact a WebSocket URL to `host/pathname` for devtools display, falling back to the raw url. */
+export declare function shortWs(url: string): string;

package/build/types/index.d.ts

@@ -22,7 +22,7 @@ export * from "./ActionRuntime/Handler/ExternalClient/Transport/err_nice_transpo
 export { HttpTransport, type IHttpTransportOptions, } from "./ActionRuntime/Handler/ExternalClient/Transport/Http/HttpTransport";
 export { type ITransportConnectionContext, Transport, } from "./ActionRuntime/Handler/ExternalClient/Transport/Transport";
 export * from "./ActionRuntime/Handler/ExternalClient/Transport/Transport.types";
-export { type IWebSocketTransportOptions, WebSocketTransport, } from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/WebSocketTransport";
+export { type IWebSocketTransportAdvancedOptions, type IWebSocketTransportSocketOptions, type TWebSocketTransportOptions, WebSocketTransport, } from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/WebSocketTransport";
 export { ActionLocalHandler, createLocalHandler, } from "./ActionRuntime/Handler/Local/ActionLocalHandler";
 export * from "./ActionRuntime/RuntimeCoordinate";
 export { EErrId_NiceAction, err_nice_action } from "./errors/err_nice_action";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nice-code/action",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "private": false,
   "type": "module",
   "exports": {
@@ -44,9 +44,9 @@
     "build-types": "tsc --project tsconfig.build.json"
   },
   "dependencies": {
-    "@nice-code/common-errors": "0.4.5",
-    "@nice-code/error": "0.4.5",
-    "@nice-code/util": "0.4.5",
+    "@nice-code/common-errors": "0.4.7",
+    "@nice-code/error": "0.4.7",
+    "@nice-code/util": "0.4.7",
     "@standard-schema/spec": "^1.1.0",
     "@tanstack/react-virtual": "^3.13.26",
     "http-status-codes": "^2.3.0",