@fuzdev/fuz_app 0.26.0 → 0.28.0

package/dist/actions/register_action_ws.d.ts

@@ -1,5 +1,11 @@
 /**
- * WebSocket JSON-RPC dispatch — the canonical WS transport binding.
+ * WebSocket JSON-RPC dispatch — the low-level WS transport binding.
+ *
+ * Most consumers should mount WS endpoints via `register_ws_endpoint`
+ * (`./register_ws_endpoint.js`), which wraps this function with the standard
+ * upgrade stack (origin check + auth + optional role). This module stays
+ * exported as the lower-level entry point for tests that drive the
+ * dispatcher directly via `create_ws_test_harness`.
  *
  * Symmetric to `create_rpc_endpoint` (from `actions/action_rpc.ts`):
  * consumer supplies action specs + a handler map, the dispatcher parses the
@@ -15,9 +21,10 @@
  * ## Auth expectations
  *
  * The consumer is responsible for rejecting unauthenticated upgrades *before*
- * routing to this handler (fuz_app's `require_auth` middleware). Inside the
- * dispatcher, `get_request_context(c)` is treated as guaranteed non-null and
- * per-action auth is enforced on each message.
+ * routing to this handler (fuz_app's `require_auth` middleware, or
+ * `register_ws_endpoint` which wires it for you). Inside the dispatcher,
+ * `get_request_context(c)` is treated as guaranteed non-null and per-action
+ * auth is enforced on each message.
  *
  * @module
  */

package/dist/actions/register_action_ws.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register_action_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_action_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,KAAK,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,MAAM,CAAC;AACxC,OAAO,KAAK,EAAC,gBAAgB,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AAEzD,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAgB1E,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,YAAY,CAAC;AAErC,OAAO,EAAC,KAAK,MAAM,EAAE,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAC,MAAM,mBAAmB,CAAC;AAG7F,OAAO,EAAC,yBAAyB,EAAE,KAAK,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AAE9F,YAAY,EAAC,MAAM,EAAE,kBAAkB,EAAE,eAAe,EAAC,CAAC;AAE1D,0EAA0E;AAC1E,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC,qFAAqF;IACrF,EAAE,EAAE,SAAS,CAAC;IACd,4EAA4E;IAC5E,aAAa,EAAE,IAAI,CAAC;IACpB,oDAAoD;IACpD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;OAGG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,wFAAwF;IACxF,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,EAAE,EAAE,SAAS,CAAC;IACd,2CAA2C;IAC3C,aAAa,EAAE,IAAI,CAAC;IACpB,kGAAkG;IAClG,QAAQ,EAAE,kBAAkB,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACtC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,uBAAuB,CAAC,IAAI,SAAS,kBAAkB;IACvE,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,GAAG,EAAE,IAAI,CAAC;IACV,iEAAiE;IACjE,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;;;;OAMG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACrC;;;;;OAKG;IACH,cAAc,EAAE,CAAC,IAAI,EAAE,kBAAkB,EAAE,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/D;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACtC,yEAAyE;IACzE,SAAS,EAAE,yBAAyB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,GAAI,IAAI,SAAS,kBAAkB,EACjE,SAAS,uBAAuB,CAAC,IAAI,CAAC,KACpC,sBA8WF,CAAC"}
+{"version":3,"file":"register_action_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_action_ws.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAC,OAAO,EAAE,IAAI,EAAC,MAAM,MAAM,CAAC;AACxC,OAAO,KAAK,EAAC,gBAAgB,EAAE,SAAS,EAAC,MAAM,SAAS,CAAC;AAEzD,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAgB1E,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,YAAY,CAAC;AAErC,OAAO,EAAC,KAAK,MAAM,EAAE,KAAK,kBAAkB,EAAE,KAAK,eAAe,EAAC,MAAM,mBAAmB,CAAC;AAG7F,OAAO,EAAC,yBAAyB,EAAE,KAAK,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AAE9F,YAAY,EAAC,MAAM,EAAE,kBAAkB,EAAE,eAAe,EAAC,CAAC;AAE1D,0EAA0E;AAC1E,eAAO,MAAM,gCAAgC,QAAS,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IACjC,qFAAqF;IACrF,EAAE,EAAE,SAAS,CAAC;IACd,4EAA4E;IAC5E,aAAa,EAAE,IAAI,CAAC;IACpB,oDAAoD;IACpD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B;;;OAGG;IACH,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,wFAAwF;IACxF,MAAM,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,EAAE,EAAE,SAAS,CAAC;IACd,2CAA2C;IAC3C,aAAa,EAAE,IAAI,CAAC;IACpB,kGAAkG;IAClG,QAAQ,EAAE,kBAAkB,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACtC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,uBAAuB,CAAC,IAAI,SAAS,kBAAkB;IACvE,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,GAAG,EAAE,IAAI,CAAC;IACV,iEAAiE;IACjE,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;;;;OAMG;IACH,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACrC;;;;;OAKG;IACH,cAAc,EAAE,CAAC,IAAI,EAAE,kBAAkB,EAAE,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/D;;;;OAIG;IACH,SAAS,CAAC,EAAE,yBAAyB,CAAC;IACtC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,sBAAsB,CAAC;IAC7C,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,GAAG,CAAC,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED,sCAAsC;AACtC,MAAM,WAAW,sBAAsB;IACtC,yEAAyE;IACzE,SAAS,EAAE,yBAAyB,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,GAAI,IAAI,SAAS,kBAAkB,EACjE,SAAS,uBAAuB,CAAC,IAAI,CAAC,KACpC,sBA8WF,CAAC"}

