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/dist/index.d.ts CHANGED
@@ -4,8 +4,8 @@ export { Link, } from "./navigation/link.js";
4
4
  export type { LudicordLinkProps } from "./navigation/link.js";
5
5
  export { PrefixLink, prefixHref } from "./navigation/prefix-link.js";
6
6
  export type { LudicordPrefixLinkProps } from "./navigation/prefix-link.js";
7
- export { clearActivityQueryCache, useActivityLifecycle, useActivityPresence, useActivityQuery, useActivityStorage, useGameLoop, useSharedActivityState, } from "./activity/index.js";
8
- export type { LudicordActivityLifecycle, LudicordActivityPresence, LudicordActivityQuery, LudicordActivityQueryKey, LudicordActivityQueryOptions, LudicordActivityQueryStatus, LudicordActivityStorage, LudicordActivityStorageOptions, LudicordActivityStorageScope, LudicordGameFrame, LudicordGameLoop, LudicordGameLoopOptions, LudicordSharedActivityState, } from "./activity/index.js";
7
+ export { clearActivityQueryCache, useActivityLifecycle, useActivityPresence, useActivityQuery, useActivityStorage, useGameLoop, useSharedActivityState, useActivityPerformance, getActivityStartupTimings, subscribeActivityStartupTimings, } from "./activity/index.js";
8
+ export type { LudicordActivityLifecycle, LudicordActivityPresence, LudicordActivityQuery, LudicordActivityQueryKey, LudicordActivityQueryOptions, LudicordActivityQueryStatus, LudicordActivityStorage, LudicordActivityStorageOptions, LudicordActivityStorageScope, LudicordGameFrame, LudicordGameLoop, LudicordGameLoopOptions, LudicordSharedActivityState, LudicordActivityPerformance, LudicordActivityPerformanceOptions, LudicordStartupTiming, } from "./activity/index.js";
9
9
  export type { LudicordMetadata, LudicordMetadataTitle } from "./metadata/index.js";
10
10
  export { LudicordActivity, LudicordErrorBoundary, LudicordLoadingBoundary, EmbedOutlet, useActivityPrefix, usePageParams, } from "./runtime/client/embed-router.js";
11
11
  export { LudicordMinimizeProvider, useLudicordMinimize, } from "./runtime/client/minimize.js";
package/dist/index.js CHANGED
@@ -2,7 +2,7 @@ export { LUDICORD_VERSION } from "./version.js";
2
2
  export { defineMetadata } from "./metadata/index.js";
3
3
  export { Link, } from "./navigation/link.js";
4
4
  export { PrefixLink, prefixHref } from "./navigation/prefix-link.js";
5
- export { clearActivityQueryCache, useActivityLifecycle, useActivityPresence, useActivityQuery, useActivityStorage, useGameLoop, useSharedActivityState, } from "./activity/index.js";
5
+ export { clearActivityQueryCache, useActivityLifecycle, useActivityPresence, useActivityQuery, useActivityStorage, useGameLoop, useSharedActivityState, useActivityPerformance, getActivityStartupTimings, subscribeActivityStartupTimings, } from "./activity/index.js";
6
6
  export { LudicordActivity, LudicordErrorBoundary, LudicordLoadingBoundary, EmbedOutlet, useActivityPrefix, usePageParams, } from "./runtime/client/embed-router.js";
7
7
  export { LudicordMinimizeProvider, useLudicordMinimize, } from "./runtime/client/minimize.js";
8
8
  export { Minimize } from "./runtime/client/minimize-card.js";
@@ -0,0 +1,12 @@
1
+ export interface LudicordStartupTiming {
2
+ readonly stage: string;
3
+ readonly startMs: number;
4
+ readonly durationMs: number;
5
+ readonly status: "complete" | "error" | "skipped";
6
+ }
7
+ export declare const EMPTY_STARTUP_TIMINGS: readonly LudicordStartupTiming[];
8
+ /** A stable immutable snapshot of this page scope's startup measurements. */
9
+ export declare const getActivityStartupTimings: () => readonly LudicordStartupTiming[];
10
+ export declare const subscribeActivityStartupTimings: (listener: () => void) => (() => void);
11
+ export declare function resetActivityStartupTimings(): void;
12
+ export declare function recordActivityStartupTiming(stage: string, startMs: number, durationMs: number, status?: LudicordStartupTiming["status"]): void;
@@ -0,0 +1,22 @@
1
+ export const EMPTY_STARTUP_TIMINGS = Object.freeze([]);
2
+ let timings = EMPTY_STARTUP_TIMINGS;
3
+ const listeners = new Set();
4
+ /** A stable immutable snapshot of this page scope's startup measurements. */
5
+ export const getActivityStartupTimings = () => timings;
6
+ export const subscribeActivityStartupTimings = (listener) => {
7
+ listeners.add(listener);
8
+ return () => { listeners.delete(listener); };
9
+ };
10
+ export function resetActivityStartupTimings() {
11
+ timings = EMPTY_STARTUP_TIMINGS;
12
+ for (const listener of listeners)
13
+ listener();
14
+ }
15
+ export function recordActivityStartupTiming(stage, startMs, durationMs, status = "complete") {
16
+ // Generated startup has nine fixed stage names; retain a bounded snapshot.
17
+ if (timings.length >= 16 || timings.some((entry) => entry.stage === stage))
18
+ return;
19
+ timings = Object.freeze([...timings, Object.freeze({ stage, startMs, durationMs, status })]);
20
+ for (const listener of listeners)
21
+ listener();
22
+ }
@@ -2,10 +2,13 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
2
2
  import { Suspense, createElement, lazy, useEffect } from "react";
