@fuzdev/fuz_app 0.18.0 → 0.19.0

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

@@ -1 +1 @@
-{"version":3,"file":"action_event.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_event.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAC,gBAAgB,EAAc,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAWpF,OAAO,KAAK,EACX,cAAc,EACd,sBAAsB,EACtB,mBAAmB,EAEnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,sBAAsB,EAAE,eAAe,EAAC,MAAM,yBAAyB,CAAC;AACrF,OAAO,EAAkB,KAAK,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAwBlF,MAAM,MAAM,yBAAyB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,IAAI,CACxE,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,EACvC,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,EACvC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,KACvB,IAAI,CAAC;AAEV;;GAEG;AACH,qBAAa,WAAW,CACvB,OAAO,SAAS,MAAM,GAAG,MAAM,EAC/B,MAAM,SAAS,gBAAgB,GAAG,gBAAgB,EAClD,KAAK,SAAS,eAAe,GAAG,eAAe;;IAK/C,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAE/B,IAAI,IAAI,IAAI,oBAAoB,CAAC,OAAO,CAAC,GAAG;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAA;KAAC,CAEvE;gBAGA,WAAW,EAAE,sBAAsB,EACnC,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,oBAAoB,CAAC,OAAO,CAAC;IAOpC,MAAM,IAAI,oBAAoB,CAAC,OAAO,CAAC;IAMvC,OAAO,CAAC,QAAQ,EAAE,yBAAyB,CAAC,OAAO,CAAC,GAAG,MAAM,IAAI;IAKjE,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI;IAUvD;;OAEG;IACH,KAAK,IAAI,IAAI;IA8Cb;;OAEG;IAGG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IA0CnC;;OAEG;IACH,WAAW,IAAI,IAAI;IAkCnB;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAezC,WAAW,IAAI,OAAO;IAItB,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAIxC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAQ1C,YAAY,CAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI;IAUpD,gBAAgB,CAAC,YAAY,EAAE,mBAAmB,GAAG,IAAI;CAyKzD;AAGD;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EAClE,aAAa,sBAAsB,EACnC,MAAM,eAAe,EACrB,OAAO,OAAO,EACd,gBAAgB,gBAAgB,KAC9B,WAAW,CAAC,OAAO,CAiBrB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,6BAA6B,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EAC5E,MAAM,oBAAoB,CAAC,OAAO,CAAC,EACnC,aAAa,sBAAsB,KACjC,WAAW,CAAC,OAAO,CAOrB,CAAC;AAIF,eAAO,MAAM,kBAAkB,GAC9B,UAAU,OAAO,EACjB,aAAa,sBAAsB,KACjC,WAGF,CAAC"}
+{"version":3,"file":"action_event.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_event.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAC,gBAAgB,EAAc,eAAe,EAAC,MAAM,kBAAkB,CAAC;AAWpF,OAAO,KAAK,EACX,cAAc,EACd,sBAAsB,EACtB,mBAAmB,EAEnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,sBAAsB,EAAE,eAAe,EAAC,MAAM,yBAAyB,CAAC;AACrF,OAAO,EAAkB,KAAK,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAelF,MAAM,MAAM,yBAAyB,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,IAAI,CACxE,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,EACvC,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,EACvC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,KACvB,IAAI,CAAC;AAEV;;GAEG;AACH,qBAAa,WAAW,CACvB,OAAO,SAAS,MAAM,GAAG,MAAM,EAC/B,MAAM,SAAS,gBAAgB,GAAG,gBAAgB,EAClD,KAAK,SAAS,eAAe,GAAG,eAAe;;IAK/C,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;IAC7C,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAE/B,IAAI,IAAI,IAAI,oBAAoB,CAAC,OAAO,CAAC,GAAG;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAA;KAAC,CAEvE;gBAGA,WAAW,EAAE,sBAAsB,EACnC,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,oBAAoB,CAAC,OAAO,CAAC;IAOpC,MAAM,IAAI,oBAAoB,CAAC,OAAO,CAAC;IAMvC,OAAO,CAAC,QAAQ,EAAE,yBAAyB,CAAC,OAAO,CAAC,GAAG,MAAM,IAAI;IAKjE,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,GAAG,IAAI;IAUvD;;OAEG;IACH,KAAK,IAAI,IAAI;IA8Cb;;OAEG;IAGG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IA0CnC;;OAEG;IACH,WAAW,IAAI,IAAI;IAkCnB;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAezC,WAAW,IAAI,OAAO;IAItB,eAAe,CAAC,QAAQ,EAAE,OAAO,GAAG,IAAI;IAIxC,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAQ1C,YAAY,CAAC,QAAQ,EAAE,sBAAsB,GAAG,IAAI;IAUpD,gBAAgB,CAAC,YAAY,EAAE,mBAAmB,GAAG,IAAI;CAyKzD;AAGD;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EAClE,aAAa,sBAAsB,EACnC,MAAM,eAAe,EACrB,OAAO,OAAO,EACd,gBAAgB,gBAAgB,KAC9B,WAAW,CAAC,OAAO,CAiBrB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,6BAA6B,GAAI,OAAO,SAAS,MAAM,GAAG,MAAM,EAC5E,MAAM,oBAAoB,CAAC,OAAO,CAAC,EACnC,aAAa,sBAAsB,KACjC,WAAW,CAAC,OAAO,CAOrB,CAAC;AAIF,eAAO,MAAM,kBAAkB,GAC9B,UAAU,OAAO,EACjB,aAAa,sBAAsB,KACjC,WAGF,CAAC"}

