ludicord 4.2.0 → 4.2.2

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 (39) hide show
  1. package/dist/docs/README.md +2 -1
  2. package/dist/docs/activity-rooms.md +1 -1
  3. package/dist/docs/ai-agents.md +1 -1
  4. package/dist/docs/api-reference.md +1 -1
  5. package/dist/docs/api-routes.md +1 -1
  6. package/dist/docs/build.md +1 -1
  7. package/dist/docs/cli.md +1 -1
  8. package/dist/docs/configuration.md +1 -1
  9. package/dist/docs/deployment.md +1 -1
  10. package/dist/docs/development.md +1 -1
  11. package/dist/docs/discord-developer-portal.md +1 -1
  12. package/dist/docs/discord-sdk.md +1 -1
  13. package/dist/docs/distribution.md +1 -1
  14. package/dist/docs/embeds.md +1 -1
  15. package/dist/docs/engine-compatibility.md +87 -0
  16. package/dist/docs/environment-variables.md +1 -1
  17. package/dist/docs/getting-started.md +1 -1
  18. package/dist/docs/installation.md +2 -2
  19. package/dist/docs/login.md +1 -1
  20. package/dist/docs/migration.md +13 -5
  21. package/dist/docs/mobile-layout.md +1 -1
  22. package/dist/docs/navigation.md +1 -1
  23. package/dist/docs/pages.md +1 -1
  24. package/dist/docs/participants.md +1 -1
  25. package/dist/docs/prefix-router.md +1 -1
  26. package/dist/docs/project-structure.md +1 -1
  27. package/dist/docs/recipes.md +1 -1
  28. package/dist/docs/security.md +1 -1
  29. package/dist/docs/start.md +1 -1
  30. package/dist/docs/state-and-effects.md +1 -1
  31. package/dist/docs/troubleshooting.md +1 -1
  32. package/dist/docs/voice-events.md +1 -1
  33. package/dist/docs/websockets.md +3 -1
  34. package/dist/runtime/server/dev-server.js +5 -4
  35. package/dist/skills/ludicord/SKILL.md +2 -2
  36. package/dist/skills/ludicord/manifest.yaml +1 -1
  37. package/dist/version.js +1 -1
  38. package/dist/ws/client.js +5 -2
  39. package/package.json +1 -1
@@ -1,6 +1,6 @@
1
1
  # Ludicord documentation
2
2
 
3
- > Documentation for Ludicord 4.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
 
6
6
  ## Learn Ludicord
@@ -15,6 +15,7 @@
15
15
  - [Embeds](embeds.md)
16
16
  - [Navigation and generated route types](navigation.md)
17
17
  - [React state and effects](state-and-effects.md)
18
+ - [Native rendering libraries](engine-compatibility.md)
18
19
  - [Discord SDK](discord-sdk.md)
19
20
  - [Login and sessions](login.md)
20
21
  - [Environment Variables](environment-variables.md)
@@ -1,6 +1,6 @@
1
1
  # Activity Rooms
2
2
 
3
- > Documentation for Ludicord 4.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0 ships documentation and agent skills with the npm package. They
3
+ Ludicord 4.2.2 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,6 +1,6 @@
1
1
  # Public API reference
2
2
 
3
- > Documentation for Ludicord 4.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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
 
@@ -1,6 +1,6 @@
1
1
  # API Routes
2
2
 
3
- > Documentation for Ludicord 4.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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
 
@@ -1,6 +1,6 @@
1
1
  # Deployment
2
2
 
3
- > Documentation for Ludicord 4.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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:
@@ -1,6 +1,6 @@
1
1
  # Discord Developer Portal Setup
2
2
 