3
3
  import { STARTUP_SHELL_STYLE } from "../startup-shell.js";
4
4
  import { reportClientError, useLudicordFiles } from "./files.js";
5
+ import { recordActivityStartupTiming, resetActivityStartupTimings } from "./performance-data.js";
5
6
  const PREFIX = "ludicord:startup:";
6
7
  let startup;
7
8
  // Opted in by the generated entry only; standalone runtime consumers are untouched.
8
9
  export function beginActivityStartup() {
10
+ startup = undefined;
11
+ resetActivityStartupTimings();
9
12
  const timing = globalThis.performance;
10
13
  if (typeof timing?.mark !== "function" || typeof timing.measure !== "function")
11
14
  return () => undefined;
@@ -22,6 +25,9 @@ export function beginActivityStartup() {
22
25
  const current = { performance: timing, recorded: new Set(["runtime"]) };
23
26
  startup = current;
24
27
  timing.measure(`${PREFIX}runtime`, { start: 0, end: timing.now() });
28
+ const runtime = timing.getEntriesByName(`${PREFIX}runtime`, "measure").at(-1);
29
+ if (runtime !== undefined)
30
+ recordActivityStartupTiming("runtime", runtime.startTime, runtime.duration);
25
31
  return () => { if (startup === current)
26
32
  startup = undefined; };
27
33
  }
@@ -40,6 +46,9 @@ export function startStartupStage(stage) {
40
46
  const end = `${PREFIX}${stage}:end`;
41
47
  current.performance.mark(end);
42
48
  current.performance.measure(`${PREFIX}${stage}`, { start, end, detail: { status } });
49
+ const entry = current.performance.getEntriesByName(`${PREFIX}${stage}`, "measure").at(-1);
50
+ if (entry !== undefined)
51
+ recordActivityStartupTiming(stage, entry.startTime, entry.duration, status);
43
52
  };
44
53
  }
