@fuzdev/fuz_app 0.64.0 → 0.66.0

package/dist/testing/ws_round_trip.d.ts

@@ -5,8 +5,8 @@
  * specs + handlers; the harness constructs real `WSContext` instances
  * backed by test-owned `send`/`close` pairs, fakes the authenticated
  * Hono context (`request_context`, credential type, session id, api
- * token id), and exposes a `connect()` factory returning a
- * `MockWsClient` per connection.
+ * token id), and exposes a `connect()` factory returning a `WsClient`
+ * per connection.
  *
  * Three layers are exported:
  *
@@ -14,19 +14,19 @@
  *     `create_stub_upgrade`, `MinimalActionEnvironment`,
  *     `dispatch_ws_message`) — used by fuz_app's own dispatcher tests
  *     and by consumers wiring tight one-off tests.
- *   - **Harness** (`create_ws_test_harness`, `MockWsClient`,
- *     `keeper_identity`) — the high-level driver. Give it specs +
- *     handlers, get back `{transport, connect()}`. `connect()` is async
- *     and resolves after `on_socket_open` completes, so broadcasts sent
- *     immediately after `await harness.connect()` reach the client.
- *   - **Round-trip helpers** — `is_notification` / `is_notification_with`
- *     / `is_response_for` predicates, JSON-RPC wire-frame types
- *     (`JsonrpcNotificationFrame`, `JsonrpcSuccessResponseFrame`,
- *     `JsonrpcErrorResponseFrame` — distinct from the runtime Zod types
- *     in `http/jsonrpc.ts` so tests can narrow `params` / `result`),
- *     and `build_broadcast_api` for wiring a typed broadcast API against
- *     the harness's transport. Used by consumer round-trip test suites
- *     to replace ~100 lines of verbatim-identical glue.
+ *   - **Harness** (`create_ws_test_harness`, `keeper_identity`) — the
+ *     high-level driver. Give it specs + handlers, get back
+ *     `{transport, connect()}`. `connect()` is async and resolves after
+ *     `on_socket_open` completes, so broadcasts sent immediately after
+ *     `await harness.connect()` reach the client. Returns a `WsClient`
+ *     (shared interface — see `transports/ws_client.ts`); the same
+ *     interface is implemented by `transports/ws_transport.ts` for
+ *     cross-process tests.
+ *   - **Broadcast wiring** — `build_broadcast_api` for wiring a typed
+ *     broadcast API against the harness's transport. Wire-frame types
+ *     + predicates (`is_notification`, `is_response_for`,
+ *     `JsonrpcNotificationFrame`, ...) live in `transports/ws_client.ts`
+ *     so both in-process and cross-process drivers reference one source.
  *
  * Hono's wire upgrade is skipped — the Node test runtime has no
  * `@hono/node-ws` adapter — but the full dispatch path is exercised
@@ -47,7 +47,7 @@ import { type RegisterActionWsOptions } from '../actions/register_action_ws.js';
 import { BackendWebsocketTransport } from '../actions/transports_ws_backend.js';
 import { type RequestContext } from '../auth/request_context.js';
 import { type CredentialType } from '../hono_context.js';
-import { JSONRPC_VERSION } from '../http/jsonrpc.js';
+import { type WsClient } from './transports/ws_client.js';
 /**
  * A `WSContext` paired with capture arrays. Use `sends` to assert on
  * outgoing frames; use `closes` to assert on revocation / close.
@@ -127,92 +127,6 @@ export interface WsConnectIdentity {
     /** Roles to grant via active role_grants. Pass `[ROLE_KEEPER]` for keeper actions. */
     roles?: Array<string>;
 }