package/dist/actions/register_action_ws.js

@@ -1,5 +1,11 @@
 /**
- * WebSocket JSON-RPC dispatch — the canonical WS transport binding.
+ * WebSocket JSON-RPC dispatch — the low-level WS transport binding.
+ *
+ * Most consumers should mount WS endpoints via `register_ws_endpoint`
+ * (`./register_ws_endpoint.js`), which wraps this function with the standard
+ * upgrade stack (origin check + auth + optional role). This module stays
+ * exported as the lower-level entry point for tests that drive the
+ * dispatcher directly via `create_ws_test_harness`.
  *
  * Symmetric to `create_rpc_endpoint` (from `actions/action_rpc.ts`):
  * consumer supplies action specs + a handler map, the dispatcher parses the
@@ -15,9 +21,10 @@
  * ## Auth expectations
  *
  * The consumer is responsible for rejecting unauthenticated upgrades *before*
- * routing to this handler (fuz_app's `require_auth` middleware). Inside the
- * dispatcher, `get_request_context(c)` is treated as guaranteed non-null and
- * per-action auth is enforced on each message.
+ * routing to this handler (fuz_app's `require_auth` middleware, or
+ * `register_ws_endpoint` which wires it for you). Inside the dispatcher,
+ * `get_request_context(c)` is treated as guaranteed non-null and per-action
+ * auth is enforced on each message.
  *
  * @module
  */

package/dist/actions/register_ws_endpoint.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Composed WebSocket endpoint registration — the idiomatic consumer entry
+ * point for mounting a fuz_app WS endpoint.
+ *
+ * Wraps the standard upgrade stack every consumer writes by hand:
+ *
+ * 1. `verify_request_source(allowed_origins)` — reject disallowed origins
+ *    before the upgrade handshake runs.
+ * 2. `require_auth` — reject unauthenticated upgrades.
+ * 3. Optional `require_role(required_role)` — for endpoints gated to a
+ *    specific role.
+ *
+ * Then delegates to {@link register_action_ws} for per-message JSON-RPC
+ * dispatch.
+ *
+ * @module
+ */
+import type { RoleName } from '../auth/role_schema.js';
+import { type RegisterActionWsOptions, type RegisterActionWsResult } from './register_action_ws.js';
+import type { BaseHandlerContext } from './action_types.js';
+/** Options for {@link register_ws_endpoint}. */
+export interface RegisterWsEndpointOptions<TCtx extends BaseHandlerContext> extends RegisterActionWsOptions<TCtx> {
+    /**
+     * Origin allowlist regexes — typically parsed from the `ALLOWED_ORIGINS`
+     * env var via `parse_allowed_origins`. Passed straight to
+     * `verify_request_source`.
+     */
+    allowed_origins: Array<RegExp>;
+    /**
+     * Role required to upgrade. Omit for any authenticated account (`require_auth`
+     * alone); set to e.g. `ROLE_ADMIN` to gate the endpoint behind a role. The
+     * per-action `auth` in each spec still applies at dispatch time — this is
+     * a coarse upgrade-time gate.
+     */
+    required_role?: RoleName;
+}
+/**
+ * Mount a WebSocket endpoint with the standard upgrade stack (origin check
+ * + auth + optional role) and JSON-RPC dispatch.
+ *
+ * Returns the {@link BackendWebsocketTransport} (supplied or freshly
+ * created), same as {@link register_action_ws} — retain it to wire
+ * `create_ws_auth_guard` on `on_audit_event` or to broadcast.
+ */
+export declare const register_ws_endpoint: <TCtx extends BaseHandlerContext>(options: RegisterWsEndpointOptions<TCtx>) => RegisterActionWsResult;
+//# sourceMappingURL=register_ws_endpoint.d.ts.map

package/dist/actions/register_ws_endpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register_ws_endpoint.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/register_ws_endpoint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAEN,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,mBAAmB,CAAC;AAE1D,gDAAgD;AAChD,MAAM,WAAW,yBAAyB,CACzC,IAAI,SAAS,kBAAkB,CAC9B,SAAQ,uBAAuB,CAAC,IAAI,CAAC;IACtC;;;;OAIG;IACH,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,QAAQ,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,SAAS,kBAAkB,EACnE,SAAS,yBAAyB,CAAC,IAAI,CAAC,KACtC,sBAUF,CAAC"}

package/dist/actions/register_ws_endpoint.js

