Documentation / scene / ScriptRegistry

Class: ScriptRegistry

Defined in: libs/scene/src/app/scriptregistry.ts:153

Resolves, builds, and serves runtime modules using a VFS.

Responsibilities:

• Resolve logical module IDs to physical paths or URLs.
• In editor mode, bundle local script modules into a single data URL 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): local script graphs are bundled to data URLs.
• Runtime mode (editorMode === false): returns .js/.mjs URLs directly (with .ts -> .js mapping).

Caching:

• Built bundles are memoized in _built map keyed by canonical source path.
• At runtime, all bundles built by the same registry share one realm-global module registry (keyed by a per-registry namespace): a local module is evaluated once no matter how many entry bundles inline it, so module-level singletons are identical across entries. Module records are versioned by a content hash — rebuilding an unchanged module reuses its evaluated instance, while changed content replaces the record so the next load re-evaluates the new code.

Constructors

Constructor

new ScriptRegistry(vfs, scriptsRoot): ScriptRegistry

Defined in: libs/scene/src/app/scriptregistry.ts:165

Parameters

vfs

VFS

The virtual file system for existence checks, reads, and path ops.

scriptsRoot

string

Root directory for script resolution (used with #/ specifiers).

Returns

ScriptRegistry

Accessors

VFS

Get Signature

get VFS(): VFS

Defined in: libs/scene/src/app/scriptregistry.ts:179

The active virtual file system.

Assigning a new VFS clears the build cache.

Returns

VFS

Set Signature

set VFS(vfs): void

Defined in: libs/scene/src/app/scriptregistry.ts:182

Parameters

vfs

VFS

Returns

void

---

scriptsRoot

Get Signature

get scriptsRoot(): string

Defined in: libs/scene/src/app/scriptregistry.ts:201

The root path used by #/ specifiers.

Returns

string

Set Signature

set scriptsRoot(path): void

Defined in: libs/scene/src/app/scriptregistry.ts:204

Parameters

path

string

Returns

void

Methods

invalidate()

invalidate(moduleId?): void

Defined in: libs/scene/src/app/scriptregistry.ts:216

Invalidates cached built module output for one logical module id, or clears the full cache.

Pass the same logical id shape that callers use with ScriptRegistry.resolveRuntimeUrl, for example /assets/scripts/foo.ts, /assets/scripts/foo.js, or /assets/scripts/foo.

Parameters

moduleId?

string

Optional logical module id to invalidate. Omit to clear the entire build cache.

Returns

void

---

fetchSource()

protected fetchSource(id): Promise<{ code: string; type: "js" | "ts"; path: string; }>

Defined in: libs/scene/src/app/scriptregistry.ts:261

Fetches raw source for a logical module id by probing known extensions.

Search order:

• If id already ends with .ts, .js, or .mjs and is a file -> return it.
• Else try .id.ts, then .id.js, then .id.mjs.

Parameters

id

string

Logical module identifier (absolute or logical path-like).

Returns

Promise<{ code: string; type: "js" | "ts"; path: string; }>

Source code, resolved path, and type ('js' | 'ts'), or undefined if not found.

---

resolveRuntimeUrl()

resolveRuntimeUrl(entryId): Promise<string>

Defined in: libs/scene/src/app/scriptregistry.ts:315

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 or .mjs URL directly:
  • If id ends with .js: return as-is.
  • If id ends with .mjs: return as-is.
  • If id ends with .ts: map to .js (assumes pre-built file exists).
  • Else: append .js.

Parameters

entryId

string

Entry module identifier (logical or path-like).

Returns

Promise<string>

A URL string that can be used in import(...).

---

getDependencies()

getDependencies(entryId, fromId, dependencies): Promise<void>

Defined in: libs/scene/src/app/scriptregistry.ts:339

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.

Parameters

entryId

string

The starting (possibly relative) specifier from fromId.

fromId

string

The logical id of the module containing entryId.

dependencies

Record<string, string>

Output map of resolvedSourcePath -\> file contents.

Returns

Promise<void>

---

resolveLogicalId()

resolveLogicalId(spec, fromId?): Promise<string>

Defined in: libs/scene/src/app/scriptregistry.ts:766

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).

Parameters

spec

string

Import specifier string.

fromId?

string

Optional base logical id used for relative resolution.

Returns

Promise<string>

A normalized logical id or an external specifier string.

Throws

If a relative import is provided without fromId.

---

resolveSourcePath()

resolveSourcePath(logicalId): Promise<{ type: "js" | "ts"; path: string; }>

Defined in: libs/scene/src/app/scriptregistry.ts:805

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'.

Parameters

logicalId

string

The normalized logical module id (path-like).

Returns

Promise<{ type: "js" | "ts"; path: string; }>

{ type, path } or null if not found.