ludicord 4.1.2 → 4.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/README.md +2 -0
  2. package/dist/activity/index.d.ts +4 -0
  3. package/dist/activity/index.js +2 -0
  4. package/dist/activity/performance.d.ts +17 -0
  5. package/dist/activity/performance.js +56 -0
  6. package/dist/compiler/client-entry.js +1 -1
  7. package/dist/config/defaults.js +14 -0
  8. package/dist/config/index.d.ts +1 -1
  9. package/dist/config/types.d.ts +19 -0
  10. package/dist/docs/README.md +1 -1
  11. package/dist/docs/activity-rooms.md +1 -1
  12. package/dist/docs/ai-agents.md +1 -1
  13. package/dist/docs/api-reference.md +3 -1
  14. package/dist/docs/api-routes.md +1 -1
  15. package/dist/docs/build.md +1 -1
  16. package/dist/docs/cli.md +1 -1
  17. package/dist/docs/configuration.md +3 -1
  18. package/dist/docs/deployment.md +1 -1
  19. package/dist/docs/development.md +21 -1
  20. package/dist/docs/discord-developer-portal.md +1 -1
  21. package/dist/docs/discord-sdk.md +1 -1
  22. package/dist/docs/distribution.md +1 -1
  23. package/dist/docs/embeds.md +1 -1
  24. package/dist/docs/environment-variables.md +1 -1
  25. package/dist/docs/getting-started.md +1 -1
  26. package/dist/docs/installation.md +2 -2
  27. package/dist/docs/login.md +1 -1
  28. package/dist/docs/migration.md +15 -5
  29. package/dist/docs/mobile-layout.md +1 -1
  30. package/dist/docs/navigation.md +1 -1
  31. package/dist/docs/pages.md +1 -1
  32. package/dist/docs/participants.md +1 -1
  33. package/dist/docs/prefix-router.md +1 -1
  34. package/dist/docs/project-structure.md +1 -1
  35. package/dist/docs/recipes.md +1 -1
  36. package/dist/docs/security.md +1 -1
  37. package/dist/docs/start.md +1 -1
  38. package/dist/docs/state-and-effects.md +1 -1
  39. package/dist/docs/troubleshooting.md +1 -1
  40. package/dist/docs/voice-events.md +1 -1
  41. package/dist/docs/websockets.md +41 -1
  42. package/dist/index.d.ts +2 -2
  43. package/dist/index.js +1 -1
  44. package/dist/runtime/client/performance-data.d.ts +12 -0
  45. package/dist/runtime/client/performance-data.js +22 -0
  46. package/dist/runtime/client/startup.js +12 -0
  47. package/dist/runtime/index.d.ts +4 -0
  48. package/dist/runtime/index.js +2 -0
  49. package/dist/skills/ludicord/SKILL.md +2 -2
  50. package/dist/skills/ludicord/manifest.yaml +1 -1
  51. package/dist/version.js +1 -1
  52. package/dist/ws/client.d.ts +47 -0
  53. package/dist/ws/client.js +197 -13
  54. package/dist/ws/health.d.ts +1 -0
  55. package/dist/ws/health.js +2 -0
  56. package/dist/ws/index.d.ts +2 -2
  57. package/dist/ws/index.js +1 -1
  58. package/dist/ws/server.js +14 -0
  59. package/package.json +1 -1