@@ -0,0 +1,38 @@
+/**
+ * Composed WebSocket endpoint registration — the idiomatic consumer entry
+ * point for mounting a fuz_app WS endpoint.
+ *
+ * Wraps the standard upgrade stack every consumer writes by hand:
+ *
+ * 1. `verify_request_source(allowed_origins)` — reject disallowed origins
+ *    before the upgrade handshake runs.
+ * 2. `require_auth` — reject unauthenticated upgrades.
+ * 3. Optional `require_role(required_role)` — for endpoints gated to a
+ *    specific role.
+ *
+ * Then delegates to {@link register_action_ws} for per-message JSON-RPC
+ * dispatch.
+ *
+ * @module
+ */
+import { Logger } from '@fuzdev/fuz_util/log.js';
+import { require_auth, require_role } from '../auth/request_context.js';
+import { verify_request_source } from '../http/origin.js';
+import { register_action_ws, } from './register_action_ws.js';
+/**
+ * Mount a WebSocket endpoint with the standard upgrade stack (origin check
+ * + auth + optional role) and JSON-RPC dispatch.
+ *
+ * Returns the {@link BackendWebsocketTransport} (supplied or freshly
+ * created), same as {@link register_action_ws} — retain it to wire
+ * `create_ws_auth_guard` on `on_audit_event` or to broadcast.
+ */
+export const register_ws_endpoint = (options) => {
+    const { app, path, allowed_origins, required_role, log = new Logger('[ws]'), ...rest } = options;
+    app.use(path, verify_request_source(allowed_origins));
+    app.use(path, require_auth);
+    if (required_role !== undefined) {
+        app.use(path, require_role(required_role));
+    }
+    return register_action_ws({ app, path, log, ...rest });
+};

package/dist/actions/socket.svelte.d.ts

@@ -24,6 +24,7 @@
  * @module
  */
 import type { Logger } from '@fuzdev/fuz_util/log.js';
+import type { AsyncStatus } from '@fuzdev/fuz_util/async.js';
 import { type JsonrpcRequestId } from '../http/jsonrpc.js';
 import type { WebsocketConnection } from './transports_ws.js';
 /** Default WebSocket close code (normal closure). */
@@ -91,11 +92,11 @@ export interface FrontendWebsocketClientOptions {
      */
     reconnect?: boolean | FrontendWebsocketReconnectOptions | null;
     /**
-     * Activity-aware heartbeat. `true` or omit for defaults; `false` disables
+     * Activity-aware heartbeat. `true`/`null`/omit for defaults; `false` disables
      * the timer entirely (only do this if the server side is also running
      * without heartbeat); pass an object to tune `interval` / `receive_timeout`.
      */
-    heartbeat?: boolean | FrontendWebsocketHeartbeatOptions;
+    heartbeat?: boolean | FrontendWebsocketHeartbeatOptions | null;
     /**
      * Durable queue for {@link FrontendWebsocketClient.request}. `true` or omit
      * for defaults; `false` disables buffering (requests while disconnected
@@ -163,6 +164,33 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
      * does not synthesize a reconnect — wait for the next close.
      */
     set_reconnect(reconnect?: boolean | FrontendWebsocketReconnectOptions | null): void;
+    /**
+     * Swap the heartbeat policy in place. Accepts the same shape as the
+     * constructor's `heartbeat` option: `false` disables the timer, `true` or
+     * `null`/omitted restores the defaults, or a config object customizes
+     * specific fields (missing fields fall back to defaults, not "keep
+     * current" — each call defines the whole policy atomically, same as the
+     * constructor and {@link set_reconnect}).
+     *
+     * When connected, the live timer is restarted immediately so the new
+     * `interval` / `receive_timeout` take effect without a reconnect; when
+     * disconnected, just stashes the policy for the next open.
+     */
+    set_heartbeat(heartbeat?: boolean | FrontendWebsocketHeartbeatOptions | null): void;
+    /**
+     * Cancel a scheduled reconnect without closing the client or disabling
+     * auto-reconnect. Transitions status from `reconnecting` → `closed` and
+     * resets the backoff counters — the next close still triggers a fresh
+     * reconnect cycle under the current policy. No-op when no reconnect is
+     * pending.
+     *
+     * Use this when UI state asks "stop trying for now" without the finality
+     * of {@link disconnect} (which also rejects pending/queued requests and
+     * clears heartbeat) or the policy change of `set_reconnect(false)`
+     * (which disables future reconnects). The queue stays intact so that
+     * calling {@link connect} later flushes buffered work.
+     */
+    cancel_reconnect(): void;
     get url(): string;
     /**
      * Whether the server has permanently closed the session. Once `true`, all
@@ -219,4 +247,17 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
     add_message_handler(handler: SocketMessageHandler): () => void;
     add_error_handler(handler: SocketErrorHandler): () => void;
 }
+/**
+ * Project {@link SocketStatus} onto fuz_util's {@link AsyncStatus} — the
+ * 5-way → 4-way mapping every consumer re-derives to surface connection state
+ * to UI (loading indicators, retry banners). Collapses `reconnecting` into
+ * `failure` (UI shows "lost, retrying") and splits `closed` by `revoked` so
+ * a terminal session-revocation read as `failure` while a clean client-
+ * initiated close reads as `initial` (the "not connected, not trying" state).
+ *
+ * @param status - the socket's current {@link SocketStatus}
+ * @param revoked - whether the session has been permanently revoked
+ *   (typically `FrontendWebsocketClient.revoked`)
+ */
+export declare const socket_status_to_async_status: (status: SocketStatus, revoked: boolean) => AsyncStatus;
 //# sourceMappingURL=socket.svelte.d.ts.map

package/dist/actions/socket.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/socket.svelte.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"socket.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/socket.svelte.ts"],"names":[],"mappings":"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"}

