@zephyr3d/scene 0.6.1 → 0.7.0

package/dist/app/scriptingsystem.js

@@ -0,0 +1,220 @@
+import { HttpFS } from '@zephyr3d/base';
+import { ScriptRegistry } from './scriptregistry.js';
+import { RuntimeScript } from './runtimescript.js';
+
+/**
+ * Script system that resolves, loads, and manages lifecycle of runtime scripts.
+ *
+ * Responsibilities:
+ * - Resolves module IDs to URLs via {@link ScriptRegistry}
+ * - Dynamically imports modules and instantiates a `RuntimeScript` (default export)
+ * - Tracks attachments between hosts and script instances
+ * - Bridges script lifecycle hooks: `onCreated`, `onAttached`, `onDetached`, `onDestroy`, `onUpdate`
+ * - Auto-detaches scripts when a host is disposed
+ *
+ * Notes:
+ * - Multiple hosts can reference the same `RuntimeScript` instance; destruction
+ *   occurs when the last host detaches.
+ * - Errors during load/attach/update are caught and logged; an optional
+ *   `onLoadError` callback can be provided.
+ *
+ * @public
+ */ class ScriptingSystem {
+    _registry;
+    _hostScripts;
+    _scriptHosts;
+    _onLoadError;
+    _importComment;
+    /**
+   * Constructs a new scripting system.
+   *
+   * @param opts - Optional configuration.
+   */ constructor(opts = {}){
+        this._registry = new ScriptRegistry(opts.VFS ?? new HttpFS('./'), opts.scriptsRoot ?? '/', opts.editorMode ?? false);
+        this._hostScripts = new Map();
+        this._scriptHosts = new Map();
+        this._importComment = opts.importComment;
+        this._onLoadError = opts.onLoadError;
+    }
+    /**
+   * Accessor for the underlying script registry used for module resolution.
+   */ get registry() {
+        return this._registry;
+    }
+    /**
+   * Attaches a script to a host and returns the `RuntimeScript` instance.
+   *
+   * Process:
+   * 1. Resolve module ID to a runtime URL via the registry.
+   * 2. Dynamically import the module.
+   * 3. Instantiate the default export if it is a constructor.
+   * 4. If this is the first time the instance is seen, call `onCreated()`.
+   * 5. Link the instance to the host, and call `onAttached(host)`.
+   * 6. Subscribe to the host's `'dispose'` event to auto-detach.
+   *
+   * If the module cannot be resolved or does not export a default `RuntimeScript`
+   * subclass, a warning is logged and `null` is returned.
+   *
+   * @typeParam T - Host type.
+   * @param host - The host object to attach the script to.
+   * @param module - Module identifier used by the registry (logical ID or path).
+   * @returns The instantiated `RuntimeScript<T>` or `null` on failure.
+   */ async attachScript(host, module) {
+        try {
+            const url = await this._registry.resolveRuntimeUrl(module);
+            if (!url) {
+                return null;
+            }
+            const mod = await import(url + (this._importComment ?? ''));
+            let instance = null;
+            if (typeof mod?.default === 'function') {
+                // default export
+                instance = new mod.default();
+                if (instance instanceof RuntimeScript) {
+                    if (!this._scriptHosts.has(instance)) {
+                        const P = instance.onCreated();
+                        if (P instanceof Promise) {
+                            await P;
+                        }
+                    }
+                } else {
+                    instance = null;
+                }
+            }
+            if (!instance) {
+                console.warn(`Script '${module}' does not have RuntimeScript class exported as default`);
+                return null;
+            }
+            let hostList = this._scriptHosts.get(instance);
+            if (!hostList) {
+                hostList = [];
+                this._scriptHosts.set(instance, hostList);
+            }
+            if (hostList.includes(host)) {
+                console.warn(`Script '${module}' already attached`);
+                return instance;
+            }
+            hostList.push(host);
+            const P = instance.onAttached(host);
+            if (P instanceof Promise) {
+                await P;
+            }
+            const attached = {
+                id: module,
+                url,
+                instance
+            };
+            let list = this._hostScripts.get(host);
+            if (!list) {
+                list = [];
+                this._hostScripts.set(host, list);
+                if (host) {
+                    host.on('dispose', ()=>{
+                        this.detachScript(host);
+                    });
+                }
+            }
+            list.push(attached);
+            return attached.instance;
+        } catch (e) {
+            const moduleName = module ? String(module).slice(0, 64) : '';
+            console.error(`Load module '${moduleName}' failed: ${e}`);
+            this._onLoadError?.(e, module);
+            return null;
+        }
+    }
+    /**
+   * Detaches script(s) from a host.
+   *
+   * Behavior:
+   * - If `idOrInstance` is omitted, detaches all scripts from the host.
+   * - If a module ID is provided, detaches only the matching script.
+   * - If a `RuntimeScript` instance is provided, detaches that instance.
+   * - Invokes `onDetached(host)` on each detached instance.
+   * - If the instance has no remaining hosts, invokes `onDestroy()` and disposes tracking.
+   *
+   * @typeParam T - Host type.
+   * @param host - The host to detach from.
+   * @param idOrInstance - Optional module ID or script instance to target.
+   */ detachScript(host, idOrInstance) {
+        const list = this._hostScripts.get(host);
+        if (!list || list.length === 0) {
+            return;
+        }
+        for(let i = list.length - 1; i >= 0; i--){
+            const it = list[i];
+            const hit = !idOrInstance || typeof idOrInstance === 'string' ? it.id === idOrInstance : it.instance === idOrInstance;
+            if (hit) {
+                list.splice(i, 1);
+                try {
+                    it.instance.onDetached(host);
+                } catch (err) {
+                    console.error(`Error occured at onDetach() of module '${it.id}': ${err}`);
+                }
+                const hostList = this._scriptHosts.get(it.instance);
+                const index = hostList.indexOf(host);
+                if (index >= 0) {
+                    hostList.splice(index, 1);
+                }
+                if (hostList.length === 0) {
+                    try {
+                        it.instance.onDestroy();
+                    } catch (err) {
+                        console.error(`Error occured at onDestroy() of module '${it.id}': ${err}`);
+                    } finally{
+                        this._scriptHosts.delete(it.instance);
+                    }
+                }
+            }
+        }
+        if (list.length === 0) {
+            this._hostScripts.delete(host);
+        }
+    }
+    /**
+   * Get all script instances attached to a host.
+   *
+   * @typeParam T - Expected script type.
+   * @param host - The host whose scripts to retrieve.
+   * @returns Script instances attached to the host, or an empty array if none.
+   */ getScriptObjects(host) {
+        return this._hostScripts.get(host) || [];
+    }
+    /**
+   * Ticks all attached script instances.
+   *
+   * Calls `onUpdate(deltaTime, elapsedTime)` on every attached script instance
+   * across all hosts. Exceptions thrown by a script are caught and logged,
+   * allowing other scripts to continue updating.
+   *
+   * @param deltaTime - Time in seconds since last update.
+   * @param elapsedTime - Total time in seconds since start.
+   */ update(deltaTime, elapsedTime) {
+        if (this._hostScripts.size === 0) {
+            return;
+        }
+        for (const list of this._hostScripts.values()){
+            for (const s of list){
+                try {
+                    s.instance.onUpdate(deltaTime, elapsedTime);
+                } catch (err) {
+                    console.error(`Error occured at onUpdate() of module '${s.id}': ${err}`);
+                }
+            }
+        }
+    }
+    /**
+   * Detaches all scripts from all hosts.
+   *
+   * Iteratively calls {@link ScriptingSystem.detachScript} on each host until no attachments remain.
+   */ detachAllScripts() {
+        while(this._hostScripts.size > 0){
+            for (const entry of this._hostScripts){
+                this.detachScript(entry[0]);
+            }
+        }
+    }
+}
+
+export { ScriptingSystem };
+//# sourceMappingURL=scriptingsystem.js.map

