ludicord 4.1.0 → 4.1.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 (57) hide show
  1. package/dist/compiler/build.d.ts +2 -0
  2. package/dist/compiler/build.js +13 -4
  3. package/dist/compiler/client-assets.d.ts +2 -0
  4. package/dist/compiler/client-assets.js +5 -0
  5. package/dist/compiler/client-entry.js +40 -15
  6. package/dist/config/types.d.ts +5 -0
  7. package/dist/docs/README.md +1 -1
  8. package/dist/docs/activity-rooms.md +1 -1
  9. package/dist/docs/ai-agents.md +1 -1
  10. package/dist/docs/api-reference.md +1 -1
  11. package/dist/docs/api-routes.md +15 -1
  12. package/dist/docs/build.md +1 -1
  13. package/dist/docs/cli.md +1 -1
  14. package/dist/docs/configuration.md +15 -2
  15. package/dist/docs/deployment.md +18 -1
  16. package/dist/docs/development.md +32 -1
  17. package/dist/docs/discord-developer-portal.md +1 -1
  18. package/dist/docs/discord-sdk.md +1 -1
  19. package/dist/docs/distribution.md +1 -1
  20. package/dist/docs/embeds.md +1 -1
  21. package/dist/docs/environment-variables.md +1 -1
  22. package/dist/docs/getting-started.md +1 -1
  23. package/dist/docs/installation.md +2 -2
  24. package/dist/docs/login.md +1 -1
  25. package/dist/docs/migration.md +5 -5
  26. package/dist/docs/mobile-layout.md +1 -1
  27. package/dist/docs/navigation.md +1 -1
  28. package/dist/docs/pages.md +7 -1
  29. package/dist/docs/participants.md +1 -1
  30. package/dist/docs/prefix-router.md +1 -1
  31. package/dist/docs/project-structure.md +1 -1
  32. package/dist/docs/recipes.md +1 -1
  33. package/dist/docs/security.md +2 -2
  34. package/dist/docs/start.md +1 -1
  35. package/dist/docs/state-and-effects.md +1 -1
  36. package/dist/docs/troubleshooting.md +1 -1
  37. package/dist/docs/voice-events.md +1 -1
  38. package/dist/docs/websockets.md +1 -1
  39. package/dist/lint/index.js +1 -1
  40. package/dist/runtime/client/embed-router.js +23 -5
  41. package/dist/runtime/client/root.d.ts +2 -0
  42. package/dist/runtime/client/root.js +5 -1
  43. package/dist/runtime/client/startup.d.ts +17 -0
  44. package/dist/runtime/client/startup.js +72 -0
  45. package/dist/runtime/server/dev-server.js +4 -3
  46. package/dist/runtime/server/production-server.js +38 -2
  47. package/dist/runtime/startup-shell.d.ts +12 -0
  48. package/dist/runtime/startup-shell.js +16 -0
  49. package/dist/server/request-security.d.ts +2 -0
  50. package/dist/server/request-security.js +17 -6
  51. package/dist/skills/ludicord/SKILL.md +2 -2
  52. package/dist/skills/ludicord/manifest.yaml +1 -1
  53. package/dist/skills/ludicord/references/config-deploy.md +5 -1
  54. package/dist/version.js +1 -1
  55. package/dist/ws/server.d.ts +1 -1
  56. package/dist/ws/server.js +3 -2
  57. package/package.json +1 -1
@@ -11,6 +11,8 @@ export interface LudicordBuildMetadata {
11
11
  readonly frameworkVersion: string;
12
12
  readonly createdAt: string;
13
13
  readonly clientEntry: string;
14
+ /** Compiler-emitted content-hashed assets; absent in older schema-4 builds. */
15
+ readonly immutableAssets?: readonly string[];
14
16
  readonly api: readonly RouteBundle[];
15
17
  readonly websocket: readonly RouteBundle[];
16
18
  readonly instrumentation?: RouteBundle;
@@ -9,6 +9,8 @@ import { generateManifests } from "./scanner.js";
9
9
  import { writeManifests } from "./write-manifests.js";
10
10
  import { generateLudicordTypes } from "./type-generation.js";
11
11
  import { clientEntry } from "./client-entry.js";
12
+ import { isHashedClientAsset } from "./client-assets.js";
13
+ import { STARTUP_SHELL_HTML } from "../runtime/startup-shell.js";
12
14
  import { clientAliases as ludicordClientAliases, clientPlugins, ludicordLogger } from "./client-tooling.js";
13
15
  import { bundleServerGraph } from "./server-bundle.js";
14
16
  import { loadProjectEnvironment } from "../config/environment.js";
@@ -172,6 +174,11 @@ async function buildClient(projectRoot, outputDirectory, manifests, config) {
172
174
  },
173
175
  }));
174
176
  const outputs = Array.isArray(result) ? result : [result];
177
+ // Rollup output excludes files copied verbatim from public/. A hash-looking
178
+ // public filename alone must never opt mutable content into immutable caching.
179
+ const immutableAssets = [...new Set(outputs.flatMap((output) => output.output)
180
+ .map((item) => item.fileName)
181
+ .filter(isHashedClientAsset))].sort();
175
182
  const entry = outputs
176
183
  .flatMap((output) => output.output)
177
184
  .find((item) => item.type === "chunk" && item.isEntry);
@@ -200,22 +207,24 @@ async function buildClient(projectRoot, outputDirectory, manifests, config) {
200
207
  ${[...styles].map((file) => `<link rel="stylesheet" href="/${file}" />`).join("\n ")}
201
208
  </head>
202
209
  <body>
203
- <div id="ludicord-root"></div>
210
+ <div id="ludicord-root">${STARTUP_SHELL_HTML}</div>
204
211
  <script type="module" src="/${clientEntry}"></script>
205
212
  </body>
206
213
  </html>
207
214
  `, "utf8");
208
215
  return {
209
216
  clientEntry,
217
+ immutableAssets,
210
218
  bundleReport: createBundleReport(path.join(outputDirectory, "client"), clientEntry, config.build.clientAssetWarningLimit),
211
219
  };
212
220
  }
213
- function buildMetadata(clientEntry, api, websocket, instrumentation, proxy, bundleReport, config) {
221
+ function buildMetadata(clientEntry, immutableAssets, api, websocket, instrumentation, proxy, bundleReport, config) {
214
222
  return {
215
223
  buildSchemaVersion: LUDICORD_BUILD_SCHEMA_VERSION,
216
224
  frameworkVersion: LUDICORD_VERSION,
217
225
  createdAt: new Date().toISOString(),
218
226
  clientEntry,
227
+ immutableAssets,
219
228
  api,
220
229
  websocket,
221
230
  ...(instrumentation === undefined ? {} : { instrumentation }),
@@ -259,7 +268,7 @@ export async function buildLudicordProject(projectRoot) {
259
268
  const typeErrors = checkProjectTypes(root);
260
269
  if (typeErrors.length > 0)
261
270
  throw new Error(typeErrors.map((item) => `${item.file ?? "TypeScript"}:${item.line ?? 1}:${item.column ?? 1}\n${item.message}\n${item.frame ?? ""}`).join("\n\n"));
262
- const { clientEntry, bundleReport } = await buildClient(root, temporaryDirectory, manifests, config);
271
+ const { clientEntry, immutableAssets, bundleReport } = await buildClient(root, temporaryDirectory, manifests, config);
263
272
  const graph = await bundleServerGraph(root, path.join(temporaryDirectory, "server"), manifests, config.imports.aliases, config.plugins, "production");
264
273
  const api = graph.bundles.filter((route) => route.kind === "api").map((route) => ({ source: route.source, bundle: `server/${route.bundle}` }));
265
274
  const websocket = graph.bundles.filter((route) => route.kind === "ws").map((route) => ({ source: route.source, bundle: `server/${route.bundle}` }));
@@ -276,7 +285,7 @@ export async function buildLudicordProject(projectRoot) {
276
285
  writeFileSync(path.join(temporaryDirectory, "types", "routes.d.ts"), readFileSync(path.join(root, "ludicord.generated.d.ts"), "utf8"), "utf8");
277
286
  writeFileSync(path.join(temporaryDirectory, "types", "plugins.d.ts"), readFileSync(path.join(root, "ludicord.plugins.generated.d.ts"), "utf8"), "utf8");
278
287
  writeFileSync(path.join(temporaryDirectory, "bundle-report.json"), `${JSON.stringify(bundleReport, null, 2)}\n`, "utf8");
279
- const metadata = buildMetadata(clientEntry, api, websocket, instrumentation, proxy, bundleReport, config);
288
+ const metadata = buildMetadata(clientEntry, immutableAssets, api, websocket, instrumentation, proxy, bundleReport, config);
280
289
  writeFileSync(path.join(temporaryDirectory, "build.json"), `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
281
290
  if (clientContainsSecret(path.join(temporaryDirectory, "client")))
282
291
  throw new Error("LUDICORD7001: Server secret detected in client output.");
@@ -0,0 +1,2 @@
1
+ /** Matches the content-hashed filenames emitted by the client compiler. */
2
+ export declare function isHashedClientAsset(file: string): boolean;
@@ -0,0 +1,5 @@
1
+ /** Matches the content-hashed filenames emitted by the client compiler. */
2
+ export function isHashedClientAsset(file) {
3
+ return /^assets\/(?:[^/]+\/)*[^/]+-[A-Za-z0-9_-]{8,}\.[^/]+$/.test(file) &&
4
+ !file.split("/").some((segment) => segment === "." || segment === "..");
5
+ }
@@ -11,27 +11,33 @@ export function clientEntry(root, manifests, config, development) {
11
11
  const imports = [
12
12
  `import React from "react";`,
13
13
  `import { createRoot } from "react-dom/client";`,
14
- `import { LudicordRoot, matchPageRoute } from "ludicord/internal";`,
14
+ `import { LudicordRoot, matchPageRoute, beginActivityStartup, deferredFile, startStartupStage, StartupError, reportClientError } from "ludicord/internal";`,
15
15
  `import { LudicordActivity } from "ludicord";`,
16
16
  `import { installLudicordLaunchIsolation } from "ludicord/auth";`,
17
17
  ];
18
18
  if (existsSync(path.join(root, "app", "globals.css"))) {
19
19
  imports.push(`import ${JSON.stringify(file("app/globals.css"))};`);
20
20
  }
21
- const activityDefinition = (activity, scopeIndex, bindings, loaders) => {
21
+ const activityDefinition = (activity, scopeIndex, bindings, loaders, declarations) => {
22
22
  const bindDefault = (name, source) => {
23
23
  bindings.push(name);
24
24
  loaders.push(`import(${JSON.stringify(file(source))}).then((module) => module.default)`);
25
25
  };
26
26
  const pages = `Pages_${scopeIndex}`;
27
- bindDefault(pages, activity.root);
27
+ declarations.push(`const finishPage = startStartupStage("page-module");
28
+ const pageModule = import(${JSON.stringify(file(activity.root))}).then((module) => { finishPage(); return module; }, (error) => { finishPage("error"); throw error; });
29
+ void pageModule.catch(() => undefined);
30
+ const ${pages} = React.lazy(() => pageModule);`);
28
31
  const components = [];
29
32
  for (const key of FILE_COMPONENTS) {
30
33
  const source = activity[key];
31
34
  if (source === undefined)
32
35
  continue;
33
36
  const name = `Scope_${scopeIndex}_${key}`;
34
- bindDefault(name, source);
37
+ if (key === "layout" || key === "loading")
38
+ bindDefault(name, source);
39
+ else
40
+ declarations.push(`const ${name} = deferredFile(() => import(${JSON.stringify(file(source))}));`);
35
41
  components.push(`${key}: ${name}`);
36
42
  }
37
43
  if (activity.metadata === undefined) {
@@ -44,24 +50,26 @@ export function clientEntry(root, manifests, config, development) {
44
50
  const scopeDefinition = (scope, scopeIndex) => {
45
51
  const bindings = [];
46
52
  const loaders = [];
47
- const bindDefault = (name, source) => {
48
- bindings.push(name);
49
- loaders.push(`import(${JSON.stringify(file(source))}).then((module) => module.default)`);
50
- };
51
- const activity = activityDefinition(scope.activity, scopeIndex, bindings, loaders);
53
+ const declarations = [];
54
+ const layoutNames = new Map();
55
+ const activity = activityDefinition(scope.activity, scopeIndex, bindings, loaders, declarations);
52
56
  const embeds = scope.embeds.map((route, routeIndex) => {
53
57
  const fields = [`load: () => import(${JSON.stringify(file(route.file))})`];
54
58
  for (const [key, source] of [["loading", route.loading], ["error", route.error]]) {
55
59
  if (source === undefined)
56
60
  continue;
57
61
  const name = `Scope_${scopeIndex}_Embed_${routeIndex}_${key}`;
58
- bindDefault(name, source);
62
+ declarations.push(`const ${name} = deferredFile(() => import(${JSON.stringify(file(source))}));`);
59
63
  fields.push(`${key}: ${name}`);
60
64
  }
61
65
  if (route.layouts !== undefined) {
62
- const layouts = route.layouts.map((source, layoutIndex) => {
63
- const name = `Scope_${scopeIndex}_Embed_${routeIndex}_layout_${layoutIndex}`;
64
- bindDefault(name, source);
66
+ const layouts = route.layouts.map((source) => {
67
+ const existing = layoutNames.get(source);
68
+ if (existing !== undefined)
69
+ return existing;
70
+ const name = `Scope_${scopeIndex}_layout_${layoutNames.size}`;
71
+ layoutNames.set(source, name);
72
+ declarations.push(`const ${name} = React.lazy(() => import(${JSON.stringify(file(source))}));`);
65
73
  return name;
66
74
  });
67
75
  fields.push(`layouts: [${layouts.join(",")}]`);
@@ -69,6 +77,7 @@ export function clientEntry(root, manifests, config, development) {
69
77
  return `${JSON.stringify(route.route)}: { ${fields.join(", ")} }`;
70
78
  });
71
79
  return `${JSON.stringify(scope.prefix)}: async () => {
80
+ ${declarations.join("\n ")}
72
81
  const [${bindings.join(",")}] = await Promise.all([${loaders.join(",")}]);
73
82
  return { Pages: ${activity.pages}, managedActivity: ${scope.activity.managedActivity === true}, files: ${activity.files}, metadata: ${activity.metadata}, embeds: {${embeds.join(",\n")} } };
74
83
  }`;
@@ -87,6 +96,7 @@ export function clientEntry(root, manifests, config, development) {
87
96
  websocket: { enabled: config.websocket.enabled, reconnect: config.websocket.reconnect },
88
97
  };
89
98
  return `${imports.join("\n")}
99
+ const disposeStartup = beginActivityStartup();
90
100
  const prefixScopes = {${scopeDefinitions.join(",\n")}};
91
101
  const normalizePrefix = (value) => {
92
102
  const pathname = value.replace(/\\/{2,}/g, "/").replace(/\\/$/, "");
@@ -105,10 +115,15 @@ globalThis.__LUDICORD_ACTIVE_PREFIX__ = activePrefix;
105
115
  globalThis.__LUDICORD_PAGE_PARAMS__ = selectedPage?.match.params ?? {};
106
116
  installLudicordLaunchIsolation();
107
117
  let mountedRoot;
118
+ let disposed = false;
108
119
  const bootPrefix = async () => {
120
+ const finishScope = startStartupStage("scope");
121
+ try {
109
122
  const loadScope = selectedPage && prefixScopes[selectedPage.scope.prefix];
110
123
  if (!loadScope) throw new Error('LUDICORD2004: Unknown Activity prefix "' + activePrefix + '".');
111
124
  const selectedScope = await loadScope();
125
+ finishScope();
126
+ if (disposed) return;
112
127
  globalThis.__LUDICORD_EMBEDS__ = selectedScope.embeds;
113
128
  const container = document.getElementById("ludicord-root");
114
129
  if (!container) throw new Error("LUDICORD2003: Missing #ludicord-root container.");
@@ -117,7 +132,17 @@ const bootPrefix = async () => {
117
132
  const content = selectedScope.managedActivity ? React.createElement(LudicordActivity, { defaultEmbed: ${JSON.stringify(config.activity.defaultEmbed)} }, page) : page;
118
133
  const activity = React.createElement(LudicordRoot, { files: selectedScope.files, metadata: selectedScope.metadata }, content);
119
134
  mountedRoot.render(${config.react.strictMode ? "React.createElement(React.StrictMode, null, activity)" : "activity"});
135
+ } catch (error) { finishScope("error"); throw error; }
120
136
  };
121
- void bootPrefix();
122
- ${development ? `if (import.meta.hot) import.meta.hot.dispose(() => mountedRoot?.unmount());` : ""}`;
137
+ const bootPromise = bootPrefix().catch((error) => {
138
+ if (disposed) return;
139
+ reportClientError(error instanceof Error ? error : new Error(String(error)));
140
+ if (globalThis.__LUDICORD_PUBLIC_CONFIG__.environment === "development") console.error(error);
141
+ const container = document.getElementById("ludicord-root");
142
+ if (container) {
143
+ mountedRoot ??= createRoot(container);
144
+ mountedRoot.render(React.createElement(StartupError));
145
+ }
146
+ });
147
+ ${development ? `if (import.meta.hot) import.meta.hot.dispose(() => { disposed = true; disposeStartup(); mountedRoot?.unmount(); });` : ""}`;
123
148
  }
@@ -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`
@@ -1,6 +1,6 @@
1
1
  # Ludicord documentation
2
2
 
3
- > Documentation for Ludicord 4.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.2. 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.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.1.0 ships documentation and agent skills with the npm package. They
3
+ Ludicord 4.1.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.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.
@@ -24,3 +24,17 @@ Handlers use native `Request` and `Response` objects. Export `GET`, `POST`, `PUT
24
24
  Routes require a valid Ludicord session by default. Set `export const auth = false` for a public route. Authenticated handlers should trust identity from `request.ludicord`, never user IDs supplied in a request body.
25
25
 
26
26
  Ludicord returns 404 for no route, 405 with `Allow` for unsupported methods, supplies HEAD from GET, and supplies OPTIONS when no custom handler exists. API and Activity traffic run on the same Node server.
27
+
28
+ The production server defaults dynamic responses to `Cache-Control: no-store`. For intentionally public, non-personalized data, a handler can explicitly opt into caching:
29
+
30
+ ```ts
31
+ export const auth = false;
32
+
33
+ export function GET() {
34
+ return Response.json({ status: "online" }, {
35
+ headers: { "Cache-Control": "public, max-age=60" },
36
+ });
37
+ }
38
+ ```
39
+
40
+ Keep user- and Activity-specific responses out of shared caches. See [production HTTP caching](deployment.md#production-http-caching) for the asset and HTML policies.
@@ -1,6 +1,6 @@
1
1
  # Build
2
2
 
3
- > Documentation for Ludicord 4.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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
 
@@ -83,7 +83,20 @@ 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
 
@@ -1,6 +1,6 @@
1
1
  # Deployment
2
2
 
3
- > Documentation for Ludicord 4.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.
@@ -16,6 +16,23 @@ Do not place a CDN cache in front of `/_ludicord/auth`, authenticated `/api/*`,
16
16
 
17
17
  The Client ID can be present during the build or supplied to `ludicord start`. A runtime value takes precedence and is injected into the Activity document, allowing one promoted build to run against the intended Discord application. The same effective ID protects HTTP, authentication, and WebSocket requests. With the default origin policy, the exact Activity proxy origin is `https://<clientId>.discordsays.com`; do not add a wildcard for all Discord applications.
18
18
 
19
+ ## Production HTTP caching
20
+
21
+ The production server applies these policies automatically:
22
+
23
+ | Response | `Cache-Control` | Behavior |
24
+ | --- | --- | --- |
25
+ | Compiler-generated hashed JavaScript, CSS, and other assets | `public, max-age=31536000, immutable` | Browsers and CDNs can reuse the file for one year. Changed content receives a new URL on the next build. |
26
+ | Activity HTML, including `/index.html` and nested pages | `no-cache` | Validate before reuse so the document points to the current build and runtime Client ID. |
27
+ | Files copied from `public/` and other unversioned static files | `no-cache` | Validate before reuse, even when a filename happens to look hashed. |
28
+ | Auth, API, health, missing assets, and other dynamic responses | `no-store` by default | Do not store responses unless an application handler deliberately supplies its own caching header. |
29
+
30
+ HTML and static files include ETags for conditional requests. Unchanged resources return `304 Not Modified` without retransmitting their body; static files also provide `Last-Modified` validators. GET, HEAD, and successful range responses use the same resource cache policy. Missing hashed chunks return an uncached 404 even when the app defines a catch-all page.
31
+
32
+ The build records the immutable asset list from compiler output in `build.json`; it does not infer immutability from arbitrary public filenames. Older schema-4 builds without that list remain supported and revalidate all static files. Rebuild with the updated compiler to enable long-lived asset caching.
33
+
34
+ Configure your CDN or reverse proxy to honor these headers. When deploying, retain older hashed assets for existing Activity sessions that may still request lazy chunks from the previous build. The local build replacement does not retain those assets automatically. Do not apply a one-year cache policy to HTML or the entire `public/` directory.
35
+
19
36
  The built-in session, OAuth-token, WebSocket, and shared-state implementations are process-local. Multiple replicas should use a custom launcher:
20
37
 
21
38
  ```ts
@@ -1,6 +1,6 @@
1
1
  # Development runtime
2
2
 
3
- > Documentation for Ludicord 4.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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:
@@ -25,3 +25,34 @@ Ludicord's development panel handles syntax, TypeScript, render, event-handler,
25
25
  Successful server graph rebuilds remove obsolete temporary bundles; failed rebuilds keep the last working graph. The current run directory is removed on shutdown. Vite remains an internal compiler, not a separate developer-facing server. `vite.config.ts` is unnecessary and ignored. Tailwind is detected when `@tailwindcss/vite` is installed in the app.
26
26
 
27
27
  Run `ludicord routes` to inspect recursive page and embed ownership, `ludicord info` for environment and project details, `ludicord lint` for React Hooks rules, and `ludicord build` for the complete production validation and client-secret scan.
28
+
29
+ ## Startup measurements
30
+
31
+ 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
+
33
+ ```js
34
+ console.table(performance.getEntriesByType("measure")
35
+ .filter(entry => entry.name.startsWith("ludicord:startup:"))
36
+ .map(entry => ({
37
+ stage: entry.name.replace("ludicord:startup:", ""),
38
+ startMs: Math.round(entry.startTime),
39
+ durationMs: Math.round(entry.duration),
40
+ status: entry.detail?.status,
41
+ })));
42
+ ```
43
+
44
+ | Measure | Meaning |
45
+ | --- | --- |
46
+ | `runtime` | Time from document navigation until the generated entry begins executing, including entry downloads and imported runtime evaluation. |
47
+ | `scope` | Preparation of the selected page's layout, loading UI, metadata, and route registry. |
48
+ | `page-module` | Import and evaluation of the selected page module, started alongside scope preparation. |
49
+ | `discord` | Discord initialization after the Activity mounts. |
50
+ | `auth` | Authentication after Discord initialization; skipped when initialization returns without a session. |
51
+ | `embed-module` | Import and evaluation of the first requested embed module. |
52
+ | `root-commit` | Navigation to the first React root effect, which may still show a loading screen. |
53
+ | `content-commit` | Navigation to the first committed Activity content after its sign-in gate allows rendering. An embed may still be loading. |
54
+ | `embed-commit` | Navigation to the first committed embed subtree, including its layouts. |
55
+
56
+ Stage measures have `detail.status` of `complete`, `skipped`, or `error`. Only stages actually reached are recorded; for example, failed Discord initialization does not produce an authentication measure. Commit milestones use React effects and do not claim to measure browser paint. Use browser network/resource timings to separate download time from module evaluation; deferred modules and shared imports can overlap, so these durations should not be added together.
57
+
58
+ Measures are recorded once per entry boot, including under React Strict Mode. HMR entry disposal prevents old asynchronous imports from mounting a stale root or finishing stale measurements; the next entry clears only Ludicord's startup marks and measures. Later embed navigation does not overwrite opening measurements. These timings remain in the browser and are not sent to a server.
@@ -1,6 +1,6 @@
1
1
  # Discord Developer Portal Setup
2
2
 
3
- > Documentation for Ludicord 4.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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:
@@ -1,6 +1,6 @@
1
1
  # Environment Variables
2
2
 
3
- > Documentation for Ludicord 4.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.1.0 before upgrading a production deployment.
8
+ The commands below install the latest **published** release. Confirm the registry reports 4.1.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.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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,15 @@
1
- # Upgrading to Ludicord 4.1.0
1
+ # Upgrading to Ludicord 4.1.2
2
2
 
3
- > Documentation for Ludicord 4.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.2. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
4
4
 
5
- Check that both 4.1.0 packages are available before upgrading:
5
+ Check that both 4.1.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.1.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.1.2` (or your package-manager equivalent), update its lockfile, and create a fresh production build. The generator is for new projects; do not run it over an existing non-empty application. Existing V3 trees remain supported through legacy compatibility mode; follow [the routing migration](migration-v4.md) before switching file conventions.
13
13
 
14
14
  ## Review your application
15
15
 
@@ -42,4 +42,4 @@ Update an existing application's framework dependency with `npm install ludicord
42
42
  - Every expected prefix pathname and default embed URL returns the correct shell.
43
43
  - Unknown production prefixes return 404 instead of falling through to an unrelated scope.
44
44
 
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.0 release notes](https://github.com/mrcholer/ludicord/blob/main/releases/v4/4.1.0.md), [security](security.md), and [deployment](deployment.md).
45
+ Back up your current lockfile and keep the last deployable build for rollback. Review the detailed [V4 migration guide](migration-v4.md), [plugins and WebAssembly](plugins.md), [4.1.2 release notes](https://github.com/mrcholer/ludicord/blob/main/releases/v4/4.1.2.md), [security](security.md), and [deployment](deployment.md).
@@ -1,6 +1,6 @@
1
1
  # Mobile and Layout
2
2
 
3
- > Documentation for Ludicord 4.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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
 
@@ -30,4 +30,10 @@ Do not hide an explicit Activity boundary in another component: keep it visible
30
30
 
31
31
  Automatic files are discovered without imports in the page: `layout.tsx` receives children, `loading.tsx` supplies a fallback, `error.tsx` receives error/reset, `minimize.tsx` supplies compact UI, and `auth/{loading,error,denied}.tsx` supplies sign-in states. Place them beside the page they configure. Embed directories can have their own layout/loading/error files. Production error components receive sanitized errors.
32
32
 
33
+ The HTML initially contains an accessible “Loading Activity…” shell, visible before the client modules finish loading. The selected page module starts downloading alongside its layout, loading component, and metadata. Those three convention files are prepared before React mounts; keep them small. Your `loading.tsx` then replaces the built-in shell while the page suspends. Global CSS can set `--ludicord-startup-background` and `--ludicord-startup-color` to match the Activity theme.
34
+
35
+ Error, not-found, minimized, and sign-in components load when rendered. Embed layouts, loading screens, and error screens also load on demand, so an unopened embed's UI modules do not block startup. Shared embed layouts retain their identity and state across hash navigation. Lazy convention screens use the page's loading component while downloading, or the built-in shell if none exists. A failed convention-screen import displays a safe reload screen. Keep essential startup work out of module-level side effects in deferred files.
36
+
37
+ See [startup measurements](development.md#startup-measurements) to identify the remaining delays.
38
+
33
39
  See [embeds](embeds.md), [project structure](project-structure.md), and [migration](migration-v4.md).
@@ -1,6 +1,6 @@
1
1
  # Participants
2
2
 
3
- > Documentation for Ludicord 4.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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.1.0. See [release status](https://github.com/mrcholer/ludicord/blob/main/releases/README.md).
3
+ > Documentation for Ludicord 4.1.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