-/** A mock WS client: send requests, inspect/await incoming messages. */
-export interface MockWsClient {
-    /**
-     * Send a JSON-RPC message (request or notification) to the server.
-     *
-     * @throws Error if called after `close()` resolves — the harness rejects
-     *   sends on a closed socket so post-close test bugs surface immediately.
-     */
-    send: (message: unknown) => Promise<void>;
-    /**
-     * Send a JSON-RPC request and await its response. Resolves with the
-     * `result`; throws with a useful message (code, text, and any `data`
-     * payload) on an error frame — without this, asserting on
-     * `result.foo` for a failed request throws
-     * `Cannot read property 'foo' of undefined`, which hides the real
-     * cause. Use `send` + `wait_for(is_response_for(id))` directly when
-     * you need to assert on the error frame itself.
-     *
-     * @throws Error if the server returns a JSON-RPC error frame for `id`,
-     *   or if `wait_for` times out before a matching response arrives.
-     */
-    request: <R = unknown>(id: number | string, method: string, params: unknown, timeout_ms?: number) => Promise<R>;
-    /**
-     * Close the connection, firing `onClose`. Returns a promise that
-     * resolves once `on_socket_close` (and the transport's own cleanup)
-     * have completed — tests that assert on post-close state should await.
-     */
-    close: (code?: number, reason?: string) => Promise<void>;
-    /** Every message the server has sent, in arrival order. */
-    readonly messages: ReadonlyArray<unknown>;
-    /**
-     * Wait until a message satisfies `predicate`. Matches are checked
-     * against already-received messages first, then new arrivals until
-     * the timeout (defaults to 1000ms).
-     *
-     * When `predicate` is a type guard (e.g. `is_notification_with<P>`),
-     * the result is narrowed automatically and callers don't need to
-     * spell `<JsonrpcNotificationFrame<P>>` on the call site.
-     *
-     * @throws Error if `timeout_ms` elapses before a matching message
-     *   arrives — the pending waiter is dropped from the internal list so
-     *   later messages don't keep iterating it.
-     */
-    wait_for: {
-        <T>(predicate: (msg: unknown) => msg is T, timeout_ms?: number): Promise<T>;
-        <T = unknown>(predicate: (msg: unknown) => boolean, timeout_ms?: number): Promise<T>;
-    };
-}
-export interface JsonrpcNotificationFrame<P = unknown> {
-    jsonrpc: typeof JSONRPC_VERSION;
-    method: string;
-    params: P;
-}
-export interface JsonrpcSuccessResponseFrame<R = unknown> {
-    jsonrpc: typeof JSONRPC_VERSION;
-    id: number | string;
-    result: R;
-}
-export interface JsonrpcErrorResponseFrame<D = unknown> {
-    jsonrpc: typeof JSONRPC_VERSION;
-    id: number | string;
-    error: {
-        code: number;
-        message: string;
-        data?: D;
-    };
-}
-/** Predicate matching a JSON-RPC notification with the given method name. */
-export declare const is_notification: (method: string) => (msg: unknown) => boolean;
-/**
- * Type-guard combinator: match a notification whose typed `params` satisfies
- * `match`. Collapses the common test pattern of casting `msg` to
- * `JsonrpcNotificationFrame<P>` in every predicate body.
- *
- * ```ts
- * const match_roster_for = (id: Uuid) =>
- *   is_notification_with<RosterChangedParams>(
- *     WORLD_METHODS.roster_changed,
- *     (params) => params.character_id === id && !params.removed,
- *   );
- * const roster = await client.wait_for(match_roster_for(char_id));
- * ```
- */
-export declare const is_notification_with: <P>(method: string, match: (params: P) => boolean) => (msg: unknown) => msg is JsonrpcNotificationFrame<P>;
-/** Predicate matching a JSON-RPC response frame (success or error) for the given request id. */
-export declare const is_response_for: (id: number | string) => (msg: unknown) => boolean;
 /** Options for `create_ws_test_harness`. */
 export interface CreateWsTestHarnessOptions {
     /**
@@ -246,8 +160,12 @@ export interface WsTestHarness {
      * immediately after the `await` reach the connection. Earlier
      * revisions returned synchronously and required a `settle_open()`
      * microtask drain — no longer necessary.
+     *
+     * Returns the shared `WsClient` interface — same surface the
+     * cross-process driver in `transports/ws_transport.ts` implements,
+     * so assertion helpers and suite bodies work against either impl.
      */
-    connect: (identity?: WsConnectIdentity) => Promise<MockWsClient>;
+    connect: (identity?: WsConnectIdentity) => Promise<WsClient>;
 }
 /**
  * Create a WebSocket test harness for the given specs + handlers.

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

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

package/dist/testing/ws_round_trip.js

@@ -5,8 +5,8 @@
  * specs + handlers; the harness constructs real `WSContext` instances
  * backed by test-owned `send`/`close` pairs, fakes the authenticated
  * Hono context (`request_context`, credential type, session id, api
- * token id), and exposes a `connect()` factory returning a
- * `MockWsClient` per connection.
+ * token id), and exposes a `connect()` factory returning a `WsClient`
+ * per connection.
  *
  * Three layers are exported:
  *
@@ -14,19 +14,19 @@
  *     `create_stub_upgrade`, `MinimalActionEnvironment`,
  *     `dispatch_ws_message`) — used by fuz_app's own dispatcher tests
  *     and by consumers wiring tight one-off tests.
- *   - **Harness** (`create_ws_test_harness`, `MockWsClient`,
- *     `keeper_identity`) — the high-level driver. Give it specs +
- *     handlers, get back `{transport, connect()}`. `connect()` is async
- *     and resolves after `on_socket_open` completes, so broadcasts sent
- *     immediately after `await harness.connect()` reach the client.
- *   - **Round-trip helpers** — `is_notification` / `is_notification_with`
- *     / `is_response_for` predicates, JSON-RPC wire-frame types
- *     (`JsonrpcNotificationFrame`, `JsonrpcSuccessResponseFrame`,
- *     `JsonrpcErrorResponseFrame` — distinct from the runtime Zod types
- *     in `http/jsonrpc.ts` so tests can narrow `params` / `result`),
- *     and `build_broadcast_api` for wiring a typed broadcast API against
- *     the harness's transport. Used by consumer round-trip test suites
- *     to replace ~100 lines of verbatim-identical glue.
+ *   - **Harness** (`create_ws_test_harness`, `keeper_identity`) — the
+ *     high-level driver. Give it specs + handlers, get back
+ *     `{transport, connect()}`. `connect()` is async and resolves after
+ *     `on_socket_open` completes, so broadcasts sent immediately after
+ *     `await harness.connect()` reach the client. Returns a `WsClient`
+ *     (shared interface — see `transports/ws_client.ts`); the same
+ *     interface is implemented by `transports/ws_transport.ts` for
+ *     cross-process tests.
+ *   - **Broadcast wiring** — `build_broadcast_api` for wiring a typed
+ *     broadcast API against the harness's transport. Wire-frame types
+ *     + predicates (`is_notification`, `is_response_for`,
+ *     `JsonrpcNotificationFrame`, ...) live in `transports/ws_client.ts`
+ *     so both in-process and cross-process drivers reference one source.
  *
  * Hono's wire upgrade is skipped — the Node test runtime has no
  * `@hono/node-ws` adapter — but the full dispatch path is exercised
@@ -47,9 +47,9 @@ import { BackendWebsocketTransport } from '../actions/transports_ws_backend.js';
 import { REQUEST_CONTEXT_KEY } from '../auth/request_context.js';
 import { ROLE_KEEPER } from '../auth/role_schema.js';
 import { ACCOUNT_ID_KEY, AUTH_API_TOKEN_ID_KEY, CREDENTIAL_TYPE_KEY, TEST_CONTEXT_PRESET_KEY, } from '../hono_context.js';
-import { JSONRPC_VERSION } from '../http/jsonrpc.js';
-import { create_jsonrpc_request, is_jsonrpc_error_response, is_jsonrpc_notification, is_jsonrpc_response, } from '../http/jsonrpc_helpers.js';
+import { create_jsonrpc_request } from '../http/jsonrpc_helpers.js';
 import { create_test_account, create_test_actor, create_test_role_grant } from './entities.js';
+import { WS_CLIENT_DEFAULT_TIMEOUT_MS, is_response_for, } from './transports/ws_client.js';
 /**
  * Build a real `WSContext` backed by in-memory `send`/`close` capture.
  * Parsing of outgoing frames is left to the caller — `sends` holds the
@@ -138,28 +138,6 @@ export const dispatch_ws_message = async (on_message, event, ws) => {
     if (result instanceof Promise)
         await result;
 };
-/** Predicate matching a JSON-RPC notification with the given method name. */
-export const is_notification = (method) => (msg) => is_jsonrpc_notification(msg) && msg.method === method;
-/**
- * Type-guard combinator: match a notification whose typed `params` satisfies
- * `match`. Collapses the common test pattern of casting `msg` to
- * `JsonrpcNotificationFrame<P>` in every predicate body.
- *
- * ```ts
- * const match_roster_for = (id: Uuid) =>
- *   is_notification_with<RosterChangedParams>(
- *     WORLD_METHODS.roster_changed,
- *     (params) => params.character_id === id && !params.removed,
- *   );
- * const roster = await client.wait_for(match_roster_for(char_id));
- * ```
- */
-export const is_notification_with = (method, match) => (msg) => is_jsonrpc_notification(msg) &&
-    msg.method === method &&
-    match(msg.params);
-/** Predicate matching a JSON-RPC response frame (success or error) for the given request id. */
-export const is_response_for = (id) => (msg) => (is_jsonrpc_response(msg) || is_jsonrpc_error_response(msg)) && msg.id === id;
-const DEFAULT_TIMEOUT_MS = 1000;
 /**
  * Build a `RequestContext` with a fresh UUID account/actor and role_grants
  * for the supplied roles. Used by the high-level harness so callers can
@@ -266,6 +244,11 @@ export const create_ws_test_harness = (options) => {
         };
         const received = [];
         const waiters = [];
+        // Resolvers awaiting a server-initiated close — fired by the
+        // `WSContext.close` callback below so `wait_for_close` resolves
+        // whether the dispatcher (e.g. an auth-guard revocation) or the
+        // test closed the socket.
+        const close_waiters = [];
         let is_closed = false;
         // Captured in `ws.close` below; `client.close(...)` returns it so
         // tests can await async `on_socket_close` cleanup.
@@ -291,6 +274,8 @@ export const create_ws_test_harness = (options) => {
                 if (is_closed)
                     return;
                 is_closed = true;
+                for (const resolve of close_waiters.splice(0))
+                    resolve();
                 const close_event = new Event('close');
                 Object.defineProperties(close_event, {
                     code: { value: code ?? 1000, writable: false },
@@ -315,7 +300,7 @@ export const create_ws_test_harness = (options) => {
         // onOpen is typed as `void` by Hono but `register_action_ws`
         // returns a promise when `on_socket_open` does async bootstrap.
         await events.onOpen?.(new Event('open'), ws);
-        const wait_for_impl = (predicate, timeout_ms = DEFAULT_TIMEOUT_MS) => {
+        const wait_for_impl = (predicate, timeout_ms = WS_CLIENT_DEFAULT_TIMEOUT_MS) => {
             for (const msg of received) {
                 if (predicate(msg))
                     return Promise.resolve(msg);
@@ -371,6 +356,23 @@ export const create_ws_test_harness = (options) => {
                     await close_pending;
             },
             wait_for: wait_for_impl,
+            wait_for_close: (timeout_ms = WS_CLIENT_DEFAULT_TIMEOUT_MS) => {
+                if (is_closed)
+                    return Promise.resolve(true);
+                return new Promise((resolve) => {
+                    const on_close = () => {
+                        clearTimeout(timer);
+                        resolve(true);
+                    };
+                    const timer = setTimeout(() => {
+                        const i = close_waiters.indexOf(on_close);
+                        if (i >= 0)
+                            close_waiters.splice(i, 1);
+                        resolve(false);
+                    }, timeout_ms);
+                    close_waiters.push(on_close);
+                });
+            },
         };
     };
     return { transport, connect };

package/dist/ui/CLAUDE.md

@@ -89,9 +89,11 @@ pattern rather than reintroducing prop-drilling.
   `SidebarState` if `sidebar_state` prop is not supplied).
 - `ColumnLayout.svelte` — fixed `aside` column + fluid `children`
   column; `column_width = '280px'`.
-- `MenuLink.svelte` — SvelteKit `<a>` with `selected`/`highlighted`
-  derived from `page.url.pathname`. Takes `path` (resolved via
-  `resolve` from `$app/paths`).
+- `MenuLink.svelte` — SvelteKit `<a>` with `selected` derived from
+  `page.url.pathname` (fires for exact match + descendant pages).
+  Exact matches additionally get `aria-current="page"`. Takes `path`
+  (resolved via `resolve` from `$app/paths`). The `.highlighted` name is
+  intentionally free for orthogonal emphasis (badges, recent activity).
 - `sidebar_state.svelte.ts` — `SidebarState` (with `activate()` cleanup
   pattern, optional reactive `enabled` getter), `sidebar_state_context`.
 

package/dist/ui/MenuLink.svelte

@@ -1,8 +1,19 @@
 <script lang="ts">
 	/**
 	 * SvelteKit-aware navigation link. Resolves `path` via `resolve` from
-	 * `$app/paths`, then derives `selected` (exact match) and `highlighted`
-	 * (current path is below `path`) from `page.url.pathname`.
+	 * `$app/paths`, then derives `selected` from `page.url.pathname` —
+	 * fires for both the exact page (`/admin/repos`) and any descendant
+	 * page (`/admin/repos/foo/log`). Exact matches additionally carry
+	 * `aria-current="page"` so CSS / assistive tech can distinguish
+	 * "this exact page" from "current section" when needed.
+	 *
+	 * The earlier `highlighted` flag (which fired only on the prefix-only
+	 * case) was dropped: in every practical use it sat next to `.selected`
+	 * with a near-identical visual treatment and just made callers compute
+	 * two booleans for what reads to users as one "you are here" state.
+	 * The `highlighted` *name* is now free for orthogonal emphasis (recent
+	 * activity, unread badges, search matches) — that's how `fuz_ui`'s
+	 * `DocsPageLinks` already uses it.
 	 *
 	 * @module
 	 */