package/dist/actions/socket.svelte.js

@@ -111,7 +111,7 @@ export class FrontendWebsocketClient {
         this.#backoff_factor = config.factor ?? DEFAULT_BACKOFF_FACTOR;
         const heartbeat = options.heartbeat;
         this.#heartbeat_enabled = heartbeat !== false;
-        const heartbeat_config = typeof heartbeat === 'object' ? heartbeat : {};
+        const heartbeat_config = typeof heartbeat === 'object' && heartbeat !== null ? heartbeat : {};
         this.#heartbeat_interval = heartbeat_config.interval ?? DEFAULT_HEARTBEAT_INTERVAL;
         this.#heartbeat_receive_timeout =
             heartbeat_config.receive_timeout ?? DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT;
@@ -152,8 +152,7 @@ export class FrontendWebsocketClient {
         if (!next_auto) {
             this.#cancel_reconnect();
             this.status = 'closed';
-            this.reconnect_count = 0;
-            this.current_reconnect_delay = 0;
+            this.#reset_reconnect_counters();
             return;
         }
         // Auto-reconnect still on: monotonically shorten the pending wait if
@@ -176,6 +175,50 @@ export class FrontendWebsocketClient {
             this.connect();
         }, new_remaining);
     }
+    /**
+     * Swap the heartbeat policy in place. Accepts the same shape as the
+     * constructor's `heartbeat` option: `false` disables the timer, `true` or
+     * `null`/omitted restores the defaults, or a config object customizes
+     * specific fields (missing fields fall back to defaults, not "keep
+     * current" — each call defines the whole policy atomically, same as the
+     * constructor and {@link set_reconnect}).
+     *
+     * When connected, the live timer is restarted immediately so the new
+     * `interval` / `receive_timeout` take effect without a reconnect; when
+     * disconnected, just stashes the policy for the next open.
+     */
+    set_heartbeat(heartbeat = null) {
+        this.#heartbeat_enabled = heartbeat !== false;
+        const config = typeof heartbeat === 'object' && heartbeat !== null ? heartbeat : {};
+        this.#heartbeat_interval = config.interval ?? DEFAULT_HEARTBEAT_INTERVAL;
+        this.#heartbeat_receive_timeout = config.receive_timeout ?? DEFAULT_HEARTBEAT_RECEIVE_TIMEOUT;
+        if (this.connected) {
+            this.#start_heartbeat();
+        }
+        else {
+            this.#cancel_heartbeat();
+        }
+    }
+    /**
+     * Cancel a scheduled reconnect without closing the client or disabling
+     * auto-reconnect. Transitions status from `reconnecting` → `closed` and
+     * resets the backoff counters — the next close still triggers a fresh
+     * reconnect cycle under the current policy. No-op when no reconnect is
+     * pending.
+     *
+     * Use this when UI state asks "stop trying for now" without the finality
+     * of {@link disconnect} (which also rejects pending/queued requests and
+     * clears heartbeat) or the policy change of `set_reconnect(false)`
+     * (which disables future reconnects). The queue stays intact so that
+     * calling {@link connect} later flushes buffered work.
+     */
+    cancel_reconnect() {
+        if (this.#reconnect_timeout === null)
+            return;
+        this.#cancel_reconnect();
+        this.status = 'closed';
+        this.#reset_reconnect_counters();
+    }
     get url() {
         return this.#url;
     }
@@ -229,8 +272,7 @@ export class FrontendWebsocketClient {
         this.#cancel_heartbeat();
         this.#teardown(code);
         this.status = 'closed';
-        this.reconnect_count = 0;
-        this.current_reconnect_delay = 0;
+        this.#reset_reconnect_counters();
         this.#reject_all('client disconnected');
     }
     /** Explicit-resource-management hook — supports `using client = new FrontendWebsocketClient(url)`. */
@@ -535,10 +577,14 @@ export class FrontendWebsocketClient {
         }
         this.#reconnect_scheduled_at = null;
     }
-    #handle_open = (_event) => {
-        this.status = 'connected';
+    /** Reset the reactive reconnect counters — the pair always travels together. */
+    #reset_reconnect_counters() {
         this.reconnect_count = 0;
         this.current_reconnect_delay = 0;
+    }
+    #handle_open = (_event) => {
+        this.status = 'connected';
+        this.#reset_reconnect_counters();
         this.last_connect_time = Date.now();
         this.#cancel_reconnect();
         this.#start_heartbeat();
