@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.
@@ -0,0 +1 @@
1
+ {"version":3,"file":"vite.js","names":[],"sources":["../src/vite/errors.ts","../src/vite/modules.ts","../src/vite/private-dir.ts","../src/vite/plugin.ts"],"sourcesContent":["/**\n * The error the Vite plugin throws.\n *\n * @remarks\n * The plugin runs in the dev server's Node process, where loading `@ignifx/core` (and through it\n * Babylon Lite) to throw its `IgnifxError` would be pure cost. Like `@ignifx/vite-plugin`'s own\n * error, it carries the same registered `IGX-####` codes the page half throws.\n */\n\nimport type { EditorHostErrorCode } from \"../error-codes.js\";\n\n/**\n * The error every `@ignifx/editor-host/vite` API throws for a misconfiguration\n * (`CONSTITUTION.md` §3.9).\n *\n * @beta\n */\nexport class EditorHostPluginError extends Error {\n /** The stable diagnostic code for this failure. */\n readonly code: EditorHostErrorCode;\n\n /**\n * Creates a plugin error.\n *\n * @param code - The stable `IGX-####` code for the failure.\n * @param message - An actionable description of what went wrong and how to fix it.\n */\n constructor(code: EditorHostErrorCode, message: string) {\n super(message);\n this.name = \"EditorHostPluginError\";\n this.code = code;\n }\n}\n","/**\n * The page and the two modules the plugin generates: the scene view's HTML entry, the module that\n * page runs, and `virtual:ignifx/editor`, the play view's controls.\n */\n\nimport {\n ASSET_CHANGED_EVENT,\n IGNIFX_CONFIG_DEFINE_KEY,\n MANIFEST_MODULE_ID,\n SCRIPTS_MODULE_ID,\n} from \"@ignifx/vite-plugin\";\nimport { EditorHostErrorCode } from \"../error-codes.js\";\nimport { EditorHostPluginError } from \"./errors.js\";\n\n/**\n * The path the scene view is served at, below the dev server's `base`.\n *\n * @beta\n */\nexport const EDITOR_PAGE_PATH = \"/__ignifx_editor__/\";\n\n/**\n * The module a game imports to hand its app to the editor's play controls.\n *\n * @example\n * ```ts\n * import { attachEditorPlayControls } from \"virtual:ignifx/editor\";\n *\n * attachEditorPlayControls(app);\n * ```\n *\n * @beta\n */\nexport const EDITOR_MODULE_ID = \"virtual:ignifx/editor\";\n\n/**\n * The resolved id of {@link EDITOR_MODULE_ID}. The `\\0` prefix marks it as owned by a plugin.\n *\n * @beta\n */\nexport const RESOLVED_EDITOR_MODULE_ID: string = `\\0${EDITOR_MODULE_ID}`;\n\n/**\n * The module the scene view's page runs. Only the generated page imports it.\n *\n * @beta\n */\nexport const EDITOR_ENTRY_MODULE_ID = \"virtual:ignifx/editor-host-entry\";\n\n/**\n * The resolved id of {@link EDITOR_ENTRY_MODULE_ID}.\n *\n * @beta\n */\nexport const RESOLVED_EDITOR_ENTRY_MODULE_ID: string = `\\0${EDITOR_ENTRY_MODULE_ID}`;\n\n/**\n * The function `virtual:ignifx/editor` exports. It takes the game's app and returns a function that\n * detaches the controls; in a production build it does nothing.\n *\n * @beta\n */\nexport const EDITOR_PLAY_CONTROLS_EXPORT = \"attachEditorPlayControls\";\n\n/**\n * The module the scene view imports the project's extensions from, unless the plugin is told\n * otherwise. It exports `extensions()`, which returns the list `main.ts` passes to `createApp`.\n *\n * @beta\n */\nexport const DEFAULT_EXTENSIONS_MODULE = \"/src/extensions.ts\";\n\n/**\n * The `id` of the scene view's canvas.\n *\n * @beta\n */\nexport const EDITOR_CANVAS_ID = \"ignifx-editor-view\";\n\n/** The package the generated modules import the host from, resolved from the project's root. */\nconst HOST_PACKAGE = \"@ignifx/editor-host\";\n\n/**\n * Options accepted by {@link editorEntryModuleSource}.\n *\n * @beta\n */\nexport interface EditorEntryModuleOptions {\n /** The origin the editor is served from. */\n readonly editorOrigin: string;\n /** The root-absolute path of the project's extensions module, or `null` when it has none. */\n readonly extensionsModule: string | null;\n /** A scene address to load before the app starts, or `null`. */\n readonly bootScene: string | null;\n /** The project's `@ignifx/core` version, or `null` when it could not be read. */\n readonly engineVersion: string | null;\n /** Milliseconds between heartbeats, or `null` for the host's default. */\n readonly heartbeatIntervalMs: number | null;\n}\n\n/**\n * Options accepted by {@link playControlsModuleSource}.\n *\n * @beta\n */\nexport interface PlayControlsModuleOptions {\n /** The origin the editor is served from. */\n readonly editorOrigin: string;\n /** The project's `@ignifx/core` version, or `null` when it could not be read. */\n readonly engineVersion: string | null;\n /** Milliseconds between heartbeats, or `null` for the host's default. */\n readonly heartbeatIntervalMs: number | null;\n /**\n * Emit the development module. `false` emits the production no-op, which imports nothing and has\n * no `import.meta.hot` reference.\n */\n readonly hot: boolean;\n}\n\n/**\n * Turns the `extensions` option into the root-absolute path the generated module imports.\n *\n * @param path - The path as configured, relative to the Vite root or already root-absolute.\n * @returns The root-absolute path, for example `\"/src/extensions.ts\"`.\n * @throws EditorHostPluginError `IGX-1803` when the path is empty or leaves the root with `..`.\n *\n * @beta\n */\nexport function normalizeExtensionsModule(path: string): string {\n const trimmed = path.startsWith(\"./\") ? path.slice(2) : path;\n if (trimmed === \"\" || trimmed === \"/\" || trimmed.split(\"/\").some((segment) => segment === \"..\")) {\n throw new EditorHostPluginError(\n EditorHostErrorCode.invalidOption,\n `The \"extensions\" option must name a module inside the Vite root, for example \"src/extensions.ts\"; got \"${path}\".`,\n );\n }\n return trimmed.startsWith(\"/\") ? trimmed : `/${trimmed}`;\n}\n\n/**\n * The fields shared by both generated calls, as source text.\n *\n * @param engineVersion - The version to report, or `null`.\n * @param heartbeatIntervalMs - The heartbeat period, or `null`.\n * @returns Zero, one, or two `key: value,` lines.\n */\nfunction reportingLines(engineVersion: string | null, heartbeatIntervalMs: number | null): readonly string[] {\n return [\n ...(engineVersion === null ? [] : [` engineVersion: ${JSON.stringify(engineVersion)},`]),\n ...(heartbeatIntervalMs === null ? [] : [` heartbeatIntervalMs: ${JSON.stringify(heartbeatIntervalMs)},`]),\n ];\n}\n\n/**\n * Generates the module the scene view's page runs.\n *\n * @remarks\n * The module is the only code with an import-time effect: it creates the host. The package itself\n * creates nothing when imported (`CONSTITUTION.md` §3.5). Every import is resolved from the\n * project's root, so the host, the scripts, and the extensions share the project's one copy of\n * `@ignifx/core`. It hands every `ignifx:asset-changed` event to `host.assetChanged`, which\n * reloads the asset in place; the `import.meta.hot` calls are written out literally, because Vite\n * finds them by reading the source.\n *\n * @param options - The editor origin, the project's extensions module, and the reporting options.\n * @returns The ES module source.\n *\n * @beta\n */\nexport function editorEntryModuleSource(options: EditorEntryModuleOptions): string {\n const { extensionsModule } = options;\n return [\n `import { startEditorHost } from ${JSON.stringify(HOST_PACKAGE)};`,\n `import { manifest } from ${JSON.stringify(MANIFEST_MODULE_ID)};`,\n `import { acceptHotReload, scripts } from ${JSON.stringify(SCRIPTS_MODULE_ID)};`,\n ...(extensionsModule === null ? [] : [`import { extensions } from ${JSON.stringify(extensionsModule)};`]),\n \"\",\n \"const host = await startEditorHost({\",\n ` editorOrigin: ${JSON.stringify(options.editorOrigin)},`,\n ' hostKind: \"scene\",',\n ` canvas: document.getElementById(${JSON.stringify(EDITOR_CANVAS_ID)}),`,\n ` settings: ${IGNIFX_CONFIG_DEFINE_KEY},`,\n \" assets: { manifest },\",\n ` extensions: ${extensionsModule === null ? \"[]\" : \"extensions()\"},`,\n \" scripts,\",\n ` bootScene: ${JSON.stringify(options.bootScene)},`,\n ...reportingLines(options.engineVersion, options.heartbeatIntervalMs),\n \"});\",\n \"acceptHotReload(host.app);\",\n \"if (import.meta.hot) {\",\n ` import.meta.hot.on(${JSON.stringify(ASSET_CHANGED_EVENT)}, (change) => {`,\n \" void host.assetChanged(change);\",\n \" });\",\n \"}\",\n \"\",\n ].join(\"\\n\");\n}\n\n/**\n * Generates the scene view's HTML page, before Vite's own `transformIndexHtml` adds its client.\n *\n * @returns The HTML document.\n *\n * @beta\n */\nexport function editorPageHtml(): string {\n return [\n \"<!doctype html>\",\n '<html lang=\"en\">',\n \" <head>\",\n ' <meta charset=\"utf-8\" />',\n ' <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />',\n \" <title>ignifx editor host</title>\",\n \" <style>\",\n \" html, body { margin: 0; height: 100%; overflow: hidden; background: #000; }\",\n ` #${EDITOR_CANVAS_ID} { display: block; width: 100%; height: 100%; }`,\n \" </style>\",\n \" </head>\",\n \" <body>\",\n ` <canvas id=\"${EDITOR_CANVAS_ID}\"></canvas>`,\n ` <script type=\"module\" src=\"/@id/${EDITOR_ENTRY_MODULE_ID}\"></script>`,\n \" </body>\",\n \"</html>\",\n \"\",\n ].join(\"\\n\");\n}\n\n/**\n * Generates `virtual:ignifx/editor`.\n *\n * @remarks\n * In development, the module listens for the editor's connect message as soon as it is evaluated,\n * which is before the game's `main.ts` runs, and keeps the port\n * (`listenForEditorPlayControls`); `attachEditorPlayControls(app)` then starts the play controls on\n * it, so the editor's first connect message is never lost to `await createApp(...)`. Vite replacing\n * the module stops both. The `import.meta.hot` calls are written out literally because Vite\n * finds them by reading the source, not by running it. In a production build the export is an empty\n * function, the same shape as `acceptHotReload` from `virtual:ignifx/scripts`, so the game's\n * `main.ts` builds either way and ships no editor code.\n *\n * @param options - The editor origin, the reporting options, and whether to emit the development module.\n * @returns The ES module source.\n *\n * @beta\n */\nexport function playControlsModuleSource(options: PlayControlsModuleOptions): string {\n if (!options.hot) {\n return [`export function ${EDITOR_PLAY_CONTROLS_EXPORT}() {`, \" return () => {};\", \"}\", \"\"].join(\"\\n\");\n }\n return [\n `import { listenForEditorPlayControls } from ${JSON.stringify(HOST_PACKAGE)};`,\n \"\",\n \"// Listens now, before main.ts awaits createApp, so the editor's first port is kept.\",\n \"const connector = listenForEditorPlayControls({\",\n ` editorOrigin: ${JSON.stringify(options.editorOrigin)},`,\n ...reportingLines(options.engineVersion, options.heartbeatIntervalMs),\n \"});\",\n \"if (import.meta.hot) {\",\n \" import.meta.hot.dispose(() => {\",\n \" connector.dispose();\",\n \" });\",\n \"}\",\n \"\",\n `export function ${EDITOR_PLAY_CONTROLS_EXPORT}(app) {`,\n \" const controls = connector.attach(app);\",\n \" return () => {\",\n \" controls.dispose();\",\n \" };\",\n \"}\",\n \"\",\n ].join(\"\\n\");\n}\n","/**\n * A copy of `@ignifx/vite-plugin`'s `.ignifx/` request guard (`src/private-dir.ts` there), kept\n * here as defence in depth: a project whose Vite config lists `editorHostPlugin()` without\n * `ignifx()` would otherwise serve `.ignifx/mcp.json`, the editor's MCP token, to any page.\n * `@ignifx/vite-plugin` is an optional peer, so this package cannot import it; keep the two in step.\n */\n\nimport { existsSync, realpathSync } from \"node:fs\";\nimport { basename, dirname, isAbsolute, join, relative, resolve } from \"node:path\";\nimport type { Connect } from \"vite\";\n\n/** The editor-private directory at a project's root. */\nconst PRIVATE_DIR_NAME = \".ignifx\";\n\n/** Percent-decoding passes before a path counts as private regardless of what it decodes to. */\nconst MAX_DECODE_PASSES = 8;\n\n/** Windows 8.3 short names of `.ignifx` (`IGNIFX~1`), which resolve to it on NTFS. */\nconst SHORT_NAME_RE = /^ignifx~\\d+$/u;\n\n/**\n * Decodes every `%XX` escape, byte by byte, so a malformed sequence never stops decoding.\n *\n * @param text - The text to decode.\n * @returns The text with each escape replaced by the byte it names.\n */\nfunction decodeEscapes(text: string): string {\n return text.replaceAll(/%([0-9a-f]{2})/giu, (_match, hex: string) => String.fromCodePoint(Number.parseInt(hex, 16)));\n}\n\n/**\n * Reports whether one path segment names the private directory.\n *\n * @param segment - One decoded segment.\n * @returns `true` for `.ignifx` in any case, with Windows' ignored trailing dots and spaces, an\n * alternate data stream suffix, or as an 8.3 short name.\n */\nfunction isPrivateSegment(segment: string): boolean {\n const name = (segment.normalize(\"NFKC\").toLowerCase().split(\":\")[0] ?? \"\").replace(/[. ]+$/u, \"\");\n return name === PRIVATE_DIR_NAME || SHORT_NAME_RE.test(name);\n}\n\n/**\n * Reports whether a request URL reaches into the private directory.\n *\n * @remarks\n * The query and fragment are dropped, then escapes are decoded until the path stops changing (so\n * `%252e` counts as `.`). Every segment between `/`, `\\`, `?` and `#` is checked: resolving `.` and\n * `..` only removes segments, so a path that names no `.ignifx` segment cannot reach one, and this\n * covers `/@fs/<absolute path>` and `/@id/` forms alike.\n *\n * @param url - The request URL as the server received it.\n * @returns `true` when the request must be refused.\n */\nexport function isPrivateRequestPath(url: string): boolean {\n const path = decodedRequestPath(url);\n return path === null || hasPrivateSegment(path);\n}\n\n/**\n * The path part of a request URL with every escape decoded, nested ones included.\n *\n * @param url - The request URL as the server received it.\n * @returns The decoded path, or `null` when it still changes after the last decoding pass.\n */\nfunction decodedRequestPath(url: string): string | null {\n let path = url.split(/[?#]/u, 1)[0] ?? \"\";\n for (let pass = 0; ; pass += 1) {\n const decoded = decodeEscapes(path);\n if (decoded === path) {\n return path;\n }\n if (pass === MAX_DECODE_PASSES) {\n return null;\n }\n path = decoded;\n }\n}\n\n/**\n * Reports whether a path names the private directory in any of its segments.\n *\n * @param path - A path with `/` or `\\` separators, relative or absolute.\n * @returns `true` when a segment between separators is a spelling of `.ignifx`.\n */\nfunction hasPrivateSegment(path: string): boolean {\n return path.split(/[/\\\\?#]/u).some(isPrivateSegment);\n}\n\n/**\n * Reports whether a file, once every symbolic link on its path is followed, lies in a private\n * directory.\n *\n * @remarks\n * A link such as `src/link -> ../.ignifx` hides the directory from every check that reads the path\n * as written. The deepest part of `path` that exists is resolved with `realpath` and the rest\n * appended, so a request for a file the server would find by adding an extension is judged too.\n * Only the part of the real path below `realBase` and its common ancestor with the file counts:\n * a project that itself lives under some `.ignifx` directory is not refused wholesale.\n *\n * @param realBase - The real path the result is measured from, normally the project root.\n * @param path - An absolute path, existing or not.\n * @returns `true` when the real path has a `.ignifx` segment, or when it cannot be resolved for a\n * reason other than not existing (the check fails closed).\n *\n * It is synchronous, like Vite's own file lookups: a few `realpath` calls per request or module.\n */\nexport function isPrivateRealPath(realBase: string, path: string): boolean {\n let current = path;\n const rest: string[] = [];\n for (;;) {\n try {\n return hasPrivateSegment(relative(realBase, join(realpathSync.native(current), ...rest)));\n } catch (error) {\n const missing = isMissingFileError(error);\n const parent = dirname(current);\n if (!missing || parent === current) {\n return !missing;\n }\n rest.unshift(basename(current));\n current = parent;\n }\n }\n}\n\n/**\n * Reports whether a caught failure means \"there is no such file\".\n *\n * @param error - The caught value.\n * @returns `true` for `ENOENT` and `ENOTDIR`.\n */\nfunction isMissingFileError(error: unknown): boolean {\n const code = typeof error === \"object\" && error !== null && \"code\" in error ? error.code : null;\n return code === \"ENOENT\" || code === \"ENOTDIR\";\n}\n\n/**\n * Resolves a path to its real path, or returns it unchanged when it cannot be resolved.\n *\n * @param path - An absolute path.\n * @returns The real path.\n */\nexport function realPathOrSelf(path: string): string {\n try {\n return realpathSync.native(path);\n } catch {\n return path;\n }\n}\n\n/**\n * Answers 404 with no body and no caching.\n *\n * @param response - The response to end.\n */\nfunction refuse(response: Parameters<Connect.NextHandleFunction>[1]): void {\n response.statusCode = 404;\n response.setHeader(\"Cache-Control\", \"no-store\");\n response.end();\n}\n\n/** Where a server finds the file a request URL names. */\ninterface PrivateDirGuardOptions {\n /** The real path of the project root, which real paths are judged against. */\n readonly realRoot: string;\n /** The server's `base`; a URL is tried with and without it. */\n readonly base: string;\n /** The directories a root-relative URL is served from: the root and `publicDir` in dev, `outDir` in preview. */\n readonly serveDirs: readonly string[];\n /** `resolve.alias`, which Vite's static middleware applies to request paths in dev; `[]` in preview. */\n readonly alias: readonly { readonly find: string | RegExp; readonly replacement: string }[];\n /** `resolve.extensions`, which Vite tries for a module request whose file does not exist. */\n readonly extensions: readonly string[];\n}\n\n/** The `/@fs/` prefix Vite serves absolute paths under, and `/@id/` for unresolved ids. */\nconst FS_PREFIX = \"/@fs/\";\nconst ID_PREFIX = \"/@id/\";\nconst DRIVE_RE = /^[a-z]:/iu;\n\n/**\n * The files a decoded request path could be served from.\n *\n * @param path - The decoded request path, `/`-separated.\n * @param options - The server's directories and base.\n * @returns Absolute paths, existing or not.\n */\nfunction candidateFiles(path: string, options: PrivateDirGuardOptions): string[] {\n const basePath = options.base.startsWith(\"/\") ? options.base : \"/\";\n const forms = [path];\n if (basePath !== \"/\" && path.startsWith(basePath)) {\n forms.push(`/${path.slice(basePath.length)}`);\n }\n const candidates: string[] = [];\n for (const form of forms) {\n const relativeForms = [form];\n // Vite's static middleware rewrites a path the first alias matches and serves it from the root.\n const alias = options.alias.find(({ find }) =>\n typeof find === \"string\" ? form.startsWith(find) : find.test(form),\n );\n if (alias !== undefined) {\n const redirected = form.replace(alias.find, alias.replacement);\n candidates.push(redirected);\n relativeForms.push(redirected);\n }\n for (const prefix of [FS_PREFIX, ID_PREFIX]) {\n if (form.startsWith(prefix)) {\n const rest = form.slice(prefix.length);\n candidates.push(DRIVE_RE.test(rest) ? rest : `/${rest.replace(/^\\/+/u, \"\")}`);\n relativeForms.push(`/${rest}`);\n }\n }\n for (const directory of options.serveDirs) {\n candidates.push(...relativeForms.map((relativeForm) => join(directory, relativeForm)));\n }\n }\n // `resolve` folds `.` and `..` the way a server normalises a URL, before anything is looked up.\n return candidates.filter((candidate) => isAbsolute(candidate)).map((candidate) => resolve(candidate));\n}\n\n/**\n * Reports whether a candidate file, or the file Vite would find by adding an extension to it, is\n * private once links are followed.\n *\n * @param file - An absolute candidate path.\n * @param options - The real root and `resolve.extensions`.\n * @returns `true` when the request must be refused.\n */\nfunction isPrivateCandidate(file: string, options: PrivateDirGuardOptions): boolean {\n if (isPrivateRealPath(options.realRoot, file)) {\n return true;\n }\n // Extensions are only worth trying where Vite would: the file is missing and its directory is not.\n if (existsSync(file) || !existsSync(dirname(file))) {\n return false;\n }\n return options.extensions.some((extension) => isPrivateRealPath(options.realRoot, `${file}${extension}`));\n}\n\n/**\n * Connect middleware that answers 404, with no body, to every request into the private directory:\n * one whose path names it ({@link isPrivateRequestPath}), and one whose file lies in it once\n * symbolic links are followed (`src/link -> ../.ignifx`).\n *\n * @remarks\n * For the second, it maps the URL to the files Vite could serve for it (root, `publicDir` or\n * `outDir`, `/@fs/` and `/@id/` absolute paths, with and without `base`, and the path a\n * `resolve.alias` entry rewrites it to) and checks each with {@link isPrivateRealPath}. A missing\n * file is judged by its deepest existing ancestor and, when its directory exists, with each of\n * `resolve.extensions` appended, as Vite completes a module request. The plugin's `load` hook\n * covers what Vite resolves some other way.\n *\n * @param options - Returns the server's directories; read per request, as they are only known once\n * the config is resolved.\n * @returns The middleware.\n */\nexport function createPrivateDirGuard(options: () => PrivateDirGuardOptions): Connect.NextHandleFunction {\n return (request, response, next) => {\n const decoded = decodedRequestPath(request.url ?? \"\");\n if (decoded === null || hasPrivateSegment(decoded)) {\n refuse(response);\n return;\n }\n const resolved = options();\n const path = decoded.replaceAll(\"\\\\\", \"/\");\n if (candidateFiles(path, resolved).some((file) => isPrivateCandidate(file, resolved))) {\n refuse(response);\n return;\n }\n next();\n };\n}\n","/**\n * The editor host's Vite plugin: the scene view's page on the project's own dev server, and\n * `virtual:ignifx/editor` for the play view (`docs/architecture/17-editor-host.md` §3).\n */\n\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { createRequire } from \"node:module\";\nimport { isAbsolute, join, resolve } from \"node:path\";\nimport { EditorHostErrorCode, isEditorOrigin } from \"../error-codes.js\";\nimport { EditorHostPluginError } from \"./errors.js\";\nimport {\n DEFAULT_EXTENSIONS_MODULE,\n EDITOR_ENTRY_MODULE_ID,\n EDITOR_MODULE_ID,\n EDITOR_PAGE_PATH,\n editorEntryModuleSource,\n editorPageHtml,\n normalizeExtensionsModule,\n playControlsModuleSource,\n RESOLVED_EDITOR_ENTRY_MODULE_ID,\n RESOLVED_EDITOR_MODULE_ID,\n} from \"./modules.js\";\nimport { createPrivateDirGuard, isPrivateRealPath, realPathOrSelf } from \"./private-dir.js\";\nimport type { ConfigEnv, Plugin, ViteDevServer } from \"vite\";\n\n/**\n * Options accepted by {@link editorHostPlugin}.\n *\n * @beta\n */\nexport interface EditorHostPluginOptions {\n /**\n * The origin the editor is served from, for example `\"ignifx://app\"` when packaged or\n * `\"http://localhost:5173\"` while the editor itself runs from a dev server. Only this origin may\n * frame either view in `vite dev`, and only it can hand either view a port.\n */\n readonly editorOrigin: string;\n /**\n * The project's extensions module, relative to the Vite root. It exports `extensions()`, which\n * returns the list `main.ts` passes to `createApp`. When the file does not exist the scene view\n * runs with no extensions. Defaults to `\"/src/extensions.ts\"`.\n */\n readonly extensions?: string;\n /** A scene address the scene view loads before it starts. Defaults to none. */\n readonly bootScene?: string | null;\n /** Milliseconds between heartbeats in both views. Defaults to the host's `1000`. */\n readonly heartbeatIntervalMs?: number;\n}\n\n/** The plugin names, as they appear in Vite's logs. */\nconst PAGE_PLUGIN_NAME = \"ignifx-editor-host\";\nconst PLAY_PLUGIN_NAME = \"ignifx-editor-host:play-controls\";\n\n/** What Vite crawls for dependencies when `optimizeDeps.entries` is not set. */\nconst DEFAULT_OPTIMIZE_ENTRIES = \"**/*.html\";\n\n/**\n * Reads the version of the project's own `@ignifx/core`.\n *\n * @param root - The Vite root.\n * @returns The version, or `null` when the project does not resolve `@ignifx/core`.\n *\n * @beta\n */\nexport function readProjectEngineVersion(root: string): string | null {\n try {\n const requireFromProject = createRequire(join(root, \"package.json\"));\n const manifest: unknown = JSON.parse(readFileSync(requireFromProject.resolve(\"@ignifx/core/package.json\"), \"utf8\"));\n if (typeof manifest === \"object\" && manifest !== null && \"version\" in manifest) {\n return typeof manifest.version === \"string\" ? manifest.version : null;\n }\n return null;\n } catch {\n // An unresolvable core is reported by the host as core's own `VERSION`, not as a failure here.\n return null;\n }\n}\n\n/**\n * Checks the options and applies their defaults.\n *\n * @param options - The options as given.\n * @returns The extensions module path and the heartbeat period.\n * @throws EditorHostPluginError `IGX-1801` for a malformed origin, `IGX-1803` for a bad option.\n */\nfunction checkOptions(options: EditorHostPluginOptions): { extensions: string; heartbeatIntervalMs: number | null } {\n if (!isEditorOrigin(options.editorOrigin)) {\n throw new EditorHostPluginError(\n EditorHostErrorCode.invalidEditorOrigin,\n `editorOrigin \"${options.editorOrigin}\" is not an origin; pass one such as \"ignifx://app\" or \"http://localhost:5173\".`,\n );\n }\n const interval = options.heartbeatIntervalMs;\n if (interval !== undefined && (!Number.isFinite(interval) || interval <= 0)) {\n throw new EditorHostPluginError(\n EditorHostErrorCode.invalidOption,\n `heartbeatIntervalMs must be a positive number of milliseconds; got ${String(interval)}.`,\n );\n }\n return {\n extensions: normalizeExtensionsModule(options.extensions ?? DEFAULT_EXTENSIONS_MODULE),\n heartbeatIntervalMs: interval ?? null,\n };\n}\n\n/**\n * The editor host's Vite plugin.\n *\n * @remarks\n * It is two plugins, because the two halves run under different commands:\n *\n * - `ignifx-editor-host` (`vite dev` only) serves the scene view at `/__ignifx_editor__/` with\n * `Content-Security-Policy: frame-ancestors <editorOrigin>`, and adds the same header to every\n * page a browser navigates to, so the game's own `index.html` (the play view) can be framed by the\n * editor and by nothing else. A `Content-Security-Policy` in `server.headers` replaces it. The page's module imports the host,\n * `virtual:ignifx/scripts`, `virtual:ignifx/manifest` and the project's extensions module from\n * the project's own graph, and calls `startEditorHost`. It adds the extensions module to\n * `optimizeDeps.entries` (keeping Vite's default crawl) and keeps `@ignifx/editor-host` out of\n * pre-bundling, so the host reaches the same pre-bundled `@ignifx/core` as the game.\n * - `ignifx-editor-host:play-controls` (every command) serves `virtual:ignifx/editor`: the play\n * controls under `vite dev`, an empty function under `vite build`. Under `vite dev` and\n * `vite preview` it also answers 404 to any request into `.ignifx/`, the editor's private\n * directory, by path or through a symbolic link, as `ignifx()` does; this covers a config that\n * lists this plugin without `ignifx()`.\n *\n * List it after `ignifx()` from `@ignifx/vite-plugin`, which serves the two modules the scene\n * view imports.\n *\n * @param options - The editor's origin and the scene view's options.\n * @returns The plugins, to be listed in `vite.config.ts`.\n * @throws EditorHostPluginError `IGX-1801` for a malformed `editorOrigin`, `IGX-1803` for a bad\n * `extensions` path or `heartbeatIntervalMs`.\n *\n * @example\n * ```ts\n * // vite.config.ts\n * import { ignifx } from \"@ignifx/vite-plugin\";\n * import { editorHostPlugin } from \"@ignifx/editor-host/vite\";\n * import { defineConfig } from \"vite\";\n *\n * export default defineConfig({\n * plugins: [ignifx(), editorHostPlugin({ editorOrigin: \"ignifx://app\" })],\n * });\n * ```\n *\n * @beta\n */\nexport function editorHostPlugin(options: EditorHostPluginOptions): Plugin[] {\n const { extensions, heartbeatIntervalMs } = checkOptions(options);\n const { editorOrigin } = options;\n let root = process.cwd();\n let base = \"/\";\n let command: ConfigEnv[\"command\"] = \"serve\";\n let engineVersion: string | null = null;\n\n const extensionsFile = (): string => resolve(root, `.${extensions}`);\n // Only the editor may put either view in a frame; any other page that tries is blocked. A tab the\n // developer opens on the dev server is not a frame, so the policy leaves it alone.\n const framePolicy = `frame-ancestors ${editorOrigin}`;\n\n /**\n * Sends the frame policy with every page a browser navigates to, the game's `index.html` (the\n * play view) included. Navigations and frames ask for `text/html`; module and asset requests do\n * not, and a policy on them would do nothing anyway.\n *\n * @param server - The dev server.\n */\n const installPlayViewPolicy = (server: ViteDevServer): void => {\n server.middlewares.use((request, response, next) => {\n const isRead = request.method === \"GET\" || request.method === \"HEAD\";\n if (isRead && (request.headers.accept ?? \"\").includes(\"text/html\")) {\n response.setHeader(\"Content-Security-Policy\", framePolicy);\n }\n next();\n });\n };\n\n /**\n * Serves the scene view's page and redirects the path without its trailing slash.\n *\n * @param server - The dev server.\n */\n const installPage = (server: ViteDevServer): void => {\n const pagePath = `${base.endsWith(\"/\") ? base.slice(0, -1) : base}${EDITOR_PAGE_PATH}`;\n server.middlewares.use((request, response, next) => {\n const url = request.url ?? \"\";\n const path = url.split(\"?\")[0] ?? \"\";\n if (path === pagePath.slice(0, -1)) {\n response.statusCode = 302;\n response.setHeader(\"Location\", `${pagePath}${url.slice(path.length)}`);\n response.end();\n return;\n }\n if (path !== pagePath && path !== `${pagePath}index.html`) {\n next();\n return;\n }\n server.transformIndexHtml(EDITOR_PAGE_PATH, editorPageHtml(), request.originalUrl).then(\n (html) => {\n response.statusCode = 200;\n response.setHeader(\"Content-Type\", \"text/html; charset=utf-8\");\n response.setHeader(\"Cache-Control\", \"no-store\");\n response.setHeader(\"Content-Security-Policy\", framePolicy);\n response.end(html);\n },\n (error: unknown) => {\n next(error);\n },\n );\n });\n };\n\n const page: Plugin = {\n name: PAGE_PLUGIN_NAME,\n // A production build must never contain the scene view.\n apply: \"serve\",\n\n config(userConfig) {\n const projectRoot = resolve(process.cwd(), userConfig.root ?? \".\");\n const scanExtensions = existsSync(resolve(projectRoot, `.${extensions}`));\n // Vite concatenates arrays when it merges this into the user's config, and setting `entries`\n // at all replaces its default crawl of every HTML file, so the default is restated only when\n // the user set nothing.\n const entries =\n userConfig.optimizeDeps?.entries === undefined\n ? [DEFAULT_OPTIMIZE_ENTRIES, extensions.slice(1)]\n : [extensions.slice(1)];\n return {\n optimizeDeps: {\n ...(scanExtensions ? { entries } : {}),\n // Served as it is, its `@ignifx/core` import resolves to the game's own pre-bundled core.\n exclude: [\"@ignifx/editor-host\"],\n },\n };\n },\n\n configResolved(resolvedConfig) {\n root = resolvedConfig.root;\n base = resolvedConfig.base;\n engineVersion = readProjectEngineVersion(root);\n },\n\n configureServer(server) {\n // Registered directly rather than returned as a post hook, so they run before Vite's own HTML\n // fallback and index middleware.\n installPlayViewPolicy(server);\n installPage(server);\n },\n\n resolveId(id) {\n return id === EDITOR_ENTRY_MODULE_ID ? RESOLVED_EDITOR_ENTRY_MODULE_ID : null;\n },\n\n load(id) {\n if (id !== RESOLVED_EDITOR_ENTRY_MODULE_ID) {\n return null;\n }\n return editorEntryModuleSource({\n editorOrigin,\n extensionsModule: existsSync(extensionsFile()) ? extensions : null,\n bootScene: options.bootScene ?? null,\n engineVersion,\n heartbeatIntervalMs,\n });\n },\n };\n\n const play: Plugin = {\n name: PLAY_PLUGIN_NAME,\n\n configResolved(resolvedConfig) {\n root = resolvedConfig.root;\n command = resolvedConfig.command;\n engineVersion = readProjectEngineVersion(root);\n },\n\n // Defence in depth for a config without `ignifx()`, whose guard otherwise keeps `.ignifx/` (the\n // editor's MCP token) off the server; registered in the hook body, ahead of Vite's file serving.\n configureServer(server) {\n const realRoot = realPathOrSelf(server.config.root);\n const { publicDir } = server.config;\n server.middlewares.use(\n createPrivateDirGuard(() => ({\n realRoot,\n base: server.config.base,\n serveDirs: publicDir === \"\" ? [server.config.root] : [server.config.root, publicDir],\n alias: server.config.resolve.alias,\n extensions: server.config.resolve.extensions,\n })),\n );\n },\n\n configurePreviewServer(server) {\n const realRoot = realPathOrSelf(server.config.root);\n const outDir = resolve(server.config.root, server.config.build.outDir);\n server.middlewares.use(\n createPrivateDirGuard(() => ({\n realRoot,\n base: server.config.base,\n serveDirs: [outDir],\n alias: [],\n extensions: [],\n })),\n );\n },\n\n resolveId(id) {\n return id === EDITOR_MODULE_ID ? RESOLVED_EDITOR_MODULE_ID : null;\n },\n\n load(id) {\n if (id === RESOLVED_EDITOR_MODULE_ID) {\n return playControlsModuleSource({ editorOrigin, engineVersion, heartbeatIntervalMs, hot: command === \"serve\" });\n }\n // Whatever resolved to it (an alias, `/@id/`, an import through a link), a module whose real\n // path is in `.ignifx/` is never loaded: in dev it would be served, in a build bundled.\n const file = id.split(\"?\", 1)[0] ?? \"\";\n if (!id.startsWith(\"\\0\") && isAbsolute(file) && isPrivateRealPath(realPathOrSelf(root), file)) {\n this.error(\n `\"${file}\" is in the editor-private .ignifx/ directory, which holds the editor's MCP token; ` +\n \"nothing may import or serve it. Remove the import or link.\",\n );\n }\n return null;\n },\n };\n\n return [page, play];\n}\n"],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ignifx/editor-host",
3
- "version": "0.9.0",
3
+ "version": "0.11.0",
4
4
  "description": "ignifx editor host: runs a project's own engine inside the ignifx editor's scene view and play view, over a versioned protocol.",
5
5
  "keywords": [
6
6
  "ignifx"
@@ -40,6 +40,7 @@
40
40
  },
41
41
  "devDependencies": {
42
42
  "@arethetypeswrong/cli": "^0.18.5",
43
+ "@babylonjs/lite": "1.34.0",
43
44
  "@microsoft/api-extractor": "^7.59.0",
44
45
  "@types/node": "^24.13.3",
45
46
  "@types/webxr": "^0.5.0",
@@ -51,13 +52,17 @@
51
52
  "typescript-native": "npm:typescript@7.0.2",
52
53
  "vite": "^8.2.2",
53
54
  "vitest": "^5.0.0",
54
- "@ignifx/core": "0.9.0",
55
- "@ignifx/vite-plugin": "0.9.0"
55
+ "@ignifx/2d": "0.11.0",
56
+ "@ignifx/physics": "0.11.0",
57
+ "@ignifx/physics-2d": "0.11.0",
58
+ "@ignifx/vite-plugin": "0.11.0",
59
+ "@ignifx/core": "0.11.0"
56
60
  },
57
61
  "peerDependencies": {
62
+ "@babylonjs/lite": "1.34.0",
58
63
  "vite": "^8.2.2",
59
- "@ignifx/core": "0.9.0",
60
- "@ignifx/vite-plugin": "0.9.0"
64
+ "@ignifx/core": "0.11.0",
65
+ "@ignifx/vite-plugin": "0.11.0"
61
66
  },
62
67
  "peerDependenciesMeta": {
63
68
  "@ignifx/vite-plugin": {
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  name: editor-host
3
- description: Connects an ignifx project to the ignifx editor with @ignifx/editor-host: the Vite plugin that serves the editor's scene view from the project's own dev server, the virtual:ignifx/editor play controls a game's main.ts hands its app to, and the host half of the editor protocol (hello/ready, ping, heartbeat) over a MessagePort. Use when wiring a project or template for the editor, when the user mentions @ignifx/editor-host, editorHostPlugin, attachEditorPlayControls, virtual:ignifx/editor, startEditorHost or /__ignifx_editor__/, or when debugging why the editor cannot connect to a view.
3
+ description: Connects an ignifx project to the ignifx editor with @ignifx/editor-host: the Vite plugin that serves the editor's scene view from the project's own dev server, the virtual:ignifx/editor play controls a game's main.ts hands its app to (play, pause, step, stop, playState, playStateChanged, playStats), and the host half of the editor protocol 0.3 over a MessagePort (hello/ready, heartbeat, and the scene document methods openScene, applyOps, readBack, select, pick, frame, setGizmo, setViewMode, screenshot, getSchemas, describeSettings, setAnimateMaterials, getColliderOutlines, sampleAnimation), including the 2D view mode (an editor Camera2D and app.twoD.pickAt picking). Use when wiring a project or template for the editor, when the user mentions @ignifx/editor-host, editorHostPlugin, attachEditorPlayControls, virtual:ignifx/editor, startEditorHost or /__ignifx_editor__/, or when debugging why the editor cannot connect to a view or why the scene view disagrees with the editor's document.
4
4
  license: Apache-2.0
5
5
  metadata:
6
- ignifx-version: "0.9.0"
6
+ ignifx-version: "0.11.0"
7
7
  ---
8
8
 
9
9
  # @ignifx/editor-host
@@ -25,8 +25,9 @@ editor's, even though its name starts with `editor-`.
25
25
 
26
26
  ## Environment
27
27
 
28
- - Engine: ignifx `0.9.0`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
29
- - Peers: `@ignifx/core`; for the `./vite` entry, `@ignifx/vite-plugin` and `vite`.
28
+ - Engine: ignifx `0.11.0`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
29
+ - Peers: `@ignifx/core` and `@babylonjs/lite` (the scene view's gizmos); for the `./vite` entry,
30
+ `@ignifx/vite-plugin` and `vite`.
30
31
  - A development dependency of the project, at the same version as its `@ignifx/core`.
31
32
  - Nothing happens at import time; the plugin's generated page module is what starts the host.
32
33
 
@@ -58,18 +59,39 @@ editor window (ignifx://app)
58
59
  ├── <iframe> scene view http://127.0.0.1:<port>/__ignifx_editor__/
59
60
  │ generated module → startEditorHost({ extensions(), scripts, settings, manifest })
60
61
  │ owns its app, in edit mode; hostKind "scene"
62
+ │ world: the open document's scene + a persistent "editor" scene (camera, never saved)
61
63
  └── <iframe> play view http://localhost:<port>/ (the game's own index.html)
62
64
  main.ts → attachEditorPlayControls(app) (virtual:ignifx/editor; a no-op in builds)
63
65
  the game owns its app; hostKind "play"
64
66
 
65
- each view ◀── MessagePort ──▶ editor JSON-RPC 2.0, protocol 0.2
66
- connect (window message, origin-checked) → hello → ready → ping/pong, heartbeat, play/pause/step/stop
67
+ each view ◀── MessagePort ──▶ editor JSON-RPC 2.0, protocol 0.3
68
+ connect (window message, origin-checked) → hello → ready → ping/pong, heartbeat
69
+ scene view: schemasChanged → openScene → applyOps… / readBack / select / pick / frame / setGizmo / screenshot
70
+ / setViewMode / getSchemas / describeSettings (on request only)
71
+ / setAnimateMaterials / getColliderOutlines / sampleAnimation
72
+ ← sceneOpened, selectionChanged, transformDragging/Dragged, hotReloaded, assetReloaded,
73
+ hostError, log
74
+ play view: play / pause / step / stop / playState / playStats
75
+ ← playStateChanged, log, hostError, hotReloaded (logRelay; kept from before hello)
67
76
  ```
68
77
 
69
78
  The editor posts `{ type: "ignifx-editor/connect" }` with a fresh `MessagePort` to each view on every
70
79
  `load`. A host takes a port only from `editorOrigin`, replaces its old port whenever a new one
71
80
  arrives, answers `hello` with `ready` (engine version, protocol, capabilities, host kind), and then
72
- sends a `heartbeat` notification every second so the editor notices a crashed view.
81
+ sends a `heartbeat` notification every second so the editor notices a crashed view. The play view's
82
+ module listens as soon as it is evaluated and keeps the port until `attachEditorPlayControls(app)`
83
+ runs, so a port posted while `main.ts` awaits `createApp` is not lost. Under `vite dev` both views
84
+ carry `Content-Security-Policy: frame-ancestors <editorOrigin>`.
85
+
86
+ The editor owns the scene document; the scene view mirrors it. `openScene` sends the whole file
87
+ object (it may hold unsaved edits) and the host builds it with `world.loadSceneFile`, keeping the
88
+ file's uids. Every command the editor applies to its document goes to the host as `applyOps`, the
89
+ same ops; any failure means the mirror drifted, and the editor resends `openScene`. What the user
90
+ does in the view comes back as notifications (`selectionChanged`, `transformDragged`) that the
91
+ editor turns into commands. The host never edits the document. When a script's hot reload changes a
92
+ field's default, the host gives the field its new default wherever the document leaves it out, and
93
+ keeps the values and overrides the document sets (`hotReloadDefaults`), so the editor need not
94
+ reopen the scene.
73
95
 
74
96
  ## First app
75
97
 
@@ -113,16 +135,24 @@ host.dispose();
113
135
 
114
136
  `skills/ignifx/references/api/editor-host.md` and `editor-host-vite.md` have the generated surface.
115
137
 
116
- | Member | What it does |
117
- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
118
- | `editorHostPlugin(options)` (`/vite`) | The two Vite plugins: the scene view's page (dev only) and `virtual:ignifx/editor` |
119
- | `attachEditorPlayControls(app)` | From `virtual:ignifx/editor`: hands the game's app to the editor; returns a detach |
120
- | `startEditorHost(options)` | Starts the scene view's host and its edit-mode app; resolves to a disposable `EditorHost` |
121
- | `startEditorPlayControls(app, options)` | What `attachEditorPlayControls` calls in development |
122
- | `EDITOR_CONNECT_MESSAGE_TYPE`, `isEditorConnectMessage` | The window message that carries the port, and its check |
123
- | `PROTOCOL_VERSION`, `RpcErrorCode`, `isRpcMessage`, `isPlayState` | The protocol 0.2 values and checks, mirrored from `@ignifx/editor-protocol`; before 1.0 the major and minor must both match |
124
- | `PlayMethod`, `PlayState` | `play`, `pause`, `step`, `stop`, and what each answers |
125
- | `EditorHostErrorCode` | `IGX-1801` bad origin, `IGX-1802` no window, `IGX-1803` bad option |
138
+ | Member | What it does |
139
+ | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
140
+ | `editorHostPlugin(options)` (`/vite`) | The two Vite plugins: the scene view's page (dev only) and `virtual:ignifx/editor` |
141
+ | `attachEditorPlayControls(app)` | From `virtual:ignifx/editor`: hands the game's app to the editor; returns a detach |
142
+ | `startEditorHost(options)` | Starts the scene view's host and its edit-mode app; resolves to a disposable `EditorHost` |
143
+ | `listenForEditorPlayControls(options)` | What `virtual:ignifx/editor` calls in development: keeps the editor's port until `attach(app)` starts the controls on it |
144
+ | `startEditorPlayControls(app, options)` | The play controls on their own, listening from the call |
145
+ | `EDITOR_CONNECT_MESSAGE_TYPE`, `isEditorConnectMessage` | The window message that carries the port, and its check |
146
+ | `PROTOCOL_VERSION`, `RpcErrorCode`, `isRpcMessage`, `isPlayState` | The protocol 0.3 values and checks, mirrored from `@ignifx/editor-protocol`; before 1.0 the major and minor must both match |
147
+ | `SceneMethod`, `SceneNotification`, `SceneOp`, `isApplyOpsParams`, … | The scene document methods, notifications, the thirteen ops, and their guards |
148
+ | `EditorHost.editorScene` | The persistent `editor` scene instance holding the host's own objects |
149
+ | `EditorHost.assetChanged(change)` | Reloads an asset changed on disk in place and sends `assetReloaded`; the generated page calls it on `ignifx:asset-changed` |
150
+ | `PlayMethod`, `PlayState` | `play`, `pause`, `step`, `stop`, and what each answers; `playState` reads the state without changing it |
151
+ | `PlayNotification`, `PlayPhase`, `isPlayStateReport` | `playStateChanged` and `playState`'s `{ state: "playing" \| "paused" \| "stopped", frameCount, time }` |
152
+ | `PlayStats`, `isPlayStats` | `playStats`'s `{ fps, frameTimeMs, entityCount, frameCount }`: the newest second of `app.diagnostics` frames, the world's entities |
153
+ | `HostCapability.hotReloadDefaults` | The scene view gives fields the document leaves out their new default after a script's hot reload |
154
+ | `HostCapability.logRelay`, `isAppErrorData`, `LoggedError` | Both views relay `log` (with the first `Error` a line carries), `hostError` (entity, component, phase, stack) and `hotReloaded` |
155
+ | `EditorHostErrorCode` | `IGX-1801` bad origin, `IGX-1802` no window, `IGX-1803` bad option |
126
156
 
127
157
  ## Recipes
128
158
 
@@ -171,8 +201,11 @@ pageWindow.dispatchEvent(
171
201
  const answers: unknown[] = [];
172
202
  const done = new Promise<void>((resolve) => {
173
203
  channel.port1.onmessage = (event: MessageEvent): void => {
174
- answers.push(event.data);
175
- if (answers.length === 3) {
204
+ // Answers carry their request's id; `heartbeat` and `playStateChanged` do not.
205
+ if (typeof event.data === "object" && event.data !== null && "id" in event.data) {
206
+ answers.push(event.data);
207
+ }
208
+ if (answers.length === 4) {
176
209
  resolve();
177
210
  }
178
211
  };
@@ -184,6 +217,7 @@ const send = (id: number, method: string, params?: object): void => {
184
217
  send(1, "hello", { editorVersion: "0.1.0", protocol: PROTOCOL_VERSION });
185
218
  send(2, "play");
186
219
  send(3, "step", { deltaSeconds: 1 / 60 });
220
+ send(4, "playState");
187
221
  await done;
188
222
  console.log(JSON.stringify(answers.at(-1)));
189
223
 
@@ -192,10 +226,64 @@ controls.dispose();
192
226
  app.dispose();
193
227
  ```
194
228
 
229
+ ### Open a scene document in the scene view
230
+
231
+ ```ts run
232
+ import { EDITOR_CONNECT_MESSAGE_TYPE, PROTOCOL_VERSION, startEditorHost } from "@ignifx/editor-host";
233
+
234
+ const frameWindow = new EventTarget();
235
+ const host = await startEditorHost({ editorOrigin: "ignifx://app", headless: true, messageTarget: frameWindow });
236
+ const channel = new MessageChannel();
237
+ frameWindow.dispatchEvent(
238
+ new MessageEvent("message", {
239
+ data: { type: EDITOR_CONNECT_MESSAGE_TYPE },
240
+ origin: "ignifx://app",
241
+ ports: [channel.port2],
242
+ }),
243
+ );
244
+
245
+ // Answers by id; notifications (heartbeat, schemasChanged, sceneOpened, log) are skipped here.
246
+ const waiting = new Map<number, (result: unknown) => void>();
247
+ channel.port1.onmessage = (event: MessageEvent<{ id?: number; result?: unknown; error?: unknown }>): void => {
248
+ const { id } = event.data;
249
+ if (id !== undefined) {
250
+ waiting.get(id)?.(event.data.result ?? event.data.error);
251
+ }
252
+ };
253
+ let nextId = 0;
254
+ const request = async (method: string, params: unknown): Promise<unknown> => {
255
+ nextId += 1;
256
+ const id = nextId;
257
+ const answer = new Promise<unknown>((resolve) => waiting.set(id, resolve));
258
+ channel.port1.postMessage({ jsonrpc: "2.0", id, method, params });
259
+ return answer;
260
+ };
261
+
262
+ await request("hello", { editorVersion: "0.1.0", protocol: PROTOCOL_VERSION });
263
+ const transform = { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: [1, 1, 1] };
264
+ const file = {
265
+ format: "ignifx.scene",
266
+ formatVersion: 1,
267
+ name: "level01",
268
+ entities: [{ uid: "01J9Z6M7E5S3A0V2Q4R8T1Y6WX", name: "Player", parent: null, transform }],
269
+ };
270
+ console.log(JSON.stringify(await request("openScene", { file, address: null })));
271
+ await request("applyOps", {
272
+ ops: [{ op: "setEntityField", entity: "01J9Z6M7E5S3A0V2Q4R8T1Y6WX", field: "name", value: "Hero" }],
273
+ commandName: "Rename Player",
274
+ commandId: "cmd-1",
275
+ });
276
+ console.log(JSON.stringify(await request("readBack", {})));
277
+
278
+ channel.port1.close();
279
+ host.dispose();
280
+ ```
281
+
195
282
  ## File formats
196
283
 
197
- None. The scene view loads the project's own scene files through the normal loader; the editor's
198
- document model lives in the editor.
284
+ None of its own. The scene view builds the editor's scene document (`ignifx.scene`) from the file
285
+ object `openScene` sends, through `world.loadSceneFile`; `readBack` answers with the records
286
+ `serializeScene` writes.
199
287
 
200
288
  ## Gotchas
201
289
 
@@ -217,6 +305,54 @@ document model lives in the editor.
217
305
  - **Script edits reload both views** while `main.ts` imports `src/scripts/**` statically: Vite's one
218
306
  module graph sends a full reload to every page when an update reaches a module that does not
219
307
  accept it.
308
+ - **Scene methods answer `notReady` until the app has started.** The host answers `hello` at once;
309
+ its first `schemasChanged` is the cue that `openScene` and the rest are accepted. `applyOps`,
310
+ `readBack` and `frame` answer `noScene` while no scene is open.
311
+ - **The scene view keeps the project's `rendering.msaaSamples`.** The gizmos and the outline draw in
312
+ core's render overlay (`app.renderer.openOverlay()`), which works at every MSAA setting.
313
+ - **A headless host lists only `heartbeat`.** Without a canvas there are no gizmos, no `screenshot`,
314
+ and every `pick` misses without a `ray`; `setGizmo` and `screenshot` then answer `methodNotFound`. In headless
315
+ tests, asset loads after `start()` settle only when something calls `app.step()`.
316
+ - **A `pick` carries the camera ray, hit or miss.** On a canvas the answer adds
317
+ `ray: { origin, direction }` (world space, from the editor camera's `screenToRay` at the converted
318
+ backing pixel) and, when the ray crosses `z = 0` ahead of the camera, `plane: [x, y, 0]`. A 3D
319
+ editor drops an asset where `ray` meets `y = 0`; a 2D one uses `plane`.
320
+ - **The 2D view mode needs a canvas, not a dependency.** On a canvas the host lists `viewMode2d` and
321
+ `pick2d`. `openScene` and `sceneOpened` report `viewMode`: `"2d"` for `twoD.mode: "sprite"` or a
322
+ scene whose cameras are all `Camera2D`. `setViewMode { mode: "2d" }` enables the host's own
323
+ `Camera2D` (priority 1 000 000) and makes the 3D editor camera orthographic over the same
324
+ rectangle; the level's `Camera2D` is never changed. In 2D mode `frame` fits sprite quads and
325
+ tilemaps, and `pick` and clicks use `app.twoD.pickAt` (unpickable sprites included): a hit's
326
+ `point` is on `z = 0` and its `distance` is `null`. The host finds `app.twoD` and the 2D classes
327
+ by name, so a project without `@ignifx/2d` still gets an orthographic 2D view of its meshes.
328
+ - **A pose on demand.** `sampleAnimation { entity, state, normalizedTime, parameters? }` calls
329
+ `Animator.sample` on the entity's `Animator` and answers `{ posed }`; the edit-mode view keeps
330
+ the pose until the next sample. `posed` is `false` while the clips load, when the model lacks a clip the state names, and
331
+ always headless. Names are capped at 256 characters and `parameters` at 64 values. An
332
+ entity without an `Animator`, or an engine refusal such as an unknown state (`data.code`
333
+ `IGX-1202`), is `invalidParams`. The host finds `ignifx/Animator` by type id, so a project
334
+ without `@ignifx/3d` simply has none.
335
+ - **Settings over the protocol.** `describeSettings` answers `{ sections, values }`: core's
336
+ `describeSettings(app)` with each section's `settingsJsonSchema` entry as `propsSchema`, and the
337
+ values the app resolved, in the settings form (`{ x, y, z }`, `{ r, g, b, a }`). No notification
338
+ announces settings; ask again after the project's settings change.
339
+ - **Materials and collider gizmos.** `setAnimateMaterials { enabled }` sets
340
+ `app.renderer.animateMaterialsInEditMode` (on at every start, so re-send it after `ready`).
341
+ `getColliderOutlines { entities }` answers `{ outlines }`: per enabled collider of each open
342
+ entity, its uid, the component's uid, `isTrigger`, and world-space `lines` (six numbers a
343
+ segment), read from `app.physics` / `app.physics2d` by shape, plus `truncated` when the request
344
+ passed 256 entities or the lines 600 000 numbers. Edit mode keeps physics bodies on the
345
+ transforms the editor moves without stepping, so the outlines and physics queries follow.
346
+ - **A changed asset reloads in place, not the view.** The scene view's page hands every
347
+ `ignifx:asset-changed` event to `host.assetChanged`, which calls `app.assets.reload(address)` for an
348
+ asset the app has loaded, of type `scene` (a scene or prefab), `model`, `mesh`, `material`,
349
+ `spriteatlas` or `shader`. A changed prefab rebuilds the document's instances of it, directly or
350
+ through another prefab, with their uids, transforms, overrides and document children; `readBack`
351
+ then writes the new prefab's hash. The host sends `assetReloaded { address, type, entities }`
352
+ (the rebuilt instance roots) once the new value is in. A texture, a removed file and the open
353
+ document's own file are left alone and send nothing.
354
+ - **Document uids only.** Members of an instanced prefab and the editor's own entities never appear
355
+ in a selection, a pick or `readBack`; a pick on a prefab member resolves to its instance root.
220
356
 
221
357
  ## Deprecated (current window)
222
358