@@ -15,31 +26,20 @@
 
 	const {
 		path,
-		highlighted,
 		children,
 		...rest
 	}: OmitStrict<SvelteHTMLElements['a'], 'href' | 'children'> & {
 		/** Route path passed to `resolve` from `$app/paths` to compute `href`. */
 		path: string;
-		/** Override the auto-derived `highlighted` flag (defaults to "current path is below `href`"). */
-		highlighted?: boolean;
 		children?: Snippet;
 	} = $props();
 
 	const href = $derived(resolve(path as any));
-	const selected = $derived(href === page.url.pathname);
-	const is_highlighted = $derived(
-		highlighted ?? (page.url.pathname.startsWith(href + '/') && !selected),
-	);
+	const is_exact = $derived(href === page.url.pathname);
+	const selected = $derived(is_exact || page.url.pathname.startsWith(href + '/'));
 </script>
 
 <!-- eslint-disable-next-line svelte/no-navigation-without-resolve -->
-<a {href} class:selected class:highlighted={is_highlighted} {...rest}>
+<a {href} class:selected aria-current={is_exact ? 'page' : undefined} {...rest}>
 	{@render children?.()}
 </a>
-
-<style>
-	.highlighted {
-		background-color: var(--fg_10);
-	}
-</style>

package/dist/ui/MenuLink.svelte.d.ts