package/README.md CHANGED
@@ -54,3 +54,5 @@ Point your existing project agent instructions at `node_modules/ludicord/AGENTS.
54
54
  Use one root and ordinary embeds by default. Prefix routing is optional for
55
55
  large projects with independent surfaces or a concrete need for separate
56
56
  pathname entry points, shells, or provider lifetimes.
57
+
58
+ Ludicord 4.2 adds configurable realtime recovery and data-only diagnostics: `useWSDiagnostics()` exposes connection latency and retries, while `useActivityPerformance({ enabled, sampleIntervalMs })` exposes optional frame samples and startup timings. Developers control sampling and build their own UI. See [WebSockets](https://ludicord.extra.codes/docs/websockets) and [performance data](https://ludicord.extra.codes/docs/development).
@@ -10,3 +10,7 @@ export { useActivityPresence } from "./presence.js";
10
10
  export type { LudicordActivityPresence } from "./presence.js";
11
11
  export { useSharedActivityState } from "./shared-state.js";
12
12
  export type { LudicordSharedActivityState } from "./shared-state.js";
13
+ export { useActivityPerformance } from "./performance.js";
14
+ export type { LudicordActivityPerformance, LudicordActivityPerformanceOptions } from "./performance.js";
15
+ export { getActivityStartupTimings, subscribeActivityStartupTimings } from "../runtime/client/performance-data.js";
16
+ export type { LudicordStartupTiming } from "../runtime/client/performance-data.js";
@@ -4,3 +4,5 @@ export { useActivityQuery, clearActivityQueryCache } from "./query.js";
4
4
  export { useGameLoop } from "./game-loop.js";
5
5
  export { useActivityPresence } from "./presence.js";
6
6
  export { useSharedActivityState } from "./shared-state.js";
7
+ export { useActivityPerformance } from "./performance.js";
8
+ export { getActivityStartupTimings, subscribeActivityStartupTimings } from "../runtime/client/performance-data.js";
@@ -0,0 +1,17 @@
1
+ import type { LudicordStartupTiming } from "../runtime/client/performance-data.js";
2
+ export interface LudicordActivityPerformanceOptions {
3
+ /** Calling the hook opts into sampling; false stops it. Default: true. */
4
+ readonly enabled?: boolean;
5
+ /** Minimum interval between frame samples published to React. Default: 1000ms. */
6
+ readonly sampleIntervalMs?: number;
7
+ }
8
+ export interface LudicordActivityPerformance {
9
+ readonly enabled: boolean;
10
+ /** Animation-frame frequency, not a GPU, paint, or server tick measurement. */
11
+ readonly fps: number | null;
12
+ readonly frameTimeMs: number | null;
13
+ readonly sampledFrames: number;
14
+ readonly startup: readonly LudicordStartupTiming[];
15
+ }
16
+ /** Data only; renders no UI and never sends telemetry. */
17
+ export declare function useActivityPerformance(options?: LudicordActivityPerformanceOptions): LudicordActivityPerformance;
@@ -0,0 +1,56 @@
1
+ import { useEffect, useMemo, useState, useSyncExternalStore } from "react";
2
+ import { EMPTY_STARTUP_TIMINGS, getActivityStartupTimings, subscribeActivityStartupTimings } from "../runtime/client/performance-data.js";
3
+ const EMPTY_FRAMES = Object.freeze({ fps: null, frameTimeMs: null, sampledFrames: 0 });
4
+ /** Data only; renders no UI and never sends telemetry. */
5
+ export function useActivityPerformance(options = {}) {
6
+ const enabled = options.enabled ?? true;
7
+ const interval = options.sampleIntervalMs ?? 1_000;
8
+ if (typeof enabled !== "boolean" || !Number.isSafeInteger(interval) || interval < 100 || interval > 60_000) {
9
+ throw new TypeError("LUDICORD2206: Performance sampling requires enabled to be boolean and sampleIntervalMs between 100 and 60000.");
10
+ }
11
+ const startup = useSyncExternalStore(subscribeActivityStartupTimings, getActivityStartupTimings, () => EMPTY_STARTUP_TIMINGS);
12
+ const [frames, setFrames] = useState(EMPTY_FRAMES);
13
+ useEffect(() => {
14
+ setFrames(EMPTY_FRAMES);
15
+ if (!enabled || typeof document === "undefined" || typeof requestAnimationFrame !== "function")
16
+ return;
17
+ let request = null;
18
+ let started = null;
19
+ let count = 0;
20
+ const tick = (time) => {
21
+ request = null;
22
+ if (document.visibilityState === "hidden")
23
+ return;
24
+ if (started === null)
25
+ started = time;
26
+ else {
27
+ count += 1;
28
+ const elapsed = time - started;
29
+ if (elapsed >= interval) {
30
+ setFrames({ fps: count * 1_000 / elapsed, frameTimeMs: elapsed / count, sampledFrames: count });
31
+ count = 0;
32
+ started = time;
33
+ }
34
+ }
35
+ request = requestAnimationFrame(tick);
36
+ };
37
+ const visibility = () => {
38
+ if (request !== null)
39
+ cancelAnimationFrame(request);
40
+ request = null;
41
+ started = null;
42
+ count = 0;
43
+ setFrames(EMPTY_FRAMES);
44
+ if (document.visibilityState !== "hidden")
45
+ request = requestAnimationFrame(tick);
46
+ };
47
+ visibility();
48
+ document.addEventListener("visibilitychange", visibility);
49
+ return () => {
50
+ document.removeEventListener("visibilitychange", visibility);
51
+ if (request !== null)
52
+ cancelAnimationFrame(request);
53
+ };
54
+ }, [enabled, interval]);
55
+ return useMemo(() => ({ enabled, ...(enabled ? frames : EMPTY_FRAMES), startup }), [enabled, frames, startup]);
56
+ }
@@ -93,7 +93,7 @@ export function clientEntry(root, manifests, config, development) {
93
93
  authRequired: config.discord.auth.required,
94
94
  defaultEmbed: config.activity.defaultEmbed,
95
95
  devFakeAuth: development && process.env.LUDICORD_DEV_FAKE_AUTH === "true",
96
- websocket: { enabled: config.websocket.enabled, reconnect: config.websocket.reconnect },
96
+ websocket: { enabled: config.websocket.enabled, reconnect: config.websocket.reconnect, connectionTimeout: config.websocket.connectionTimeout, healthCheck: config.websocket.healthCheck },
97
97
  };
98
98
  return `${imports.join("\n")}