package/dist/actions/action_event.js

@@ -12,13 +12,6 @@ import { jsonrpc_error_messages, ThrownJsonrpcError } from '../http/jsonrpc_erro
 import { ActionEventData } from './action_event_data.js';
 import { validate_step_transition, validate_phase_transition, should_validate_output, is_action_complete, create_initial_data, get_initial_phase, is_request_response, is_send_request_with_parsed_input, is_notification_send_with_parsed_input, } from './action_event_helpers.js';
 import { create_uuid } from '../uuid.js';
-/** Formats a Zod validation error with field paths for clearer error messages. */
-const format_zod_validation_error = (error) => error.issues
-    .map((i) => {
-    const path = i.path.length > 0 ? `${i.path.join('.')}: ` : '';
-    return `${path}${i.message}`;
-})
-    .join(', ');
 /**
  * Action event that manages the lifecycle of an action through its state machine.
  */
@@ -87,7 +80,7 @@ export class ActionEvent {
             // Handler errors (network, server, business logic) DO transition to error phases.
             this.#fail(
             // no need to protect this info
-            jsonrpc_error_messages.invalid_params(`failed to parse input: ${format_zod_validation_error(parsed.error)}`, { validation_errors: parsed.error.issues }));
+            jsonrpc_error_messages.invalid_params(`failed to parse input: ${z.prettifyError(parsed.error)}`, { validation_errors: parsed.error.issues }));
         }
         return this;
     }