3
- > Documentation for Ludicord 4.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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:
@@ -0,0 +1,87 @@
1
+ # Native rendering libraries
2
+
3
+ Ludicord remains a general-purpose React framework for Discord Activities.
4
+ Ordinary projects need no rendering engine, additional scene folders, or special
5
+ runtime configuration. Install a library in your own app only when you need it.
6
+
7
+ ## Initialize in a React effect
8
+
9
+ Pages and embeds are browser components. Keep browser-only initialization in an
10
+ effect; do not import an engine into `route.ts`, `socket.ts`, instrumentation, or
11
+ another server module. A dynamic import also keeps an optional engine in a
12
+ separate production chunk. Guard asynchronous completion against unmount:
13
+
14
+ ```tsx
15
+ import { useEffect, useRef } from "react";
16
+ import type Phaser from "phaser";
17
+
18
+ export default function embed() {
19
+ const host = useRef<HTMLDivElement>(null);
20
+ useEffect(() => {
21
+ let cancelled = false;
22
+ let game: Phaser.Game | undefined;
23
+ const parent = host.current;
24
+ if (!parent) return;
25
+ void import("phaser").then(({ default: Phaser }) => {
26
+ if (cancelled) return;
27
+ game = new Phaser.Game({
28
+ type: Phaser.AUTO, parent, width: 640, height: 360,
29
+ scene: { create() { this.add.text(24, 24, "Hello Activity"); } },
30
+ });
31
+ }).catch((error: unknown) => { if (!cancelled) console.error(error); });
32
+ return () => { cancelled = true; game?.destroy(true); };
33
+ }, []);
34
+ return <div ref={host} />;
35
+ }
36
+ ```
37
+
38
+ Use the original engine APIs. React Strict Mode replays effect setup and cleanup
39
+ in development. Route transitions and Fast Refresh can also unmount or restart
40
+ effects. The cancellation guard prevents a late import from creating a renderer
41
+ after the component has left the page.
42
+
43
+ ## Three.js
44
+
45
+ Install `three` and, when needed for TypeScript, `@types/three`. Load the native
46
+ module with `import("three")` and loaders with their native subpaths, for example
47
+ `import("three/addons/loaders/GLTFLoader.js")`.
48
+
49
+ Create the scene, camera and `WebGLRenderer` inside the effect. Attach the canvas
50
+ to the component's ref. Use `renderer.setAnimationLoop(callback)` for rendering
51
+ and set it to `null` in cleanup. Disconnect `ResizeObserver`, dispose geometries,
52
+ materials and textures, dispose the renderer, and remove its canvas. Resources
53
+ loaded after unmount also need disposal. A material's disposal does not dispose
54
+ its textures. See the [Three.js disposal guide](https://threejs.org/manual/pages/how-to-dispose-of-objects.html).
55
+
56
+ Sizing should follow the element's dimensions. Update the renderer dimensions,
57
+ camera aspect and projection matrix when the element resizes. For Phaser, use
58
+ its native scale manager and destroy the game on cleanup; see the
59
+ [Phaser Game API](https://docs.phaser.io/api-documentation/class/game).
60
+
61
+ ## Assets and compiler behavior
62
+
63
+ Put assets in `public/` and use same-origin URLs such as `/models/scene.glb`.
64
+ Ludicord copies public files to the production client output. For imported asset
65
+ formats that the underlying compiler does not recognize, use an explicit URL
66
+ import (`import modelUrl from "./scene.glb?url"`) or place the asset in `public/`.
67
+ Shader source can be imported as text with `?raw`. These use existing compiler
68
+ facilities; no custom asset loader is required. WebAssembly module imports use
69
+ the existing optional [WASM plugin](plugins.md).
70
+
71
+ The development compiler discovers requested browser dependencies on demand,
72
+ including packages needing CommonJS-to-ES-module conversion. It does not scan
73
+ server routes as browser entry points. Production continues to use its existing
74
+ client bundler and separate Node server graph. No Vite configuration is needed.
75
+
76
+ ## Verification limits
77
+
78
+ The isolated compatibility fixtures exercise Phaser 3.90.0 with Canvas/Arcade
79
+ physics and Three.js 0.186.1 with WebGL, texture loading and a glTF model. Their
80
+ normal dashboard has no engine imports. Version and environment results belong
81
+ to those checks; they do not establish compatibility with all engine releases,
82
+ PixiJS, Babylon.js, PlayCanvas or React Three Fiber.
83
+
84
+ Test the actual Discord Activity frame separately. Browser success does not
85
+ verify Discord proxy mappings, CSP, audio permissions, touch input, mobile GPU
86
+ limits, layout events or picture-in-picture. Use same-origin assets where
87
+ possible and retain the framework's authentication and origin protections.
@@ -1,6 +1,6 @@
1
1
  # Environment Variables
2
2
 
3
- > Documentation for Ludicord 4.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0 before upgrading a production deployment.
8
+ The commands below install the latest **published** release. Confirm the registry reports 4.2.2 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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,23 @@
1
- # Upgrading to Ludicord 4.2.0
1
+ # Upgrading to Ludicord 4.2.2
2
2
 
3
- > Documentation for Ludicord 4.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
- Check that both 4.2.0 packages are available before upgrading:
5
+ Check that both 4.2.2 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.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.
12
+ Update an existing application's framework dependency with `npm install ludicord@4.2.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.
13
+
14
+ ## Browser dependency compatibility in 4.2.2
15
+
16
+ The dev compiler now discovers browser dependencies on demand, including CommonJS libraries. Existing routes, authentication, server isolation and production compilation remain unchanged. No API or UI migration is required. See [native rendering libraries](engine-compatibility.md) for React lifecycle and asset guidance.
17
+
18
+ ## Retry fixes in 4.2.1
19
+
20
+ 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.
13
21
 
14
22
  ## Recovery and diagnostics in 4.2
15
23
 
@@ -48,4 +56,4 @@ Use `useWSDiagnostics()` for connection snapshots and `useActivityPerformance({
48
56
  - Every expected prefix pathname and default embed URL returns the correct shell.
49
57
  - Unknown production prefixes return 404 instead of falling through to an unrelated scope.
50
58
 
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).
59
+ 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.2 release notes](https://github.com/mrcholer/ludicord/blob/main/releases/v4/4.2.2.md), [security](security.md), and [deployment](deployment.md).
@@ -1,6 +1,6 @@
1
1
  # Mobile and Layout
2
2
 
3
- > Documentation for Ludicord 4.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. 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,6 @@
1
1
  # WebSockets
2
2
 
3
- > Documentation for Ludicord 4.2.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.2.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
5
  ## Connection recovery and data APIs
6
6
 
@@ -8,6 +8,8 @@ The following APIs and recovery controls are available in Ludicord 4.2.0.
8
8
 
9
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
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
+
11
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.
12
14
 
13
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.
@@ -396,10 +396,11 @@ export async function createLudicordDevServer(options) {
396
396
  watch: { ignored: ["**/.ludicord/**", "**/.dact/**"] },
397
397
  },
398
398
  optimizeDeps: {
399
- // Optimize the fixed browser runtime up front. Discovery can outlive a
400
- // short dev session and report false esbuild cancellation/filesystem
401
- // errors after the project or its temporary cache has been removed.
402
- noDiscovery: true,
399
+ // Optimize the fixed runtime up front and discover authored browser
400
+ // imports on demand, including CommonJS packages. Avoid speculative
401
+ // entry scans so server-only routes never enter the browser optimizer.
402
+ entries: [],
403
+ noDiscovery: false,
403
404
  holdUntilCrawlEnd: false,
404
405
  include: [
405
406
  "react",
@@ -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.2.0"
6
+ version: "4.2.2"
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.2.0 projects intentionally include only `dev`, `build`, and
290
+ Generated 4.2.2 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.2.0"
2
+ framework_version: "4.2.2"
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.2.0";
1
+ export const LUDICORD_VERSION = "4.2.2";
package/dist/ws/client.js CHANGED
@@ -239,7 +239,10 @@ export class LudicordWebSocketConnection {
239
239
  this.setStatus("closed");
240
240
  return;
241
241
  }
242
- const baseDelay = 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);
243
246
  const delay = Math.min(this.reconnectOptions.maxDelay, Math.max(0, Math.round(baseDelay * (1 + this.reconnectOptions.jitter * (Math.random() * 2 - 1)))));
244
247
  this.reconnectAttempts += 1;
245
248
  this.updateDiagnostics({ nextReconnectDelayMs: delay });
@@ -449,7 +452,7 @@ export class LudicordWebSocketConnection {
449
452
  this.start();
450
453
  }
451
454
  start() {
452
- if (this.socket !== null)
455
+ if (this.socket !== null || this.reconnectTimer !== null)
453
456
  return;
454
457
  this.installResumeListeners();
455
458
  this.connect();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ludicord",
3
- "version": "4.2.0",
3
+ "version": "4.2.2",
4
4
  "description": "Full-stack React framework for Discord Activities.",
5
5
  "homepage": "https://github.com/mrcholer/ludicord#readme",
6
6
  "keywords": [