99
99
  const disposeStartup = beginActivityStartup();
@@ -40,6 +40,12 @@ export function resolveConfig(config = {}) {
40
40
  },
41
41
  websocket: {
42
42
  enabled: config.websocket?.enabled ?? true,
43
+ connectionTimeout: config.websocket?.connectionTimeout ?? 10_000,
44
+ healthCheck: {
45
+ enabled: config.websocket?.healthCheck?.enabled ?? true,
46
+ interval: config.websocket?.healthCheck?.interval ?? 15_000,
47
+ timeout: config.websocket?.healthCheck?.timeout ?? 10_000,
48
+ },
43
49
  heartbeatInterval: config.websocket?.heartbeatInterval ?? 30_000,
44
50
  maxPayload: config.websocket?.maxPayload ?? 262_144,
45
51
  compression: config.websocket?.compression ?? false,
@@ -53,6 +59,7 @@ export function resolveConfig(config = {}) {
53
59
  attempts: config.websocket?.reconnect?.attempts ?? 10,
54
60
  initialDelay: config.websocket?.reconnect?.initialDelay ?? 500,
55
61
  maxDelay: config.websocket?.reconnect?.maxDelay ?? 10_000,
62
+ jitter: config.websocket?.reconnect?.jitter ?? 0.2,
56
63
  },
57
64
  },
58
65
  };
