@ignifx/editor-host 0.9.0 → 0.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/error-codes.d.ts +44 -0
- package/dist/error-codes.d.ts.map +1 -0
- package/dist/error-codes.js +46 -0
- package/dist/error-codes.js.map +1 -0
- package/dist/index.d.ts +2823 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +6580 -0
- package/dist/index.js.map +1 -0
- package/dist/vite.d.ts +248 -0
- package/dist/vite.d.ts.map +1 -0
- package/dist/vite.js +659 -0
- package/dist/vite.js.map +1 -0
- package/package.json +10 -5
- package/skills/editor-host/SKILL.md +157 -21
package/dist/vite.js
ADDED
|
@@ -0,0 +1,659 @@
|
|
|
1
|
+
import { n as isEditorOrigin, t as EditorHostErrorCode } from "./error-codes.js";
|
|
2
|
+
import { ASSET_CHANGED_EVENT, IGNIFX_CONFIG_DEFINE_KEY, MANIFEST_MODULE_ID, SCRIPTS_MODULE_ID } from "@ignifx/vite-plugin";
|
|
3
|
+
import { existsSync, readFileSync, realpathSync } from "node:fs";
|
|
4
|
+
import { createRequire } from "node:module";
|
|
5
|
+
import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
|
|
6
|
+
//#region src/vite/errors.ts
|
|
7
|
+
/**
|
|
8
|
+
* The error every `@ignifx/editor-host/vite` API throws for a misconfiguration
|
|
9
|
+
* (`CONSTITUTION.md` §3.9).
|
|
10
|
+
*
|
|
11
|
+
* @beta
|
|
12
|
+
*/
|
|
13
|
+
var EditorHostPluginError = class extends Error {
|
|
14
|
+
/** The stable diagnostic code for this failure. */
|
|
15
|
+
code;
|
|
16
|
+
/**
|
|
17
|
+
* Creates a plugin error.
|
|
18
|
+
*
|
|
19
|
+
* @param code - The stable `IGX-####` code for the failure.
|
|
20
|
+
* @param message - An actionable description of what went wrong and how to fix it.
|
|
21
|
+
*/
|
|
22
|
+
constructor(code, message) {
|
|
23
|
+
super(message);
|
|
24
|
+
this.name = "EditorHostPluginError";
|
|
25
|
+
this.code = code;
|
|
26
|
+
}
|
|
27
|
+
};
|
|
28
|
+
//#endregion
|
|
29
|
+
//#region src/vite/modules.ts
|
|
30
|
+
/**
|
|
31
|
+
* The page and the two modules the plugin generates: the scene view's HTML entry, the module that
|
|
32
|
+
* page runs, and `virtual:ignifx/editor`, the play view's controls.
|
|
33
|
+
*/
|
|
34
|
+
/**
|
|
35
|
+
* The path the scene view is served at, below the dev server's `base`.
|
|
36
|
+
*
|
|
37
|
+
* @beta
|
|
38
|
+
*/
|
|
39
|
+
const EDITOR_PAGE_PATH = "/__ignifx_editor__/";
|
|
40
|
+
/**
|
|
41
|
+
* The module a game imports to hand its app to the editor's play controls.
|
|
42
|
+
*
|
|
43
|
+
* @example
|
|
44
|
+
* ```ts
|
|
45
|
+
* import { attachEditorPlayControls } from "virtual:ignifx/editor";
|
|
46
|
+
*
|
|
47
|
+
* attachEditorPlayControls(app);
|
|
48
|
+
* ```
|
|
49
|
+
*
|
|
50
|
+
* @beta
|
|
51
|
+
*/
|
|
52
|
+
const EDITOR_MODULE_ID = "virtual:ignifx/editor";
|
|
53
|
+
/**
|
|
54
|
+
* The resolved id of {@link EDITOR_MODULE_ID}. The `\0` prefix marks it as owned by a plugin.
|
|
55
|
+
*
|
|
56
|
+
* @beta
|
|
57
|
+
*/
|
|
58
|
+
const RESOLVED_EDITOR_MODULE_ID = `\0${EDITOR_MODULE_ID}`;
|
|
59
|
+
/**
|
|
60
|
+
* The module the scene view's page runs. Only the generated page imports it.
|
|
61
|
+
*
|
|
62
|
+
* @beta
|
|
63
|
+
*/
|
|
64
|
+
const EDITOR_ENTRY_MODULE_ID = "virtual:ignifx/editor-host-entry";
|
|
65
|
+
/**
|
|
66
|
+
* The resolved id of {@link EDITOR_ENTRY_MODULE_ID}.
|
|
67
|
+
*
|
|
68
|
+
* @beta
|
|
69
|
+
*/
|
|
70
|
+
const RESOLVED_EDITOR_ENTRY_MODULE_ID = `\0${EDITOR_ENTRY_MODULE_ID}`;
|
|
71
|
+
/**
|
|
72
|
+
* The function `virtual:ignifx/editor` exports. It takes the game's app and returns a function that
|
|
73
|
+
* detaches the controls; in a production build it does nothing.
|
|
74
|
+
*
|
|
75
|
+
* @beta
|
|
76
|
+
*/
|
|
77
|
+
const EDITOR_PLAY_CONTROLS_EXPORT = "attachEditorPlayControls";
|
|
78
|
+
/**
|
|
79
|
+
* The module the scene view imports the project's extensions from, unless the plugin is told
|
|
80
|
+
* otherwise. It exports `extensions()`, which returns the list `main.ts` passes to `createApp`.
|
|
81
|
+
*
|
|
82
|
+
* @beta
|
|
83
|
+
*/
|
|
84
|
+
const DEFAULT_EXTENSIONS_MODULE = "/src/extensions.ts";
|
|
85
|
+
/**
|
|
86
|
+
* The `id` of the scene view's canvas.
|
|
87
|
+
*
|
|
88
|
+
* @beta
|
|
89
|
+
*/
|
|
90
|
+
const EDITOR_CANVAS_ID = "ignifx-editor-view";
|
|
91
|
+
/** The package the generated modules import the host from, resolved from the project's root. */
|
|
92
|
+
const HOST_PACKAGE = "@ignifx/editor-host";
|
|
93
|
+
/**
|
|
94
|
+
* Turns the `extensions` option into the root-absolute path the generated module imports.
|
|
95
|
+
*
|
|
96
|
+
* @param path - The path as configured, relative to the Vite root or already root-absolute.
|
|
97
|
+
* @returns The root-absolute path, for example `"/src/extensions.ts"`.
|
|
98
|
+
* @throws EditorHostPluginError `IGX-1803` when the path is empty or leaves the root with `..`.
|
|
99
|
+
*
|
|
100
|
+
* @beta
|
|
101
|
+
*/
|
|
102
|
+
function normalizeExtensionsModule(path) {
|
|
103
|
+
const trimmed = path.startsWith("./") ? path.slice(2) : path;
|
|
104
|
+
if (trimmed === "" || trimmed === "/" || trimmed.split("/").some((segment) => segment === "..")) throw new EditorHostPluginError(EditorHostErrorCode.invalidOption, `The "extensions" option must name a module inside the Vite root, for example "src/extensions.ts"; got "${path}".`);
|
|
105
|
+
return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* The fields shared by both generated calls, as source text.
|
|
109
|
+
*
|
|
110
|
+
* @param engineVersion - The version to report, or `null`.
|
|
111
|
+
* @param heartbeatIntervalMs - The heartbeat period, or `null`.
|
|
112
|
+
* @returns Zero, one, or two `key: value,` lines.
|
|
113
|
+
*/
|
|
114
|
+
function reportingLines(engineVersion, heartbeatIntervalMs) {
|
|
115
|
+
return [...engineVersion === null ? [] : [` engineVersion: ${JSON.stringify(engineVersion)},`], ...heartbeatIntervalMs === null ? [] : [` heartbeatIntervalMs: ${JSON.stringify(heartbeatIntervalMs)},`]];
|
|
116
|
+
}
|
|
117
|
+
/**
|
|
118
|
+
* Generates the module the scene view's page runs.
|
|
119
|
+
*
|
|
120
|
+
* @remarks
|
|
121
|
+
* The module is the only code with an import-time effect: it creates the host. The package itself
|
|
122
|
+
* creates nothing when imported (`CONSTITUTION.md` §3.5). Every import is resolved from the
|
|
123
|
+
* project's root, so the host, the scripts, and the extensions share the project's one copy of
|
|
124
|
+
* `@ignifx/core`. It hands every `ignifx:asset-changed` event to `host.assetChanged`, which
|
|
125
|
+
* reloads the asset in place; the `import.meta.hot` calls are written out literally, because Vite
|
|
126
|
+
* finds them by reading the source.
|
|
127
|
+
*
|
|
128
|
+
* @param options - The editor origin, the project's extensions module, and the reporting options.
|
|
129
|
+
* @returns The ES module source.
|
|
130
|
+
*
|
|
131
|
+
* @beta
|
|
132
|
+
*/
|
|
133
|
+
function editorEntryModuleSource(options) {
|
|
134
|
+
const { extensionsModule } = options;
|
|
135
|
+
return [
|
|
136
|
+
`import { startEditorHost } from ${JSON.stringify(HOST_PACKAGE)};`,
|
|
137
|
+
`import { manifest } from ${JSON.stringify(MANIFEST_MODULE_ID)};`,
|
|
138
|
+
`import { acceptHotReload, scripts } from ${JSON.stringify(SCRIPTS_MODULE_ID)};`,
|
|
139
|
+
...extensionsModule === null ? [] : [`import { extensions } from ${JSON.stringify(extensionsModule)};`],
|
|
140
|
+
"",
|
|
141
|
+
"const host = await startEditorHost({",
|
|
142
|
+
` editorOrigin: ${JSON.stringify(options.editorOrigin)},`,
|
|
143
|
+
" hostKind: \"scene\",",
|
|
144
|
+
` canvas: document.getElementById(${JSON.stringify(EDITOR_CANVAS_ID)}),`,
|
|
145
|
+
` settings: ${IGNIFX_CONFIG_DEFINE_KEY},`,
|
|
146
|
+
" assets: { manifest },",
|
|
147
|
+
` extensions: ${extensionsModule === null ? "[]" : "extensions()"},`,
|
|
148
|
+
" scripts,",
|
|
149
|
+
` bootScene: ${JSON.stringify(options.bootScene)},`,
|
|
150
|
+
...reportingLines(options.engineVersion, options.heartbeatIntervalMs),
|
|
151
|
+
"});",
|
|
152
|
+
"acceptHotReload(host.app);",
|
|
153
|
+
"if (import.meta.hot) {",
|
|
154
|
+
` import.meta.hot.on(${JSON.stringify(ASSET_CHANGED_EVENT)}, (change) => {`,
|
|
155
|
+
" void host.assetChanged(change);",
|
|
156
|
+
" });",
|
|
157
|
+
"}",
|
|
158
|
+
""
|
|
159
|
+
].join("\n");
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* Generates the scene view's HTML page, before Vite's own `transformIndexHtml` adds its client.
|
|
163
|
+
*
|
|
164
|
+
* @returns The HTML document.
|
|
165
|
+
*
|
|
166
|
+
* @beta
|
|
167
|
+
*/
|
|
168
|
+
function editorPageHtml() {
|
|
169
|
+
return [
|
|
170
|
+
"<!doctype html>",
|
|
171
|
+
"<html lang=\"en\">",
|
|
172
|
+
" <head>",
|
|
173
|
+
" <meta charset=\"utf-8\" />",
|
|
174
|
+
" <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />",
|
|
175
|
+
" <title>ignifx editor host</title>",
|
|
176
|
+
" <style>",
|
|
177
|
+
" html, body { margin: 0; height: 100%; overflow: hidden; background: #000; }",
|
|
178
|
+
` #${EDITOR_CANVAS_ID} { display: block; width: 100%; height: 100%; }`,
|
|
179
|
+
" </style>",
|
|
180
|
+
" </head>",
|
|
181
|
+
" <body>",
|
|
182
|
+
` <canvas id="${EDITOR_CANVAS_ID}"></canvas>`,
|
|
183
|
+
` <script type="module" src="/@id/${EDITOR_ENTRY_MODULE_ID}"><\/script>`,
|
|
184
|
+
" </body>",
|
|
185
|
+
"</html>",
|
|
186
|
+
""
|
|
187
|
+
].join("\n");
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* Generates `virtual:ignifx/editor`.
|
|
191
|
+
*
|
|
192
|
+
* @remarks
|
|
193
|
+
* In development, the module listens for the editor's connect message as soon as it is evaluated,
|
|
194
|
+
* which is before the game's `main.ts` runs, and keeps the port
|
|
195
|
+
* (`listenForEditorPlayControls`); `attachEditorPlayControls(app)` then starts the play controls on
|
|
196
|
+
* it, so the editor's first connect message is never lost to `await createApp(...)`. Vite replacing
|
|
197
|
+
* the module stops both. The `import.meta.hot` calls are written out literally because Vite
|
|
198
|
+
* finds them by reading the source, not by running it. In a production build the export is an empty
|
|
199
|
+
* function, the same shape as `acceptHotReload` from `virtual:ignifx/scripts`, so the game's
|
|
200
|
+
* `main.ts` builds either way and ships no editor code.
|
|
201
|
+
*
|
|
202
|
+
* @param options - The editor origin, the reporting options, and whether to emit the development module.
|
|
203
|
+
* @returns The ES module source.
|
|
204
|
+
*
|
|
205
|
+
* @beta
|
|
206
|
+
*/
|
|
207
|
+
function playControlsModuleSource(options) {
|
|
208
|
+
if (!options.hot) return [
|
|
209
|
+
`export function ${EDITOR_PLAY_CONTROLS_EXPORT}() {`,
|
|
210
|
+
" return () => {};",
|
|
211
|
+
"}",
|
|
212
|
+
""
|
|
213
|
+
].join("\n");
|
|
214
|
+
return [
|
|
215
|
+
`import { listenForEditorPlayControls } from ${JSON.stringify(HOST_PACKAGE)};`,
|
|
216
|
+
"",
|
|
217
|
+
"// Listens now, before main.ts awaits createApp, so the editor's first port is kept.",
|
|
218
|
+
"const connector = listenForEditorPlayControls({",
|
|
219
|
+
` editorOrigin: ${JSON.stringify(options.editorOrigin)},`,
|
|
220
|
+
...reportingLines(options.engineVersion, options.heartbeatIntervalMs),
|
|
221
|
+
"});",
|
|
222
|
+
"if (import.meta.hot) {",
|
|
223
|
+
" import.meta.hot.dispose(() => {",
|
|
224
|
+
" connector.dispose();",
|
|
225
|
+
" });",
|
|
226
|
+
"}",
|
|
227
|
+
"",
|
|
228
|
+
`export function ${EDITOR_PLAY_CONTROLS_EXPORT}(app) {`,
|
|
229
|
+
" const controls = connector.attach(app);",
|
|
230
|
+
" return () => {",
|
|
231
|
+
" controls.dispose();",
|
|
232
|
+
" };",
|
|
233
|
+
"}",
|
|
234
|
+
""
|
|
235
|
+
].join("\n");
|
|
236
|
+
}
|
|
237
|
+
//#endregion
|
|
238
|
+
//#region src/vite/private-dir.ts
|
|
239
|
+
/**
|
|
240
|
+
* A copy of `@ignifx/vite-plugin`'s `.ignifx/` request guard (`src/private-dir.ts` there), kept
|
|
241
|
+
* here as defence in depth: a project whose Vite config lists `editorHostPlugin()` without
|
|
242
|
+
* `ignifx()` would otherwise serve `.ignifx/mcp.json`, the editor's MCP token, to any page.
|
|
243
|
+
* `@ignifx/vite-plugin` is an optional peer, so this package cannot import it; keep the two in step.
|
|
244
|
+
*/
|
|
245
|
+
/** The editor-private directory at a project's root. */
|
|
246
|
+
const PRIVATE_DIR_NAME = ".ignifx";
|
|
247
|
+
/** Percent-decoding passes before a path counts as private regardless of what it decodes to. */
|
|
248
|
+
const MAX_DECODE_PASSES = 8;
|
|
249
|
+
/** Windows 8.3 short names of `.ignifx` (`IGNIFX~1`), which resolve to it on NTFS. */
|
|
250
|
+
const SHORT_NAME_RE = /^ignifx~\d+$/u;
|
|
251
|
+
/**
|
|
252
|
+
* Decodes every `%XX` escape, byte by byte, so a malformed sequence never stops decoding.
|
|
253
|
+
*
|
|
254
|
+
* @param text - The text to decode.
|
|
255
|
+
* @returns The text with each escape replaced by the byte it names.
|
|
256
|
+
*/
|
|
257
|
+
function decodeEscapes(text) {
|
|
258
|
+
return text.replaceAll(/%([0-9a-f]{2})/giu, (_match, hex) => String.fromCodePoint(Number.parseInt(hex, 16)));
|
|
259
|
+
}
|
|
260
|
+
/**
|
|
261
|
+
* Reports whether one path segment names the private directory.
|
|
262
|
+
*
|
|
263
|
+
* @param segment - One decoded segment.
|
|
264
|
+
* @returns `true` for `.ignifx` in any case, with Windows' ignored trailing dots and spaces, an
|
|
265
|
+
* alternate data stream suffix, or as an 8.3 short name.
|
|
266
|
+
*/
|
|
267
|
+
function isPrivateSegment(segment) {
|
|
268
|
+
const name = (segment.normalize("NFKC").toLowerCase().split(":")[0] ?? "").replace(/[. ]+$/u, "");
|
|
269
|
+
return name === PRIVATE_DIR_NAME || SHORT_NAME_RE.test(name);
|
|
270
|
+
}
|
|
271
|
+
/**
|
|
272
|
+
* The path part of a request URL with every escape decoded, nested ones included.
|
|
273
|
+
*
|
|
274
|
+
* @param url - The request URL as the server received it.
|
|
275
|
+
* @returns The decoded path, or `null` when it still changes after the last decoding pass.
|
|
276
|
+
*/
|
|
277
|
+
function decodedRequestPath(url) {
|
|
278
|
+
let path = url.split(/[?#]/u, 1)[0] ?? "";
|
|
279
|
+
for (let pass = 0;; pass += 1) {
|
|
280
|
+
const decoded = decodeEscapes(path);
|
|
281
|
+
if (decoded === path) return path;
|
|
282
|
+
if (pass === MAX_DECODE_PASSES) return null;
|
|
283
|
+
path = decoded;
|
|
284
|
+
}
|
|
285
|
+
}
|
|
286
|
+
/**
|
|
287
|
+
* Reports whether a path names the private directory in any of its segments.
|
|
288
|
+
*
|
|
289
|
+
* @param path - A path with `/` or `\` separators, relative or absolute.
|
|
290
|
+
* @returns `true` when a segment between separators is a spelling of `.ignifx`.
|
|
291
|
+
*/
|
|
292
|
+
function hasPrivateSegment(path) {
|
|
293
|
+
return path.split(/[/\\?#]/u).some(isPrivateSegment);
|
|
294
|
+
}
|
|
295
|
+
/**
|
|
296
|
+
* Reports whether a file, once every symbolic link on its path is followed, lies in a private
|
|
297
|
+
* directory.
|
|
298
|
+
*
|
|
299
|
+
* @remarks
|
|
300
|
+
* A link such as `src/link -> ../.ignifx` hides the directory from every check that reads the path
|
|
301
|
+
* as written. The deepest part of `path` that exists is resolved with `realpath` and the rest
|
|
302
|
+
* appended, so a request for a file the server would find by adding an extension is judged too.
|
|
303
|
+
* Only the part of the real path below `realBase` and its common ancestor with the file counts:
|
|
304
|
+
* a project that itself lives under some `.ignifx` directory is not refused wholesale.
|
|
305
|
+
*
|
|
306
|
+
* @param realBase - The real path the result is measured from, normally the project root.
|
|
307
|
+
* @param path - An absolute path, existing or not.
|
|
308
|
+
* @returns `true` when the real path has a `.ignifx` segment, or when it cannot be resolved for a
|
|
309
|
+
* reason other than not existing (the check fails closed).
|
|
310
|
+
*
|
|
311
|
+
* It is synchronous, like Vite's own file lookups: a few `realpath` calls per request or module.
|
|
312
|
+
*/
|
|
313
|
+
function isPrivateRealPath(realBase, path) {
|
|
314
|
+
let current = path;
|
|
315
|
+
const rest = [];
|
|
316
|
+
for (;;) try {
|
|
317
|
+
return hasPrivateSegment(relative(realBase, join(realpathSync.native(current), ...rest)));
|
|
318
|
+
} catch (error) {
|
|
319
|
+
const missing = isMissingFileError(error);
|
|
320
|
+
const parent = dirname(current);
|
|
321
|
+
if (!missing || parent === current) return !missing;
|
|
322
|
+
rest.unshift(basename(current));
|
|
323
|
+
current = parent;
|
|
324
|
+
}
|
|
325
|
+
}
|
|
326
|
+
/**
|
|
327
|
+
* Reports whether a caught failure means "there is no such file".
|
|
328
|
+
*
|
|
329
|
+
* @param error - The caught value.
|
|
330
|
+
* @returns `true` for `ENOENT` and `ENOTDIR`.
|
|
331
|
+
*/
|
|
332
|
+
function isMissingFileError(error) {
|
|
333
|
+
const code = typeof error === "object" && error !== null && "code" in error ? error.code : null;
|
|
334
|
+
return code === "ENOENT" || code === "ENOTDIR";
|
|
335
|
+
}
|
|
336
|
+
/**
|
|
337
|
+
* Resolves a path to its real path, or returns it unchanged when it cannot be resolved.
|
|
338
|
+
*
|
|
339
|
+
* @param path - An absolute path.
|
|
340
|
+
* @returns The real path.
|
|
341
|
+
*/
|
|
342
|
+
function realPathOrSelf(path) {
|
|
343
|
+
try {
|
|
344
|
+
return realpathSync.native(path);
|
|
345
|
+
} catch {
|
|
346
|
+
return path;
|
|
347
|
+
}
|
|
348
|
+
}
|
|
349
|
+
/**
|
|
350
|
+
* Answers 404 with no body and no caching.
|
|
351
|
+
*
|
|
352
|
+
* @param response - The response to end.
|
|
353
|
+
*/
|
|
354
|
+
function refuse(response) {
|
|
355
|
+
response.statusCode = 404;
|
|
356
|
+
response.setHeader("Cache-Control", "no-store");
|
|
357
|
+
response.end();
|
|
358
|
+
}
|
|
359
|
+
/** The `/@fs/` prefix Vite serves absolute paths under, and `/@id/` for unresolved ids. */
|
|
360
|
+
const FS_PREFIX = "/@fs/";
|
|
361
|
+
const ID_PREFIX = "/@id/";
|
|
362
|
+
const DRIVE_RE = /^[a-z]:/iu;
|
|
363
|
+
/**
|
|
364
|
+
* The files a decoded request path could be served from.
|
|
365
|
+
*
|
|
366
|
+
* @param path - The decoded request path, `/`-separated.
|
|
367
|
+
* @param options - The server's directories and base.
|
|
368
|
+
* @returns Absolute paths, existing or not.
|
|
369
|
+
*/
|
|
370
|
+
function candidateFiles(path, options) {
|
|
371
|
+
const basePath = options.base.startsWith("/") ? options.base : "/";
|
|
372
|
+
const forms = [path];
|
|
373
|
+
if (basePath !== "/" && path.startsWith(basePath)) forms.push(`/${path.slice(basePath.length)}`);
|
|
374
|
+
const candidates = [];
|
|
375
|
+
for (const form of forms) {
|
|
376
|
+
const relativeForms = [form];
|
|
377
|
+
const alias = options.alias.find(({ find }) => typeof find === "string" ? form.startsWith(find) : find.test(form));
|
|
378
|
+
if (alias !== void 0) {
|
|
379
|
+
const redirected = form.replace(alias.find, alias.replacement);
|
|
380
|
+
candidates.push(redirected);
|
|
381
|
+
relativeForms.push(redirected);
|
|
382
|
+
}
|
|
383
|
+
for (const prefix of [FS_PREFIX, ID_PREFIX]) if (form.startsWith(prefix)) {
|
|
384
|
+
const rest = form.slice(prefix.length);
|
|
385
|
+
candidates.push(DRIVE_RE.test(rest) ? rest : `/${rest.replace(/^\/+/u, "")}`);
|
|
386
|
+
relativeForms.push(`/${rest}`);
|
|
387
|
+
}
|
|
388
|
+
for (const directory of options.serveDirs) candidates.push(...relativeForms.map((relativeForm) => join(directory, relativeForm)));
|
|
389
|
+
}
|
|
390
|
+
return candidates.filter((candidate) => isAbsolute(candidate)).map((candidate) => resolve(candidate));
|
|
391
|
+
}
|
|
392
|
+
/**
|
|
393
|
+
* Reports whether a candidate file, or the file Vite would find by adding an extension to it, is
|
|
394
|
+
* private once links are followed.
|
|
395
|
+
*
|
|
396
|
+
* @param file - An absolute candidate path.
|
|
397
|
+
* @param options - The real root and `resolve.extensions`.
|
|
398
|
+
* @returns `true` when the request must be refused.
|
|
399
|
+
*/
|
|
400
|
+
function isPrivateCandidate(file, options) {
|
|
401
|
+
if (isPrivateRealPath(options.realRoot, file)) return true;
|
|
402
|
+
if (existsSync(file) || !existsSync(dirname(file))) return false;
|
|
403
|
+
return options.extensions.some((extension) => isPrivateRealPath(options.realRoot, `${file}${extension}`));
|
|
404
|
+
}
|
|
405
|
+
/**
|
|
406
|
+
* Connect middleware that answers 404, with no body, to every request into the private directory:
|
|
407
|
+
* one whose path names it ({@link isPrivateRequestPath}), and one whose file lies in it once
|
|
408
|
+
* symbolic links are followed (`src/link -> ../.ignifx`).
|
|
409
|
+
*
|
|
410
|
+
* @remarks
|
|
411
|
+
* For the second, it maps the URL to the files Vite could serve for it (root, `publicDir` or
|
|
412
|
+
* `outDir`, `/@fs/` and `/@id/` absolute paths, with and without `base`, and the path a
|
|
413
|
+
* `resolve.alias` entry rewrites it to) and checks each with {@link isPrivateRealPath}. A missing
|
|
414
|
+
* file is judged by its deepest existing ancestor and, when its directory exists, with each of
|
|
415
|
+
* `resolve.extensions` appended, as Vite completes a module request. The plugin's `load` hook
|
|
416
|
+
* covers what Vite resolves some other way.
|
|
417
|
+
*
|
|
418
|
+
* @param options - Returns the server's directories; read per request, as they are only known once
|
|
419
|
+
* the config is resolved.
|
|
420
|
+
* @returns The middleware.
|
|
421
|
+
*/
|
|
422
|
+
function createPrivateDirGuard(options) {
|
|
423
|
+
return (request, response, next) => {
|
|
424
|
+
const decoded = decodedRequestPath(request.url ?? "");
|
|
425
|
+
if (decoded === null || hasPrivateSegment(decoded)) {
|
|
426
|
+
refuse(response);
|
|
427
|
+
return;
|
|
428
|
+
}
|
|
429
|
+
const resolved = options();
|
|
430
|
+
if (candidateFiles(decoded.replaceAll("\\", "/"), resolved).some((file) => isPrivateCandidate(file, resolved))) {
|
|
431
|
+
refuse(response);
|
|
432
|
+
return;
|
|
433
|
+
}
|
|
434
|
+
next();
|
|
435
|
+
};
|
|
436
|
+
}
|
|
437
|
+
//#endregion
|
|
438
|
+
//#region src/vite/plugin.ts
|
|
439
|
+
/**
|
|
440
|
+
* The editor host's Vite plugin: the scene view's page on the project's own dev server, and
|
|
441
|
+
* `virtual:ignifx/editor` for the play view (`docs/architecture/17-editor-host.md` §3).
|
|
442
|
+
*/
|
|
443
|
+
/** The plugin names, as they appear in Vite's logs. */
|
|
444
|
+
const PAGE_PLUGIN_NAME = "ignifx-editor-host";
|
|
445
|
+
const PLAY_PLUGIN_NAME = "ignifx-editor-host:play-controls";
|
|
446
|
+
/** What Vite crawls for dependencies when `optimizeDeps.entries` is not set. */
|
|
447
|
+
const DEFAULT_OPTIMIZE_ENTRIES = "**/*.html";
|
|
448
|
+
/**
|
|
449
|
+
* Reads the version of the project's own `@ignifx/core`.
|
|
450
|
+
*
|
|
451
|
+
* @param root - The Vite root.
|
|
452
|
+
* @returns The version, or `null` when the project does not resolve `@ignifx/core`.
|
|
453
|
+
*
|
|
454
|
+
* @beta
|
|
455
|
+
*/
|
|
456
|
+
function readProjectEngineVersion(root) {
|
|
457
|
+
try {
|
|
458
|
+
const requireFromProject = createRequire(join(root, "package.json"));
|
|
459
|
+
const manifest = JSON.parse(readFileSync(requireFromProject.resolve("@ignifx/core/package.json"), "utf8"));
|
|
460
|
+
if (typeof manifest === "object" && manifest !== null && "version" in manifest) return typeof manifest.version === "string" ? manifest.version : null;
|
|
461
|
+
return null;
|
|
462
|
+
} catch {
|
|
463
|
+
return null;
|
|
464
|
+
}
|
|
465
|
+
}
|
|
466
|
+
/**
|
|
467
|
+
* Checks the options and applies their defaults.
|
|
468
|
+
*
|
|
469
|
+
* @param options - The options as given.
|
|
470
|
+
* @returns The extensions module path and the heartbeat period.
|
|
471
|
+
* @throws EditorHostPluginError `IGX-1801` for a malformed origin, `IGX-1803` for a bad option.
|
|
472
|
+
*/
|
|
473
|
+
function checkOptions(options) {
|
|
474
|
+
if (!isEditorOrigin(options.editorOrigin)) throw new EditorHostPluginError(EditorHostErrorCode.invalidEditorOrigin, `editorOrigin "${options.editorOrigin}" is not an origin; pass one such as "ignifx://app" or "http://localhost:5173".`);
|
|
475
|
+
const interval = options.heartbeatIntervalMs;
|
|
476
|
+
if (interval !== void 0 && (!Number.isFinite(interval) || interval <= 0)) throw new EditorHostPluginError(EditorHostErrorCode.invalidOption, `heartbeatIntervalMs must be a positive number of milliseconds; got ${String(interval)}.`);
|
|
477
|
+
return {
|
|
478
|
+
extensions: normalizeExtensionsModule(options.extensions ?? "/src/extensions.ts"),
|
|
479
|
+
heartbeatIntervalMs: interval ?? null
|
|
480
|
+
};
|
|
481
|
+
}
|
|
482
|
+
/**
|
|
483
|
+
* The editor host's Vite plugin.
|
|
484
|
+
*
|
|
485
|
+
* @remarks
|
|
486
|
+
* It is two plugins, because the two halves run under different commands:
|
|
487
|
+
*
|
|
488
|
+
* - `ignifx-editor-host` (`vite dev` only) serves the scene view at `/__ignifx_editor__/` with
|
|
489
|
+
* `Content-Security-Policy: frame-ancestors <editorOrigin>`, and adds the same header to every
|
|
490
|
+
* page a browser navigates to, so the game's own `index.html` (the play view) can be framed by the
|
|
491
|
+
* editor and by nothing else. A `Content-Security-Policy` in `server.headers` replaces it. The page's module imports the host,
|
|
492
|
+
* `virtual:ignifx/scripts`, `virtual:ignifx/manifest` and the project's extensions module from
|
|
493
|
+
* the project's own graph, and calls `startEditorHost`. It adds the extensions module to
|
|
494
|
+
* `optimizeDeps.entries` (keeping Vite's default crawl) and keeps `@ignifx/editor-host` out of
|
|
495
|
+
* pre-bundling, so the host reaches the same pre-bundled `@ignifx/core` as the game.
|
|
496
|
+
* - `ignifx-editor-host:play-controls` (every command) serves `virtual:ignifx/editor`: the play
|
|
497
|
+
* controls under `vite dev`, an empty function under `vite build`. Under `vite dev` and
|
|
498
|
+
* `vite preview` it also answers 404 to any request into `.ignifx/`, the editor's private
|
|
499
|
+
* directory, by path or through a symbolic link, as `ignifx()` does; this covers a config that
|
|
500
|
+
* lists this plugin without `ignifx()`.
|
|
501
|
+
*
|
|
502
|
+
* List it after `ignifx()` from `@ignifx/vite-plugin`, which serves the two modules the scene
|
|
503
|
+
* view imports.
|
|
504
|
+
*
|
|
505
|
+
* @param options - The editor's origin and the scene view's options.
|
|
506
|
+
* @returns The plugins, to be listed in `vite.config.ts`.
|
|
507
|
+
* @throws EditorHostPluginError `IGX-1801` for a malformed `editorOrigin`, `IGX-1803` for a bad
|
|
508
|
+
* `extensions` path or `heartbeatIntervalMs`.
|
|
509
|
+
*
|
|
510
|
+
* @example
|
|
511
|
+
* ```ts
|
|
512
|
+
* // vite.config.ts
|
|
513
|
+
* import { ignifx } from "@ignifx/vite-plugin";
|
|
514
|
+
* import { editorHostPlugin } from "@ignifx/editor-host/vite";
|
|
515
|
+
* import { defineConfig } from "vite";
|
|
516
|
+
*
|
|
517
|
+
* export default defineConfig({
|
|
518
|
+
* plugins: [ignifx(), editorHostPlugin({ editorOrigin: "ignifx://app" })],
|
|
519
|
+
* });
|
|
520
|
+
* ```
|
|
521
|
+
*
|
|
522
|
+
* @beta
|
|
523
|
+
*/
|
|
524
|
+
function editorHostPlugin(options) {
|
|
525
|
+
const { extensions, heartbeatIntervalMs } = checkOptions(options);
|
|
526
|
+
const { editorOrigin } = options;
|
|
527
|
+
let root = process.cwd();
|
|
528
|
+
let base = "/";
|
|
529
|
+
let command = "serve";
|
|
530
|
+
let engineVersion = null;
|
|
531
|
+
const extensionsFile = () => resolve(root, `.${extensions}`);
|
|
532
|
+
const framePolicy = `frame-ancestors ${editorOrigin}`;
|
|
533
|
+
/**
|
|
534
|
+
* Sends the frame policy with every page a browser navigates to, the game's `index.html` (the
|
|
535
|
+
* play view) included. Navigations and frames ask for `text/html`; module and asset requests do
|
|
536
|
+
* not, and a policy on them would do nothing anyway.
|
|
537
|
+
*
|
|
538
|
+
* @param server - The dev server.
|
|
539
|
+
*/
|
|
540
|
+
const installPlayViewPolicy = (server) => {
|
|
541
|
+
server.middlewares.use((request, response, next) => {
|
|
542
|
+
if ((request.method === "GET" || request.method === "HEAD") && (request.headers.accept ?? "").includes("text/html")) response.setHeader("Content-Security-Policy", framePolicy);
|
|
543
|
+
next();
|
|
544
|
+
});
|
|
545
|
+
};
|
|
546
|
+
/**
|
|
547
|
+
* Serves the scene view's page and redirects the path without its trailing slash.
|
|
548
|
+
*
|
|
549
|
+
* @param server - The dev server.
|
|
550
|
+
*/
|
|
551
|
+
const installPage = (server) => {
|
|
552
|
+
const pagePath = `${base.endsWith("/") ? base.slice(0, -1) : base}${EDITOR_PAGE_PATH}`;
|
|
553
|
+
server.middlewares.use((request, response, next) => {
|
|
554
|
+
const url = request.url ?? "";
|
|
555
|
+
const path = url.split("?")[0] ?? "";
|
|
556
|
+
if (path === pagePath.slice(0, -1)) {
|
|
557
|
+
response.statusCode = 302;
|
|
558
|
+
response.setHeader("Location", `${pagePath}${url.slice(path.length)}`);
|
|
559
|
+
response.end();
|
|
560
|
+
return;
|
|
561
|
+
}
|
|
562
|
+
if (path !== pagePath && path !== `${pagePath}index.html`) {
|
|
563
|
+
next();
|
|
564
|
+
return;
|
|
565
|
+
}
|
|
566
|
+
server.transformIndexHtml(EDITOR_PAGE_PATH, editorPageHtml(), request.originalUrl).then((html) => {
|
|
567
|
+
response.statusCode = 200;
|
|
568
|
+
response.setHeader("Content-Type", "text/html; charset=utf-8");
|
|
569
|
+
response.setHeader("Cache-Control", "no-store");
|
|
570
|
+
response.setHeader("Content-Security-Policy", framePolicy);
|
|
571
|
+
response.end(html);
|
|
572
|
+
}, (error) => {
|
|
573
|
+
next(error);
|
|
574
|
+
});
|
|
575
|
+
});
|
|
576
|
+
};
|
|
577
|
+
return [{
|
|
578
|
+
name: PAGE_PLUGIN_NAME,
|
|
579
|
+
apply: "serve",
|
|
580
|
+
config(userConfig) {
|
|
581
|
+
const projectRoot = resolve(process.cwd(), userConfig.root ?? ".");
|
|
582
|
+
const scanExtensions = existsSync(resolve(projectRoot, `.${extensions}`));
|
|
583
|
+
const entries = userConfig.optimizeDeps?.entries === void 0 ? [DEFAULT_OPTIMIZE_ENTRIES, extensions.slice(1)] : [extensions.slice(1)];
|
|
584
|
+
return { optimizeDeps: {
|
|
585
|
+
...scanExtensions ? { entries } : {},
|
|
586
|
+
exclude: ["@ignifx/editor-host"]
|
|
587
|
+
} };
|
|
588
|
+
},
|
|
589
|
+
configResolved(resolvedConfig) {
|
|
590
|
+
root = resolvedConfig.root;
|
|
591
|
+
base = resolvedConfig.base;
|
|
592
|
+
engineVersion = readProjectEngineVersion(root);
|
|
593
|
+
},
|
|
594
|
+
configureServer(server) {
|
|
595
|
+
installPlayViewPolicy(server);
|
|
596
|
+
installPage(server);
|
|
597
|
+
},
|
|
598
|
+
resolveId(id) {
|
|
599
|
+
return id === "virtual:ignifx/editor-host-entry" ? RESOLVED_EDITOR_ENTRY_MODULE_ID : null;
|
|
600
|
+
},
|
|
601
|
+
load(id) {
|
|
602
|
+
if (id !== RESOLVED_EDITOR_ENTRY_MODULE_ID) return null;
|
|
603
|
+
return editorEntryModuleSource({
|
|
604
|
+
editorOrigin,
|
|
605
|
+
extensionsModule: existsSync(extensionsFile()) ? extensions : null,
|
|
606
|
+
bootScene: options.bootScene ?? null,
|
|
607
|
+
engineVersion,
|
|
608
|
+
heartbeatIntervalMs
|
|
609
|
+
});
|
|
610
|
+
}
|
|
611
|
+
}, {
|
|
612
|
+
name: PLAY_PLUGIN_NAME,
|
|
613
|
+
configResolved(resolvedConfig) {
|
|
614
|
+
root = resolvedConfig.root;
|
|
615
|
+
command = resolvedConfig.command;
|
|
616
|
+
engineVersion = readProjectEngineVersion(root);
|
|
617
|
+
},
|
|
618
|
+
configureServer(server) {
|
|
619
|
+
const realRoot = realPathOrSelf(server.config.root);
|
|
620
|
+
const { publicDir } = server.config;
|
|
621
|
+
server.middlewares.use(createPrivateDirGuard(() => ({
|
|
622
|
+
realRoot,
|
|
623
|
+
base: server.config.base,
|
|
624
|
+
serveDirs: publicDir === "" ? [server.config.root] : [server.config.root, publicDir],
|
|
625
|
+
alias: server.config.resolve.alias,
|
|
626
|
+
extensions: server.config.resolve.extensions
|
|
627
|
+
})));
|
|
628
|
+
},
|
|
629
|
+
configurePreviewServer(server) {
|
|
630
|
+
const realRoot = realPathOrSelf(server.config.root);
|
|
631
|
+
const outDir = resolve(server.config.root, server.config.build.outDir);
|
|
632
|
+
server.middlewares.use(createPrivateDirGuard(() => ({
|
|
633
|
+
realRoot,
|
|
634
|
+
base: server.config.base,
|
|
635
|
+
serveDirs: [outDir],
|
|
636
|
+
alias: [],
|
|
637
|
+
extensions: []
|
|
638
|
+
})));
|
|
639
|
+
},
|
|
640
|
+
resolveId(id) {
|
|
641
|
+
return id === "virtual:ignifx/editor" ? RESOLVED_EDITOR_MODULE_ID : null;
|
|
642
|
+
},
|
|
643
|
+
load(id) {
|
|
644
|
+
if (id === RESOLVED_EDITOR_MODULE_ID) return playControlsModuleSource({
|
|
645
|
+
editorOrigin,
|
|
646
|
+
engineVersion,
|
|
647
|
+
heartbeatIntervalMs,
|
|
648
|
+
hot: command === "serve"
|
|
649
|
+
});
|
|
650
|
+
const file = id.split("?", 1)[0] ?? "";
|
|
651
|
+
if (!id.startsWith("\0") && isAbsolute(file) && isPrivateRealPath(realPathOrSelf(root), file)) this.error(`"${file}" is in the editor-private .ignifx/ directory, which holds the editor's MCP token; nothing may import or serve it. Remove the import or link.`);
|
|
652
|
+
return null;
|
|
653
|
+
}
|
|
654
|
+
}];
|
|
655
|
+
}
|
|
656
|
+
//#endregion
|
|
657
|
+
export { DEFAULT_EXTENSIONS_MODULE, EDITOR_CANVAS_ID, EDITOR_ENTRY_MODULE_ID, EDITOR_MODULE_ID, EDITOR_PAGE_PATH, EDITOR_PLAY_CONTROLS_EXPORT, EditorHostErrorCode, EditorHostPluginError, RESOLVED_EDITOR_ENTRY_MODULE_ID, RESOLVED_EDITOR_MODULE_ID, editorEntryModuleSource, editorHostPlugin, editorPageHtml, isEditorOrigin, normalizeExtensionsModule, playControlsModuleSource, readProjectEngineVersion };
|
|
658
|
+
|
|
659
|
+
//# sourceMappingURL=vite.js.map
|