@@ -281,7 +274,7 @@ export class ActionEvent {
                 this.#transition_step('handled', { output: parsed.data });
             }
             else {
-                this.#fail(jsonrpc_error_messages.validation_error(`failed to parse output: ${format_zod_validation_error(parsed.error)}`, { output, validation_errors: parsed.error.issues }));
+                this.#fail(jsonrpc_error_messages.validation_error(`failed to parse output: ${z.prettifyError(parsed.error)}`, { output, validation_errors: parsed.error.issues }));
             }
         }
         else {

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

@@ -80,6 +80,26 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
     last_close_reason: string | null;
     readonly connected: boolean;
     constructor(url: string, options?: FrontendWebsocketClientOptions);
+    /**
+     * Swap the auto-reconnect policy in place. Accepts the same shape as the
+     * constructor's `reconnect` option: `false` disables reconnect, `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).
+     *
+     * In-flight reconnect schedules are **monotonically shortened**: the
+     * effective total wait from arm-time never exceeds what the new policy
+     * prescribes. If the new target is already past the time already
+     * elapsed, the reconnect fires immediately (on the next tick). The wait
+     * is never extended.
+     *
+     * Turning reconnect off while a reconnect timer is pending cancels that
+     * timer and transitions status to `closed` (since the lie of
+     * `'reconnecting'` would be visible to UI indicators). Turning it back on
+     * does not synthesize a reconnect — wait for the next close.
+     */
+    set_reconnect(reconnect?: boolean | FrontendWebsocketReconnectOptions | null): void;
     get url(): string;
     /**
      * Whether the server has permanently closed the session. Once `true`, all

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":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,oBAAoB,CAAC;AAE5D,qDAAqD;AACrD,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC,kCAAkC;AAClC,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAC5C,8DAA8D;AAC9D,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AACjD,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,QAAQ,CAAC;AAE9F,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;AACjE,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;AAExD,MAAM,WAAW,iCAAiC;IACjD,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,8BAA8B;IAC9C;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,iCAAiC,GAAG,IAAI,CAAC;IAC/D,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,uBAAwB,YAAW,mBAAmB,EAAE,UAAU;;IAQ9E,EAAE,EAAE,SAAS,GAAG,IAAI,CAAoB;IACxC,MAAM,EAAE,YAAY,CAAyB;IAE7C,eAAe,EAAE,MAAM,CAAiB;IACxC,uBAAuB,EAAE,MAAM,CAAiB;IAChD,2EAA2E;IAC3E,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAoB;IACpD,yEAAyE;IACzE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAoB;IAClD,kFAAkF;IAClF,eAAe,EAAE,MAAM,GAAG,IAAI,CAAoB;IAClD,qEAAqE;IACrE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAoB;IAQpD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAyC;gBAExD,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,8BAAmC;IAWrE,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED;;;;OAIG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;OAIG;IACH,OAAO,IAAI,IAAI;IA2Bf;;;;OAIG;IACH,UAAU,CAAC,IAAI,GAAE,MAA2B,GAAG,IAAI;IAQnD,sGAAsG;IACtG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAIxB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAW3B,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAK9D,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI;CA8G1D"}
+{"version":3,"file":"socket.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/socket.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,oBAAoB,CAAC;AAE5D,qDAAqD;AACrD,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC,kCAAkC;AAClC,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAC5C,8DAA8D;AAC9D,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AACjD,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,QAAQ,CAAC;AAE9F,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;AACjE,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;AAExD,MAAM,WAAW,iCAAiC;IACjD,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,8BAA8B;IAC9C;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,iCAAiC,GAAG,IAAI,CAAC;IAC/D,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,uBAAwB,YAAW,mBAAmB,EAAE,UAAU;;IAQ9E,EAAE,EAAE,SAAS,GAAG,IAAI,CAAoB;IACxC,MAAM,EAAE,YAAY,CAAyB;IAE7C,eAAe,EAAE,MAAM,CAAiB;IACxC,uBAAuB,EAAE,MAAM,CAAiB;IAChD,2EAA2E;IAC3E,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAoB;IACpD,yEAAyE;IACzE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAoB;IAClD,kFAAkF;IAClF,eAAe,EAAE,MAAM,GAAG,IAAI,CAAoB;IAClD,qEAAqE;IACrE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAoB;IASpD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAyC;gBAExD,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,8BAAmC;IAWrE;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,SAAS,GAAE,OAAO,GAAG,iCAAiC,GAAG,IAAW,GAAG,IAAI;IA4CzF,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED;;;;OAIG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;OAIG;IACH,OAAO,IAAI,IAAI;IA2Bf;;;;OAIG;IACH,UAAU,CAAC,IAAI,GAAE,MAA2B,GAAG,IAAI;IAQnD,sGAAsG;IACtG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAIxB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAW3B,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAK9D,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI;CAiH1D"}

package/dist/actions/socket.svelte.js

@@ -54,6 +54,7 @@ export class FrontendWebsocketClient {
     /** Reason string from the most recent close event (may be empty). */
     last_close_reason = $state.raw(null);
     #reconnect_timeout = null;
+    #reconnect_scheduled_at = null;
     #revoked = $state.raw(false);
     #message_handlers = new Set();
     #error_handlers = new Set();
@@ -68,6 +69,61 @@ export class FrontendWebsocketClient {
         this.#backoff_factor = config.factor ?? DEFAULT_BACKOFF_FACTOR;
         this.#log = options.log ?? null;
     }
+    /**
+     * Swap the auto-reconnect policy in place. Accepts the same shape as the
+     * constructor's `reconnect` option: `false` disables reconnect, `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).
+     *
+     * In-flight reconnect schedules are **monotonically shortened**: the
+     * effective total wait from arm-time never exceeds what the new policy
+     * prescribes. If the new target is already past the time already
+     * elapsed, the reconnect fires immediately (on the next tick). The wait
+     * is never extended.
+     *
+     * Turning reconnect off while a reconnect timer is pending cancels that
+     * timer and transitions status to `closed` (since the lie of
+     * `'reconnecting'` would be visible to UI indicators). Turning it back on
+     * does not synthesize a reconnect — wait for the next close.
+     */
+    set_reconnect(reconnect = null) {
+        const next_auto = reconnect !== false;
+        const config = typeof reconnect === 'object' && reconnect !== null ? reconnect : {};
+        this.#auto_reconnect = next_auto;
+        this.#reconnect_delay = config.delay ?? DEFAULT_RECONNECT_DELAY;
+        this.#reconnect_delay_max = config.delay_max ?? DEFAULT_RECONNECT_DELAY_MAX;
+        this.#backoff_factor = config.factor ?? DEFAULT_BACKOFF_FACTOR;
+        if (this.#reconnect_timeout === null)
+            return;
+        if (!next_auto) {
+            this.#cancel_reconnect();
+            this.status = 'closed';
+            this.reconnect_count = 0;
+            this.current_reconnect_delay = 0;
+            return;
+        }
+        // Auto-reconnect still on: monotonically shorten the pending wait if
+        // the new policy would produce a shorter total wait from arm-time.
+        // Never extends.
+        const scheduled_at = this.#reconnect_scheduled_at ?? Date.now();
+        const elapsed = Math.max(0, Date.now() - scheduled_at);
+        const remaining = Math.max(0, this.current_reconnect_delay - elapsed);
+        const new_target = Math.round(Math.min(this.#reconnect_delay_max, this.#reconnect_delay * this.#backoff_factor ** Math.max(0, this.reconnect_count - 1)));
+        const new_remaining = Math.max(0, new_target - elapsed);
+        if (new_remaining >= remaining)
+            return;
+        clearTimeout(this.#reconnect_timeout);
+        this.current_reconnect_delay = new_target;
+        // Keep #reconnect_scheduled_at at the original arm time so subsequent
+        // set_reconnect calls compute elapsed against a stable origin.
+        this.#reconnect_timeout = setTimeout(() => {
+            this.#reconnect_timeout = null;
+            this.#reconnect_scheduled_at = null;
+            this.connect();
+        }, new_remaining);
+    }
     get url() {
         return this.#url;
     }
@@ -179,8 +235,10 @@ export class FrontendWebsocketClient {
         this.reconnect_count++;
         this.current_reconnect_delay = Math.round(Math.min(this.#reconnect_delay_max, this.#reconnect_delay * this.#backoff_factor ** (this.reconnect_count - 1)));
         this.status = 'reconnecting';
+        this.#reconnect_scheduled_at = Date.now();
         this.#reconnect_timeout = setTimeout(() => {
             this.#reconnect_timeout = null;
+            this.#reconnect_scheduled_at = null;
             this.connect();
         }, this.current_reconnect_delay);
     }
@@ -189,6 +247,7 @@ export class FrontendWebsocketClient {
             clearTimeout(this.#reconnect_timeout);
             this.#reconnect_timeout = null;
         }
+        this.#reconnect_scheduled_at = null;
     }
     #handle_open = (_event) => {
         this.status = 'connected';

package/dist/env/dotenv.d.ts

@@ -10,6 +10,19 @@ import type { FsReadDeps } from '../runtime/deps.js';
 /**
  * Parse a dotenv-format string into a record.
  *
+ * Values wrapped in `"..."` have `\\` → `\`, `\"` → `"`, `\n` → newline,
+ * and `\r` → carriage-return decoded (symmetric with the writer in
+ * `update_env_variable`). Values wrapped in `'...'` are taken literally —
+ * no escape processing. Unquoted values are unchanged.
+ *
+ * Inline comments are stripped after a closing quote (e.g. `KEY="v" # c` → `v`)
+ * and after whitespace on unquoted values (e.g. `KEY=v # c` → `v`). Unquoted
+ * values keep `#` literal when no whitespace precedes it so URL fragments
+ * like `KEY=https://x.com#frag` round-trip unchanged.
+ *
+ * Trailing whitespace on unquoted values is lost (the raw value is trimmed);
+ * wrap the value in `"..."` or `'...'` to preserve surrounding spacing.
+ *
  * @param content - dotenv file content
  * @returns parsed key-value pairs
  */
@@ -17,6 +30,10 @@ export declare const parse_dotenv: (content: string) => Record<string, string>;
 /**
  * Load and parse an env file.
  *
+ * Returns null only when the file does not exist. Other read errors
+ * (permission denied, I/O failure, etc.) are re-thrown so callers can
+ * distinguish "no file" from "couldn't read".
+ *
  * @param runtime - runtime with `read_text_file` capability
  * @param path - path to env file
  * @returns parsed env record, or null if file doesn't exist

package/dist/env/dotenv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dotenv.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/env/dotenv.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAqBnE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GACzB,SAAS,IAAI,CAAC,UAAU,EAAE,gBAAgB,CAAC,EAC3C,MAAM,MAAM,KACV,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAOvC,CAAC"}
+{"version":3,"file":"dotenv.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/env/dotenv.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;GAkBG;AAGH,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAkCnE,CAAC;AAiEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,GACzB,SAAS,IAAI,CAAC,UAAU,EAAE,gBAAgB,CAAC,EAC3C,MAAM,MAAM,KACV,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CASvC,CAAC"}

package/dist/env/dotenv.js

@@ -9,14 +9,28 @@
 /**
  * Parse a dotenv-format string into a record.
  *
+ * Values wrapped in `"..."` have `\\` → `\`, `\"` → `"`, `\n` → newline,
+ * and `\r` → carriage-return decoded (symmetric with the writer in
+ * `update_env_variable`). Values wrapped in `'...'` are taken literally —
+ * no escape processing. Unquoted values are unchanged.
+ *
+ * Inline comments are stripped after a closing quote (e.g. `KEY="v" # c` → `v`)
+ * and after whitespace on unquoted values (e.g. `KEY=v # c` → `v`). Unquoted
+ * values keep `#` literal when no whitespace precedes it so URL fragments
+ * like `KEY=https://x.com#frag` round-trip unchanged.
+ *
+ * Trailing whitespace on unquoted values is lost (the raw value is trimmed);
+ * wrap the value in `"..."` or `'...'` to preserve surrounding spacing.
+ *
  * @param content - dotenv file content
  * @returns parsed key-value pairs
  */
+// Line tokenization (trim, skip empties/comments, split on first `=`) is
+// mirrored in `update_env_variable.ts`'s `find_last_key_line_index`.
 export const parse_dotenv = (content) => {
     const result = {};
     for (const line of content.split('\n')) {
         const trimmed = line.trim();
-        // skip empty lines and comments
         if (!trimmed || trimmed.startsWith('#'))
             continue;
         const eq_index = trimmed.indexOf('=');
@@ -24,19 +38,101 @@ export const parse_dotenv = (content) => {
             continue;
         const key = trimmed.slice(0, eq_index).trim();
         let value = trimmed.slice(eq_index + 1).trim();
-        // remove surrounding quotes if present (need at least 2 chars for open+close)
-        if (value.length >= 2 &&
-            ((value.startsWith('"') && value.endsWith('"')) ||
-                (value.startsWith("'") && value.endsWith("'")))) {
-            value = value.slice(1, -1);
+        if (value.startsWith('"')) {
+            const close = find_closing_double_quote(value);
+            if (close !== -1 && is_comment_or_empty_after(value, close)) {
+                value = unescape_double_quoted(value.slice(1, close));
+            }
+        }
+        else if (value.startsWith("'")) {
+            const close = value.indexOf("'", 1);
+            if (close !== -1 && is_comment_or_empty_after(value, close)) {
+                value = value.slice(1, close);
+            }
+        }
+        else if (value.startsWith('#')) {
+            // Leading `#` on an unquoted value means the value is empty and the
+            // rest is a comment (`KEY=#c` or `KEY= # c` → `''`).
+            value = '';
+        }
+        else {
+            // Unquoted: strip trailing `\s+#...` so `KEY=v # c` → `v` while
+            // `KEY=https://x.com#frag` (no whitespace before `#`) stays literal.
+            const comment_idx = value.search(/\s+#/);
+            if (comment_idx !== -1)
+                value = value.slice(0, comment_idx).trimEnd();
         }
         result[key] = value;
     }
     return result;
 };
+/**
+ * Find the index of the unescaped closing `"` in a `"..."`-wrapped value.
+ * Returns -1 if no closing quote is found. Caller guarantees `value[0] === '"'`.
+ */
+const find_closing_double_quote = (value) => {
+    let i = 1;
+    while (i < value.length) {
+        const ch = value[i];
+        if (ch === '\\' && i + 1 < value.length) {
+            i += 2;
+            continue;
+        }
+        if (ch === '"')
+            return i;
+        i++;
+    }
+    return -1;
+};
+/**
+ * Returns true if everything after `pos` (the closing quote) is whitespace
+ * or a `# ...` inline comment. Used to decide whether the line is a clean
+ * `KEY="value" [# comment]` assignment vs. something we should leave raw.
+ */
+const is_comment_or_empty_after = (value, pos) => /^\s*(#.*)?$/.test(value.slice(pos + 1));
+/**
+ * Single-pass unescape for the inside of a `"..."` dotenv value.
+ *
+ * Recognizes `\\` → `\`, `\"` → `"`, `\n` → newline, `\r` → CR. Any other
+ * backslash is emitted literally. A chained `.replace(/\\\\/g, '\\').replace(...)`
+ * would mishandle real-backslash followed by escaped-quote (`\\"` on disk
+ * = `[\][\]["]` would collapse to `"` instead of `\"`).
+ */
+const unescape_double_quoted = (s) => {
+    let result = '';
+    let i = 0;
+    while (i < s.length) {
+        const ch = s[i];
+        if (ch === '\\' && i + 1 < s.length) {
+            const next = s[i + 1];
+            if (next === '\\' || next === '"') {
+                result += next;
+                i += 2;
+                continue;
+            }
+            if (next === 'n') {
+                result += '\n';
+                i += 2;
+                continue;
+            }
+            if (next === 'r') {
+                result += '\r';
+                i += 2;
+                continue;
+            }
+        }
+        result += ch;
+        i++;
+    }
+    return result;
+};
 /**
  * Load and parse an env file.
  *
+ * Returns null only when the file does not exist. Other read errors
+ * (permission denied, I/O failure, etc.) are re-thrown so callers can
+ * distinguish "no file" from "couldn't read".
+ *
  * @param runtime - runtime with `read_text_file` capability
  * @param path - path to env file
  * @returns parsed env record, or null if file doesn't exist
@@ -46,7 +142,10 @@ export const load_env_file = async (runtime, path) => {
         const content = await runtime.read_text_file(path);
         return parse_dotenv(content);
     }
-    catch {
-        return null;
+    catch (error) {
+        // Node (`ENOENT`) and Deno (`Deno.errors.NotFound`) — handle both.
+        if (error?.code === 'ENOENT' || error?.name === 'NotFound')
+            return null;
+        throw error;
     }
 };

package/dist/env/update_env_variable.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Write updates to `.env` files while preserving formatting.
+ *
+ * @module
+ */
+/**
+ * Options for updating environment variables in a .env file.
+ */
+export interface UpdateEnvVariableOptions {
+    /** Path to the .env file. */
+    env_file_path: string;
+    /** Function to read file contents (defaults to `node:fs/promises` `readFile`). */
+    read_file?: (path: string, encoding: string) => Promise<string>;
+    /** Function to write file contents (defaults to `node:fs/promises` `writeFile`). */
+    write_file?: (path: string, content: string, encoding: string) => Promise<void>;
+}
+/**
+ * Updates or adds an environment variable in the .env file.
+ * Preserves existing formatting, comments, and other variables.
+ *
+ * Behavior:
+ * - **Duplicate keys**: updates the LAST occurrence (matches dotenv behavior)
+ * - **Inline comments**: preserved after the value (e.g., `KEY=value # comment`)
+ * - **Quote style**: preserved from original (quoted/unquoted)
+ *
+ * @warning Not atomic; not safe for concurrent writers. Reads the file, mutates
+ * in memory, then writes it back — a crash or concurrent write can corrupt
+ * the file. Acceptable for single-user, infrequent edits; revisit if a
+ * concurrent-writer consumer emerges.
+ *
+ * @param key - the environment variable name (e.g., `'SOME_CONFIGURATION_KEY'`)
+ * @param value - the new value for the environment variable
+ * @param options - file path and optional read/write overrides
+ */
+export declare const update_env_variable: (key: string, value: string, options: UpdateEnvVariableOptions) => Promise<void>;
+//# sourceMappingURL=update_env_variable.d.ts.map

package/dist/env/update_env_variable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update_env_variable.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/env/update_env_variable.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACxC,6BAA6B;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,oFAAoF;IACpF,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,GAC/B,KAAK,MAAM,EACX,OAAO,MAAM,EACb,SAAS,wBAAwB,KAC/B,OAAO,CAAC,IAAI,CAmDd,CAAC"}

package/dist/env/update_env_variable.js

@@ -0,0 +1,160 @@
+/**
+ * Write updates to `.env` files while preserving formatting.
+ *
+ * @module
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+/**
+ * Updates or adds an environment variable in the .env file.
+ * Preserves existing formatting, comments, and other variables.
+ *
+ * Behavior:
+ * - **Duplicate keys**: updates the LAST occurrence (matches dotenv behavior)
+ * - **Inline comments**: preserved after the value (e.g., `KEY=value # comment`)
+ * - **Quote style**: preserved from original (quoted/unquoted)
+ *
+ * @warning Not atomic; not safe for concurrent writers. Reads the file, mutates
+ * in memory, then writes it back — a crash or concurrent write can corrupt
+ * the file. Acceptable for single-user, infrequent edits; revisit if a
+ * concurrent-writer consumer emerges.
+ *
+ * @param key - the environment variable name (e.g., `'SOME_CONFIGURATION_KEY'`)
+ * @param value - the new value for the environment variable
+ * @param options - file path and optional read/write overrides
+ */
+export const update_env_variable = async (key, value, options) => {
+    const { env_file_path, read_file = readFile, write_file = writeFile } = options;
+    const file_path = resolve(env_file_path);
+    let content = '';
+    try {
+        content = await read_file(file_path, 'utf-8');
+    }
+    catch (error) {
+        if (error?.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    // TODO CRLF: split on `/\r?\n/` + remember per-line delimiter (pinned by edge_cases.test.ts)
+    // Preserve trailing-newline state: `split('\n')` on `'a\n'` yields `['a', '']`
+    // — drop that trailing empty so appends don't insert a blank line. Re-add
+    // the trailing `\n` at the end if the original had one.
+    const has_trailing_newline = content.endsWith('\n');
+    const lines = content.split('\n');
+    if (has_trailing_newline)
+        lines.pop();
+    // Find the LAST occurrence of the key (matches dotenv "last wins" behavior)
+    const last_match_idx = find_last_key_line_index(lines, key);
+    const updated_lines = lines.map((line, idx) => {
+        if (idx === last_match_idx) {
+            const equals_pos = line.indexOf('=');
+            const value_part = line.substring(equals_pos + 1);
+            const inline_comment = extract_inline_comment(value_part);
+            const trimmed_value = value_part.trim();
+            const has_quotes = is_quoted_value(trimmed_value);
+            return has_quotes
+                ? `${key}=${quote_value(value)}${inline_comment}`
+                : `${key}=${value}${inline_comment}`;
+        }
+        return line;
+    });
+    if (last_match_idx === -1) {
+        if (content === '') {
+            await write_file(file_path, `${key}=${quote_value(value)}\n`, 'utf-8');
+            return;
+        }
+        updated_lines.push(`${key}=${quote_value(value)}`);
+    }
+    const updated_content = updated_lines.join('\n') + (has_trailing_newline ? '\n' : '');
+    await write_file(file_path, updated_content, 'utf-8');
+};
+// Keep this tokenization aligned with `parse_dotenv` in `./dotenv.ts`:
+// trim, skip empties/comments, split on the first `=`.
+const find_last_key_line_index = (lines, key) => {
+    if (!key)
+        return -1;
+    let last_match_idx = -1;
+    lines.forEach((line, idx) => {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            return;
+        const eq_index = trimmed.indexOf('=');
+        if (eq_index === -1)
+            return;
+        if (trimmed.slice(0, eq_index).trim() === key)
+            last_match_idx = idx;
+    });
+    return last_match_idx;
+};
+const extract_inline_comment = (value_part) => {
+    const trimmed_value = value_part.trim();
+    if (is_quoted_value(trimmed_value)) {
+        const quote_char = trimmed_value[0];
+        let closing_quote_idx = trimmed_value.indexOf(quote_char, 1);
+        while (closing_quote_idx > 0 && is_quote_escaped(trimmed_value, closing_quote_idx)) {
+            closing_quote_idx = trimmed_value.indexOf(quote_char, closing_quote_idx + 1);
+        }
+        if (closing_quote_idx !== -1) {
+            const after_quote = trimmed_value.substring(closing_quote_idx + 1);
+            const comment_match = /(\s*#.*)/.exec(after_quote);
+            const captured_comment = comment_match?.[1];
+            if (captured_comment) {
+                return captured_comment;
+            }
+        }
+    }
+    else {
+        // Leading `#` (e.g. `KEY=#c`) — whole trailing text is a comment. Emit
+        // with a space separator so it can't merge with the new value and the
+        // parser can round-trip the new value cleanly.
+        const trimmed_vp = value_part.trimStart();
+        if (trimmed_vp.startsWith('#'))
+            return ' ' + trimmed_vp;
+        // Require whitespace before `#` — symmetric with `parse_dotenv`, which
+        // strips `\s+#...` from unquoted values. URL fragments (no whitespace
+        // before `#`) are literal on both sides.
+        const comment_match = /(\s+#.*)/.exec(value_part);
+        const captured_comment = comment_match?.[1];
+        if (captured_comment) {
+            return captured_comment;
+        }
+    }
+    return '';
+};
+/**
+ * Checks if a quote character at a specific position is escaped by counting
+ * consecutive backslashes before it. An odd count means the quote is escaped.
+ */
+const is_quote_escaped = (str, quote_pos) => {
+    let backslash_count = 0;
+    let pos = quote_pos - 1;
+    while (pos >= 0 && str[pos] === '\\') {
+        backslash_count++;
+        pos--;
+    }
+    return backslash_count % 2 === 1;
+};
+const QUOTE_CHARS = ['"', "'"];
+const is_quoted_value = (value) => QUOTE_CHARS.some((char) => value.startsWith(char));
+/**
+ * Wraps a value for safe insertion into a double- or single-quoted dotenv line.
+ *
+ * - Uses `'...'` when the value contains `"` but no `'`, no `\n`, and no `\r`
+ *   (single-quoted dotenv values are taken literally — no escape processing,
+ *   and a literal newline would break the line into two).
+ * - Otherwise uses `"..."` with `\` → `\\`, `"` → `\"`, newline → `\n`, and
+ *   CR → `\r` so the line stays a single parseable assignment and round-trips
+ *   through `parse_dotenv` losslessly.
+ */
+const quote_value = (value) => {
+    if (value.includes('"') && !value.includes("'") && !has_newline_chars(value)) {
+        return `'${value}'`;
+    }
+    return `"${escape_for_double_quoted(value)}"`;
+};
+const has_newline_chars = (value) => value.includes('\n') || value.includes('\r');
+/**
+ * Order matters: backslashes must be escaped first so the introduced
+ * backslashes from later replacements aren't re-escaped.
+ */
+const escape_for_double_quoted = (value) => value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n').replace(/\r/g, '\\r');

package/dist/testing/mock_fs.d.ts

@@ -0,0 +1,21 @@
+/**
+ * In-memory file system mock for tests that use dependency-injected
+ * `read_file` and `write_file` callbacks. Avoids module-level mocking.
+ *
+ * @module
+ */
+export interface MockFs {
+    read_file: (path: string, encoding: string) => Promise<string>;
+    write_file: (path: string, content: string, encoding: string) => Promise<void>;
+    get_file: (path: string) => string | undefined;
+}
+/**
+ * Creates an in-memory file system for tests.
+ *
+ * `read_file` throws an `ENOENT`-tagged error for missing paths so callers
+ * can exercise the same "file doesn't exist" code path as `node:fs`.
+ *
+ * @param initial_files - starting contents keyed by absolute path
+ */
+export declare const create_mock_fs: (initial_files?: Record<string, string>) => MockFs;
+//# sourceMappingURL=mock_fs.d.ts.map

package/dist/testing/mock_fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock_fs.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/mock_fs.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,MAAM;IACtB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/D,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/E,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CAC/C;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,gBAAe,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,KAAG,MAuB3E,CAAC"}

package/dist/testing/mock_fs.js

@@ -0,0 +1,37 @@
+/**
+ * In-memory file system mock for tests that use dependency-injected
+ * `read_file` and `write_file` callbacks. Avoids module-level mocking.
+ *
+ * @module
+ */
+/**
+ * Creates an in-memory file system for tests.
+ *
+ * `read_file` throws an `ENOENT`-tagged error for missing paths so callers
+ * can exercise the same "file doesn't exist" code path as `node:fs`.
+ *
+ * @param initial_files - starting contents keyed by absolute path
+ */
+export const create_mock_fs = (initial_files = {}) => {
+    const files = { ...initial_files };
+    return {
+        // eslint-disable-next-line @typescript-eslint/require-await
+        read_file: async (path, _encoding) => {
+            if (!(path in files)) {
+                const error = new Error(`ENOENT: no such file or directory, open '${path}'`);
+                error.code = 'ENOENT';
+                throw error;
+            }
+            const file_content = files[path];
+            if (file_content === undefined) {
+                throw new Error(`File at ${path} exists in record but has undefined content`);
+            }
+            return file_content;
+        },
+        // eslint-disable-next-line @typescript-eslint/require-await
+        write_file: async (path, content, _encoding) => {
+            files[path] = content;
+        },
+        get_file: (path) => files[path],
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",