package/dist/app/scriptingsystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scriptingsystem.js","sources":["../../src/app/scriptingsystem.ts"],"sourcesContent":["import type { IDisposable, VFS } from '@zephyr3d/base';\r\nimport { HttpFS } from '@zephyr3d/base';\r\nimport { ScriptRegistry } from './scriptregistry';\r\nimport { RuntimeScript } from './runtimescript';\r\n\r\n/**\r\n * A host object that supports disposal.\r\n *\r\n * Hosts are objects to which scripts can be attached. They are expected to\r\n * emit a `'dispose'` event compatible with `IDisposable` so that scripts\r\n * can be automatically detached when the host is destroyed.\r\n *\r\n * @public\r\n */\r\nexport type Host = IDisposable;\r\n\r\n/**\r\n * Options for configuring a `ScriptingSystem`.\r\n *\r\n * @public\r\n */\r\nexport type ScriptingSystemOptions = {\r\n  /** Virtual file system used by the script registry. Defaults to `new HttpFS('./')`. */\r\n  VFS?: VFS;\r\n  /** Root path for scripts within the VFS. Defaults to `/`. */\r\n  scriptsRoot?: string;\r\n  /** If true, enables editor-oriented behaviors in the registry. Defaults to `false`. */\r\n  editorMode?: boolean;\r\n  /**\r\n   * Optional string appended to dynamic import URLs (e.g., for cache busting).\r\n   * Example: `'?v=' + Date.now()`\r\n   */\r\n  importComment?: string;\r\n  /**\r\n   * Optional callback invoked when a module fails to load.\r\n   * @param e - The error that occurred.\r\n   * @param id - The module ID that failed to load.\r\n   */\r\n  onLoadError?: (e: unknown, id: string) => void;\r\n};\r\n\r\n/**\r\n * Information about a script attached to a host.\r\n *\r\n * @public\r\n */\r\nexport interface IAttachedScript {\r\n  /** The logical module identifier used to resolve the script. */\r\n  id: string;\r\n  /** The resolved runtime URL used for dynamic import. */\r\n  url: string;\r\n  /** The instantiated runtime script. */\r\n  instance: RuntimeScript<any>;\r\n}\r\n\r\n/**\r\n * Script system that resolves, loads, and manages lifecycle of runtime scripts.\r\n *\r\n * Responsibilities:\r\n * - Resolves module IDs to URLs via {@link ScriptRegistry}\r\n * - Dynamically imports modules and instantiates a `RuntimeScript` (default export)\r\n * - Tracks attachments between hosts and script instances\r\n * - Bridges script lifecycle hooks: `onCreated`, `onAttached`, `onDetached`, `onDestroy`, `onUpdate`\r\n * - Auto-detaches scripts when a host is disposed\r\n *\r\n * Notes:\r\n * - Multiple hosts can reference the same `RuntimeScript` instance; destruction\r\n *   occurs when the last host detaches.\r\n * - Errors during load/attach/update are caught and logged; an optional\r\n *   `onLoadError` callback can be provided.\r\n *\r\n * @public\r\n */\r\nexport class ScriptingSystem {\r\n  private _registry: ScriptRegistry;\r\n  private _hostScripts: Map<Host, IAttachedScript[]>;\r\n  private _scriptHosts: Map<RuntimeScript<any>, Host[]>;\r\n  private _onLoadError?: (e: unknown, id: string) => void;\r\n  private _importComment?: string;\r\n\r\n  /**\r\n   * Constructs a new scripting system.\r\n   *\r\n   * @param opts - Optional configuration.\r\n   */\r\n  constructor(opts: ScriptingSystemOptions = {}) {\r\n    this._registry = new ScriptRegistry(\r\n      opts.VFS ?? new HttpFS('./'),\r\n      opts.scriptsRoot ?? '/',\r\n      opts.editorMode ?? false\r\n    );\r\n    this._hostScripts = new Map();\r\n    this._scriptHosts = new Map();\r\n    this._importComment = opts.importComment;\r\n    this._onLoadError = opts.onLoadError;\r\n  }\r\n\r\n  /**\r\n   * Accessor for the underlying script registry used for module resolution.\r\n   */\r\n  get registry() {\r\n    return this._registry;\r\n  }\r\n\r\n  /**\r\n   * Attaches a script to a host and returns the `RuntimeScript` instance.\r\n   *\r\n   * Process:\r\n   * 1. Resolve module ID to a runtime URL via the registry.\r\n   * 2. Dynamically import the module.\r\n   * 3. Instantiate the default export if it is a constructor.\r\n   * 4. If this is the first time the instance is seen, call `onCreated()`.\r\n   * 5. Link the instance to the host, and call `onAttached(host)`.\r\n   * 6. Subscribe to the host's `'dispose'` event to auto-detach.\r\n   *\r\n   * If the module cannot be resolved or does not export a default `RuntimeScript`\r\n   * subclass, a warning is logged and `null` is returned.\r\n   *\r\n   * @typeParam T - Host type.\r\n   * @param host - The host object to attach the script to.\r\n   * @param module - Module identifier used by the registry (logical ID or path).\r\n   * @returns The instantiated `RuntimeScript<T>` or `null` on failure.\r\n   */\r\n  async attachScript<T extends Host>(host: T, module: string): Promise<RuntimeScript<T>> {\r\n    try {\r\n      const url = await this._registry.resolveRuntimeUrl(module);\r\n      if (!url) {\r\n        return null;\r\n      }\r\n      const mod = await import(url + (this._importComment ?? ''));\r\n      let instance: RuntimeScript<T> = null;\r\n      if (typeof mod?.default === 'function') {\r\n        // default export\r\n        instance = new mod.default();\r\n        if (instance instanceof RuntimeScript) {\r\n          if (!this._scriptHosts.has(instance)) {\r\n            const P = instance.onCreated();\r\n            if (P instanceof Promise) {\r\n              await P;\r\n            }\r\n          }\r\n        } else {\r\n          instance = null;\r\n        }\r\n      }\r\n      if (!instance) {\r\n        console.warn(`Script '${module}' does not have RuntimeScript class exported as default`);\r\n        return null;\r\n      }\r\n\r\n      let hostList = this._scriptHosts.get(instance);\r\n      if (!hostList) {\r\n        hostList = [];\r\n        this._scriptHosts.set(instance, hostList);\r\n      }\r\n      if (hostList.includes(host)) {\r\n        console.warn(`Script '${module}' already attached`);\r\n        return instance;\r\n      }\r\n      hostList.push(host);\r\n\r\n      const P = instance.onAttached(host);\r\n      if (P instanceof Promise) {\r\n        await P;\r\n      }\r\n\r\n      const attached: IAttachedScript = {\r\n        id: module,\r\n        url,\r\n        instance\r\n      };\r\n\r\n      let list = this._hostScripts.get(host);\r\n      if (!list) {\r\n        list = [];\r\n        this._hostScripts.set(host, list);\r\n        if (host) {\r\n          host.on('dispose', () => {\r\n            this.detachScript(host);\r\n          });\r\n        }\r\n      }\r\n      list.push(attached);\r\n\r\n      return attached.instance;\r\n    } catch (e) {\r\n      const moduleName = module ? String(module).slice(0, 64) : '';\r\n      console.error(`Load module '${moduleName}' failed: ${e}`);\r\n      this._onLoadError?.(e, module);\r\n      return null;\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Detaches script(s) from a host.\r\n   *\r\n   * Behavior:\r\n   * - If `idOrInstance` is omitted, detaches all scripts from the host.\r\n   * - If a module ID is provided, detaches only the matching script.\r\n   * - If a `RuntimeScript` instance is provided, detaches that instance.\r\n   * - Invokes `onDetached(host)` on each detached instance.\r\n   * - If the instance has no remaining hosts, invokes `onDestroy()` and disposes tracking.\r\n   *\r\n   * @typeParam T - Host type.\r\n   * @param host - The host to detach from.\r\n   * @param idOrInstance - Optional module ID or script instance to target.\r\n   */\r\n  detachScript<T extends Host>(host: T, idOrInstance?: string | RuntimeScript<T>) {\r\n    const list = this._hostScripts.get(host);\r\n    if (!list || list.length === 0) {\r\n      return;\r\n    }\r\n    for (let i = list.length - 1; i >= 0; i--) {\r\n      const it = list[i];\r\n      const hit =\r\n        !idOrInstance || typeof idOrInstance === 'string'\r\n          ? it.id === idOrInstance\r\n          : it.instance === idOrInstance;\r\n      if (hit) {\r\n        list.splice(i, 1);\r\n        try {\r\n          it.instance.onDetached(host);\r\n        } catch (err) {\r\n          console.error(`Error occured at onDetach() of module '${it.id}': ${err}`);\r\n        }\r\n\r\n        const hostList = this._scriptHosts.get(it.instance);\r\n        const index = hostList.indexOf(host);\r\n        if (index >= 0) {\r\n          hostList.splice(index, 1);\r\n        }\r\n\r\n        if (hostList.length === 0) {\r\n          try {\r\n            it.instance.onDestroy();\r\n          } catch (err) {\r\n            console.error(`Error occured at onDestroy() of module '${it.id}': ${err}`);\r\n          } finally {\r\n            this._scriptHosts.delete(it.instance);\r\n          }\r\n        }\r\n      }\r\n    }\r\n    if (list.length === 0) {\r\n      this._hostScripts.delete(host);\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Get all script instances attached to a host.\r\n   *\r\n   * @typeParam T - Expected script type.\r\n   * @param host - The host whose scripts to retrieve.\r\n   * @returns Script instances attached to the host, or an empty array if none.\r\n   */\r\n  getScriptObjects<T extends RuntimeScript<any>>(host: unknown): T[] {\r\n    return (this._hostScripts.get(host as Host) as unknown as T[]) || [];\r\n  }\r\n\r\n  /**\r\n   * Ticks all attached script instances.\r\n   *\r\n   * Calls `onUpdate(deltaTime, elapsedTime)` on every attached script instance\r\n   * across all hosts. Exceptions thrown by a script are caught and logged,\r\n   * allowing other scripts to continue updating.\r\n   *\r\n   * @param deltaTime - Time in seconds since last update.\r\n   * @param elapsedTime - Total time in seconds since start.\r\n   */\r\n  update(deltaTime: number, elapsedTime: number): void {\r\n    if (this._hostScripts.size === 0) {\r\n      return;\r\n    }\r\n    for (const list of this._hostScripts.values()) {\r\n      for (const s of list) {\r\n        try {\r\n          s.instance.onUpdate(deltaTime, elapsedTime);\r\n        } catch (err) {\r\n          console.error(`Error occured at onUpdate() of module '${s.id}': ${err}`);\r\n        }\r\n      }\r\n    }\r\n  }\r\n\r\n  /**\r\n   * Detaches all scripts from all hosts.\r\n   *\r\n   * Iteratively calls {@link ScriptingSystem.detachScript} on each host until no attachments remain.\r\n   */\r\n  detachAllScripts() {\r\n    while (this._hostScripts.size > 0) {\r\n      for (const entry of this._hostScripts) {\r\n        this.detachScript(entry[0]);\r\n      }\r\n    }\r\n  }\r\n}\r\n"],"names":["ScriptingSystem","_registry","_hostScripts","_scriptHosts","_onLoadError","_importComment","opts","ScriptRegistry","VFS","HttpFS","scriptsRoot","editorMode","Map","importComment","onLoadError","registry","attachScript","host","module","url","resolveRuntimeUrl","mod","instance","default","RuntimeScript","has","P","onCreated","Promise","console","warn","hostList","get","set","includes","push","onAttached","attached","id","list","on","detachScript","e","moduleName","String","slice","error","idOrInstance","length","i","it","hit","splice","onDetached","err","index","indexOf","onDestroy","delete","getScriptObjects","update","deltaTime","elapsedTime","size","values","s","onUpdate","detachAllScripts","entry"],"mappings":"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"}

package/dist/app/scriptregistry.js

@@ -0,0 +1,432 @@
+import { textToBase64 } from '@zephyr3d/base';
+import { init, parse } from '../node_modules/es-module-lexer/dist/lexer.js';
+
+/**
+ * Converts JavaScript source to a data URL tied to a logical module id.
+ *
+ * @param js - The JavaScript source code to embed.
+ * @param id - Logical module identifier (used only for sourceURL tagging).
+ * @returns A `data:text/javascript;base64,...` URL with an encoded `#id` suffix.
+ * @internal
+ */ function toDataUrl(js, id) {
+    const b64 = textToBase64(js);
+    return `data:text/javascript;base64,${b64}#${encodeURIComponent(String(id))}`;
+}
+/**
+ * Checks whether a specifier is an absolute HTTP(S) URL.
+ * @internal
+ */ function isAbsoluteUrl(spec) {
+    return /^https?:\/\//i.test(spec);
+}
+/**
+ * Checks whether a specifier is a special URL (data: or blob:).
+ * @internal
+ */ function isSpecialUrl(spec) {
+    return /^(data|blob):/i.test(spec);
+}
+/**
+ * Checks whether a specifier is a bare module (not starting with ./, ../, /, or #/).
+ * @internal
+ */ function isBareModule(spec) {
+    return !spec.startsWith('./') && !spec.startsWith('../') && !spec.startsWith('/') && !spec.startsWith('#/');
+}
+/**
+ * Resolves, builds, and serves runtime modules using a VFS.
+ *
+ * Responsibilities:
+ * - Resolve logical module IDs to physical paths or URLs.
+ * - In editor mode, rewrite import specifiers and serve modules as data URLs after transpile.
+ * - Transpile TypeScript to JavaScript on the fly (requires `window.ts` TypeScript runtime).
+ * - Gather static and dynamic import dependencies for tooling.
+ *
+ * Modes:
+ * - Editor mode (`editorMode === true`): modules are rewritten to data URLs after transpile/build.
+ * - Runtime mode (`editorMode === false`): returns .js URLs directly (with .ts -\> .js mapping).
+ *
+ * Caching:
+ * - Built modules are memoized in `_built` map keyed by logical ID.
+ *
+ * @public
+ */ class ScriptRegistry {
+    _vfs;
+    _scriptsRoot;
+    _built = new Map();
+    _editorMode = false;
+    /**
+   * @param vfs - The virtual file system for existence checks, reads, and path ops.
+   * @param scriptsRoot - Root directory for script resolution (used with `#/` specifiers).
+   * @param editorMode - Whether to build modules to data URLs and rewrite imports.
+   */ constructor(vfs, scriptsRoot, editorMode){
+        this._vfs = vfs;
+        this._scriptsRoot = scriptsRoot;
+        this._editorMode = editorMode;
+    }
+    /**
+   * The active virtual file system.
+   *
+   * Assigning a new VFS clears the build cache.
+   */ get VFS() {
+        return this._vfs;
+    }
+    set VFS(vfs) {
+        if (vfs !== this._vfs) {
+            this._vfs = vfs;
+            this._built.clear();
+        }
+    }
+    /**
+   * Whether the registry operates in editor mode (rewrite/build to data URLs).
+   */ get editorMode() {
+        return this._editorMode;
+    }
+    set editorMode(val) {
+        this._editorMode = val;
+    }
+    /**
+   * The root path used by `#/` specifiers.
+   */ get scriptsRoot() {
+        return this._scriptsRoot;
+    }
+    set scriptsRoot(path) {
+        this._scriptsRoot = path;
+    }
+    /**
+   * Fetches raw source for a logical module id by probing known extensions.
+   *
+   * Search order:
+   * - If `id` already ends with `.ts` or `.js` and is a file -\> return it.
+   * - Else try `.id.ts`, then `.id.js`.
+   *
+   * @param id - Logical module identifier (absolute or logical path-like).
+   * @returns Source code, resolved path, and type (`'js' | 'ts'`), or `undefined` if not found.
+   */ async fetchSource(id) {
+        let type = null;
+        let pathWithExt = '';
+        if (id.endsWith('.ts')) {
+            pathWithExt = id;
+            type = 'ts';
+        } else if (id.endsWith('.js')) {
+            pathWithExt = id;
+            type = 'js';
+        }
+        if (type) {
+            const exists = await this._vfs.exists(pathWithExt);
+            if (!exists) {
+                type = null;
+            }
+            const stat = await this._vfs.stat(pathWithExt);
+            if (stat.isDirectory) {
+                type = null;
+            }
+        }
+        const types = [
+            'ts',
+            'js'
+        ];
+        if (!type) {
+            for (const t of types){
+                pathWithExt = `${id}.${t}`;
+                const exists = await this._vfs.exists(pathWithExt);
+                if (exists) {
+                    const stats = await this._vfs.stat(pathWithExt);
+                    if (stats.isFile) {
+                        type = t;
+                        break;
+                    }
+                }
+            }
+        }
+        if (type) {
+            const code = await this._vfs.readFile(pathWithExt, {
+                encoding: 'utf8'
+            });
+            return {
+                code,
+                type,
+                path: pathWithExt
+            };
+        }
+    }
+    /**
+   * Resolves a module entry to a URL suitable for dynamic import.
+   *
+   * Behavior:
+   * - In editor mode, builds the module to a data URL.
+   * - Otherwise, returns `.js` URL directly:
+   *   - If `id` ends with `.js`: return as-is.
+   *   - If `id` ends with `.ts`: map to `.js` (assumes pre-built file exists).
+   *   - Else: append `.js`.
+   *
+   * @param entryId - Entry module identifier (logical or path-like).
+   * @returns A URL string that can be used in `import(...)`.
+   */ async resolveRuntimeUrl(entryId) {
+        const id = await this.resolveLogicalId(entryId);
+        return this._editorMode ? await this.build(String(id)) : id.endsWith('.js') ? id : id.endsWith('.ts') ? `${id.slice(0, -3)}.js` : `${id}.js`;
+    }
+    /**
+   * Recursively gathers direct static and dynamic import dependencies for a module.
+   *
+   * Only relative specifiers (`./` or `../`) are followed. Absolute, special, and bare
+   * module specifiers are ignored here.
+   *
+   * @param entryId - The starting (possibly relative) specifier from `fromId`.
+   * @param fromId - The logical id of the module containing `entryId`.
+   * @param dependencies - Output map of `resolvedSourcePath -\> file contents`.
+   */ async getDependencies(entryId, fromId, dependencies) {
+        const reStatic = /\b(?:import|export)\s+[^"']*?from\s+(['"])([^'"]+)\1/g;
+        const reDynamic = /\bimport\s*\(\s*(['"])([^'"]+)\1\s*\)/g;
+        const normalizedId = await this.resolveLogicalId(entryId, fromId);
+        const srcPath = await this.resolveSourcePath(normalizedId);
+        if (!srcPath || dependencies[srcPath.path] !== undefined) {
+            return;
+        }
+        const code = await this._vfs.readFile(srcPath.path, {
+            encoding: 'utf8'
+        });
+        dependencies[srcPath.path] = code;
+        const gather = async (input, re)=>{
+            for(;;){
+                const m = re.exec(input);
+                if (!m) {
+                    break;
+                }
+                const spec = m[2];
+                if (spec.startsWith('./') || spec.startsWith('../')) {
+                    await this.getDependencies(spec, normalizedId, dependencies);
+                }
+            }
+        };
+        await gather(code, reStatic);
+        await gather(code, reDynamic);
+    }
+    /**
+   * Builds a logical module id into a data URL (editor mode pipeline).
+   *
+   * Steps:
+   * - Resolve source path (.ts/.js) via {@link ScriptRegistry.resolveSourcePath}.
+   * - Read source code.
+   * - Rewrite import specifiers via {@link ScriptRegistry.rewriteImports}.
+   * - Transpile TypeScript if needed via {@link ScriptRegistry.transpile}.
+   * - Convert to `data:` URL and memoize in `_built`.
+   *
+   * @param id - Logical module id to build.
+   * @returns Data URL string for dynamic import, or empty string if not found.
+   */ async build(id) {
+        const key = String(id);
+        const cached = this._built.get(key);
+        if (cached) {
+            return cached;
+        }
+        const srcPath = await this.resolveSourcePath(key);
+        if (!srcPath) {
+            return '';
+        }
+        const code = await this._vfs.readFile(srcPath.path, {
+            encoding: 'utf8'
+        });
+        const rewritten = await this.rewriteImports(code, key);
+        const js = await this.transpile(rewritten, key, srcPath.type);
+        const url = toDataUrl(js, key);
+        this._built.set(key, url);
+        return url;
+    }
+    /**
+   * Transpiles code to JavaScript and appends sourceURL/sourceMap hints.
+   *
+   * Behavior:
+   * - For `'js'`, returns code with `//# sourceURL=logicalId`.
+   * - For `'ts'`, requires `window.ts` (TypeScript compiler) to be present and
+   *   transpiles to ES2015/ESNext module with inline source maps.
+   *
+   * @param code - Source code to transpile.
+   * @param _id - Logical module id (used for fileName/sourceURL).
+   * @param type - Source type (`'js' | 'ts'`).
+   * @returns Transpiled JavaScript source.
+   * @throws If TypeScript runtime is not found for TS input.
+   */ async transpile(code, _id, type) {
+        const logicalId = String(_id);
+        if (type === 'js') {
+            return `${code}\n//# sourceURL=${logicalId}`;
+        }
+        const ts = window.ts;
+        if (!ts) {
+            throw new Error('TypeScript runtime (window.ts) not found. Load typescript.js first.');
+        }
+        const res = ts.transpileModule(code, {
+            compilerOptions: {
+                target: ts.ScriptTarget.ES2015,
+                module: ts.ModuleKind.ESNext,
+                sourceMap: true,
+                inlineSources: true,
+                experimentalDecorators: true,
+                useDefineForClassFields: false
+            },
+            fileName: logicalId
+        });
+        let out = res.outputText || '';
+        if (res.sourceMapText) {
+            const mapBase64 = btoa(unescape(encodeURIComponent(res.sourceMapText)));
+            out += `\n//# sourceMappingURL=data:application/json;base64,${mapBase64}`;
+        }
+        out += `\n//# sourceURL=${logicalId}`;
+        return out;
+    }
+    /**
+   * Rewrites ESM import specifiers in `code` into runtime-loadable URLs.
+   *
+   * Parsing:
+   * - Uses `es-module-lexer` to find import spans; sorts them ascending by start.
+   *
+   * Replacement rules:
+   * - Skip invalid spans or ones without quoted specifiers.
+   * - If spec is absolute URL, special URL (data:, blob:), or bare module:
+   *   - If it starts with `@zephyr3d/`, keep as-is (external).
+   *   - Otherwise resolve to a logical id and attempt to `build` it (if available).
+   * - Else (relative spec), resolve from `fromId` and `build` recursively.
+   *
+   * Output:
+   * - Directly writes the replacement specifier without re-adding quotes,
+   *   so replacements must themselves be quoted or be valid URLs/data URLs.
+   *
+   * @param code - Module source code to transform.
+   * @param fromId - The logical id of the current module (resolution base for relatives).
+   * @returns Transformed source with rewritten import specifiers.
+   */ async rewriteImports(code, fromId) {
+        await init;
+        const [imports] = parse(code);
+        const list = [
+            ...imports
+        ].sort((a, b)=>(a.s || 0) - (b.s || 0));
+        let out = '';
+        let last = 0;
+        for (const im of list){
+            // must have quotes
+            const hasQuote = im.ss != null && im.se != null;
+            if (!hasQuote || im.se <= im.ss) {
+                continue;
+            }
+            // must have contents
+            if (im.e <= im.s) {
+                continue;
+            }
+            // append [last, s)
+            out += code.slice(last, im.s);
+            const spec = code.slice(im.s, im.e); // original spec
+            let replacement = spec;
+            if (isAbsoluteUrl(spec) || isSpecialUrl(spec) || isBareModule(spec)) {
+                if (spec.startsWith('@zephyr3d/')) {
+                    replacement = spec;
+                } else {
+                    const depId = await this.resolveLogicalId(spec);
+                    replacement = await this.build(depId); // try build as dependence
+                }
+            } else {
+                const depId = await this.resolveLogicalId(spec, String(fromId));
+                replacement = await this.build(depId); // recursively build as dataURL
+            }
+            out += replacement; // 不加引号
+            last = im.e;
+        }
+        out += code.slice(last);
+        return out;
+    }
+    /**
+   * Resolves a specifier to a logical id suitable for further processing.
+   *
+   * Resolution rules:
+   * - `#/path`: resolved against `scriptsRoot` via VFS join/normalize.
+   * - `./` or `../`: resolved relative to `fromId` directory (requires `fromId`).
+   * - `/absolute`: treated as absolute from root (normalized).
+   * - Bare module in editor mode: if `/deps.lock.json` exists and contains an entry,
+   *   map to the dependency's `entry` path; otherwise return as-is.
+   * - Else (non-editor bare module): return `spec` unchanged (external).
+   *
+   * @param spec - Import specifier string.
+   * @param fromId - Optional base logical id used for relative resolution.
+   * @returns A normalized logical id or an external specifier string.
+   * @throws If a relative import is provided without `fromId`.
+   */ async resolveLogicalId(spec, fromId) {
+        let path;
+        if (spec.startsWith('#/')) {
+            path = this._vfs.normalizePath(this._vfs.join(this._scriptsRoot, spec.slice(2)));
+        } else if (spec.startsWith('./') || spec.startsWith('../')) {
+            if (!fromId) {
+                throw new Error(`Relative import "${spec}" requires fromId`);
+            }
+            path = this._vfs.normalizePath(this._vfs.join(this._vfs.dirname(this._vfs.normalizePath(fromId)), spec));
+        } else if (spec.startsWith('/')) {
+            path = spec.replace(/^\/+/, '/');
+        } else if (this._editorMode) {
+            // naked module, checking if it is a installed module in editor mode
+            const depsExists = await this._vfs.exists('/libs/deps.lock.json');
+            if (depsExists) {
+                const content = await this._vfs.readFile('/libs/deps.lock.json', {
+                    encoding: 'utf8'
+                });
+                const depsInfo = JSON.parse(content);
+                if (depsInfo?.dependencies[spec]) {
+                    path = this._vfs.normalizePath(depsInfo.dependencies[spec].entry);
+                }
+            }
+        } else {
+            return spec;
+        }
+        return path;
+    }
+    /**
+   * Resolves a logical id to a concrete source path and type by probing extensions.
+   *
+   * Rules:
+   * - If `logicalId` ends with `.ts` or `.js`/`.mjs` and is a file, return it.
+   * - Else probe `logicalId.ts`, `logicalId.js`, `logicalId.mjs` in that order.
+   * - Maps `.mjs` to type `'js'`.
+   *
+   * @param logicalId - The normalized logical module id (path-like).
+   * @returns `{ type, path }` or `null` if not found.
+   */ async resolveSourcePath(logicalId) {
+        let type = null;
+        let pathWithExt = '';
+        if (logicalId.endsWith('.ts')) {
+            pathWithExt = logicalId;
+            type = 'ts';
+        } else if (logicalId.endsWith('.js') || logicalId.endsWith('.mjs')) {
+            pathWithExt = logicalId;
+            type = 'js';
+        }
+        if (type) {
+            const exists = await this._vfs.exists(pathWithExt);
+            if (!exists) {
+                type = null;
+            }
+            const stat = await this._vfs.stat(pathWithExt);
+            if (stat.isDirectory) {
+                type = null;
+            }
+        }
+        const types = [
+            'ts',
+            'js',
+            'mjs'
+        ];
+        if (!type) {
+            for (const t of types){
+                pathWithExt = `${logicalId}.${t}`;
+                const exists = await this._vfs.exists(pathWithExt);
+                if (exists) {
+                    const stats = await this._vfs.stat(pathWithExt);
+                    if (stats.isFile) {
+                        type = t === 'ts' ? 'ts' : 'js';
+                        break;
+                    }
+                }
+            }
+        }
+        return type ? {
+            type,
+            path: pathWithExt
+        } : null;
+    }
+}
+
+export { ScriptRegistry };
+//# sourceMappingURL=scriptregistry.js.map