@@ -556,8 +602,7 @@ export class FrontendWebsocketClient {
             this.#revoked = true;
             this.status = 'closed';
             this.#cancel_reconnect();
-            this.reconnect_count = 0;
-            this.current_reconnect_delay = 0;
+            this.#reset_reconnect_counters();
             this.#reject_all('session revoked');
             return;
         }
@@ -630,3 +675,29 @@ export class FrontendWebsocketClient {
         }
     };
 }
+/**
+ * Project {@link SocketStatus} onto fuz_util's {@link AsyncStatus} — the
+ * 5-way → 4-way mapping every consumer re-derives to surface connection state
+ * to UI (loading indicators, retry banners). Collapses `reconnecting` into
+ * `failure` (UI shows "lost, retrying") and splits `closed` by `revoked` so
+ * a terminal session-revocation read as `failure` while a clean client-
+ * initiated close reads as `initial` (the "not connected, not trying" state).
+ *
+ * @param status - the socket's current {@link SocketStatus}
+ * @param revoked - whether the session has been permanently revoked
+ *   (typically `FrontendWebsocketClient.revoked`)
+ */
+export const socket_status_to_async_status = (status, revoked) => {
+    switch (status) {
+        case 'initial':
+            return 'initial';
+        case 'connecting':
+            return 'pending';
+        case 'connected':
+            return 'success';
+        case 'reconnecting':
+            return 'failure';
+        case 'closed':
+            return revoked ? 'failure' : 'initial';
+    }
+};

package/dist/runtime/deno.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deno.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/runtime/deno.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,WAAW,EAA4B,MAAM,WAAW,CAAC;AAsCtE;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,aAAa,CAAC,MAAM,CAAC,KAAG,WAwEhE,CAAC"}
+{"version":3,"file":"deno.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/runtime/deno.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,WAAW,EAA4B,MAAM,WAAW,CAAC;AAwDtE;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,aAAa,CAAC,MAAM,CAAC,KAAG,WA4HhE,CAAC"}

package/dist/runtime/deno.js