@@ -1,7 +1,18 @@
 /**
      * SvelteKit-aware navigation link. Resolves `path` via `resolve` from
-     * `$app/paths`, then derives `selected` (exact match) and `highlighted`
-     * (current path is below `path`) from `page.url.pathname`.
+     * `$app/paths`, then derives `selected` from `page.url.pathname` —
+     * fires for both the exact page (`/admin/repos`) and any descendant
+     * page (`/admin/repos/foo/log`). Exact matches additionally carry
+     * `aria-current="page"` so CSS / assistive tech can distinguish
+     * "this exact page" from "current section" when needed.
+     *
+     * The earlier `highlighted` flag (which fired only on the prefix-only
+     * case) was dropped: in every practical use it sat next to `.selected`
+     * with a near-identical visual treatment and just made callers compute
+     * two booleans for what reads to users as one "you are here" state.
+     * The `highlighted` *name* is now free for orthogonal emphasis (recent
+     * activity, unread badges, search matches) — that's how `fuz_ui`'s
+     * `DocsPageLinks` already uses it.
      *
      * @module
      */
@@ -11,8 +22,6 @@ import type { OmitStrict } from '@fuzdev/fuz_util/types.js';
 type $$ComponentProps = OmitStrict<SvelteHTMLElements['a'], 'href' | 'children'> & {
     /** Route path passed to `resolve` from `$app/paths` to compute `href`. */
     path: string;
-    /** Override the auto-derived `highlighted` flag (defaults to "current path is below `href`"). */
-    highlighted?: boolean;
     children?: Snippet;
 };
 declare const MenuLink: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/ui/MenuLink.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MenuLink.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/MenuLink.svelte"],"names":[],"mappings":"AAGA;;;;;;OAMI;AACJ,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,QAAQ,CAAC;AACpC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAC;AAGxD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,2BAA2B,CAAC;AAEzD,KAAK,gBAAgB,GAAI,UAAU,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC,GAAG;IACnF,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAiCH,QAAA,MAAM,QAAQ,sDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"MenuLink.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/ui/MenuLink.svelte"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;OAiBI;AACJ,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,QAAQ,CAAC;AACpC,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,iBAAiB,CAAC;AAGxD,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,2BAA2B,CAAC;AAEzD,KAAK,gBAAgB,GAAI,UAAU,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC,GAAG;IACnF,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AA4BH,QAAA,MAAM,QAAQ,sDAAwC,CAAC;AACvD,KAAK,QAAQ,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;AAC5C,eAAe,QAAQ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.64.0",