@@ -73,6 +80,13 @@ export function resolveConfig(config = {}) {
73
80
  integer(resolved.websocket.reconnect.attempts, 0, 10000, "websocket.reconnect.attempts");
74
81
  integer(resolved.websocket.reconnect.initialDelay, 0, 2_147_483_647, "websocket.reconnect.initialDelay");
75
82
  integer(resolved.websocket.reconnect.maxDelay, resolved.websocket.reconnect.initialDelay, 2_147_483_647, "websocket.reconnect.maxDelay");
83
+ integer(resolved.websocket.connectionTimeout, 100, 120_000, "websocket.connectionTimeout");
84
+ integer(resolved.websocket.healthCheck.interval, 1_000, 300_000, "websocket.healthCheck.interval");
85
+ integer(resolved.websocket.healthCheck.timeout, 100, 120_000, "websocket.healthCheck.timeout");
86
+ if (!Number.isFinite(resolved.websocket.reconnect.jitter) || resolved.websocket.reconnect.jitter < 0 || resolved.websocket.reconnect.jitter > 1)
87
+ fail("websocket.reconnect.jitter");
88
+ if (typeof resolved.websocket.healthCheck.enabled !== "boolean")
89
+ fail("websocket.healthCheck.enabled");
76
90
  if (!["allow", "mock", "error"].includes(resolved.activity.outsideDiscord))
77
91
  fail("activity.outsideDiscord");
78
92
  if (typeof resolved.activity.defaultEmbed !== "string" || !resolved.activity.defaultEmbed.trim())
@@ -1,2 +1,2 @@
1
1
  export { defineConfig, definePlugin } from "./types.js";
2
- export type { LudicordActivityConfig, LudicordAuthConfig, LudicordConfig, LudicordDiscordConfig, LudicordImportsConfig, LudicordPlugin, LudicordPluginContext, LudicordPluginHookResult, LudicordPluginLoadResult, LudicordPluginMode, LudicordPluginOption, LudicordPluginTarget, LudicordReconnectConfig, LudicordServerConfig, LudicordServerLimits, LudicordWebSocketConfig, OutsideDiscordBehavior, ResolvedLudicordConfig, } from "./types.js";
2
+ export type { LudicordActivityConfig, LudicordAuthConfig, LudicordConfig, LudicordDiscordConfig, LudicordImportsConfig, LudicordPlugin, LudicordPluginContext, LudicordPluginHookResult, LudicordPluginLoadResult, LudicordPluginMode, LudicordPluginOption, LudicordPluginTarget, LudicordReconnectConfig, LudicordServerConfig, LudicordServerLimits, LudicordWebSocketConfig, LudicordWSHealthCheckConfig, OutsideDiscordBehavior, ResolvedLudicordConfig, } from "./types.js";
@@ -58,9 +58,21 @@ export interface LudicordReconnectConfig {
58
58
  attempts?: number;
59
59
  initialDelay?: number;
60
60
  maxDelay?: number;
61
+ /** Random delay variation from 0 to 1; use 0 for deterministic backoff. */
62
+ jitter?: number;
63
+ }
64
+ export interface LudicordWSHealthCheckConfig {
65
+ enabled?: boolean;
66
+ /** Interval between negotiated application-level health probes, in milliseconds. */
67
+ interval?: number;
68
+ /** Maximum time to wait for a probe response, in milliseconds. */
69
+ timeout?: number;
61
70
  }
62
71
  export interface LudicordWebSocketConfig {
63
72
  enabled?: boolean;
73
+ /** Maximum browser connection handshake duration, in milliseconds. */
74
+ connectionTimeout?: number;
75
+ healthCheck?: LudicordWSHealthCheckConfig;
64
76
  heartbeatInterval?: number;
65
77
  maxPayload?: number;
66
78
  compression?: boolean;
@@ -154,6 +166,12 @@ export interface ResolvedLudicordConfig {
154
166
  };
155
167
  websocket: {
156
168
  enabled: boolean;
169
+ connectionTimeout: number;
170
+ healthCheck: {
171
+ enabled: boolean;
172
+ interval: number;
173
+ timeout: number;
174
+ };
157
175
  heartbeatInterval: number;
158
176
  maxPayload: number;
159
177
  compression: boolean;
@@ -167,6 +185,7 @@ export interface ResolvedLudicordConfig {
167
185
  attempts: number;
168
186
  initialDelay: number;
169
187
  maxDelay: number;
188
+ jitter: number;
170
189
  };
171
190
  };
172
191
  }
@@ -1,6 +1,6 @@
1
1
  # Ludicord documentation
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  ## Learn Ludicord
@@ -1,6 +1,6 @@
1
1
  # Activity Rooms
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  Every authenticated WebSocket client can join the Activity Instance room:
@@ -1,6 +1,6 @@
1
1
  # AI coding agents
2
2
 
3
- Ludicord 4.1.2 ships documentation and agent skills with the npm package. They
3
+ Ludicord 4.2.1 ships documentation and agent skills with the npm package. They
4
4
  are available offline and change together with the installed framework:
5
5
 
6
6
  ```text
@@ -1,9 +1,11 @@
1
1
  # Public API reference
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
  This page describes supported import paths and their purpose. The package includes TypeScript declarations for exact signatures and data shapes; use editor completion against the version you actually installed.
6
6
 
7
+ New in Ludicord 4.2.0: `useWSDiagnostics()` and `LudicordWSDiagnostics` from `ludicord/ws/client`; `useActivityPerformance()`, `getActivityStartupTimings()`, `subscribeActivityStartupTimings()`, and their types from `ludicord/runtime`, `ludicord/activity`, and `ludicord`. See [WebSocket data](websockets.md) and [performance sampling](development.md) for usage and controls. These APIs render no UI and send no telemetry.
8
+
7
9
  ## React and navigation
8
10
 
9
11
  | Import path | APIs |
@@ -1,6 +1,6 @@
1
1
  # API Routes
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  Create a `route.ts` anywhere under `app/`. For example, `app/api/hello/route.ts` serves `/api/hello`; `app/health/route.ts` serves `/health`. The `api/` directory is optional. Do not place another route file in the same directory.
@@ -1,6 +1,6 @@
1
1
  # Build
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  ```bash
package/dist/docs/cli.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # CLI reference
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
  Run commands through your generated package scripts or the locally installed `ludicord` executable.
6
6
 
@@ -1,6 +1,6 @@
1
1
  # Configuration reference
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
  Create `ludicord.config.mjs` in the application root:
6
6
 
@@ -100,6 +100,8 @@ CLI host/port flags override environment values; `HOST` and `PORT` override conf
100
100
 
101
101
  ## WebSockets
102
102
 
103
+ Client-recovery settings added in 4.2.0: `websocket.connectionTimeout` defaults to `10000` (range 100–120000ms); `websocket.healthCheck` defaults to `{ enabled: true, interval: 15000, timeout: 10000 }` (interval 1000–300000ms, timeout 100–120000ms); `websocket.reconnect.jitter` defaults to `0.2` (range 0–1). These values are validated before startup and passed to browser connections; `useWS()` options can override them for one connection. See [WebSockets](websockets.md) for capability negotiation and recovery behavior.
104
+
103
105
  All durations below are milliseconds.
104
106
 
105
107
  | Setting | Default | Meaning |
@@ -1,6 +1,6 @@
1
1
  # Deployment
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  Deploy Ludicord to a Node.js 20.19+ environment that supports long-lived HTTP upgrades for WebSockets.
@@ -1,6 +1,6 @@
1
1
  # Development runtime
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  `ludicord dev` owns the HTTP server, API routes, WebSockets, React hot updates, and diagnostics. It binds and announces the local URL before the initial compilation, then reports a clear `listening` → `compiling` → `ready` lifecycle. Requests wait for that first compilation instead of racing an incomplete server:
@@ -28,6 +28,26 @@ Run `ludicord routes` to inspect recursive page and embed ownership, `ludicord i
28
28
 
29
29
  ## Startup measurements
30
30
 
31
+ ### Performance data for your own UI
32
+
33
+ These data APIs are available in Ludicord 4.2.0. They render no panel, widget, or overlay and send no telemetry.
34
+
35
+ ```tsx
36
+ import { useActivityPerformance } from "ludicord/runtime";
37
+
38
+ const performanceData = useActivityPerformance({
39
+ enabled: showMyMetrics,
40
+ sampleIntervalMs: 1_000,
41
+ });
42
+ // Your component chooses how to display performanceData.
43
+ ```
44
+
45
+ Calling the hook opts into animation-frame sampling. `enabled: false` stops sampling and clears frame values. `sampleIntervalMs` accepts integers from 100 to 60000 and defaults to 1000. Sampling stops while hidden and resets when visible; React updates only when a sample is ready, rather than every frame. Strict Mode and unmount clean up the listener and pending frame request.
46
+
47
+ The result contains `enabled`, `fps`, `frameTimeMs`, `sampledFrames`, and `startup`. Frame values are `null` until a sample is available, while hidden, or when disabled. FPS measures animation-frame callback frequency, not GPU paint performance or server ticks. Startup data is independent of the frame-sampling toggle and contains only framework stage names, start/duration milliseconds, and `complete`, `error`, or `skipped` outcomes. Overlapping stages should not be added together.
48
+
49
+ Use `getActivityStartupTimings()` and `subscribeActivityStartupTimings(listener)` from `ludicord/runtime` for non-React consumers; subscriptions return cleanup. Snapshots are immutable, bounded, and reset for a new generated page scope. The hook returns empty startup data during server rendering. The same performance APIs are exported by `ludicord/activity` and the root `ludicord` entry point. Use `useWSDiagnostics()` from `ludicord/ws/client` for connection data alongside these samples.
50
+
31
51
  Generated Activity entries record local User Timing measures in development and production. Record an opening in the browser's Performance panel, or inspect them in the console:
32
52
 
33
53
  ```js
@@ -1,6 +1,6 @@
1
1
  # Discord Developer Portal Setup
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  1. Create a Discord application and enable Activities.
@@ -1,6 +1,6 @@
1
1
  # Discord SDK
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  Ludicord uses the official `@discord/embedded-app-sdk` package and initializes one SDK instance per Activity. `LudicordActivity` waits for SDK readiness before authentication and reuses shared subscriptions rather than registering one listener per component.
@@ -1,6 +1,6 @@
1
1
  # Package distribution and automated releases
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
  Ludicord uses a two-stage release pipeline so its public package links and npm provenance are correct without publishing the original TypeScript implementation.
6
6
 
@@ -1,6 +1,6 @@
1
1
  # Embeds
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  An embed is an internal Activity screen owned by its nearest ancestor page. Create `app/home/embed.tsx` for the root page:
@@ -1,6 +1,6 @@
1
1
  # Environment Variables
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  ```env
@@ -1,6 +1,6 @@
1
1
  # Getting Started
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  Create an Activity and start the development server:
@@ -1,11 +1,11 @@
1
1
  # Installation
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  Node.js 20.19 or newer is required. A new project is the simplest installation:
7
7
 
8
- The commands below install the latest **published** release. Confirm the registry reports 4.1.2 before upgrading a production deployment.
8
+ The commands below install the latest **published** release. Confirm the registry reports 4.2.1 before upgrading a production deployment.
9
9
 
10
10
  ```bash
11
11
  npx create-ludicord-app my-activity
@@ -1,6 +1,6 @@
1
1
  # Login and sessions
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  Ludicord authentication follows the Embedded App SDK authorization-code flow:
@@ -1,15 +1,25 @@
1
- # Upgrading to Ludicord 4.1.2
1
+ # Upgrading to Ludicord 4.2.1
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
- Check that both 4.1.2 packages are available before upgrading:
5
+ Check that both 4.2.1 packages are available before upgrading:
6
6
 
7
7
  ```bash
8
8
  npm view ludicord version
9
9
  npm view create-ludicord-app version
10
10
  ```
11
11
 
12
- Update an existing application's framework dependency with `npm install ludicord@4.1.2` (or your package-manager equivalent), update its lockfile, and create a fresh production build. The generator is for new projects; do not run it over an existing non-empty application. Existing V3 trees remain supported through legacy compatibility mode; follow [the routing migration](migration-v4.md) before switching file conventions.
12
+ Update an existing application's framework dependency with `npm install ludicord@4.2.1` (or your package-manager equivalent), update its lockfile, and create a fresh production build. The generator is for new projects; do not run it over an existing non-empty application. Existing V3 trees remain supported through legacy compatibility mode; follow [the routing migration](migration-v4.md) before switching file conventions.
13
+
14
+ ## Retry fixes in 4.2.1
15
+
16
+ This patch preserves scheduled backoff when `LudicordWebSocketConnection.start()` is called repeatedly and prevents non-finite delays for zero-delay connections with large retry budgets. Explicit `reconnect()` still starts immediately. No routes, API signatures, or UI migration is required.
17
+
18
+ ## Recovery and diagnostics in 4.2
19
+
20
+ Existing 4.x applications can upgrade without changing routes or UI. Client connections now use a 10-second handshake deadline, negotiated health probes, and 20% reconnect jitter. Review unusually low WebSocket rate limits because health probes share those limits; configure `websocket.healthCheck` or set `reconnect.jitter: 0` when needed. Missed application actions are never replayed automatically.
21
+
22
+ Use `useWSDiagnostics()` for connection snapshots and `useActivityPerformance({ enabled, sampleIntervalMs })` for optional frame samples and startup timings. These APIs render no UI; applications control sampling, presentation, logging, and resynchronization. See [WebSockets](websockets.md) and [performance data](development.md).
13
23
 
14
24
  ## Review your application
15
25
 
@@ -42,4 +52,4 @@ Update an existing application's framework dependency with `npm install ludicord
42
52
  - Every expected prefix pathname and default embed URL returns the correct shell.
43
53
  - Unknown production prefixes return 404 instead of falling through to an unrelated scope.
44
54
 
45
- Back up your current lockfile and keep the last deployable build for rollback. Review the detailed [V4 migration guide](migration-v4.md), [plugins and WebAssembly](plugins.md), [4.1.2 release notes](https://github.com/mrcholer/ludicord/blob/main/releases/v4/4.1.2.md), [security](security.md), and [deployment](deployment.md).
55
+ Back up your current lockfile and keep the last deployable build for rollback. Review the detailed [V4 migration guide](migration-v4.md), [plugins and WebAssembly](plugins.md), [4.2.1 release notes](https://github.com/mrcholer/ludicord/blob/main/releases/v4/4.2.1.md), [security](security.md), and [deployment](deployment.md).
@@ -1,6 +1,6 @@
1
1
  # Mobile and Layout
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  Ludicord installs four CSS custom properties:
@@ -1,6 +1,6 @@
1
1
  # Navigation and generated route types
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  Inside one prefix scope, use the Ludicord embed router. The current local embed is synchronized through the hash (`#/profile/user-one`) for deep links and browser back/forward, and hashes are validated against that prefix's generated registry:
@@ -1,6 +1,6 @@
1
1
  # Pages: page.tsx
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
  A default-exported React component in `app/page.tsx` renders at `/`. Nested `page.tsx` files render at their directory paths. A page can render plain UI without any embed:
6
6
 
@@ -1,6 +1,6 @@
1
1
  # Participants
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  ```tsx
@@ -1,6 +1,6 @@
1
1
  # Page scopes and optional prefix navigation
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
  ## Choose the simplest structure
6
6
 
@@ -1,6 +1,6 @@
1
1
  # Project structure
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
  The `app/` tree is the router. These four files define routes:
6
6
 
@@ -1,6 +1,6 @@
1
1
  # Usage recipes
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
  These small application examples illustrate the public API. They are not framework implementation or complete production applications.
6
6
 
@@ -1,6 +1,6 @@
1
1
  # Security
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  Ludicord encrypts and authenticates session cookies with AES-256-GCM, validates OAuth state, keeps server secrets out of React stores, requires sessions for API and WebSocket routes by default, and scans production client output for actual secret values.
@@ -1,6 +1,6 @@
1
1
  # Start
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  Build once, then run the existing output:
@@ -1,6 +1,6 @@
1
1
  # React state and effects
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
  Ludicord is React, so ordinary React state is the first choice for ordinary interface state. Framework hooks add Activity-aware lifecycles; they do not replace `useState`, `useReducer`, or correct effect cleanup.
6
6
 
@@ -1,6 +1,6 @@
1
1
  # Troubleshooting
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  Run the checks relevant to the failure:
@@ -1,6 +1,6 @@
1
1
  # Voice Events
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  Request the `rpc.voice.read` scope, then use:
@@ -1,6 +1,46 @@
1
1
  # WebSockets
2
2
 
3
- > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
+
5
+ ## Connection recovery and data APIs
6
+
7
+ The following APIs and recovery controls are available in Ludicord 4.2.0.
8
+
9
+ Client connections have a 10-second handshake deadline and bounded exponential retries with 20% random delay variation. Failed socket construction, transport errors, and stalled handshakes follow the same retry budget. Set `reconnect.jitter: 0` for deterministic delays. Manual close cancels all connection, retry, and health timers; `reconnect.enabled: false` disables automatic retries and browser-resume recovery.
10
+
11
+ Since 4.2.1, repeated `LudicordWebSocketConnection.start()` calls preserve a pending retry instead of bypassing its backoff. Use `reconnect()` when an immediate restart is intentional; it cancels the pending timer. Zero-delay retries remain finite even with large configured retry budgets.
12
+
13
+ New clients request a health capability using the framework-owned `ludicord_health=1` query parameter. Only authenticated upgrades advertise support, and health probes do not invoke application handlers. Older clients receive no additional capability messages; newer clients connected to older servers do not send probes. The flag grants no authentication or Activity membership.
14
+
15
+ Supported servers receive a probe every 15 seconds with a 10-second response deadline. Returning to a visible, online Activity checks an existing open connection as well. A missing response replaces the stale socket through the existing retry policy. Hidden time does not trigger a health failure. Probes share session, payload, message-rate, and byte-rate protections. Disable probes or tune their interval when an application uses unusually low rate limits.
16
+
17
+ ```tsx
18
+ import { useWS, useWSDiagnostics } from "ludicord/ws/client";
19
+
20
+ const connection = useWS("/ws/presence", {
21
+ connectionTimeout: 10_000,
22
+ healthCheck: { enabled: true, interval: 15_000, timeout: 10_000 },
23
+ reconnect: { enabled: true, attempts: 10, initialDelay: 500, maxDelay: 10_000, jitter: 0.2 },
24
+ });
25
+ const network = useWSDiagnostics(connection);
26
+ // Pass network to your own HUD, connection banner, or logging policy.
27
+ ```
28
+
29
+ `useWSDiagnostics()` subscribes to immutable snapshots separately from `useWS()`; ordinary message consumers do not rerender solely because latency changes. For non-reactive reads, use `connection.diagnostics` or `getDiagnostics()`. Non-React connections also expose `subscribeDiagnostics(listener)`, which returns cleanup.
30
+
31
+ | Field | Meaning |
32
+ | --- | --- |
33
+ | `status` | Current connection status |
34
+ | `connectionAttempts` | Total socket construction attempts, including the initial attempt |
35
+ | `reconnectAttempts` | Consecutive retry attempts; resets after a successful connection |
36
+ | `reconnectCount` | Successful connections after the first open |
37
+ | `nextReconnectDelayMs` | Scheduled retry delay, or `null` |
38
+ | `latencyMs` | Most recent round-trip probe time; `null` before a valid response and after disconnect |
39
+ | `lastConnectedAt` | Unix milliseconds of the most recent successful open, or `null` |
40
+ | `lastErrorCode` | Most recent framework transport or protocol/handler error code; cleared after a successful open |
41
+ | `lastClose` | Most recent received close code, reason, and clean-close flag, or `null` |
42
+
43
+ `LUDICORD9105` identifies handshake timeout, `LUDICORD9106` identifies health timeout, and `LUDICORD9107` identifies transport failure. These APIs mount no UI and send no telemetry. Treat close reasons as text when rendering your own UI. Missed actions are never replayed automatically; applications own idempotency and resynchronization. `useSharedActivityState()` continues subscribing for a fresh snapshot after reconnect.
4
44
 
5
45
 
6
46
  Create `app/ws/presence/socket.ts` for `/ws/presence`, or `app/live/socket.ts` for `/live`. The `ws/` folder is optional. A directory may contain only one route file. Use the full discovered URL in `useWS()`; no `/ws` prefix is added automatically.