ludicord 4.1.1 → 4.2.0

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 (64) 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 +24 -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 +17 -2
  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 +11 -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 +2 -2
  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 +39 -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/runtime/server/dev-server.js +2 -2
  50. package/dist/server/request-security.d.ts +2 -0
  51. package/dist/server/request-security.js +17 -6
  52. package/dist/skills/ludicord/SKILL.md +2 -2
  53. package/dist/skills/ludicord/manifest.yaml +1 -1
  54. package/dist/skills/ludicord/references/config-deploy.md +5 -1
  55. package/dist/version.js +1 -1
  56. package/dist/ws/client.d.ts +47 -0
  57. package/dist/ws/client.js +193 -12
  58. package/dist/ws/health.d.ts +1 -0
  59. package/dist/ws/health.js +2 -0
  60. package/dist/ws/index.d.ts +2 -2
  61. package/dist/ws/index.js +1 -1
  62. package/dist/ws/server.d.ts +1 -1
  63. package/dist/ws/server.js +17 -2
  64. 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";
@@ -35,6 +35,11 @@ export interface LudicordServerLimits {
35
35
  export interface LudicordServerConfig {
36
36
  port?: number;
37
37
  host?: string;
38
+ /**
39
+ * Hostnames allowed by HTTP, WebSocket and development asset routes.
40
+ * Restricted lists also include the configured application's exact
41
+ * `<clientId>.discordsays.com` hostname. `true` accepts every host.
42
+ */
38
43
  allowedHosts?: true | readonly string[];
39
44
  /**
40
45
  * Browser origins allowed to call framework routes. `discord-activity`
@@ -53,9 +58,21 @@ export interface LudicordReconnectConfig {
53
58
  attempts?: number;
54
59
  initialDelay?: number;
55
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;
56
70
  }
57
71
  export interface LudicordWebSocketConfig {
58
72
  enabled?: boolean;
73
+ /** Maximum browser connection handshake duration, in milliseconds. */
74
+ connectionTimeout?: number;
75
+ healthCheck?: LudicordWSHealthCheckConfig;
59
76
  heartbeatInterval?: number;
60
77
  maxPayload?: number;
61
78
  compression?: boolean;
@@ -149,6 +166,12 @@ export interface ResolvedLudicordConfig {
149
166
  };
150
167
  websocket: {
151
168
  enabled: boolean;
169
+ connectionTimeout: number;
170
+ healthCheck: {
171
+ enabled: boolean;
172
+ interval: number;
173
+ timeout: number;
174
+ };
152
175
  heartbeatInterval: number;
153
176
  maxPayload: number;
154
177
  compression: boolean;
@@ -162,6 +185,7 @@ export interface ResolvedLudicordConfig {
162
185
  attempts: number;
163
186
  initialDelay: number;
164
187
  maxDelay: number;
188
+ jitter: number;
165
189
  };
166
190
  };
167
191
  }
@@ -1,6 +1,6 @@
1
1
  # Ludicord documentation
2
2
 
3
- > Documentation for Ludicord 4.1.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1 ships documentation and agent skills with the npm package. They
3
+ Ludicord 4.2.0 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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
 
@@ -83,10 +83,25 @@ Targets must be `.` or remain inside the project through a `./` path. Absolute p
83
83
 
84
84
  The `"discord-activity"` policy derives `https://<clientId>.discordsays.com` from `discord.clientId` or `LUDICORD_DISCORD_CLIENT_ID`. It also permits normal same-origin requests and never trusts a wildcard for every Activity. Use `"same-origin"` for a host-only policy. When an array adds another trusted browser origin, include both built-in policies explicitly: `["same-origin", "discord-activity", "https://admin.example.com"]`.
85
85
 
86
- Use an explicit host list when appropriate. CLI host/port flags override environment values; `HOST` and `PORT` override configured defaults.
86
+ Use an explicit host list when appropriate. Ludicord automatically adds the
87
+ configured application's exact `<clientId>.discordsays.com` hostname to that list
88
+ for HTTP requests, WebSocket upgrades and development assets. Other Activities'
89
+ proxy hostnames are not added. The effective Client ID comes from configuration
90
+ in development and uses the supported runtime environment override in production.
91
+ Your deployed server or tunnel hostname must still be listed explicitly because
92
+ Discord URL mappings can target it. A hostname allowance does not replace user
93
+ authentication or the separate Origin policy.
94
+
95
+ For example, `server: { allowedHosts: ["play.example.com"] }` also recognizes
96
+ `123456789.discordsays.com` when the effective application ID is `123456789`.
97
+ No Discord hostname is added when the application ID is missing or malformed.
98
+
99
+ CLI host/port flags override environment values; `HOST` and `PORT` override configured defaults.
87
100
 
88
101
  ## WebSockets
89
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
+
90
105
  All durations below are milliseconds.
91
106
 
92
107
  | Setting | Default | Meaning |
@@ -1,6 +1,6 @@
1
1
  # Deployment
2
2
 
3
- > Documentation for Ludicord 4.1.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1 before upgrading a production deployment.
8
+ The commands below install the latest **published** release. Confirm the registry reports 4.2.0 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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,21 @@
1
- # Upgrading to Ludicord 4.1.1
1
+ # Upgrading to Ludicord 4.2.0
2
2
 
3
- > Documentation for Ludicord 4.1.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
- Check that both 4.1.1 packages are available before upgrading:
5
+ Check that both 4.2.0 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.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.
12
+ Update an existing application's framework dependency with `npm install ludicord@4.2.0` (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
+ ## Recovery and diagnostics in 4.2
15
+
16
+ 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.
17
+
18
+ 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
19
 
14
20
  ## Review your application
15
21
 
@@ -42,4 +48,4 @@ Update an existing application's framework dependency with `npm install ludicord
42
48
  - Every expected prefix pathname and default embed URL returns the correct shell.
43
49
  - Unknown production prefixes return 404 instead of falling through to an unrelated scope.
44
50
 
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.1 release notes](https://github.com/mrcholer/ludicord/blob/main/releases/v4/4.1.1.md), [security](security.md), and [deployment](deployment.md).
51
+ 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.0 release notes](https://github.com/mrcholer/ludicord/blob/main/releases/v4/4.2.0.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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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,11 +1,11 @@
1
1
  # Security
2
2
 
3
- > Documentation for Ludicord 4.1.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.
7
7
 
8
- HTTP requests and WebSocket upgrades share the same boundary checks. `server.allowedOrigins` defaults to `"discord-activity"`, which accepts same-origin requests and the configured application's exact `https://<clientId>.discordsays.com` proxy origin. Ludicord derives the hostname from `discord.clientId` or `LUDICORD_DISCORD_CLIENT_ID` and never trusts a wildcard for other applications. The initial Discord iframe navigation is a safe `GET` request and browsers may omit its `Origin` header, so Ludicord permits origin-less `GET` and `HEAD` navigation. Cross-site mutation requests without an allowed `Origin` remain blocked. Use `"same-origin"` for a host-only policy. An origin array must include `"same-origin"` and `"discord-activity"` explicitly when both built-in policies should remain active alongside additional trusted HTTPS origins. `server.allowedHosts` can restrict the `Host` header to production and tunnel hostnames; `true` accepts every host and produces a production warning.
8
+ HTTP requests and WebSocket upgrades share the same boundary checks. `server.allowedOrigins` defaults to `"discord-activity"`, which accepts same-origin requests and the configured application's exact `https://<clientId>.discordsays.com` proxy origin. Ludicord derives the hostname from `discord.clientId` or `LUDICORD_DISCORD_CLIENT_ID` and never trusts a wildcard for other applications. The initial Discord iframe navigation is a safe `GET` request and browsers may omit its `Origin` header, so Ludicord permits origin-less `GET` and `HEAD` navigation. Cross-site mutation requests without an allowed `Origin` remain blocked. Use `"same-origin"` for a host-only policy. An origin array must include `"same-origin"` and `"discord-activity"` explicitly when both built-in policies should remain active alongside additional trusted HTTPS origins. `server.allowedHosts` can restrict the `Host` header to production and tunnel hostnames; `true` accepts every host and produces a production warning. Restricted host lists automatically include only the effective application’s exact `<clientId>.discordsays.com` hostname across HTTP, WebSockets and development assets. Other application IDs and lookalike domains are not automatically trusted. Keep the production or tunnel target hostname in the explicit list; host recognition does not authenticate a player or grant Activity membership.
9
9
 
10
10
  In production, `LUDICORD_DISCORD_CLIENT_ID` may be supplied when the server starts. That effective runtime ID is injected into the served Activity document and reused by HTTP, authentication, and WebSocket origin checks. This keeps promoted build artifacts consistent with the Discord application that runs them.
11
11
 
@@ -1,6 +1,6 @@
1
1
  # Start
2
2
 
3
- > Documentation for Ludicord 4.1.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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.1. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.0. 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: