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.
- package/dist/compiler/build.d.ts +2 -0
- package/dist/compiler/build.js +13 -4
- package/dist/compiler/client-assets.d.ts +2 -0
- package/dist/compiler/client-assets.js +5 -0
- package/dist/compiler/client-entry.js +40 -15
- package/dist/config/types.d.ts +5 -0
- package/dist/docs/README.md +1 -1
- package/dist/docs/activity-rooms.md +1 -1
- package/dist/docs/ai-agents.md +1 -1
- package/dist/docs/api-reference.md +1 -1
- package/dist/docs/api-routes.md +15 -1
- package/dist/docs/build.md +1 -1
- package/dist/docs/cli.md +1 -1
- package/dist/docs/configuration.md +15 -2
- package/dist/docs/deployment.md +18 -1
- package/dist/docs/development.md +32 -1
- package/dist/docs/discord-developer-portal.md +1 -1
- package/dist/docs/discord-sdk.md +1 -1
- package/dist/docs/distribution.md +1 -1
- package/dist/docs/embeds.md +1 -1
- package/dist/docs/environment-variables.md +1 -1
- package/dist/docs/getting-started.md +1 -1
- package/dist/docs/installation.md +2 -2
- package/dist/docs/login.md +1 -1
- package/dist/docs/migration.md +5 -5
- package/dist/docs/mobile-layout.md +1 -1
- package/dist/docs/navigation.md +1 -1
- package/dist/docs/pages.md +7 -1
- package/dist/docs/participants.md +1 -1
- package/dist/docs/prefix-router.md +1 -1
- package/dist/docs/project-structure.md +1 -1
- package/dist/docs/recipes.md +1 -1
- package/dist/docs/security.md +2 -2
- package/dist/docs/start.md +1 -1
- package/dist/docs/state-and-effects.md +1 -1
- package/dist/docs/troubleshooting.md +1 -1
- package/dist/docs/voice-events.md +1 -1
- package/dist/docs/websockets.md +1 -1
- package/dist/lint/index.js +1 -1
- package/dist/runtime/client/embed-router.js +23 -5
- package/dist/runtime/client/root.d.ts +2 -0
- package/dist/runtime/client/root.js +5 -1
- package/dist/runtime/client/startup.d.ts +17 -0
- package/dist/runtime/client/startup.js +72 -0
- package/dist/runtime/server/dev-server.js +4 -3
- package/dist/runtime/server/production-server.js +38 -2
- package/dist/runtime/startup-shell.d.ts +12 -0
- package/dist/runtime/startup-shell.js +16 -0
- package/dist/server/request-security.d.ts +2 -0
- package/dist/server/request-security.js +17 -6
- package/dist/skills/ludicord/SKILL.md +2 -2
- package/dist/skills/ludicord/manifest.yaml +1 -1
- package/dist/skills/ludicord/references/config-deploy.md +5 -1
- package/dist/version.js +1 -1
- package/dist/ws/server.d.ts +1 -1
- package/dist/ws/server.js +3 -2
- package/package.json +1 -1
package/dist/compiler/build.d.ts
CHANGED
|
@@ -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;
|
package/dist/compiler/build.js
CHANGED
|
@@ -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"
|
|
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,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
|
-
|
|
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
|
-
|
|
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
|
|
48
|
-
|
|
49
|
-
|
|
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
|
-
|
|
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
|
|
63
|
-
const
|
|
64
|
-
|
|
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
|
-
|
|
122
|
-
|
|
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
|
}
|
package/dist/config/types.d.ts
CHANGED
|
@@ -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`
|
package/dist/docs/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Ludicord documentation
|
|
2
2
|
|
|
3
|
-
> Documentation for Ludicord 4.1.
|
|
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.
|
|
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:
|
package/dist/docs/ai-agents.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# AI coding agents
|
|
2
2
|
|
|
3
|
-
Ludicord 4.1.
|
|
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.
|
|
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
|
|
package/dist/docs/api-routes.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# API Routes
|
|
2
2
|
|
|
3
|
-
> Documentation for Ludicord 4.1.
|
|
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.
|
package/dist/docs/build.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Build
|
|
2
2
|
|
|
3
|
-
> Documentation for Ludicord 4.1.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
|
package/dist/docs/deployment.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Deployment
|
|
2
2
|
|
|
3
|
-
> Documentation for Ludicord 4.1.
|
|
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
|
package/dist/docs/development.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Development runtime
|
|
2
2
|
|
|
3
|
-
> Documentation for Ludicord 4.1.
|
|
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.
|
|
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.
|
package/dist/docs/discord-sdk.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Discord SDK
|
|
2
2
|
|
|
3
|
-
> Documentation for Ludicord 4.1.
|
|
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.
|
|
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
|
|
package/dist/docs/embeds.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Embeds
|
|
2
2
|
|
|
3
|
-
> Documentation for Ludicord 4.1.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
package/dist/docs/login.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Login and sessions
|
|
2
2
|
|
|
3
|
-
> Documentation for Ludicord 4.1.
|
|
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:
|
package/dist/docs/migration.md
CHANGED
|
@@ -1,15 +1,15 @@
|
|
|
1
|
-
# Upgrading to Ludicord 4.1.
|
|
1
|
+
# Upgrading to Ludicord 4.1.2
|
|
2
2
|
|
|
3
|
-
> Documentation for Ludicord 4.1.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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:
|
package/dist/docs/navigation.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Navigation and generated route types
|
|
2
2
|
|
|
3
|
-
> Documentation for Ludicord 4.1.
|
|
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:
|
package/dist/docs/pages.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Pages: page.tsx
|
|
2
2
|
|
|
3
|
-
> Documentation for Ludicord 4.1.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|
|
package/dist/docs/recipes.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Usage recipes
|
|
2
2
|
|
|
3
|
-
> Documentation for Ludicord 4.1.
|
|
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
|
|