@@ -38,6 +38,33 @@ export const create_deno_runtime = (args) => ({
     mkdir: (path, options) => Deno.mkdir(path, options),
     read_text_file: (path) => Deno.readTextFile(path),
     read_file: (path) => Deno.readFile(path),
+    read_text_from_offset: async (path, offset) => {
+        const s = await Deno.stat(path);
+        const file_size = s.size;
+        const bytes_to_read = Math.max(0, file_size - offset);
+        if (bytes_to_read === 0)
+            return { content: '', bytes_read: 0, file_size };
+        const handle = await Deno.open(path, { read: true });
+        try {
+            await handle.seek(offset, Deno.SeekMode.Start);
+            const buffer = new Uint8Array(bytes_to_read);
+            const bytes_read = (await handle.read(buffer)) ?? 0;
+            return {
+                content: new TextDecoder().decode(buffer.subarray(0, bytes_read)),
+                bytes_read,
+                file_size,
+            };
+        }
+        finally {
+            handle.close();
+        }
+    },
+    readdir: async (path) => {
+        const names = [];
+        for await (const entry of Deno.readDir(path))
+            names.push(entry.name);
+        return names;
+    },
     write_text_file: (path, content) => Deno.writeTextFile(path, content),
     write_file: (path, data) => Deno.writeFile(path, data),
     rename: (old_path, new_path) => Deno.rename(old_path, new_path),
@@ -45,20 +72,46 @@ export const create_deno_runtime = (args) => ({
     // === HTTP ===
     fetch: globalThis.fetch,
     // === Local Commands ===
-    run_command: async (cmd, args) => {
+    run_command: async (cmd, args, options) => {
         try {
-            const proc = new Deno.Command(cmd, {
-                args,
-                stdout: 'piped',
-                stderr: 'piped',
-            });
-            const result = await proc.output();
-            return {
-                success: result.code === 0,
-                code: result.code,
-                stdout: new TextDecoder().decode(result.stdout),
-                stderr: new TextDecoder().decode(result.stderr),
-            };
+            const controller = options?.timeout_ms !== undefined ? new AbortController() : null;
+            const signal = controller && options?.signal
+                ? AbortSignal.any([controller.signal, options.signal])
+                : (controller?.signal ?? options?.signal);
+            const timer = controller && options?.timeout_ms !== undefined
+                ? setTimeout(() => controller.abort(), options.timeout_ms)
+                : null;
+            let timed_out = false;
+            if (controller) {
+                controller.signal.addEventListener('abort', () => {
+                    if (options?.signal?.aborted)
+                        return;
+                    timed_out = true;
+                }, { once: true });
+            }
+            try {
+                const proc = new Deno.Command(cmd, {
+                    args,
+                    cwd: options?.cwd,
+                    signal,
+                    stdout: 'piped',
+                    stderr: 'piped',
+                });
+                const result = await proc.output();
+                const base = {
+                    success: result.code === 0 && !timed_out,
+                    code: result.code,
+                    stdout: new TextDecoder().decode(result.stdout),
+                    stderr: new TextDecoder().decode(result.stderr),
+                };
+                if (options?.timeout_ms !== undefined)
+                    base.timed_out = timed_out;
+                return base;
+            }
+            finally {
+                if (timer !== null)
+                    clearTimeout(timer);
+            }
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);

package/dist/runtime/deps.d.ts

@@ -16,12 +16,28 @@ export interface StatResult {
 }
 /**
  * Result of executing a command.
+ *
+ * `timed_out` is present only when `timeout_ms` was passed in `RunCommandOptions`
+ * and the process was killed after exceeding the timeout. Callers that pass
+ * `timeout_ms` should check this flag to distinguish timeout from exit-code failure.
  */
 export interface CommandResult {
     success: boolean;
     code: number;
     stdout: string;
     stderr: string;
+    timed_out?: boolean;
+}
+/**
+ * Options for `run_command`.
+ */
+export interface RunCommandOptions {
+    /** Working directory for the child process. */
+    cwd?: string;
+    /** AbortSignal to terminate the child process. */
+    signal?: AbortSignal;
+    /** Kill the process and return `timed_out: true` after this many milliseconds. */
+    timeout_ms?: number;
 }
 /**
  * Environment variable access.
@@ -32,16 +48,37 @@ export interface EnvDeps {
     /** Set an environment variable. */
     env_set: (name: string, value: string) => void;
 }
+/**
+ * Result of reading text from a byte offset.
+ */
+export interface ReadTextFromOffsetResult {
+    /** Decoded text content read from the offset. */
+    content: string;
+    /** Number of bytes actually read. */
+    bytes_read: number;
+    /** Total file size at the time of the read (for truncation detection). */
+    file_size: number;
+}
 /**
  * File system read operations.
  */
 export interface FsReadDeps {
     /** Get file/directory stats, or null if path doesn't exist. */
     stat: (path: string) => Promise<StatResult | null>;
-    /** Read a file as text. */
+    /** Read a file as text. Throws if the file does not exist. */
     read_text_file: (path: string) => Promise<string>;
-    /** Read a file as bytes. */
+    /** Read a file as bytes. Throws if the file does not exist. */
     read_file: (path: string) => Promise<Uint8Array>;
+    /**
+     * Read text starting from a byte offset. Throws if the file does not exist.
+     *
+     * Returns `content`, `bytes_read`, and `file_size` so callers can detect
+     * truncation (when `file_size < offset`) and tail incrementally without
+     * re-reading the whole file.
+     */
+    read_text_from_offset: (path: string, offset: number) => Promise<ReadTextFromOffsetResult>;
+    /** List directory entries (names, not full paths). Throws if the directory does not exist. */
+    readdir: (path: string) => Promise<Array<string>>;
 }
 /**
  * File system write operations.
@@ -71,8 +108,15 @@ export interface FsRemoveDeps {
  * Command execution.
  */
 export interface CommandDeps {
-    /** Run a command and return the result. */
-    run_command: (cmd: string, args: Array<string>) => Promise<CommandResult>;
+    /**
+     * Run a command and return the result. Never throws — failures surface as
+     * `success: false`.
+     *
+     * `options.cwd` sets the child's working directory. `options.signal` aborts
+     * the child when the signal fires. `options.timeout_ms` kills the child
+     * after the given duration and returns `timed_out: true` on the result.
+     */
+    run_command: (cmd: string, args: Array<string>, options?: RunCommandOptions) => Promise<CommandResult>;
 }
 /**
  * HTTP fetch capability.

package/dist/runtime/deps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deps.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/runtime/deps.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"deps.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/runtime/deps.ts"],"names":[],"mappings":"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"}

package/dist/runtime/mock.d.ts

@@ -7,7 +7,7 @@
  *
  * @module
  */
-import type { RuntimeDeps, CommandResult } from './deps.js';
+import type { RuntimeDeps, CommandResult, RunCommandOptions } from './deps.js';
 /**
  * Mock `RuntimeDeps` with observable state for assertions.
  */
@@ -22,10 +22,11 @@ export interface MockRuntime extends RuntimeDeps {
     mock_dirs: Set<string>;
     /** Exit calls recorded (exit codes). */
     exit_calls: Array<number>;
-    /** Commands executed. */
+    /** Commands executed. Captures `options` when passed so tests can assert cwd/timeout/signal. */
     command_calls: Array<{
         cmd: string;
         args: Array<string>;
+        options?: RunCommandOptions;
     }>;
     /** Commands executed with inherit. */
     command_inherit_calls: Array<{

package/dist/runtime/mock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/runtime/mock.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,WAAW,EAAc,aAAa,EAAC,MAAM,WAAW,CAAC;AAItE;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,kCAAkC;IAClC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,0CAA0C;IAC1C,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,+CAA+C;IAC/C,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACvC,mCAAmC;IACnC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB,wCAAwC;IACxC,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1B,yBAAyB;IACzB,aAAa,EAAE,KAAK,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;KAAC,CAAC,CAAC;IACzD,sCAAsC;IACtC,qBAAqB,EAAE,KAAK,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;KAAC,CAAC,CAAC;IACjE,8BAA8B;IAC9B,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,4CAA4C;IAC5C,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACjD,yCAAyC;IACzC,YAAY,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC,4BAA4B;IAC5B,WAAW,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,WAAW,CAAA;KAAC,CAAC,CAAC;IACxE,wDAAwD;IACxD,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAM,KAAK,CAAC,MAAM,CAAM,KAAG,WA4K9D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,WAAW,KAAG,IAazD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,WAAW,EAAE,OAAO,MAAM,KAAG,IAEpE,CAAC;AAEF;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM;CAKxB"}
+{"version":3,"file":"mock.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/runtime/mock.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,WAAW,EAAc,aAAa,EAAE,iBAAiB,EAAC,MAAM,WAAW,CAAC;AAIzF;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,kCAAkC;IAClC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,0CAA0C;IAC1C,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,+CAA+C;IAC/C,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACvC,mCAAmC;IACnC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB,wCAAwC;IACxC,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1B,gGAAgG;IAChG,aAAa,EAAE,KAAK,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,iBAAiB,CAAA;KAAC,CAAC,CAAC;IACtF,sCAAsC;IACtC,qBAAqB,EAAE,KAAK,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;KAAC,CAAC,CAAC;IACjE,8BAA8B;IAC9B,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,4CAA4C;IAC5C,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACjD,yCAAyC;IACzC,YAAY,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC,4BAA4B;IAC5B,WAAW,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,WAAW,CAAA;KAAC,CAAC,CAAC;IACxE,wDAAwD;IACxD,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAM,KAAK,CAAC,MAAM,CAAM,KAAG,WAkO9D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,WAAW,KAAG,IAazD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,WAAW,EAAE,OAAO,MAAM,KAAG,IAEpE,CAAC;AAEF;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM;CAKxB"}

package/dist/runtime/mock.js

@@ -114,6 +114,55 @@ export const create_mock_runtime = (args = []) => {
             error.code = 'ENOENT';
             throw error;
         },
+        read_text_from_offset: async (path, offset) => {
+            let bytes;
+            const stored_bytes = mock_fs_bytes.get(path);
+            if (stored_bytes !== undefined) {
+                bytes = stored_bytes;
+            }
+            else {
+                const content = mock_fs.get(path);
+                if (content === undefined) {
+                    const error = new Error(`ENOENT: no such file or directory: ${path}`);
+                    error.code = 'ENOENT';
+                    throw error;
+                }
+                bytes = new TextEncoder().encode(content);
+            }
+            const file_size = bytes.length;
+            const bytes_to_read = Math.max(0, file_size - offset);
+            if (bytes_to_read === 0)
+                return { content: '', bytes_read: 0, file_size };
+            const slice = bytes.subarray(offset, offset + bytes_to_read);
+            return {
+                content: new TextDecoder().decode(slice),
+                bytes_read: slice.length,
+                file_size,
+            };
+        },
+        readdir: async (path) => {
+            const prefix = path.endsWith('/') ? path : path + '/';
+            const seen = new Set();
+            const collect = (key) => {
+                if (!key.startsWith(prefix))
+                    return;
+                const rest = key.slice(prefix.length);
+                const slash = rest.indexOf('/');
+                seen.add(slash === -1 ? rest : rest.slice(0, slash));
+            };
+            for (const key of mock_fs.keys())
+                collect(key);
+            for (const key of mock_fs_bytes.keys())
+                collect(key);
+            for (const key of mock_dirs)
+                collect(key);
+            if (seen.size === 0 && !mock_dirs.has(path)) {
+                const error = new Error(`ENOENT: no such file or directory: ${path}`);
+                error.code = 'ENOENT';
+                throw error;
+            }
+            return Array.from(seen).sort();
+        },
         write_text_file: async (path, content) => {
             mock_fs.set(path, content);
         },
@@ -163,13 +212,20 @@ export const create_mock_runtime = (args = []) => {
             throw new TypeError(`fetch failed (no mock for ${url})`);
         },
         // === Local Commands ===
-        run_command: async (cmd, args) => {
-            command_calls.push({ cmd, args });
+        run_command: async (cmd, args, options) => {
+            command_calls.push(options ? { cmd, args, options } : { cmd, args });
             const key = `${cmd} ${args.join(' ')}`;
             const mocked = mock_command_results.get(key);
-            if (mocked)
+            if (mocked) {
+                if (options?.timeout_ms !== undefined && mocked.timed_out === undefined) {
+                    return { ...mocked, timed_out: false };
+                }
                 return mocked;
-            return { success: true, code: 0, stdout: '', stderr: '' };
+            }
+            const result = { success: true, code: 0, stdout: '', stderr: '' };
+            if (options?.timeout_ms !== undefined)
+                result.timed_out = false;
+            return result;
         },
         run_command_inherit: async (cmd, args) => {
             command_inherit_calls.push({ cmd, args });

package/dist/runtime/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/runtime/node.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAAC,WAAW,EAA4B,MAAM,WAAW,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAC/B,OAAM,aAAa,CAAC,MAAM,CAAyB,KACjD,WAkHD,CAAC"}
+{"version":3,"file":"node.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/runtime/node.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAAC,WAAW,EAA4B,MAAM,WAAW,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAC/B,OAAM,aAAa,CAAC,MAAM,CAAyB,KACjD,WAmKD,CAAC"}

package/dist/runtime/node.js

@@ -8,7 +8,7 @@
  */
 import { Buffer } from 'node:buffer';
 import { spawn } from 'node:child_process';
-import { stat, mkdir, readFile, writeFile, rename, rm } from 'node:fs/promises';
+import { stat, mkdir, readFile, readdir, writeFile, rename, rm, open } from 'node:fs/promises';
 import process from 'node:process';
 /**
  * Create a `RuntimeDeps` backed by Node.js APIs.
@@ -42,6 +42,27 @@ export const create_node_runtime = (args = process.argv.slice(2)) => ({
     },
     read_text_file: (path) => readFile(path, 'utf-8'),
     read_file: (path) => readFile(path).then((buf) => new Uint8Array(buf)),
+    read_text_from_offset: async (path, offset) => {
+        const s = await stat(path);
+        const file_size = s.size;
+        const bytes_to_read = Math.max(0, file_size - offset);
+        if (bytes_to_read === 0)
+            return { content: '', bytes_read: 0, file_size };
+        const handle = await open(path, 'r');
+        try {
+            const buffer = Buffer.alloc(bytes_to_read);
+            const { bytesRead } = await handle.read(buffer, 0, bytes_to_read, offset);
+            return {
+                content: buffer.toString('utf-8', 0, bytesRead),
+                bytes_read: bytesRead,
+                file_size,
+            };
+        }
+        finally {
+            await handle.close();
+        }
+    },
+    readdir: (path) => readdir(path),
     write_text_file: (path, content) => writeFile(path, content, 'utf-8'),
     write_file: (path, data) => writeFile(path, data),
     rename: (old_path, new_path) => rename(old_path, new_path),
@@ -49,17 +70,45 @@ export const create_node_runtime = (args = process.argv.slice(2)) => ({
     // === HTTP ===
     fetch: globalThis.fetch,
     // === Local Commands ===
-    run_command: (cmd, args) => {
+    run_command: (cmd, args, options) => {
         return new Promise((resolve) => {
             const proc = spawn(cmd, args, {
                 stdio: ['ignore', 'pipe', 'pipe'],
+                cwd: options?.cwd,
             });
             const stdout_chunks = [];
             const stderr_chunks = [];
+            let timed_out = false;
+            let done = false;
+            const finish = (result) => {
+                if (done)
+                    return;
+                done = true;
+                if (timer !== null)
+                    clearTimeout(timer);
+                if (options?.signal)
+                    options.signal.removeEventListener('abort', on_abort);
+                resolve(result);
+            };
+            const on_abort = () => {
+                proc.kill();
+            };
+            const timer = options?.timeout_ms !== undefined
+                ? setTimeout(() => {
+                    timed_out = true;
+                    proc.kill();
+                }, options.timeout_ms)
+                : null;
+            if (options?.signal) {
+                if (options.signal.aborted)
+                    proc.kill();
+                else
+                    options.signal.addEventListener('abort', on_abort, { once: true });
+            }
             proc.stdout.on('data', (chunk) => stdout_chunks.push(chunk));
             proc.stderr.on('data', (chunk) => stderr_chunks.push(chunk));
             proc.on('error', (error) => {
-                resolve({
+                finish({
                     success: false,
                     code: 1,
                     stdout: '',
@@ -67,12 +116,15 @@ export const create_node_runtime = (args = process.argv.slice(2)) => ({
                 });
             });
             proc.on('close', (code) => {
-                resolve({
-                    success: code === 0,
+                const result = {
+                    success: code === 0 && !timed_out,
                     code: code ?? 1,
                     stdout: Buffer.concat(stdout_chunks).toString('utf-8').trim(),
                     stderr: Buffer.concat(stderr_chunks).toString('utf-8').trim(),
-                });
+                };
+                if (options?.timeout_ms !== undefined)
+                    result.timed_out = timed_out;
+                finish(result);
             });
         });
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",
@@ -45,9 +45,9 @@
     "@fuzdev/blake3_wasm": "^0.1.0",
     "@fuzdev/fuz_code": "^0.45.1",
     "@fuzdev/fuz_css": "^0.58.0",
-    "@fuzdev/fuz_ui": "^0.191.2",
-    "@fuzdev/fuz_util": "^0.56.0",
-    "@fuzdev/gro": "^0.197.3",
+    "@fuzdev/fuz_ui": "^0.191.4",
+    "@fuzdev/fuz_util": "^0.57.0",
+    "@fuzdev/gro": "^0.198.0",
     "@jridgewell/trace-mapping": "^0.3.31",
     "@node-rs/argon2": "^2.0.2",
     "@ryanatkn/eslint-config": "^0.11.0",