+  "version": "0.66.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",
@@ -30,6 +30,7 @@
     "hono": ">=4",
     "pg": ">=8",
     "svelte": "^5",
+    "ws": ">=8",
     "zod": ">=4"
   },
   "peerDependenciesMeta": {
@@ -38,6 +39,9 @@
     },
     "pg": {
       "optional": true
+    },
+    "ws": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -46,11 +50,11 @@
     "@fuzdev/fuz_code": "^0.45.1",
     "@fuzdev/fuz_css": "^0.59.0",
     "@fuzdev/fuz_ui": "^0.192.0",
-    "@fuzdev/fuz_util": "^0.59.0",
+    "@fuzdev/fuz_util": "^0.60.1",
     "@fuzdev/gro": "^0.199.0",
     "@jridgewell/trace-mapping": "^0.3.31",
     "@node-rs/argon2": "^2.0.2",
-    "@ryanatkn/eslint-config": "^0.11.0",
+    "@ryanatkn/eslint-config": "^0.12.1",
     "@sveltejs/acorn-typescript": "^1.0.9",
     "@sveltejs/adapter-static": "^3.0.10",
     "@sveltejs/kit": "^2.55.0",
@@ -58,11 +62,12 @@
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@types/estree": "^1.0.8",
     "@types/pg": "^8.18.0",
+    "@types/ws": "^8.18.1",
     "@webref/css": "^8.2.0",
     "eslint": "^9.39.4",
     "eslint-plugin-svelte": "^3.15.1",
     "esm-env": "^1.2.2",
-    "hono": "^4.12.7",
+    "hono": "^4.12.21",
     "jsdom": "^28.1.0",
     "magic-string": "^0.30.21",
     "pg": "^8.20.0",
@@ -76,6 +81,7 @@
     "typescript-eslint": "^8.57.0",
     "vite": "^7.3.1",
     "vitest": "^4.0.18",
+    "ws": "^8.20.1",
     "zimmerframe": "^1.1.4",
     "zod": "^4.3.6"
   },