@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/vite.d.ts ADDED
@@ -0,0 +1,248 @@
1
+ import { n as isEditorOrigin, t as EditorHostErrorCode } from "./error-codes.js";
2
+ import { Plugin } from "vite";
3
+ //#region src/vite/errors.d.ts
4
+ /**
5
+ * The error every `@ignifx/editor-host/vite` API throws for a misconfiguration
6
+ * (`CONSTITUTION.md` §3.9).
7
+ *
8
+ * @beta
9
+ */
10
+ export declare class EditorHostPluginError extends Error {
11
+ /** The stable diagnostic code for this failure. */
12
+ readonly code: EditorHostErrorCode;
13
+ /**
14
+ * Creates a plugin error.
15
+ *
16
+ * @param code - The stable `IGX-####` code for the failure.
17
+ * @param message - An actionable description of what went wrong and how to fix it.
18
+ */
19
+ constructor(code: EditorHostErrorCode, message: string);
20
+ }
21
+ //#endregion
22
+ //#region src/vite/modules.d.ts
23
+ /**
24
+ * The path the scene view is served at, below the dev server's `base`.
25
+ *
26
+ * @beta
27
+ */
28
+ export declare const EDITOR_PAGE_PATH = "/__ignifx_editor__/";
29
+ /**
30
+ * The module a game imports to hand its app to the editor's play controls.
31
+ *
32
+ * @example
33
+ * ```ts
34
+ * import { attachEditorPlayControls } from "virtual:ignifx/editor";
35
+ *
36
+ * attachEditorPlayControls(app);
37
+ * ```
38
+ *
39
+ * @beta
40
+ */
41
+ export declare const EDITOR_MODULE_ID = "virtual:ignifx/editor";
42
+ /**
43
+ * The resolved id of {@link EDITOR_MODULE_ID}. The `\0` prefix marks it as owned by a plugin.
44
+ *
45
+ * @beta
46
+ */
47
+ export declare const RESOLVED_EDITOR_MODULE_ID: string;
48
+ /**
49
+ * The module the scene view's page runs. Only the generated page imports it.
50
+ *
51
+ * @beta
52
+ */
53
+ export declare const EDITOR_ENTRY_MODULE_ID = "virtual:ignifx/editor-host-entry";
54
+ /**
55
+ * The resolved id of {@link EDITOR_ENTRY_MODULE_ID}.
56
+ *
57
+ * @beta
58
+ */
59
+ export declare const RESOLVED_EDITOR_ENTRY_MODULE_ID: string;
60
+ /**
61
+ * The function `virtual:ignifx/editor` exports. It takes the game's app and returns a function that
62
+ * detaches the controls; in a production build it does nothing.
63
+ *
64
+ * @beta
65
+ */
66
+ export declare const EDITOR_PLAY_CONTROLS_EXPORT = "attachEditorPlayControls";
67
+ /**
68
+ * The module the scene view imports the project's extensions from, unless the plugin is told
69
+ * otherwise. It exports `extensions()`, which returns the list `main.ts` passes to `createApp`.
70
+ *
71
+ * @beta
72
+ */
73
+ export declare const DEFAULT_EXTENSIONS_MODULE = "/src/extensions.ts";
74
+ /**
75
+ * The `id` of the scene view's canvas.
76
+ *
77
+ * @beta
78
+ */
79
+ export declare const EDITOR_CANVAS_ID = "ignifx-editor-view";
80
+ /**
81
+ * Options accepted by {@link editorEntryModuleSource}.
82
+ *
83
+ * @beta
84
+ */
85
+ interface EditorEntryModuleOptions {
86
+ /** The origin the editor is served from. */
87
+ readonly editorOrigin: string;
88
+ /** The root-absolute path of the project's extensions module, or `null` when it has none. */
89
+ readonly extensionsModule: string | null;
90
+ /** A scene address to load before the app starts, or `null`. */
91
+ readonly bootScene: string | null;
92
+ /** The project's `@ignifx/core` version, or `null` when it could not be read. */
93
+ readonly engineVersion: string | null;
94
+ /** Milliseconds between heartbeats, or `null` for the host's default. */
95
+ readonly heartbeatIntervalMs: number | null;
96
+ }
97
+ /**
98
+ * Options accepted by {@link playControlsModuleSource}.
99
+ *
100
+ * @beta
101
+ */
102
+ interface PlayControlsModuleOptions {
103
+ /** The origin the editor is served from. */
104
+ readonly editorOrigin: string;
105
+ /** The project's `@ignifx/core` version, or `null` when it could not be read. */
106
+ readonly engineVersion: string | null;
107
+ /** Milliseconds between heartbeats, or `null` for the host's default. */
108
+ readonly heartbeatIntervalMs: number | null;
109
+ /**
110
+ * Emit the development module. `false` emits the production no-op, which imports nothing and has
111
+ * no `import.meta.hot` reference.
112
+ */
113
+ readonly hot: boolean;
114
+ }
115
+ /**
116
+ * Turns the `extensions` option into the root-absolute path the generated module imports.
117
+ *
118
+ * @param path - The path as configured, relative to the Vite root or already root-absolute.
119
+ * @returns The root-absolute path, for example `"/src/extensions.ts"`.
120
+ * @throws EditorHostPluginError `IGX-1803` when the path is empty or leaves the root with `..`.
121
+ *
122
+ * @beta
123
+ */
124
+ export declare function normalizeExtensionsModule(path: string): string;
125
+ /**
126
+ * Generates the module the scene view's page runs.
127
+ *
128
+ * @remarks
129
+ * The module is the only code with an import-time effect: it creates the host. The package itself
130
+ * creates nothing when imported (`CONSTITUTION.md` §3.5). Every import is resolved from the
131
+ * project's root, so the host, the scripts, and the extensions share the project's one copy of
132
+ * `@ignifx/core`. It hands every `ignifx:asset-changed` event to `host.assetChanged`, which
133
+ * reloads the asset in place; the `import.meta.hot` calls are written out literally, because Vite
134
+ * finds them by reading the source.
135
+ *
136
+ * @param options - The editor origin, the project's extensions module, and the reporting options.
137
+ * @returns The ES module source.
138
+ *
139
+ * @beta
140
+ */
141
+ export declare function editorEntryModuleSource(options: EditorEntryModuleOptions): string;
142
+ /**
143
+ * Generates the scene view's HTML page, before Vite's own `transformIndexHtml` adds its client.
144
+ *
145
+ * @returns The HTML document.
146
+ *
147
+ * @beta
148
+ */
149
+ export declare function editorPageHtml(): string;
150
+ /**
151
+ * Generates `virtual:ignifx/editor`.
152
+ *
153
+ * @remarks
154
+ * In development, the module listens for the editor's connect message as soon as it is evaluated,
155
+ * which is before the game's `main.ts` runs, and keeps the port
156
+ * (`listenForEditorPlayControls`); `attachEditorPlayControls(app)` then starts the play controls on
157
+ * it, so the editor's first connect message is never lost to `await createApp(...)`. Vite replacing
158
+ * the module stops both. The `import.meta.hot` calls are written out literally because Vite
159
+ * finds them by reading the source, not by running it. In a production build the export is an empty
160
+ * function, the same shape as `acceptHotReload` from `virtual:ignifx/scripts`, so the game's
161
+ * `main.ts` builds either way and ships no editor code.
162
+ *
163
+ * @param options - The editor origin, the reporting options, and whether to emit the development module.
164
+ * @returns The ES module source.
165
+ *
166
+ * @beta
167
+ */
168
+ export declare function playControlsModuleSource(options: PlayControlsModuleOptions): string;
169
+ //#endregion
170
+ //#region src/vite/plugin.d.ts
171
+ /**
172
+ * Options accepted by {@link editorHostPlugin}.
173
+ *
174
+ * @beta
175
+ */
176
+ interface EditorHostPluginOptions {
177
+ /**
178
+ * The origin the editor is served from, for example `"ignifx://app"` when packaged or
179
+ * `"http://localhost:5173"` while the editor itself runs from a dev server. Only this origin may
180
+ * frame either view in `vite dev`, and only it can hand either view a port.
181
+ */
182
+ readonly editorOrigin: string;
183
+ /**
184
+ * The project's extensions module, relative to the Vite root. It exports `extensions()`, which
185
+ * returns the list `main.ts` passes to `createApp`. When the file does not exist the scene view
186
+ * runs with no extensions. Defaults to `"/src/extensions.ts"`.
187
+ */
188
+ readonly extensions?: string;
189
+ /** A scene address the scene view loads before it starts. Defaults to none. */
190
+ readonly bootScene?: string | null;
191
+ /** Milliseconds between heartbeats in both views. Defaults to the host's `1000`. */
192
+ readonly heartbeatIntervalMs?: number;
193
+ }
194
+ /**
195
+ * Reads the version of the project's own `@ignifx/core`.
196
+ *
197
+ * @param root - The Vite root.
198
+ * @returns The version, or `null` when the project does not resolve `@ignifx/core`.
199
+ *
200
+ * @beta
201
+ */
202
+ export declare function readProjectEngineVersion(root: string): string | null;
203
+ /**
204
+ * The editor host's Vite plugin.
205
+ *
206
+ * @remarks
207
+ * It is two plugins, because the two halves run under different commands:
208
+ *
209
+ * - `ignifx-editor-host` (`vite dev` only) serves the scene view at `/__ignifx_editor__/` with
210
+ * `Content-Security-Policy: frame-ancestors <editorOrigin>`, and adds the same header to every
211
+ * page a browser navigates to, so the game's own `index.html` (the play view) can be framed by the
212
+ * editor and by nothing else. A `Content-Security-Policy` in `server.headers` replaces it. The page's module imports the host,
213
+ * `virtual:ignifx/scripts`, `virtual:ignifx/manifest` and the project's extensions module from
214
+ * the project's own graph, and calls `startEditorHost`. It adds the extensions module to
215
+ * `optimizeDeps.entries` (keeping Vite's default crawl) and keeps `@ignifx/editor-host` out of
216
+ * pre-bundling, so the host reaches the same pre-bundled `@ignifx/core` as the game.
217
+ * - `ignifx-editor-host:play-controls` (every command) serves `virtual:ignifx/editor`: the play
218
+ * controls under `vite dev`, an empty function under `vite build`. Under `vite dev` and
219
+ * `vite preview` it also answers 404 to any request into `.ignifx/`, the editor's private
220
+ * directory, by path or through a symbolic link, as `ignifx()` does; this covers a config that
221
+ * lists this plugin without `ignifx()`.
222
+ *
223
+ * List it after `ignifx()` from `@ignifx/vite-plugin`, which serves the two modules the scene
224
+ * view imports.
225
+ *
226
+ * @param options - The editor's origin and the scene view's options.
227
+ * @returns The plugins, to be listed in `vite.config.ts`.
228
+ * @throws EditorHostPluginError `IGX-1801` for a malformed `editorOrigin`, `IGX-1803` for a bad
229
+ * `extensions` path or `heartbeatIntervalMs`.
230
+ *
231
+ * @example
232
+ * ```ts
233
+ * // vite.config.ts
234
+ * import { ignifx } from "@ignifx/vite-plugin";
235
+ * import { editorHostPlugin } from "@ignifx/editor-host/vite";
236
+ * import { defineConfig } from "vite";
237
+ *
238
+ * export default defineConfig({
239
+ * plugins: [ignifx(), editorHostPlugin({ editorOrigin: "ignifx://app" })],
240
+ * });
241
+ * ```
242
+ *
243
+ * @beta
244
+ */
245
+ export declare function editorHostPlugin(options: EditorHostPluginOptions): Plugin[];
246
+ //#endregion
247
+ export { type EditorEntryModuleOptions, EditorHostErrorCode, type EditorHostPluginOptions, type PlayControlsModuleOptions, isEditorOrigin };
248
+ //# sourceMappingURL=vite.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"vite.d.ts","names":[],"sources":["../src/vite/errors.ts","../src/vite/modules.ts","../src/vite/plugin.ts"],"mappings":";;;;;;;;;qBAiBa,8BAA8B;;WAEhC,MAAM;;;;;;;EAQf,YAAY,MAAM,qBAAqB;;;;;;;;;qBCR5B;;;;;;;;;;;;;qBAcA;;;;;;qBAOA;;;;;;qBAOA;;;;;;qBAOA;;;;;;;qBAQA;;;;;;;qBAQA;;;;;;qBAOA;;;;;;UAUI;;WAEN;;WAEA;;WAEA;;WAEA;;WAEA;;;;;;;UAQM;;WAEN;;WAEA;;WAEA;;;;;WAKA;;;;;;;;;;;wBAYK,0BAA0B;;;;;;;;;;;;;;;;;wBAyC1B,wBAAwB,SAAS;;;;;;;;wBAoCjC;;;;;;;;;;;;;;;;;;;wBAwCA,yBAAyB,SAAS;;;;;;;;UCvNjC;;;;;;WAMN;;;;;;WAMA;;WAEA;;WAEA;;;;;;;;;;wBAkBK,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAmFzB,iBAAiB,SAAS,0BAA0B"}