45
54
  export function recordStartupMilestone(milestone) {
@@ -48,6 +57,9 @@ export function recordStartupMilestone(milestone) {
48
57
  return;
49
58
  current.recorded.add(milestone);
50
59
  current.performance.measure(`${PREFIX}${milestone}`, { start: 0, end: current.performance.now() });
60
+ const entry = current.performance.getEntriesByName(`${PREFIX}${milestone}`, "measure").at(-1);
61
+ if (entry !== undefined)
62
+ recordActivityStartupTiming(milestone, entry.startTime, entry.duration);
51
63
  }
52
64
  export function StartupCommit({ children, milestone }) {
53
65
  useEffect(() => recordStartupMilestone(milestone), [milestone]);
@@ -1,3 +1,7 @@
1
+ export { useActivityPerformance } from "../activity/performance.js";
2
+ export type { LudicordActivityPerformance, LudicordActivityPerformanceOptions } from "../activity/performance.js";
3
+ export { getActivityStartupTimings, subscribeActivityStartupTimings } from "./client/performance-data.js";
4
+ export type { LudicordStartupTiming } from "./client/performance-data.js";
1
5
  export declare function useLudicordRuntime(): {
2
6
  readonly environment: string;
3
7
  readonly version: string;
@@ -3,6 +3,8 @@ import { useDiscord } from "../discord/runtime.js";
3
3
  import { useAuthStatus } from "../auth/client.js";
4
4
  import { subscribeWebSocketRuntime, isWebSocketRuntimeReady } from "../ws/client.js";
5
5
  import { LUDICORD_VERSION } from "../version.js";
6
+ export { useActivityPerformance } from "../activity/performance.js";
7
+ export { getActivityStartupTimings, subscribeActivityStartupTimings } from "./client/performance-data.js";
6
8
  export function useLudicordRuntime() {
7
9
  const discord = useDiscord();
8
10
  const authStatus = useAuthStatus();
@@ -3,7 +3,7 @@ name: ludicord
3
3
  description: "Build, modify, debug, review, or document Ludicord Discord Activities. Use for Activity roots, embeds, typed navigation, React state and effects, API or WebSocket routes, shared Activity state, Discord SDK data, participants, voice, authentication, security, configuration, compiler plugins, WebAssembly, development diagnostics, deployment, migration, and release compatibility."
4
4
  metadata:
5
5
  author: ludicord
6
- version: "4.1.2"
6
+ version: "4.2.1"
7
7
  ---
8
8
 
9
9
  # Ludicord
@@ -287,7 +287,7 @@ npx create-ludicord-app@latest my-activity --tailwind # scripted styling choice
287
287
  npx create-ludicord-app@latest my-activity --no-tailwind
288
288
  ```
289
289
 
290
- Generated 4.1.2 projects intentionally include only `dev`, `build`, and
290
+ Generated 4.2.1 projects intentionally include only `dev`, `build`, and
291
291
  `start` scripts. Run advanced commands with the project's package runner.
292
292
 
293
293
  ## Routed Intelligence References
@@ -1,5 +1,5 @@
1
1
  schema: 1
2
- framework_version: "4.1.2"
2
+ framework_version: "4.2.1"
3
3
  path_base: package-dist-or-repository-root
4
4
  canonical_skill: skills/ludicord/SKILL.md
5
5
  router: skills/ludicord/references/intelligence/skill-router.md
package/dist/version.js CHANGED
@@ -1 +1 @@
1
- export const LUDICORD_VERSION = "4.1.2";
1
+ export const LUDICORD_VERSION = "4.2.1";
@@ -15,11 +15,18 @@ export declare const isWebSocketRuntimeReady: () => boolean;
15
15
  export interface LudicordWSConnectionOptions {
16
16
  readonly enabled?: boolean;
17
17
  readonly autoConnect?: boolean;
18
+ readonly connectionTimeout?: number;
19
+ readonly healthCheck?: {
20
+ readonly enabled?: boolean;
21
+ readonly interval?: number;
22
+ readonly timeout?: number;
23
+ };
18
24
  readonly reconnect?: {
19
25
  readonly enabled?: boolean;
20
26
  readonly attempts?: number;
21
27
  readonly initialDelay?: number;
22
28
  readonly maxDelay?: number;
29
+ readonly jitter?: number;
23
30
  };
24
31
  readonly webSocketFactory?: (url: string) => BrowserSocket;
25
32
  }
@@ -28,6 +35,9 @@ export interface LudicordWSAckOptions {
28
35
  }
29
36
  export interface LudicordWSConnection {
30
37
  readonly status: LudicordWSStatus;
38
+ readonly diagnostics: LudicordWSDiagnostics;
39
+ getDiagnostics(): LudicordWSDiagnostics;
40
+ subscribeDiagnostics(listener: () => void): () => void;
31
41
  emit(event: string, data?: unknown): void;
32
42
  emitWithAck(event: string, data?: unknown, options?: LudicordWSAckOptions): Promise<void>;
33
43
  on(event: string, listener: (data: unknown) => void): () => void;
@@ -35,6 +45,22 @@ export interface LudicordWSConnection {
35
45
  close(): void;
36
46
  reconnect(): void;
37
47
  }
48
+ /** Local connection data only. Times are Unix milliseconds; latency is round-trip milliseconds. */
49
+ export interface LudicordWSDiagnostics {
50
+ readonly status: LudicordWSStatus;
51
+ readonly connectionAttempts: number;
52
+ readonly reconnectAttempts: number;
53
+ readonly reconnectCount: number;
54
+ readonly nextReconnectDelayMs: number | null;
55
+ readonly latencyMs: number | null;
56
+ readonly lastConnectedAt: number | null;
57
+ readonly lastErrorCode: string | null;
58
+ readonly lastClose: {
59
+ readonly code: number;
60
+ readonly reason: string;
61
+ readonly wasClean: boolean;
62
+ } | null;
63
+ }
38
64
  export declare class LudicordWebSocketConnection {
39
65
  private readonly route;
40
66
  private statusValue;
@@ -48,14 +74,33 @@ export declare class LudicordWebSocketConnection {
48
74
  private readonly factory;
49
75
  private readonly enabled;
50
76
  private resumeListenersInstalled;
77
+ private readonly connectionTimeout;
78
+ private readonly healthOptions;
79
+ private connectionTimer;
80
+ private healthTimer;
81
+ private probeTimer;
82
+ private probe;
83
+ private healthSupported;
84
+ private openedBefore;
85
+ private diagnosticsValue;
51
86
  private acknowledgementCounter;
52
87
  private readonly acknowledgements;
53
88
  constructor(route: LudicordWSRoute, options?: LudicordWSConnectionOptions);
54
89
  readonly subscribe: (listener: () => void) => (() => void);
55
90
  readonly getStatus: () => LudicordWSStatus;
91
+ readonly getDiagnostics: () => LudicordWSDiagnostics;
92
+ readonly subscribeDiagnostics: (listener: () => void) => (() => void);
93
+ get diagnostics(): LudicordWSDiagnostics;
94
+ private updateDiagnostics;
56
95
  private setStatus;
57
96
  private connect;
58
97
  private scheduleReconnect;
98
+ private clearConnectionTimer;
99
+ private clearProbe;
100
+ private clearHealthCheck;
101
+ private scheduleHealthCheck;
102
+ private checkHealth;
103
+ private failConnection;
59
104
  private clearReconnectTimer;
60
105
  private readonly resume;
61
106
  private installResumeListeners;
@@ -70,4 +115,6 @@ export declare class LudicordWebSocketConnection {
70
115
  start(): void;
71
116
  }
72
117
  export declare function useWS(route: LudicordWSRoute, options?: LudicordWSConnectionOptions): LudicordWSConnection;
118
+ /** Opt into reactive connection metrics separately from normal event consumers. */
119
+ export declare function useWSDiagnostics(connection: Pick<LudicordWSConnection, "getDiagnostics" | "subscribeDiagnostics">): LudicordWSDiagnostics;
73
120
  export {};
package/dist/ws/client.js CHANGED
@@ -1,14 +1,18 @@
1
1
  import { useEffect, useMemo, useSyncExternalStore, } from "react";
2
2
  import { useLudicordAuth } from "../auth/client.js";
3
3
  import { getLudicordLaunchId, LUDICORD_LAUNCH_QUERY } from "../sessions/launch.js";
4
+ import { LUDICORD_HEALTH_QUERY } from "./health.js";
4
5
  const openConnections = new Set();
5
6
  const runtimeListeners = new Set();
6
7
  export const subscribeWebSocketRuntime = (listener) => { runtimeListeners.add(listener); return () => { runtimeListeners.delete(listener); }; };
7
8
  export const isWebSocketRuntimeReady = () => openConnections.size > 0;
8
- function websocketUrl(route) {
9
+ function websocketUrl(route, healthCheck) {
9
10
  if (/^wss?:\/\//.test(route)) {
10
11
  const absolute = new URL(route);
11
12
  absolute.searchParams.set(LUDICORD_LAUNCH_QUERY, getLudicordLaunchId());
13
+ absolute.searchParams.delete(LUDICORD_HEALTH_QUERY);
14
+ if (healthCheck)
15
+ absolute.searchParams.set(LUDICORD_HEALTH_QUERY, "1");
12
16
  return absolute.href;
13
17
  }
14
18
  if (typeof window === "undefined") {
@@ -19,6 +23,8 @@ function websocketUrl(route) {
19
23
  const path = normalized;
20
24
  const absolute = new URL(`${protocol}//${window.location.host}${path}`);
21
25
  absolute.searchParams.set(LUDICORD_LAUNCH_QUERY, getLudicordLaunchId());
26
+ if (healthCheck)
27
+ absolute.searchParams.set(LUDICORD_HEALTH_QUERY, "1");
22
28
  return absolute.href;
23
29
  }
24
30
  function assertEventName(event) {
@@ -41,6 +47,18 @@ export class LudicordWebSocketConnection {
41
47
  factory;
42
48
  enabled;
43
49
  resumeListenersInstalled = false;
50
+ connectionTimeout;
51
+ healthOptions;
52
+ connectionTimer = null;
53
+ healthTimer = null;
54
+ probeTimer = null;
55
+ probe = null;
56
+ healthSupported = false;
57
+ openedBefore = false;
58
+ diagnosticsValue = Object.freeze({
59
+ status: "idle", connectionAttempts: 0, reconnectAttempts: 0, reconnectCount: 0,
60
+ nextReconnectDelayMs: null, latencyMs: null, lastConnectedAt: null, lastErrorCode: null, lastClose: null,
61
+ });
44
62
  acknowledgementCounter = 0;
45
63
  acknowledgements = new Map();
46
64
  constructor(route, options = {}) {
@@ -52,7 +70,28 @@ export class LudicordWebSocketConnection {
52
70
  attempts: options.reconnect?.attempts ?? defaults?.reconnect?.attempts ?? 10,
53
71
  initialDelay: options.reconnect?.initialDelay ?? defaults?.reconnect?.initialDelay ?? 500,
54
72
  maxDelay: options.reconnect?.maxDelay ?? defaults?.reconnect?.maxDelay ?? 10_000,
73
+ jitter: options.reconnect?.jitter ?? defaults?.reconnect?.jitter ?? 0.2,
55
74
  };
75
+ this.connectionTimeout = options.connectionTimeout ?? defaults?.connectionTimeout ?? 10_000;
76
+ this.healthOptions = {
77
+ enabled: options.healthCheck?.enabled ?? defaults?.healthCheck?.enabled ?? true,
78
+ interval: options.healthCheck?.interval ?? defaults?.healthCheck?.interval ?? 15_000,
79
+ timeout: options.healthCheck?.timeout ?? defaults?.healthCheck?.timeout ?? 10_000,
80
+ };
81
+ const integer = (value, min, max, field) => {
82
+ if (!Number.isSafeInteger(value) || value < min || value > max)
83
+ throw new TypeError(`LUDICORD0004: Invalid WebSocket ${field}.`);
84
+ };
85
+ integer(this.connectionTimeout, 100, 120_000, "connectionTimeout");
86
+ integer(this.healthOptions.interval, 1_000, 300_000, "healthCheck.interval");
87
+ integer(this.healthOptions.timeout, 100, 120_000, "healthCheck.timeout");
88
+ integer(this.reconnectOptions.attempts, 0, 10_000, "reconnect.attempts");
89
+ integer(this.reconnectOptions.initialDelay, 0, 2_147_483_647, "reconnect.initialDelay");
90
+ integer(this.reconnectOptions.maxDelay, this.reconnectOptions.initialDelay, 2_147_483_647, "reconnect.maxDelay");
91
+ if (!Number.isFinite(this.reconnectOptions.jitter) || this.reconnectOptions.jitter < 0 || this.reconnectOptions.jitter > 1 ||
92
+ typeof this.healthOptions.enabled !== "boolean" || typeof this.reconnectOptions.enabled !== "boolean" || typeof this.enabled !== "boolean") {
93
+ throw new TypeError("LUDICORD0004: Invalid WebSocket recovery options.");
94
+ }
56
95
  this.factory =
57
96
  options.webSocketFactory ??
58
97
  ((url) => new WebSocket(url));
@@ -64,6 +103,14 @@ export class LudicordWebSocketConnection {
64
103
  return () => this.statusListeners.delete(listener);
65
104
  };
66
105
  getStatus = () => this.statusValue;
106
+ getDiagnostics = () => this.diagnosticsValue;
107
+ subscribeDiagnostics = this.subscribe;
108
+ get diagnostics() { return this.diagnosticsValue; }
109
+ updateDiagnostics(patch) {
110
+ this.diagnosticsValue = Object.freeze({ ...this.diagnosticsValue, ...patch });
111
+ for (const listener of this.statusListeners)
112
+ listener();
113
+ }
67
114
  setStatus(status) {
68
115
  const wasReady = openConnections.size > 0;
69
116
  if (status === "open")
@@ -74,8 +121,7 @@ export class LudicordWebSocketConnection {
74
121
  for (const listener of runtimeListeners)
75
122
  listener();
76
123
  this.statusValue = status;
77
- for (const listener of this.statusListeners)
78
- listener();
124
+ this.updateDiagnostics({ status, reconnectAttempts: this.reconnectAttempts });
79
125
  }
80
126
  connect() {
81
127
  if (!this.enabled) {
@@ -84,19 +130,31 @@ export class LudicordWebSocketConnection {
84
130
  }
85
131
  this.clearReconnectTimer();
86
132
  this.manuallyClosed = false;
133
+ this.updateDiagnostics({ connectionAttempts: this.diagnosticsValue.connectionAttempts + 1, nextReconnectDelayMs: null });
87
134
  this.setStatus(this.reconnectAttempts === 0 ? "connecting" : "reconnecting");
88
135
  let socket;
89
136
  try {
90
- socket = this.factory(websocketUrl(this.route));
137
+ socket = this.factory(websocketUrl(this.route, this.healthOptions.enabled));
91
138
  }
92
139
  catch {
93
- this.setStatus("error");
140
+ this.failConnection("LUDICORD9102");
94
141
  return;
95
142
  }
96
143
  this.socket = socket;
144
+ this.connectionTimer = setTimeout(() => {
145
+ if (this.socket === socket)
146
+ this.failConnection("LUDICORD9105");
147
+ }, this.connectionTimeout);
148
+ this.connectionTimer.unref?.();
97
149
  socket.onopen = () => {
98
150
  if (this.socket !== socket)
99
151
  return;
152
+ this.clearConnectionTimer();
153
+ this.updateDiagnostics({
154
+ lastConnectedAt: Date.now(), lastErrorCode: null,
155
+ reconnectCount: this.diagnosticsValue.reconnectCount + (this.openedBefore ? 1 : 0),
156
+ });
157
+ this.openedBefore = true;
100
158
  this.reconnectAttempts = 0;
101
159
  this.setStatus("open");
102
160
  };
@@ -113,6 +171,24 @@ export class LudicordWebSocketConnection {
113
171
  const internal = typeof envelope.data === "object" && envelope.data !== null
114
172
  ? envelope.data
115
173
  : null;
174
+ if (envelope.event === "$ludicord:ready") {
175
+ if (internal?.healthCheck === true && !this.healthSupported) {
176
+ this.healthSupported = true;
177
+ this.checkHealth();
178
+ }
179
+ return;
180
+ }
181
+ if (envelope.event === "$ludicord:pong") {
182
+ if (this.probe !== null && internal?.id === this.probe.id) {
183
+ this.updateDiagnostics({ latencyMs: Math.max(0, performance.now() - this.probe.startedAt) });
184
+ this.clearProbe();
185
+ this.scheduleHealthCheck();
186
+ }
187
+ return;
188
+ }
189
+ if (envelope.event === "$ludicord:error" && typeof internal?.code === "string" && /^LUDICORD[A-Z0-9_]{1,96}$/.test(internal.code)) {
190
+ this.updateDiagnostics({ lastErrorCode: internal.code });
191
+ }
116
192
  if (envelope.event === "$ludicord:ack" && typeof internal?.id === "string") {
117
193
  const acknowledgement = this.acknowledgements.get(internal.id);
118
194
  if (acknowledgement !== undefined) {
@@ -141,12 +217,15 @@ export class LudicordWebSocketConnection {
141
217
  socket.onerror = () => {
142
218
  if (this.socket !== socket)
143
219
  return;
144
- this.setStatus("error");
220
+ this.failConnection("LUDICORD9107");
145
221
  };
146
- socket.onclose = () => {
222
+ socket.onclose = (event) => {
147
223
  if (this.socket !== socket)
148
224
  return;
225
+ this.clearConnectionTimer();
226
+ this.clearHealthCheck();
149
227
  this.socket = null;
228
+ this.updateDiagnostics({ latencyMs: null, lastClose: Object.freeze({ code: event.code ?? 1006, reason: event.reason ?? "", wasClean: event.wasClean === true }) });
150
229
  this.rejectAcknowledgements("LUDICORD9104: WebSocket closed before the server acknowledged the event.");
151
230
  if (this.manuallyClosed || !this.reconnectOptions.enabled) {
152
231
  this.setStatus("closed");
@@ -160,10 +239,85 @@ export class LudicordWebSocketConnection {
160
239
  this.setStatus("closed");
161
240
  return;
162
241
  }
163
- const delay = Math.min(this.reconnectOptions.initialDelay * 2 ** this.reconnectAttempts, this.reconnectOptions.maxDelay);
242
+ const baseDelay = Math.min(
243
+ // Integer delays reach the timer ceiling by attempt 31. Bounding the
244
+ // exponent also keeps a zero initial delay from becoming 0 * Infinity.
245
+ this.reconnectOptions.initialDelay * 2 ** Math.min(this.reconnectAttempts, 31), this.reconnectOptions.maxDelay);
246
+ const delay = Math.min(this.reconnectOptions.maxDelay, Math.max(0, Math.round(baseDelay * (1 + this.reconnectOptions.jitter * (Math.random() * 2 - 1)))));
164
247
  this.reconnectAttempts += 1;
248
+ this.updateDiagnostics({ nextReconnectDelayMs: delay });
165
249
  this.setStatus("reconnecting");
166
250
  this.reconnectTimer = setTimeout(() => this.connect(), delay);
251
+ this.reconnectTimer.unref?.();
252
+ }
253
+ clearConnectionTimer() {
254
+ if (this.connectionTimer !== null)
255
+ clearTimeout(this.connectionTimer);
256
+ this.connectionTimer = null;
257
+ }
258
+ clearProbe() {
259
+ if (this.probeTimer !== null)
260
+ clearTimeout(this.probeTimer);
261
+ this.probeTimer = null;
262
+ this.probe = null;
263
+ }
264
+ clearHealthCheck() {
265
+ if (this.healthTimer !== null)
266
+ clearTimeout(this.healthTimer);
267
+ this.healthTimer = null;
268
+ this.clearProbe();
269
+ this.healthSupported = false;
270
+ }
271
+ scheduleHealthCheck() {
272
+ if (this.healthTimer !== null)
273
+ clearTimeout(this.healthTimer);
274
+ this.healthTimer = setTimeout(() => { this.healthTimer = null; this.checkHealth(); }, this.healthOptions.interval);
275
+ this.healthTimer.unref?.();
276
+ }
277
+ checkHealth() {
278
+ if (!this.healthOptions.enabled || !this.healthSupported || this.socket?.readyState !== 1 || this.probe !== null)
279
+ return;
280
+ if (typeof document !== "undefined" && document.visibilityState === "hidden") {
281
+ this.scheduleHealthCheck();
282
+ return;
283
+ }
284
+ const id = `health_${++this.acknowledgementCounter}`;
285
+ this.probe = { id, startedAt: performance.now() };
286
+ this.probeTimer = setTimeout(() => {
287
+ this.probeTimer = null;
288
+ if (typeof document !== "undefined" && document.visibilityState === "hidden") {
289
+ this.clearProbe();
290
+ this.scheduleHealthCheck();
291
+ }
292
+ else
293
+ this.failConnection("LUDICORD9106");
294
+ }, this.healthOptions.timeout);
295
+ this.probeTimer.unref?.();
296
+ try {
297
+ this.socket.send(JSON.stringify({ v: 1, type: "ping", id }));
298
+ }
299
+ catch {
300
+ this.failConnection("LUDICORD9107");
301
+ }
302
+ }
303
+ failConnection(code) {
304
+ this.clearConnectionTimer();
305
+ this.clearHealthCheck();
306
+ const socket = this.socket;
307
+ this.socket = null;
308
+ if (socket !== null) {
309
+ socket.onopen = socket.onmessage = socket.onclose = socket.onerror = null;
310
+ try {
311
+ socket.close(4000, code);
312
+ }
313
+ catch { /* Already closed or failed handshake. */ }
314
+ }
315
+ this.rejectAcknowledgements(`${code}: WebSocket connection was interrupted.`);
316
+ this.updateDiagnostics({ lastErrorCode: code, latencyMs: null });
317
+ if (this.manuallyClosed || !this.reconnectOptions.enabled)
318
+ this.setStatus("error");
319
+ else
320
+ this.scheduleReconnect();
167
321
  }
168
322
  clearReconnectTimer() {
169
323
  if (this.reconnectTimer !== null) {
@@ -174,14 +328,31 @@ export class LudicordWebSocketConnection {
174
328
  resume = () => {
175
329
  if (!this.enabled || this.manuallyClosed)
176
330
  return;
331
+ if (typeof document !== "undefined" && document.visibilityState === "hidden") {
332
+ // Cancel the outstanding deadline before the browser freezes timers.
333
+ this.clearProbe();
334
+ if (this.healthSupported && this.healthOptions.enabled)
335
+ this.scheduleHealthCheck();
336
+ return;
337
+ }
338
+ if (!this.reconnectOptions.enabled)
339
+ return;
177
340
  if (typeof navigator !== "undefined" && navigator.onLine === false)
178
341
  return;
179
- if (typeof document !== "undefined" && document.visibilityState === "hidden")
342
+ if (this.socket?.readyState === 1) {
343
+ // A socket can remain OPEN after a suspended browser loses its transport.
344
+ this.clearProbe();
345
+ this.checkHealth();
180
346
  return;
181
- if (this.socket !== null)
347
+ }
348
+ if (this.socket?.readyState === 0)
182
349
  return;
350
+ if (this.socket !== null)
351
+ this.failConnection("LUDICORD9107");
183
352
  this.reconnectAttempts = 0;
184
353
  this.clearReconnectTimer();
354
+ this.clearConnectionTimer();
355
+ this.clearHealthCheck();
185
356
  this.connect();
186
357
  };
187
358
  installResumeListeners() {
@@ -259,15 +430,21 @@ export class LudicordWebSocketConnection {
259
430
  close() {
260
431
  this.manuallyClosed = true;
261
432
  this.clearReconnectTimer();
433
+ this.clearConnectionTimer();
434
+ this.clearHealthCheck();
262
435
  this.removeResumeListeners();
263
436
  this.rejectAcknowledgements("LUDICORD9104: WebSocket closed before the server acknowledged the event.");
264
437
  const socket = this.socket;
265
438
  this.socket = null;
266
439
  if (socket !== null) {
267
440
  socket.onopen = socket.onmessage = socket.onclose = socket.onerror = null;
268
- socket.close(1000, "Client closed");
441
+ try {
442
+ socket.close(1000, "Client closed");
443
+ }
444
+ catch { /* Failed handshake already disposed. */ }
269
445
  }
270
446
  this.setStatus("closed");
447
+ this.updateDiagnostics({ nextReconnectDelayMs: null, latencyMs: null });
271
448
  }
272
449
  reconnect() {
273
450
  this.close();
@@ -275,7 +452,7 @@ export class LudicordWebSocketConnection {
275
452
  this.start();
276
453
  }
277
454
  start() {
278
- if (this.socket !== null)
455
+ if (this.socket !== null || this.reconnectTimer !== null)
279
456
  return;
280
457
  this.installResumeListeners();
281
458
  this.connect();
@@ -285,11 +462,14 @@ export function useWS(route, options = {}) {
285
462
  const auth = useLudicordAuth();
286
463
  const authRequired = globalThis.__LUDICORD_PUBLIC_CONFIG__?.authRequired === true;
287
464
  const authReady = !authRequired || (auth.session !== null && auth.session.expiresAt > Date.now());
288
- const connection = useMemo(() => new LudicordWebSocketConnection(route, { ...options, ...(authReady ? {} : { enabled: false }), autoConnect: false }), [route, authReady, options.enabled, options.webSocketFactory, options.reconnect?.enabled, options.reconnect?.attempts, options.reconnect?.initialDelay, options.reconnect?.maxDelay]);
465
+ const connection = useMemo(() => new LudicordWebSocketConnection(route, { ...options, ...(authReady ? {} : { enabled: false }), autoConnect: false }), [route, authReady, options.enabled, options.webSocketFactory, options.connectionTimeout, options.healthCheck?.enabled, options.healthCheck?.interval, options.healthCheck?.timeout, options.reconnect?.enabled, options.reconnect?.attempts, options.reconnect?.initialDelay, options.reconnect?.maxDelay, options.reconnect?.jitter]);
289
466
  useEffect(() => { connection.start(); return () => connection.close(); }, [connection]);
290
467
  const status = useSyncExternalStore(connection.subscribe, connection.getStatus, connection.getStatus);
291
468
  return useMemo(() => ({
292
469
  status,
470
+ get diagnostics() { return connection.getDiagnostics(); },
471
+ getDiagnostics: connection.getDiagnostics,
472
+ subscribeDiagnostics: connection.subscribeDiagnostics,
293
473
  emit: (event, data) => connection.emit(event, data),
294
474
  emitWithAck: (event, data, ackOptions) => connection.emitWithAck(event, data, ackOptions),
295
475
  on: (event, listener) => connection.on(event, listener),
@@ -298,3 +478,7 @@ export function useWS(route, options = {}) {
298
478
  reconnect: () => connection.reconnect(),
299
479
  }), [connection, status]);
300
480
  }
481
+ /** Opt into reactive connection metrics separately from normal event consumers. */
482
+ export function useWSDiagnostics(connection) {
483
+ return useSyncExternalStore(connection.subscribeDiagnostics, connection.getDiagnostics, connection.getDiagnostics);
484
+ }
@@ -0,0 +1 @@
1
+ export declare const LUDICORD_HEALTH_QUERY = "ludicord_health";
@@ -0,0 +1,2 @@
1
+ // Capability request only; session and Activity authority still come from the upgrade.
2
+ export const LUDICORD_HEALTH_QUERY = "ludicord_health";
@@ -1,7 +1,7 @@
1
- export { useWS } from "./client.js";
1
+ export { useWS, useWSDiagnostics } from "./client.js";
2
2
  export { defineWS } from "./server.js";
3
3
  export { createMemorySharedStateStore, defineSharedActivityState } from "./shared-state.js";
4
4
  export type { LudicordWebSocketAdapter, LudicordWebSocketAdapterListener, LudicordWebSocketAdapterMessage, LudicordWebSocketAdapterTarget, } from "./adapter.js";
5
- export type { LudicordWSConnection, LudicordWSConnectionOptions, LudicordWSAckOptions, LudicordWSStatus, } from "./client.js";
5
+ export type { LudicordWSConnection, LudicordWSConnectionOptions, LudicordWSAckOptions, LudicordWSStatus, LudicordWSDiagnostics, } from "./client.js";
6
6
  export type { LudicordWebSocketClient, LudicordWebSocketRoute, LudicordWebSocketServerContext, LudicordWSEventEnvelope, WebSocketRuntimeOptions, } from "./server.js";
7
7
  export type { LudicordSharedStateContext, LudicordSharedStateOptions, LudicordSharedStateStore, LudicordSharedStateValue, } from "./shared-state.js";
package/dist/ws/index.js CHANGED
@@ -1,3 +1,3 @@
1
- export { useWS } from "./client.js";
1
+ export { useWS, useWSDiagnostics } from "./client.js";
2
2
  export { defineWS } from "./server.js";
3
3
  export { createMemorySharedStateStore, defineSharedActivityState } from "./shared-state.js";
package/dist/ws/server.js CHANGED
@@ -6,6 +6,7 @@ import { compareRouteSpecificity, matchRoutePattern } from "../router/match.js";
6
6
  import { parseSessionCookie } from "../sessions/cookies.js";
7
7
  import { LUDICORD_LAUNCH_QUERY, normalizeLudicordLaunchId } from "../sessions/launch.js";
8
8
  import { isLudicordHostAllowed, isLudicordOriginAllowed, resolveLudicordAllowedHosts } from "../server/request-security.js";
9
+ import { LUDICORD_HEALTH_QUERY } from "./health.js";
9
10
  const INTERNAL_EVENT_PREFIX = "$ludicord:";
10
11
  function isReservedEvent(event) {
11
12
  return (event.startsWith(INTERNAL_EVENT_PREFIX) ||
@@ -447,6 +448,9 @@ export function attachWebSocketRuntime(httpServer, options) {
447
448
  const client = new RuntimeClient(webSocket, session, selected.match.params, rooms, currentRouteBroadcast, backpressureLimit, backpressureStrategy, maxQueuedMessages, selected.route.route);
448
449
  clients.add(client);
449
450
  currentRouteClients.add(client);
451
+ // Capability negotiation keeps new clients compatible with older servers.
452
+ if (requestUrl.searchParams.get(LUDICORD_HEALTH_QUERY) === "1")
453
+ client.sendInternal("ready", { healthCheck: true });
450
454
  if (adapter?.join !== undefined)
451
455
  runAdapter(() => adapter.join(routeTarget(selected.route.route), client.id));
452
456
  webSocket.on("error", () => {
@@ -499,6 +503,16 @@ export function attachWebSocketRuntime(httpServer, options) {
499
503
  client.sendInternal("error", { code: "LUDICORD_MALFORMED_JSON" });
500
504
  return;
501
505
  }
506
+ if (typeof envelope === "object" && envelope !== null &&
507
+ envelope.v === 1 && envelope.type === "ping") {
508
+ const id = envelope.id;
509
+ if (typeof id !== "string" || !/^[A-Za-z0-9_-]{1,64}$/.test(id)) {
510
+ client.sendInternal("error", { code: "LUDICORD_INVALID_EVENT_ID" });
511
+ }
512
+ else
513
+ client.sendInternal("pong", { id });
514
+ return;
515
+ }
502
516
  if (typeof envelope !== "object" ||
503
517
  envelope === null ||
504
518
  envelope.v !== 1 ||