@kvyverse/world-runtime 0.3.2 → 0.5.0

package/README.md

@@ -35,9 +35,9 @@ in your `node_modules`:
 | Package | When |
 | --- | --- |
 | `three`, `three-start` | always |
-| `howler`, `vanjs-core`, `eventemitter3` | always — npm 7+ installs them for you |
-| `@dimforge/rapier3d-compat` | worlds with physics |
-| `@tweenjs/tween.js`, `animejs`, `nipplejs` | worlds that enable these built-in libs |
+| `howler`, `vanjs-core`, `eventemitter3`, `nanostores` | always — npm 7+ installs them for you |
+| `@dimforge/rapier3d-compat` | worlds with physics (a collider on the scene is enough) |
+| `@tweenjs/tween.js`, `animejs`, `nipplejs`, `stats.js` | worlds that enable these optional libs |
 
 The optional ones are listed in the dialog only when the world actually uses
 them. Skip one it does need and the build fails with a clear
@@ -82,8 +82,15 @@ world.unmount(), world.runLoop(), world.stopLoop(), world.dispose()
 ```
 
 On top of that: `world.getUrl(path)` resolves an asset URL the same way scripts
-inside the world do, and `world.events` is the world lifecycle emitter (the same
-`world.events` your scripts use).
+inside the world do, `world.events` is the world lifecycle emitter (the same
+`world.events` your scripts use), and `world.stores` is the world's shared
+reactive state (the same `world.stores`) — your host page can read it, write it
+and subscribe to keys the world's scripts use:
+
+```js
+world.stores.listen("score", (value) => hudElement.textContent = value);
+world.stores.set("difficulty", "hard");
+```
 
 ## Good to know
 

package/dist/{RapierPhysics-zLwVZpwF.js → RapierPhysics-CU6X--c7.js}

@@ -1,3 +1,4 @@
+import { a as LibId } from "./lib-registry-D1VyVPBg.js";
 import { ContextModule, ThreeContextEvents, defineProps, readOnly } from "three-start";
 //#region packages/world-runtime/src/modules/physics/RapierPhysics.ts
 var RapierPhysics = class RapierPhysics extends ContextModule {
@@ -23,7 +24,7 @@ var RapierPhysics = class RapierPhysics extends ContextModule {
 		this.timeStep = timeStep;
 	}
 	onAwake() {
-		const Rapier = this.modules.addons.rapier;
+		const Rapier = this.modules.addons.lib(LibId.Rapier);
 		if (!Rapier) throw new Error("RapierPhysics: the physics engine is not loaded — `addons` has no rapier");
 		const [x, y, z] = this._gravity;
 		console.log(`Rapier version: ${Rapier.version()}`);

package/dist/World.d.ts

@@ -14,6 +14,8 @@ export declare class World extends ThreeStart {
     getUrl: (source: string | object) => string;
     /** World lifecycle event bus — the same one as `world.events` in scripts. */
     get events(): WorldRuntime["emitter"];
+    /** Shared reactive state — the same one as `world.stores` in scripts. */
+    get stores(): WorldRuntime["stores"];
     start(): this;
     dispose(): void;
 }

package/dist/WorldRuntime.d.ts

@@ -1,6 +1,7 @@
 import EventEmitter from "eventemitter3";
-import * as THREE from "three/webgpu";
 import { AddonsRuntime } from "./addons/AddonsRuntime";
+import { WorldStores } from "./world-stores";
+import type * as THREE from "three/webgpu";
 import type { Object3DBehaviourConstructor, ThreeContext, ThreeStart } from "three-start";
 import type { SceneBloom } from "./rendering/SceneBloom";
 import type { LoadWorldOptions, RuntimeApi, WorldDefinition } from "./types";
@@ -15,6 +16,8 @@ export declare class WorldRuntime implements RuntimeApi {
     readonly options: LoadWorldOptions;
     /** World lifecycle event bus (`world.events` in scripts). */
     readonly emitter: EventEmitter<string | symbol, any>;
+    /** Shared reactive state of the world (`world.stores` in scripts). */
+    readonly stores: WorldStores;
     private readonly _addons;
     private readonly _executedScripts;
     private readonly _builtins;
@@ -23,6 +26,7 @@ export declare class WorldRuntime implements RuntimeApi {
     /** Reverse index for `getUrl(resource)` — play mode resolves objects too. */
     private readonly _pathByResource;
     private _ctx;
+    private _starter;
     private _bloom;
     private _scriptContext;
     constructor(definition: RuntimeDefinitionSlice, options: LoadWorldOptions);
@@ -32,12 +36,12 @@ export declare class WorldRuntime implements RuntimeApi {
     get ctx(): ThreeContext;
     /** @internal Set by bootstrap. */
     setContext(ctx: ThreeContext): void;
+    /** @internal Set by bootstrap — backs `world.addModules` (register before start). */
+    setStarter(starter: ThreeStart): void;
     /** @internal World bloom, if enabled in the renderer config. */
     setBloom(bloom: SceneBloom): void;
-    /** @internal Built-in libs, externals and the physics engine, if the world needs one. */
+    /** @internal Libs (config + required by modules/behaviours) and externals. */
     loadAddons(): Promise<void>;
-    /** Physics is on in the config, or a built-in behaviour on the scene needs it. */
-    private _usesPhysics;
     /** @internal World resources by asset path — result of `loadAssets`. */
     setResources(resources: Record<string, unknown>): void;
     reportProgress(stage: string, details?: string): void;

package/dist/addons/AddonsRuntime.d.ts

@@ -1,34 +1,36 @@
 import { ContextModule } from "three-start";
 import type { AddonsModuleApi } from "../modules/contracts/addons.module-api";
+import type { LibId } from "./lib-registry";
 import type { AddonsConfig, WorldImports } from "./types";
-import type RAPIER from "@dimforge/rapier3d-compat";
 /**
- * External dependencies of the world: built-in libs, externals and the physics
- * engine. Loaded before the world starts; scripts reach them through
- * `resolve(key)` (`require`), the physics module through `rapier`.
+ * External dependencies of the world: libs and external scripts. Built-in libs
+ * are registered right away (the runtime bundles them), optional ones are loaded
+ * before the world starts — enabled in `settings.addons.json → libs` or declared
+ * by a module/behaviour through `requiredLibs`. Scripts reach all of them by
+ * `require("<key>")`.
  *
  * This is the `addons` ctx module, but it also works without a ctx: launcher
  * worlds have no 3d context while `require` still has to work, so there the
- * instance is used directly. How to import packages is up to the runtime owner
- * (see `WorldImports`).
+ * instance is used directly. How to import optional packages is up to the
+ * runtime owner (see `WorldImports`).
  */
 export declare class AddonsRuntime extends ContextModule implements AddonsModuleApi {
     private readonly _imports;
     /** libs — by requireKey (`@tweenjs/tween.js`), externals — by accessor (`Tone`). */
     private readonly _byKey;
+    private readonly _byLibId;
     private readonly _scriptTags;
-    private _rapier;
     constructor(_imports?: WorldImports);
-    /** `physics` — whether the world needs rapier (config or a physics behaviour). */
-    load(addons: AddonsConfig, options?: {
-        physics?: boolean;
-    }): Promise<void>;
-    /** Resolves a require key: enabled lib or external accessor; undefined otherwise. */
+    /** `usedBuiltinUuids` — built-in behaviours on the scene; they may require libs. */
+    load(addons: AddonsConfig, usedBuiltinUuids?: readonly string[]): Promise<void>;
+    /** Resolves a require key: a lib or an external accessor; undefined otherwise. */
     resolve(key: string): unknown;
-    /** The physics engine, loaded and initialized; `null` in worlds without physics. */
-    get rapier(): typeof RAPIER | null;
+    /** The lib itself, for runtime code that knows what it needs (physics → rapier). */
+    lib<T>(id: LibId): T | undefined;
+    /** Libs bundled with the runtime: no importer, no config, always available. */
+    private _registerBuiltins;
     private _loadLibs;
-    private _loadRapier;
+    private _register;
     private _loadExternals;
     private _mountScript;
     dispose(): void;

package/dist/addons/builtin-libs.d.ts

@@ -0,0 +1,20 @@
+import * as THREE from "three/webgpu";
+import * as TSL from "three/tsl";
+import { LibId } from "./lib-registry";
+/**
+ * Libraries the runtime bundles itself: `require("<key>")` hands these back in
+ * every world, no config and no importer involved. Metadata (keys, labels) is
+ * in `lib-registry`; the modules live here so the registry stays importable
+ * from the editor without dragging three & co along.
+ */
+export declare const BUILTIN_LIB_MODULES: Partial<Record<LibId, unknown>>;
+/**
+ * The subset of built-ins that is also a bare global in script scope — same
+ * objects as above, so `THREE === require("three")`. Typed literally: the
+ * script context contract depends on these exact shapes.
+ */
+export declare const BUILTIN_GLOBALS: {
+    readonly THREE: typeof THREE;
+    readonly TSL: typeof TSL;
+    readonly van: import("vanjs-core").Van;
+};

package/dist/addons/lib-registry.d.ts

@@ -1,21 +1,36 @@
 /**
- * Registry of built-in libraries enabled via `settings.addons.json → libs`.
+ * Registry of the libraries scripts can `require`. One entry describes one
+ * library; the flags say how it gets into the world:
  *
- * Separates two keys: `id` (short config key under `libs`) and `requireKey`
- * (what the user writes in `require(...)` in scripts — and the import specifier
- * importers are built from). Single source for:
- *  - game: the app's importer map (`core/game/settings/optional-imports`),
- *  - export: the `imports.libs` block the build emits into the world module,
- *  - editor: JSON schema (`libs` props) + require typings (`AddonsRequireTypings`).
+ * - **built-in** (`builtin: true`) — the runtime already bundles it, so it is
+ *   available in every world with no config and no importer. Some of them are
+ *   additionally exposed as a bare global (`globalName`) — that is the only
+ *   difference between `THREE` and, say, `nanostores`.
+ * - **optional** — enabled in `settings.addons.json → libs`, or pulled in by
+ *   something that declares it in `requiredLibs` (physics → rapier). The
+ *   importer comes from the runtime owner (`WorldImports`), never from the
+ *   package itself — see `./optional-imports.ts`.
  *
- * Adding a lib = add an entry here (+ importer in the app, + d.ts loader in editor).
- * The package itself never imports these — see `./optional-imports.ts`.
+ * `id` is the config key under `libs`, `requireKey` is what the user writes in
+ * `require(...)` (and the import specifier importers are built from). Single
+ * source for: the app's importer map, the `imports.libs` block of an exported
+ * world, the JSON schema and the editor's require typings.
  */
 export declare enum LibId {
+    Three = "three",
+    Tsl = "tsl",
+    ThreeStart = "threeStart",
+    Van = "van",
+    Nanostores = "nanostores",
+    EventEmitter = "eventemitter3",
+    Howler = "howler",
     Tween = "tween",
     Anime = "anime",
     Nipplejs = "nipplejs",
-    Stats = "stats"
+    Stats = "stats",
+    Rapier = "rapier",
+    Css2d = "css2d",
+    Css3d = "css3d"
 }
 export interface LibDescriptor {
     readonly id: LibId;
@@ -25,10 +40,21 @@ export interface LibDescriptor {
     readonly label: string;
     /** npm package to install; defaults to `requireKey` (differs for subpaths). */
     readonly packageName?: string;
+    /** Bundled with the runtime: always available, no importer, nothing to install. */
+    readonly builtin?: boolean;
+    /** Built-in libs that are also bare globals in script scope. */
+    readonly globalName?: string;
     /** The package exposes its API as the default export — unwrap it on load. */
     readonly defaultExport?: boolean;
+    /** Post-import step, e.g. wasm init. Returns what `require` should hand back. */
+    readonly init?: (module: unknown) => Promise<unknown>;
 }
 export declare const LIBS: Readonly<Record<LibId, LibDescriptor>>;
 export declare const LIB_IDS: LibId[];
 export declare const LIB_DESCRIPTORS: LibDescriptor[];
+/** Bundled with the runtime — available in every world. */
+export declare const BUILTIN_LIB_DESCRIPTORS: LibDescriptor[];
+/** Enabled in `settings.addons.json → libs` or required by a module/behaviour. */
+export declare const OPTIONAL_LIB_DESCRIPTORS: LibDescriptor[];
+export declare const OPTIONAL_LIB_IDS: LibId[];
 export declare function libByRequireKey(requireKey: string): LibDescriptor | undefined;

package/dist/addons/required-libs.d.ts

@@ -0,0 +1,9 @@
+import type { LibId } from "./lib-registry";
+import type { AddonsConfig } from "./types";
+/**
+ * Libs the world needs beyond what `libs` lists: an enabled module or a built-in
+ * behaviour on the scene declares them itself (`requiredLibs`), so physics keeps
+ * working without a line in `settings.addons.json`. Same answer for the game and
+ * for the export — the build emits importers from it.
+ */
+export declare function collectRequiredLibs(addons: AddonsConfig | undefined, usedBuiltinUuids?: readonly string[]): LibId[];

package/dist/addons/types.d.ts

@@ -12,9 +12,9 @@ export type PackageImport = () => Promise<unknown>;
  * `imports` in `defineWorld`.
  */
 export interface WorldImports {
-    /** `@dimforge/rapier3d-compat` — worlds with physics. */
-    rapier?: PackageImport;
-    /** Built-in libs by `LibId` (`settings.addons.json → libs`). */
+    /** Optional libs by `LibId` — enabled in `settings.addons.json → libs` or
+     *  required by a module/behaviour (physics → rapier). Built-in libs are
+     *  bundled with the runtime and need no importer. */
     libs?: Partial<Record<LibId, PackageImport>>;
 }
 /** `settings.addons.json` — pluggable modules, built-in libs, external scripts. */

package/dist/behaviours/physics/_required-patch.d.ts

@@ -1,14 +1,12 @@
+import type { RequiredPatch } from "../registry";
 import type { RapierPhysics } from "../../modules/physics/RapierPhysics";
 import type { NormalizedPhysics } from "../../modules/physics/physics.module-descriptor";
-import type { ThreeStart } from "three-start";
 /** The only place the physics module is created — called by the registry
  *  descriptor. The module itself takes rapier from `ctx.modules.addons` on awake. */
 export declare function createRapierPhysicsModule(config: NormalizedPhysics): Promise<RapierPhysics>;
 /**
- * Registers physics on demand: a built-in physics behaviour declares it via
- * `meta.requiredPatch`, so a world with a collider on the scene gets
- * `ctx.modules.rapier` even without a line in `settings.addons.json`.
- * Idempotent, and strictly before `start()` — three-start forbids `addModules`
- * afterwards.
+ * What a physics behaviour needs on top of its class: the rapier lib (loaded
+ * with the other addons, before the world starts) and the physics ctx module.
+ * A collider on the scene is enough — no line in `settings.addons.json`.
  */
-export declare function applyRapierPhysicsPatch(starter: ThreeStart): Promise<void>;
+export declare const rapierPhysicsPatch: RequiredPatch;

package/dist/behaviours/registry.d.ts

@@ -1,4 +1,5 @@
 import type { Object3DBehaviourConstructor, ThreeStart } from "three-start";
+import type { LibId } from "../addons/lib-registry";
 /**
  * Built-in behaviour: uuid is its identity in user worlds — it must never
  * change. The class loads lazily, so a world without physics doesn't pull rapier.
@@ -7,8 +8,14 @@ export interface BuiltinBehaviour {
     uuid: string;
     name: string;
     load: () => Promise<Object3DBehaviourConstructor>;
-    /** Registers ctx modules the behaviour needs. Strictly before `start()`. */
-    requiredPatch?: (starter: ThreeStart) => Promise<void>;
+    /** ctx modules (and their libs) the behaviour cannot work without. */
+    requiredPatch?: RequiredPatch;
+}
+/** What a behaviour needs beyond its own class: libs to load before the world
+ *  starts, and ctx modules to register strictly before `start()`. */
+export interface RequiredPatch {
+    requiredLibs?: LibId[];
+    apply: (starter: ThreeStart) => Promise<void>;
 }
 /** Registry of built-in behaviours by uuid — source of truth for both game and export. */
 export declare const BUILTIN_BEHAVIOURS: Record<string, BuiltinBehaviour | undefined>;

package/dist/index.d.ts

@@ -4,6 +4,9 @@ export type { InstantiateOptions, PrefabFactory } from "./WorldRuntime";
 export { setColor } from "./values";
 export { RUNTIME_VERSION, WORLD_FORMAT_VERSION } from "./version";
 export { WorldEvent } from "./world-events";
+export { lazyProxy } from "./utils/lazy";
+export { WorldStores } from "./world-stores";
+export type { WorldStore } from "./world-stores";
 export { createWorldModules, EnvModule, HtmlHudModule, InputSystemModule, isMobileDevice, SoundsModule, UtilsModule, } from "./modules";
 export type { EnvMode, WorldModules } from "./modules";
 export { DEFAULT_RESOURCE_IDS, DefaultResourceId, getDefaultResource, isDefaultResourceId, } from "./resources/default-resources";
@@ -19,8 +22,8 @@ export { AudioSource, createAudio } from "./resources/audio";
 export { createVideo, VideoSource } from "./resources/video";
 export { createFont, FontSource, fontFormatFromMime } from "./resources/font";
 export { BUILTIN_BEHAVIOUR_LIST, BUILTIN_BEHAVIOURS, getBuiltinBehaviour, } from "./behaviours/registry";
-export type { BuiltinBehaviour } from "./behaviours/registry";
-export { applyRapierPhysicsPatch } from "./behaviours/physics/_required-patch";
+export type { BuiltinBehaviour, RequiredPatch } from "./behaviours/registry";
+export { rapierPhysicsPatch } from "./behaviours/physics/_required-patch";
 export { AddonsRuntime } from "./addons/AddonsRuntime";
 export { applyRendererConfig } from "./rendering/renderer-apply";
 export { enableSceneEmissiveMrt, SceneBloom } from "./rendering/SceneBloom";
@@ -28,7 +31,8 @@ export { createTslNode, TslNode } from "./rendering/tsl-node";
 export type { TslNodeBuilder } from "./rendering/tsl-node";
 export { createUniformNode, isUniformType, UNIFORM_DEFAULTS, UNIFORM_TYPES, uniformType, } from "./rendering/tsl-uniforms";
 export type { UniformType } from "./rendering/tsl-uniforms";
-export { LIB_DESCRIPTORS, LIB_IDS, LIBS, LibId, libByRequireKey } from "./addons/lib-registry";
+export { BUILTIN_LIB_DESCRIPTORS, LIB_DESCRIPTORS, LIB_IDS, LIBS, LibId, OPTIONAL_LIB_DESCRIPTORS, OPTIONAL_LIB_IDS, libByRequireKey, } from "./addons/lib-registry";
+export { collectRequiredLibs } from "./addons/required-libs";
 export type { LibDescriptor } from "./addons/lib-registry";
 export { OPTIONAL_MODULE_IDS, OptionalModuleId } from "./modules/optional-module-descriptor";
 export { OPTIONAL_MODULES, getOptionalModuleDescriptor } from "./modules/optional-modules";

package/dist/index.js

@@ -1,4 +1,5 @@
 import { a as OPTIONAL_MODULE_IDS, i as normalizeChat, n as CHAT_INPUT_MODES, o as OptionalModuleId, r as chatModuleDescriptor } from "./chat.module-descriptor-BTsep-Kq.js";
+import { a as LibId, c as libByRequireKey, i as LIB_IDS, n as LIBS, o as OPTIONAL_LIB_DESCRIPTORS, r as LIB_DESCRIPTORS, s as OPTIONAL_LIB_IDS, t as BUILTIN_LIB_DESCRIPTORS } from "./lib-registry-D1VyVPBg.js";
 import { n as getRadiusScale, t as getHalfheightRadiusScale } from "./get-scale-from-obj-B7JlVPni.js";
 import * as THREE from "three/webgpu";
 import { BufferGeometryLoader, LoadingManager, TextureLoader } from "three/webgpu";
@@ -7,10 +8,13 @@ import { ContextModule, ThreeContextEvents, ThreeStart } from "three-start";
 import * as TSL from "three/tsl";
 import { emissive, mrt, output } from "three/tsl";
 import van from "vanjs-core";
+import * as howler from "howler";
 import { Howl, Howler } from "howler";
 import { mergeGeometries } from "three/examples/jsm/utils/BufferGeometryUtils.js";
 import { clone } from "three/examples/jsm/utils/SkeletonUtils.js";
 import EventEmitter from "eventemitter3";
+import * as nanostores from "nanostores";
+import { atom } from "nanostores";
 //#region packages/world-runtime/src/world-events.ts
 /**
 * World lifecycle events, emitted on `game.emitter` (`world.events` in scripts)
@@ -46,6 +50,10 @@ var World = class extends ThreeStart {
 	get events() {
 		return this._runtime.emitter;
 	}
+	/** Shared reactive state — the same one as `world.stores` in scripts. */
+	get stores() {
+		return this._runtime.stores;
+	}
 	start() {
 		const wasStarted = this.isStarted;
 		super.start();
@@ -59,6 +67,26 @@ var World = class extends ThreeStart {
 };
 //#endregion
 //#region packages/world-runtime/src/utils/lazy.ts
+/**
+* Object that forwards every access to `resolve()`. For script globals that are
+* shortcuts into something created later (`modules` → `ctx.modules`): the script
+* bag is destructured eagerly, so a plain reference or a getter would be read
+* before the target exists.
+*/
+function lazyProxy(resolve) {
+	return new Proxy({}, {
+		get: (_target, key) => Reflect.get(resolve(), key),
+		has: (_target, key) => Reflect.has(resolve(), key),
+		ownKeys: () => Reflect.ownKeys(resolve()),
+		getOwnPropertyDescriptor: (_target, key) => {
+			const descriptor = Reflect.getOwnPropertyDescriptor(resolve(), key);
+			return descriptor && {
+				...descriptor,
+				configurable: true
+			};
+		}
+	});
+}
 /** Lazy cached value: the factory is called once on the first `get()`. */
 function lazy(factory) {
 	let has = false;
@@ -414,18 +442,24 @@ var ControlsModule = class extends ContextModule {
 };
 //#endregion
 //#region packages/world-runtime/src/behaviours/physics/_required-patch.ts
-var lazyRapierPhysicsModule = lazy(async () => (await import("./RapierPhysics-zLwVZpwF.js")).default);
+var lazyRapierPhysicsModule = lazy(async () => (await import("./RapierPhysics-CU6X--c7.js")).default);
 /** The only place the physics module is created — called by the registry
 *  descriptor. The module itself takes rapier from `ctx.modules.addons` on awake. */
 async function createRapierPhysicsModule(config) {
 	return new (await (lazyRapierPhysicsModule.get()))({ debug: config.debug });
 }
 /**
-* Registers physics on demand: a built-in physics behaviour declares it via
-* `meta.requiredPatch`, so a world with a collider on the scene gets
-* `ctx.modules.rapier` even without a line in `settings.addons.json`.
-* Idempotent, and strictly before `start()` — three-start forbids `addModules`
-* afterwards.
+* What a physics behaviour needs on top of its class: the rapier lib (loaded
+* with the other addons, before the world starts) and the physics ctx module.
+* A collider on the scene is enough — no line in `settings.addons.json`.
+*/
+var rapierPhysicsPatch = {
+	requiredLibs: [LibId.Rapier],
+	apply: (starter) => applyRapierPhysicsPatch(starter)
+};
+/**
+* Registers the physics module. Idempotent, and strictly before `start()` —
+* three-start forbids `addModules` afterwards.
 */
 async function applyRapierPhysicsPatch(starter) {
 	if (starter.ctx.modules.rapier) return;
@@ -456,6 +490,7 @@ var physicsModuleDescriptor = {
 		debug: false
 	}),
 	create: (config) => createRapierPhysicsModule(config),
+	requiredLibs: [LibId.Rapier],
 	schema: {
 		description: "Physics engine module. false | \"rapier\" | { engine, debug }.",
 		oneOf: [
@@ -531,19 +566,25 @@ var EnvModule = class extends ContextModule {
 //#endregion
 //#region packages/world-runtime/src/modules/HtmlHudModule.ts
 var { div } = van.tags;
+var LAYER_STYLE = "position:fixed;inset:0;pointer-events:none;";
 var HtmlHudModule = class extends ContextModule {
-	root;
+	overlay;
+	underlay;
 	crosshair;
 	constructor() {
 		super();
 		this.crosshair = div({
-			id: "kvyverse-game-gui-crosshair",
+			id: "kvy-crosshair",
 			style: "position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);"
 		});
-		this.root = div({
-			id: "kvyverse-game-gui-root",
-			style: "position:fixed;inset:0;pointer-events:none;"
+		this.overlay = div({
+			id: "kvy-overlay",
+			style: LAYER_STYLE
 		}, this.crosshair);
+		this.underlay = div({
+			id: "kvy-underlay",
+			style: LAYER_STYLE
+		});
 	}
 	onAwake() {
 		const ctx = this.ctx;
@@ -551,8 +592,13 @@ var HtmlHudModule = class extends ContextModule {
 		ctx.on(ThreeContextEvents.Mount, this.onMount);
 		ctx.on(ThreeContextEvents.Unmount, this.onUnmount);
 	}
+	/** Appends nodes over the canvas (the HUD). */
 	append(...nodes) {
-		this.root.append(...nodes);
+		this.overlay.append(...nodes);
+	}
+	/** Appends nodes under the canvas — visible only through a transparent canvas. */
+	appendUnderlay(...nodes) {
+		this.underlay.append(...nodes);
 	}
 	setCrosshair(innerHtml) {
 		this.crosshair.innerHTML = innerHtml;
@@ -563,10 +609,14 @@ var HtmlHudModule = class extends ContextModule {
 		this.ctx.off(ThreeContextEvents.Unmount, this.onUnmount);
 	}
 	onMount = (container) => {
-		container.append(this.root);
+		container.prepend(this.underlay);
+		container.append(this.overlay);
+		const canvas = this.ctx.renderer.domElement;
+		if (!canvas.style.position) canvas.style.position = "relative";
 	};
 	onUnmount = () => {
-		this.root.remove();
+		this.overlay.remove();
+		this.underlay.remove();
 	};
 };
 //#endregion
@@ -921,55 +971,55 @@ var entries = [
 		uuid: "rrb",
 		name: "Rigidbody",
 		load: () => loadDefault(import("./Rigidbody-DLhN8ddv.js").then((n) => n.n)),
-		requiredPatch: applyRapierPhysicsPatch
+		requiredPatch: rapierPhysicsPatch
 	},
 	{
 		uuid: "rapierballcol",
 		name: "BallCollider",
 		load: () => loadDefault(import("./BallCollider-3L5vOrcL.js")),
-		requiredPatch: applyRapierPhysicsPatch
+		requiredPatch: rapierPhysicsPatch
 	},
 	{
 		uuid: "rapiercapscol",
 		name: "CapsuleCollider",
 		load: () => loadDefault(import("./CapsuleCollider-CBTsR-Ys.js")),
-		requiredPatch: applyRapierPhysicsPatch
+		requiredPatch: rapierPhysicsPatch
 	},
 	{
 		uuid: "rapierconecol",
 		name: "ConeCollider",
 		load: () => loadDefault(import("./ConeCollider-C3XU3Y9X.js")),
-		requiredPatch: applyRapierPhysicsPatch
+		requiredPatch: rapierPhysicsPatch
 	},
 	{
 		uuid: "rapierconvxcol",
 		name: "ConvexMeshCollider",
 		load: () => loadDefault(import("./ConvexMeshCollider-DzNV4HTO.js")),
-		requiredPatch: applyRapierPhysicsPatch
+		requiredPatch: rapierPhysicsPatch
 	},
 	{
 		uuid: "rapiercubcol",
 		name: "CuboidCollider",
 		load: () => loadDefault(import("./CuboidCollider-Dp1DZoFM.js")),
-		requiredPatch: applyRapierPhysicsPatch
+		requiredPatch: rapierPhysicsPatch
 	},
 	{
 		uuid: "rapiercylcol",
 		name: "CylinderCollider",
 		load: () => loadDefault(import("./CylinderCollider-C0h_nhB5.js")),
-		requiredPatch: applyRapierPhysicsPatch
+		requiredPatch: rapierPhysicsPatch
 	},
 	{
 		uuid: "rapiertricol",
 		name: "TrimeshCollider",
 		load: () => loadDefault(import("./TrimeshCollider-7dIs_xtZ.js")),
-		requiredPatch: applyRapierPhysicsPatch
+		requiredPatch: rapierPhysicsPatch
 	},
 	{
 		uuid: "rapierfpsplayercontroller",
 		name: "RapierFpsPlayerController",
 		load: () => loadDefault(import("./RapierFpsPlayerController-DthD8dw9.js")),
-		requiredPatch: applyRapierPhysicsPatch
+		requiredPatch: rapierPhysicsPatch
 	}
 ];
 /** Registry of built-in behaviours by uuid — source of truth for both game and export. */
@@ -1044,122 +1094,123 @@ function createFont(url, family, mime, name) {
 	return source;
 }
 //#endregion
-//#region packages/world-runtime/src/addons/lib-registry.ts
+//#region packages/world-runtime/src/addons/builtin-libs.ts
 /**
-* Registry of built-in libraries enabled via `settings.addons.json → libs`.
-*
-* Separates two keys: `id` (short config key under `libs`) and `requireKey`
-* (what the user writes in `require(...)` in scripts — and the import specifier
-* importers are built from). Single source for:
-*  - game: the app's importer map (`core/game/settings/optional-imports`),
-*  - export: the `imports.libs` block the build emits into the world module,
-*  - editor: JSON schema (`libs` props) + require typings (`AddonsRequireTypings`).
-*
-* Adding a lib = add an entry here (+ importer in the app, + d.ts loader in editor).
-* The package itself never imports these — see `./optional-imports.ts`.
+* Libraries the runtime bundles itself: `require("<key>")` hands these back in
+* every world, no config and no importer involved. Metadata (keys, labels) is
+* in `lib-registry`; the modules live here so the registry stays importable
+* from the editor without dragging three & co along.
 */
-var LibId = /* @__PURE__ */ function(LibId) {
-	LibId["Tween"] = "tween";
-	LibId["Anime"] = "anime";
-	LibId["Nipplejs"] = "nipplejs";
-	LibId["Stats"] = "stats";
-	return LibId;
-}({});
-var LIBS = {
-	["tween"]: {
-		id: "tween",
-		requireKey: "@tweenjs/tween.js",
-		label: "Tween.js"
-	},
-	["anime"]: {
-		id: "anime",
-		requireKey: "animejs/animation",
-		packageName: "animejs",
-		label: "Anime.js (animate)"
-	},
-	["nipplejs"]: {
-		id: "nipplejs",
-		requireKey: "nipplejs",
-		label: "nipplejs (on-screen joystick)",
-		defaultExport: true
-	},
-	["stats"]: {
-		id: "stats",
-		requireKey: "stats.js",
-		label: "Stats.js (fps overlay)",
-		defaultExport: true
-	}
+var BUILTIN_LIB_MODULES = {
+	[LibId.Three]: THREE,
+	[LibId.Tsl]: TSL,
+	[LibId.ThreeStart]: ThreeStartNS,
+	[LibId.Van]: van,
+	[LibId.Nanostores]: nanostores,
+	[LibId.EventEmitter]: EventEmitter,
+	[LibId.Howler]: howler
+};
+/**
+* The subset of built-ins that is also a bare global in script scope — same
+* objects as above, so `THREE === require("three")`. Typed literally: the
+* script context contract depends on these exact shapes.
+*/
+var BUILTIN_GLOBALS = {
+	THREE,
+	TSL,
+	van
 };
-var LIB_IDS = Object.values(LibId);
-var LIB_DESCRIPTORS = LIB_IDS.map((id) => LIBS[id]);
-function libByRequireKey(requireKey) {
-	return LIB_DESCRIPTORS.find((l) => l.requireKey === requireKey);
+//#endregion
+//#region packages/world-runtime/src/addons/required-libs.ts
+/**
+* Libs the world needs beyond what `libs` lists: an enabled module or a built-in
+* behaviour on the scene declares them itself (`requiredLibs`), so physics keeps
+* working without a line in `settings.addons.json`. Same answer for the game and
+* for the export — the build emits importers from it.
+*/
+function collectRequiredLibs(addons, usedBuiltinUuids = []) {
+	const required = /* @__PURE__ */ new Set();
+	const configured = addons?.libs ?? {};
+	for (const id of Object.keys(configured)) if (configured[id] && LIB_IDS.includes(id) && !LIBS[id].builtin) required.add(id);
+	for (const descriptor of OPTIONAL_MODULES) {
+		if (!descriptor.requiredLibs?.length) continue;
+		if (descriptor.normalize(addons?.modules?.[descriptor.id]) === null) continue;
+		for (const id of descriptor.requiredLibs) required.add(id);
+	}
+	for (const uuid of usedBuiltinUuids) {
+		const libs = getBuiltinBehaviour(uuid)?.requiredPatch?.requiredLibs;
+		if (libs) for (const id of libs) required.add(id);
+	}
+	return [...required];
 }
 //#endregion
 //#region packages/world-runtime/src/addons/AddonsRuntime.ts
 /**
-* External dependencies of the world: built-in libs, externals and the physics
-* engine. Loaded before the world starts; scripts reach them through
-* `resolve(key)` (`require`), the physics module through `rapier`.
+* External dependencies of the world: libs and external scripts. Built-in libs
+* are registered right away (the runtime bundles them), optional ones are loaded
+* before the world starts — enabled in `settings.addons.json → libs` or declared
+* by a module/behaviour through `requiredLibs`. Scripts reach all of them by
+* `require("<key>")`.
 *
 * This is the `addons` ctx module, but it also works without a ctx: launcher
 * worlds have no 3d context while `require` still has to work, so there the
-* instance is used directly. How to import packages is up to the runtime owner
-* (see `WorldImports`).
+* instance is used directly. How to import optional packages is up to the
+* runtime owner (see `WorldImports`).
 */
 var AddonsRuntime = class extends ContextModule {
 	_imports;
 	/** libs — by requireKey (`@tweenjs/tween.js`), externals — by accessor (`Tone`). */
 	_byKey = /* @__PURE__ */ new Map();
+	_byLibId = /* @__PURE__ */ new Map();
 	_scriptTags = [];
-	_rapier = null;
 	constructor(_imports = {}) {
 		super();
 		this._imports = _imports;
+		this._registerBuiltins();
 	}
-	/** `physics` — whether the world needs rapier (config or a physics behaviour). */
-	async load(addons, options = {}) {
-		await this._loadLibs(addons.libs);
+	/** `usedBuiltinUuids` — built-in behaviours on the scene; they may require libs. */
+	async load(addons, usedBuiltinUuids = []) {
+		await this._loadLibs(collectRequiredLibs(addons, usedBuiltinUuids));
 		await this._loadExternals(addons.externals);
-		if (options.physics) await this._loadRapier();
 	}
-	/** Resolves a require key: enabled lib or external accessor; undefined otherwise. */
+	/** Resolves a require key: a lib or an external accessor; undefined otherwise. */
 	resolve(key) {
 		return this._byKey.get(key);
 	}
-	/** The physics engine, loaded and initialized; `null` in worlds without physics. */
-	get rapier() {
-		return this._rapier;
+	/** The lib itself, for runtime code that knows what it needs (physics → rapier). */
+	lib(id) {
+		return this._byLibId.get(id);
+	}
+	/** Libs bundled with the runtime: no importer, no config, always available. */
+	_registerBuiltins() {
+		for (const descriptor of BUILTIN_LIB_DESCRIPTORS) {
+			const module = BUILTIN_LIB_MODULES[descriptor.id];
+			if (module === void 0) {
+				console.error(`[addons] built-in lib "${descriptor.id}" has no module`);
+				continue;
+			}
+			this._register(descriptor.id, module);
+		}
 	}
-	async _loadLibs(libs) {
-		if (!libs) return;
-		for (const id of LIB_IDS) {
-			if (!libs[id]) continue;
+	async _loadLibs(ids) {
+		for (const id of ids) {
+			const descriptor = LIBS[id];
 			const load = this._imports.libs?.[id];
 			if (!load) {
-				console.error(`[addons] lib "${id}" is enabled but has no importer`);
+				console.error(`[addons] lib "${id}" is needed but has no importer`);
 				continue;
 			}
 			try {
-				this._byKey.set(LIBS[id].requireKey, unwrapLib(id, await load()));
+				const module = await load();
+				this._register(id, unwrapLib(id, await (descriptor.init?.(module) ?? module)));
 			} catch (e) {
 				console.error(`[addons] failed to load lib "${id}"`, e);
 			}
 		}
 	}
-	async _loadRapier() {
-		const load = this._imports.rapier;
-		if (!load) {
-			console.error("[addons] the world needs physics but has no importer for \"@dimforge/rapier3d-compat\"");
-			return;
-		}
-		try {
-			const rapier = await load();
-			await rapier.init();
-			this._rapier = rapier;
-		} catch (e) {
-			console.error("[addons] failed to load rapier", e);
-		}
+	_register(id, value) {
+		this._byLibId.set(id, value);
+		this._byKey.set(LIBS[id].requireKey, value);
 	}
 	async _loadExternals(externals) {
 		if (!externals) return;
@@ -1190,7 +1241,7 @@ var AddonsRuntime = class extends ContextModule {
 		for (const tag of this._scriptTags) tag.remove();
 		this._scriptTags.length = 0;
 		this._byKey.clear();
-		this._rapier = null;
+		this._byLibId.clear();
 	}
 };
 /** A package like nipplejs exposes its API as the default export — that is what
@@ -1200,6 +1251,67 @@ function unwrapLib(id, module) {
 	return module.default ?? module;
 }
 //#endregion
+//#region packages/world-runtime/src/world-stores.ts
+/**
+* Shared reactive key-value state of a world (`world.stores` in scripts) — the
+* state counterpart of the `world.events` bus. Stores are created lazily on
+* first touch; `undefined` means "no value", so `delete`/`clear` only reset
+* values and never invalidate a reference taken from `of()`.
+*/
+var WorldStores = class {
+	_stores = /* @__PURE__ */ new Map();
+	/** The store behind a key, created on first touch. */
+	of(key) {
+		let store = this._stores.get(key);
+		if (!store) {
+			store = atom(void 0);
+			this._stores.set(key, store);
+		}
+		return store;
+	}
+	get(key) {
+		return this.of(key).get();
+	}
+	set(key, value) {
+		this.of(key).set(value);
+	}
+	/** Subscribe to a key; returns unsubscribe. Not called with the current value. */
+	listen(key, listener) {
+		return this.of(key).listen(listener);
+	}
+	/** Same as `listen`, but also fires immediately with the current value. */
+	subscribe(key, listener) {
+		return this.of(key).subscribe(listener);
+	}
+	/** A value has been written to the key and not deleted since. */
+	has(key) {
+		return this._stores.get(key)?.get() !== void 0;
+	}
+	/** Keys that currently hold a value. */
+	keys() {
+		const keys = [];
+		for (const [key, store] of this._stores) if (store.get() !== void 0) keys.push(key);
+		return keys;
+	}
+	/** Plain object with all current values — for debugging and saves. */
+	snapshot() {
+		const result = {};
+		for (const [key, store] of this._stores) {
+			const value = store.get();
+			if (value !== void 0) result[key] = value;
+		}
+		return result;
+	}
+	/** Resets the key to `undefined`; listeners are notified. */
+	delete(key) {
+		this._stores.get(key)?.set(void 0);
+	}
+	/** Resets every key; listeners are notified. */
+	clear() {
+		for (const store of this._stores.values()) store.set(void 0);
+	}
+};
+//#endregion
 //#region packages/world-runtime/src/WorldRuntime.ts
 /**
 * Owner of the world's runtime state: assets, script execution, ctx access.
@@ -1210,6 +1322,8 @@ var WorldRuntime = class {
 	options;
 	/** World lifecycle event bus (`world.events` in scripts). */
 	emitter = new EventEmitter();
+	/** Shared reactive state of the world (`world.stores` in scripts). */
+	stores = new WorldStores();
 	_addons;
 	_executedScripts = /* @__PURE__ */ new Map();
 	_builtins = /* @__PURE__ */ new Map();
@@ -1218,6 +1332,7 @@ var WorldRuntime = class {
 	/** Reverse index for `getUrl(resource)` — play mode resolves objects too. */
 	_pathByResource = /* @__PURE__ */ new Map();
 	_ctx = null;
+	_starter = null;
 	_bloom = null;
 	_scriptContext = null;
 	constructor(definition, options) {
@@ -1238,18 +1353,17 @@ var WorldRuntime = class {
 	setContext(ctx) {
 		this._ctx = ctx;
 	}
+	/** @internal Set by bootstrap — backs `world.addModules` (register before start). */
+	setStarter(starter) {
+		this._starter = starter;
+	}
 	/** @internal World bloom, if enabled in the renderer config. */
 	setBloom(bloom) {
 		this._bloom = bloom;
 	}
-	/** @internal Built-in libs, externals and the physics engine, if the world needs one. */
+	/** @internal Libs (config + required by modules/behaviours) and externals. */
 	async loadAddons() {
-		await this._addons.load(this.definition.addons ?? {}, { physics: this._usesPhysics() });
-	}
-	/** Physics is on in the config, or a built-in behaviour on the scene needs it. */
-	_usesPhysics() {
-		if (normalizePhysics(this.definition.addons?.modules?.physics)) return true;
-		return (this.definition.usedBuiltins ?? []).some((uuid) => getBuiltinBehaviour(uuid)?.requiredPatch);
+		await this._addons.load(this.definition.addons ?? {}, this.definition.usedBuiltins ?? []);
 	}
 	/** @internal World resources by asset path — result of `loadAssets`. */
 	setResources(resources) {
@@ -1306,7 +1420,7 @@ var WorldRuntime = class {
 			const patch = getBuiltinBehaviour(uuid)?.requiredPatch;
 			if (!patch) continue;
 			try {
-				await patch(starter);
+				await patch.apply(starter);
 			} catch (error) {
 				console.error(`Required patch of "${uuid}" failed`, error);
 			}
@@ -1380,6 +1494,7 @@ var WorldRuntime = class {
 		this._styleElements.length = 0;
 		this._executedScripts.clear();
 		this.emitter.removeAllListeners();
+		this.stores.clear();
 	}
 	/** Narrow bloom facade for scripts: mode is read-only, params are live
 	* (uniforms, can be animated per frame). `null` — bloom is disabled. */
@@ -1425,20 +1540,20 @@ var WorldRuntime = class {
 				},
 				events: this.emitter,
 				emitter: this.emitter,
+				stores: this.stores,
 				rendering: { get bloom() {
 					return runtime.bloomApi;
-				} }
+				} },
+				addModules: (modules) => {
+					if (!runtime._starter) throw new Error("world.addModules is only available in the entry script (main.ts), before the world starts.");
+					runtime._starter.addModules(modules);
+				}
 			},
+			modules: lazyProxy(() => runtime.ctx.modules),
 			require: this.require,
 			instantiate: this.instantiate,
 			getUrl: this.getUrl,
-			THREE,
-			TSL,
-			van,
-			/** Physics engine global; null in worlds without physics. */
-			get RAPIER() {
-				return runtime.addons.rapier;
-			}
+			...BUILTIN_GLOBALS
 		};
 		return this._scriptContext;
 	}
@@ -1460,7 +1575,7 @@ function isAbsoluteUrl(url) {
 }
 //#endregion
 //#region packages/world-runtime/src/version.gen.ts
-var RUNTIME_VERSION = "0.3.2";
+var RUNTIME_VERSION = "0.5.0";
 //#endregion
 //#region packages/world-runtime/src/version.ts
 /**
@@ -1498,6 +1613,7 @@ async function bootstrapWorld(definition, options) {
 	runtime.reportProgress("Initializing 3D context");
 	const world = await createWorld(definition, runtime);
 	runtime.setContext(world.ctx);
+	runtime.setStarter(world);
 	await runtime.applyRequiredPatches(world);
 	runtime.reportProgress("Applying scene settings");
 	definition.applySceneSettings?.(runtime, world.ctx.scene);
@@ -1990,4 +2106,4 @@ var TONE_MAPPING_NAMES = [
 	"Neutral"
 ];
 //#endregion
-export { AddonsRuntime, AssetLoaders, AudioSource, BLOOM_MODES, BUILTIN_BEHAVIOURS, BUILTIN_BEHAVIOUR_LIST, CHAT_INPUT_MODES, DEFAULT_RESOURCE_IDS, DefaultResourceId, EXTERNAL_TYPES, EnvModule, FontSource, HtmlHudModule, InputSystemModule, LIBS, LIB_DESCRIPTORS, LIB_IDS, LOADING_MANAGER, LibId, OPTIONAL_MODULES, OPTIONAL_MODULE_IDS, OptionalModuleId, PHYSICS_ENGINES, RUNTIME_VERSION, SHADOW_MAP_TYPES, SceneBloom, SoundsModule, TONE_MAPPING_NAMES, TslNode, UNIFORM_DEFAULTS, UNIFORM_TYPES, UtilsModule, VideoSource, WORLD_FORMAT_VERSION, World, WorldEvent, applyRapierPhysicsPatch, applyRendererConfig, applyTextureDefaults, collectModelSubResources, configureAssetLoaders, createAudio, createFont, createTslNode, createUniformNode, createVideo, createWorldModules, defineWorld, enableSceneEmissiveMrt, fontFormatFromMime, getBuiltinBehaviour, getDefaultResource, getHalfheightRadiusScale, getOptionalModuleDescriptor, getRadiusScale, isDefaultResourceId, isMobileDevice, isUniformType, libByRequireKey, loadGeometry, loadHdr, loadModel, loadTexture, normalizeChat, normalizePhysics, parseGeometryJson, parseHdr, parseModel, setColor, uniformType };
+export { AddonsRuntime, AssetLoaders, AudioSource, BLOOM_MODES, BUILTIN_BEHAVIOURS, BUILTIN_BEHAVIOUR_LIST, BUILTIN_LIB_DESCRIPTORS, CHAT_INPUT_MODES, DEFAULT_RESOURCE_IDS, DefaultResourceId, EXTERNAL_TYPES, EnvModule, FontSource, HtmlHudModule, InputSystemModule, LIBS, LIB_DESCRIPTORS, LIB_IDS, LOADING_MANAGER, LibId, OPTIONAL_LIB_DESCRIPTORS, OPTIONAL_LIB_IDS, OPTIONAL_MODULES, OPTIONAL_MODULE_IDS, OptionalModuleId, PHYSICS_ENGINES, RUNTIME_VERSION, SHADOW_MAP_TYPES, SceneBloom, SoundsModule, TONE_MAPPING_NAMES, TslNode, UNIFORM_DEFAULTS, UNIFORM_TYPES, UtilsModule, VideoSource, WORLD_FORMAT_VERSION, World, WorldEvent, WorldStores, applyRendererConfig, applyTextureDefaults, collectModelSubResources, collectRequiredLibs, configureAssetLoaders, createAudio, createFont, createTslNode, createUniformNode, createVideo, createWorldModules, defineWorld, enableSceneEmissiveMrt, fontFormatFromMime, getBuiltinBehaviour, getDefaultResource, getHalfheightRadiusScale, getOptionalModuleDescriptor, getRadiusScale, isDefaultResourceId, isMobileDevice, isUniformType, lazyProxy, libByRequireKey, loadGeometry, loadHdr, loadModel, loadTexture, normalizeChat, normalizePhysics, parseGeometryJson, parseHdr, parseModel, rapierPhysicsPatch, setColor, uniformType };

package/dist/lib-registry-D1VyVPBg.js

@@ -0,0 +1,142 @@
+//#region packages/world-runtime/src/addons/lib-registry.ts
+/**
+* Registry of the libraries scripts can `require`. One entry describes one
+* library; the flags say how it gets into the world:
+*
+* - **built-in** (`builtin: true`) — the runtime already bundles it, so it is
+*   available in every world with no config and no importer. Some of them are
+*   additionally exposed as a bare global (`globalName`) — that is the only
+*   difference between `THREE` and, say, `nanostores`.
+* - **optional** — enabled in `settings.addons.json → libs`, or pulled in by
+*   something that declares it in `requiredLibs` (physics → rapier). The
+*   importer comes from the runtime owner (`WorldImports`), never from the
+*   package itself — see `./optional-imports.ts`.
+*
+* `id` is the config key under `libs`, `requireKey` is what the user writes in
+* `require(...)` (and the import specifier importers are built from). Single
+* source for: the app's importer map, the `imports.libs` block of an exported
+* world, the JSON schema and the editor's require typings.
+*/
+var LibId = /* @__PURE__ */ function(LibId) {
+	LibId["Three"] = "three";
+	LibId["Tsl"] = "tsl";
+	LibId["ThreeStart"] = "threeStart";
+	LibId["Van"] = "van";
+	LibId["Nanostores"] = "nanostores";
+	LibId["EventEmitter"] = "eventemitter3";
+	LibId["Howler"] = "howler";
+	LibId["Tween"] = "tween";
+	LibId["Anime"] = "anime";
+	LibId["Nipplejs"] = "nipplejs";
+	LibId["Stats"] = "stats";
+	LibId["Rapier"] = "rapier";
+	LibId["Css2d"] = "css2d";
+	LibId["Css3d"] = "css3d";
+	return LibId;
+}({});
+var LIBS = {
+	["three"]: {
+		id: "three",
+		requireKey: "three",
+		label: "three.js (WebGPU build)",
+		builtin: true,
+		globalName: "THREE"
+	},
+	["tsl"]: {
+		id: "tsl",
+		requireKey: "three/tsl",
+		packageName: "three",
+		label: "Three Shading Language",
+		builtin: true,
+		globalName: "TSL"
+	},
+	["threeStart"]: {
+		id: "threeStart",
+		requireKey: "three-start",
+		label: "three-start (engine core)",
+		builtin: true
+	},
+	["van"]: {
+		id: "van",
+		requireKey: "vanjs-core",
+		label: "VanJS (HTML UI)",
+		builtin: true,
+		globalName: "van",
+		defaultExport: true
+	},
+	["nanostores"]: {
+		id: "nanostores",
+		requireKey: "nanostores",
+		label: "nanostores (atoms behind world.stores)",
+		builtin: true
+	},
+	["eventemitter3"]: {
+		id: "eventemitter3",
+		requireKey: "eventemitter3",
+		label: "EventEmitter3",
+		builtin: true,
+		defaultExport: true
+	},
+	["howler"]: {
+		id: "howler",
+		requireKey: "howler",
+		label: "howler.js (audio)",
+		builtin: true
+	},
+	["tween"]: {
+		id: "tween",
+		requireKey: "@tweenjs/tween.js",
+		label: "Tween.js"
+	},
+	["anime"]: {
+		id: "anime",
+		requireKey: "animejs/animation",
+		packageName: "animejs",
+		label: "Anime.js (animate)"
+	},
+	["nipplejs"]: {
+		id: "nipplejs",
+		requireKey: "nipplejs",
+		label: "nipplejs (on-screen joystick)",
+		defaultExport: true
+	},
+	["stats"]: {
+		id: "stats",
+		requireKey: "stats.js",
+		label: "Stats.js (fps overlay)",
+		defaultExport: true
+	},
+	["rapier"]: {
+		id: "rapier",
+		requireKey: "@dimforge/rapier3d-compat",
+		label: "Rapier (physics engine)",
+		init: async (module) => {
+			await module.init();
+			return module;
+		}
+	},
+	["css2d"]: {
+		id: "css2d",
+		requireKey: "three/addons/renderers/CSS2DRenderer.js",
+		packageName: "three",
+		label: "CSS2DRenderer (DOM labels at 3d positions)"
+	},
+	["css3d"]: {
+		id: "css3d",
+		requireKey: "three/addons/renderers/CSS3DRenderer.js",
+		packageName: "three",
+		label: "CSS3DRenderer (DOM elements in 3d)"
+	}
+};
+var LIB_IDS = Object.values(LibId);
+var LIB_DESCRIPTORS = LIB_IDS.map((id) => LIBS[id]);
+/** Bundled with the runtime — available in every world. */
+var BUILTIN_LIB_DESCRIPTORS = LIB_DESCRIPTORS.filter((lib) => lib.builtin);
+/** Enabled in `settings.addons.json → libs` or required by a module/behaviour. */
+var OPTIONAL_LIB_DESCRIPTORS = LIB_DESCRIPTORS.filter((lib) => !lib.builtin);
+var OPTIONAL_LIB_IDS = OPTIONAL_LIB_DESCRIPTORS.map((lib) => lib.id);
+function libByRequireKey(requireKey) {
+	return LIB_DESCRIPTORS.find((l) => l.requireKey === requireKey);
+}
+//#endregion
+export { LibId as a, libByRequireKey as c, LIB_IDS as i, LIBS as n, OPTIONAL_LIB_DESCRIPTORS as o, LIB_DESCRIPTORS as r, OPTIONAL_LIB_IDS as s, BUILTIN_LIB_DESCRIPTORS as t };

package/dist/modules/HtmlHudModule.d.ts

@@ -1,11 +1,15 @@
 import { ContextModule } from "three-start";
 import type { HtmlModuleApi } from "./contracts/html.module-api";
 export declare class HtmlHudModule extends ContextModule implements HtmlModuleApi {
-    readonly root: HTMLDivElement;
+    readonly overlay: HTMLDivElement;
+    readonly underlay: HTMLDivElement;
     readonly crosshair: HTMLDivElement;
     constructor();
     onAwake(): void;
+    /** Appends nodes over the canvas (the HUD). */
     append(...nodes: Array<Node | string>): void;
+    /** Appends nodes under the canvas — visible only through a transparent canvas. */
+    appendUnderlay(...nodes: Array<Node | string>): void;
     setCrosshair(innerHtml: string): void;
     /** three-start ContextModule has no onDestroy; teardown is explicit. */
     dispose(): void;

package/dist/modules/contracts/addons.module-api.d.ts

@@ -1,15 +1,15 @@
-import type RAPIER from "@dimforge/rapier3d-compat";
+import type { LibId } from "../../addons/lib-registry";
 /**
- * Public API of the `addons` module — external dependencies of the world:
- * built-in libs and external scripts enabled in `settings.addons.json`, loaded
- * before the world starts.
+ * Public API of the `addons` module — the world's libraries and external
+ * scripts: built-in ones, those enabled in `settings.addons.json` and those
+ * required by an enabled module or a behaviour on the scene.
  *
  * Scripts normally reach a lib by `require("<key>")`; this module is the same
- * bag behind that call, plus the physics engine.
+ * bag behind that call.
  */
 export interface AddonsModuleApi {
-    /** Value by require key (a lib) or by accessor (an external); null if absent. */
+    /** Value by require key (a lib) or by accessor (an external); undefined if absent. */
     resolve: (key: string) => unknown;
-    /** The physics engine — loaded and initialized; null in worlds without physics. */
-    readonly rapier: typeof RAPIER | null;
+    /** The lib by its registry id — for runtime code that knows what it needs. */
+    lib: <T>(id: LibId) => T | undefined;
 }

package/dist/modules/contracts/html.module-api.d.ts

@@ -1,15 +1,27 @@
 /**
- * Public API of the `html` module — fullscreen HTML HUD on top of the canvas.
+ * Public API of the `html` module — two fullscreen DOM layers around the canvas:
+ * the HUD above it (`overlay`) and the underlay below it (`underlay`).
  *
- * The root is `pointer-events: none` on purpose: the HUD covers the whole screen
- * and must not swallow clicks meant for the world. Anything interactive you
- * append has to set `pointer-events: auto` on itself.
+ * Both are `pointer-events: none` on purpose: they cover the whole screen and
+ * must not swallow clicks meant for the world. Anything interactive appended to
+ * the HUD has to set `pointer-events: auto` on itself; the underlay can never
+ * be clicked at all — the canvas is on top of it.
+ *
+ * The underlay is only visible through a transparent canvas, which needs all
+ * three: `renderer.alpha` in `settings.renderer.json`, an empty scene
+ * background (a background colour paints over everything), and bloom off —
+ * the bloom pass currently loses the scene alpha, see
+ * `/docs/potential-issues.md`.
  */
 export interface HtmlModuleApi {
     /** HUD container over the canvas; click-through (`pointer-events: none`). */
-    readonly root: HTMLDivElement;
+    readonly overlay: HTMLDivElement;
+    /** Container under the canvas — for DOM that the world should render on top of. */
+    readonly underlay: HTMLDivElement;
     readonly crosshair: HTMLDivElement;
-    /** Appends nodes into the click-through root — see the note above. */
+    /** Appends nodes over the canvas — see the note above. */
     append: (...nodes: Array<Node | string>) => void;
+    /** Appends nodes under the canvas — see the note above. */
+    appendUnderlay: (...nodes: Array<Node | string>) => void;
     setCrosshair: (innerHtml: string) => void;
 }

package/dist/modules/optional-module-descriptor.d.ts

@@ -1,4 +1,5 @@
 import type { ContextModule } from "three-start";
+import type { LibId } from "../addons/lib-registry";
 /**
  * Keys of the pluggable modules — the same keys as in
  * `settings.addons.json → modules`. Core modules (`addons`/`env`/`html`/`input`/
@@ -27,6 +28,8 @@ export interface OptionalModuleDescriptor<TConfig = unknown> {
     defaultConfig: () => TConfig;
     /** The module class is pulled here — a disabled module never reaches the bundle. */
     create: (config: TConfig) => Promise<ContextModule>;
+    /** Libs the module cannot work without: enabling it loads them (physics → rapier). */
+    requiredLibs?: LibId[];
     /**
      * JSON Schema fragment for `modules.<id>`: the platform assembles the
      * `settings.addons.json` schema from these, so module keys never drift from the

package/dist/utils/lazy.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Object that forwards every access to `resolve()`. For script globals that are
+ * shortcuts into something created later (`modules` → `ctx.modules`): the script
+ * bag is destructured eagerly, so a plain reference or a getter would be read
+ * before the target exists.
+ */
+export declare function lazyProxy<T extends object>(resolve: () => T): T;
 /** Lazy cached value: the factory is called once on the first `get()`. */
 export declare function lazy<T>(factory: () => T): {
     get: () => T;

package/dist/version.gen.d.ts

@@ -1 +1 @@
-export declare const RUNTIME_VERSION = "0.3.2";
+export declare const RUNTIME_VERSION = "0.5.0";

package/dist/world-stores.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A single reactive value of `world.stores`. Narrow facade over a nanostores
+ * atom: scripts see exactly these four methods.
+ */
+export interface WorldStore<T> {
+    get: () => T | undefined;
+    set: (value: T | undefined) => void;
+    /** Fires on every change; returns unsubscribe. */
+    listen: (listener: (value: T | undefined) => void) => () => void;
+    /** Same as `listen`, but also fires immediately with the current value. */
+    subscribe: (listener: (value: T | undefined) => void) => () => void;
+}
+/**
+ * Shared reactive key-value state of a world (`world.stores` in scripts) — the
+ * state counterpart of the `world.events` bus. Stores are created lazily on
+ * first touch; `undefined` means "no value", so `delete`/`clear` only reset
+ * values and never invalidate a reference taken from `of()`.
+ */
+export declare class WorldStores {
+    private readonly _stores;
+    /** The store behind a key, created on first touch. */
+    of<T = unknown>(key: string): WorldStore<T>;
+    get<T = unknown>(key: string): T | undefined;
+    set<T = unknown>(key: string, value: T | undefined): void;
+    /** Subscribe to a key; returns unsubscribe. Not called with the current value. */
+    listen<T = unknown>(key: string, listener: (value: T | undefined) => void): () => void;
+    /** Same as `listen`, but also fires immediately with the current value. */
+    subscribe<T = unknown>(key: string, listener: (value: T | undefined) => void): () => void;
+    /** A value has been written to the key and not deleted since. */
+    has(key: string): boolean;
+    /** Keys that currently hold a value. */
+    keys(): string[];
+    /** Plain object with all current values — for debugging and saves. */
+    snapshot(): Record<string, unknown>;
+    /** Resets the key to `undefined`; listeners are notified. */
+    delete(key: string): void;
+    /** Resets every key; listeners are notified. */
+    clear(): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kvyverse/world-runtime",
-	"version": "0.3.2",
+	"version": "0.5.0",
 	"description": "Runtime for worlds exported from the Kvyverse platform for self-hosting",
 	"license": "SEE LICENSE IN LICENSE.md",
 	"author": "Vladislav Kruteniuk",
@@ -35,6 +35,7 @@
 		"animejs": "^4.5.0",
 		"eventemitter3": "^5.0.1",
 		"howler": "^2.2.4",
+		"nanostores": "^1.3.0",
 		"nipplejs": "^0.10.2",
 		"stats.js": "^0.17.0",
 		"three": "^0.184.0",