ecspresso 0.10.2 → 0.12.0

package/README.md

@@ -7,7 +7,7 @@ A type-safe, modular, and extensible Entity Component System (ECS) framework for
 ## Features
 
 - **Type-Safe**: Full TypeScript support with component, event, and resource type inference
-- **Modular**: Bundle-based architecture for organizing features
+- **Modular**: Plugin-based architecture for organizing features
 - **Developer-Friendly**: Clean, fluent API with method chaining
 - **Event-Driven**: Integrated event system for decoupled communication
 - **Resource Management**: Global state management with lazy loading
@@ -20,8 +20,9 @@ A type-safe, modular, and extensible Entity Component System (ECS) framework for
 - **Reactive Queries**: Enter/exit callbacks when entities match or unmatch queries
 - **System Groups**: Enable/disable groups of systems at runtime
 - **Component Lifecycle**: Callbacks for component add/remove with unsubscribe support
+- **Required Components**: Auto-add dependent components on spawn/addComponent (e.g. `localTransform` implies `worldTransform`)
 - **Command Buffer**: Deferred structural changes for safe entity/component operations during systems
-- **Timer Bundle**: ECS-native timers with event-based completion notifications
+- **Timer Plugin**: ECS-native timers with event-based completion notifications
 
 ## Installation
 
@@ -47,7 +48,7 @@ npm install ecspresso
 - [Entity Hierarchy](#entity-hierarchy) -- [Traversal](#traversal), [Parent-First Traversal](#parent-first-traversal), [Cascade Deletion](#cascade-deletion)
 - [Change Detection](#change-detection) -- [Marking Changes](#marking-changes), [Changed Query Filter](#changed-query-filter), [Sequence Timing](#sequence-timing)
 - [Command Buffer](#command-buffer) -- [Available Commands](#available-commands)
-- [Bundles](#bundles) -- [Built-in Bundles](#built-in-bundles), [Timer Bundle](#timer-bundle)
+- [Plugins](#plugins) -- [Plugin Factory](#plugin-factory), [Required Components](#required-components), [Built-in Plugins](#built-in-plugins), [Timer Plugin](#timer-plugin)
 - [Asset Management](#asset-management)
 - [Screen Management](#screen-management) -- [Screen-Scoped Systems](#screen-scoped-systems), [Screen Resource](#screen-resource)
 - [Type Safety](#type-safety)
@@ -66,8 +67,10 @@ interface Components {
   health: { value: number };
 }
 
-// 2. Create a world
-const world = new ECSpresso<Components>();
+// 2. Create a world using the builder — types are inferred automatically
+const world = ECSpresso.create()
+  .withComponentTypes<Components>()
+  .build();
 
 // 3. Add a movement system
 world.addSystem('movement')
@@ -77,8 +80,7 @@ world.addSystem('movement')
       entity.components.position.x += entity.components.velocity.x * deltaTime;
       entity.components.position.y += entity.components.velocity.y * deltaTime;
     }
-  })
-  .build();
+  });
 
 // 4. Create entities
 const player = world.spawn({
@@ -107,7 +109,7 @@ const entity = world.spawn({
 // Add components later
 world.entityManager.addComponent(entity.id, 'velocity', { x: 5, y: 0 });
 
-// Get component data (returns null if not found)
+// Get component data (returns undefined if not found)
 const position = world.entityManager.getComponent(entity.id, 'position');
 
 // Remove components or entities
@@ -186,8 +188,7 @@ world.addSystem('combat')
         // Combat logic here
       }
     }
-  })
-  .build();
+  });
 ```
 
 ### Resources
@@ -200,10 +201,11 @@ interface Resources {
   settings: { difficulty: 'easy' | 'hard' };
 }
 
-const world = new ECSpresso<Components, {}, Resources>();
-
-// Direct values
-world.addResource('score', { value: 0 });
+const world = ECSpresso.create()
+  .withComponentTypes<Components>()
+  .withResourceTypes<Resources>()
+  .withResource('score', { value: 0 })
+  .build();
 
 // Sync or async factories (lazy initialization)
 world.addResource('config', () => ({ difficulty: 'normal', soundEnabled: true }));
@@ -223,16 +225,14 @@ world.addSystem('scoring')
   .setProcess((queries, deltaTime, ecs) => {
     const score = ecs.getResource('score');
     score.value += 10;
-  })
-  .build();
+  });
 ```
 
-**Builder pattern** -- resources chain naturally with other builder methods:
+Resources also chain naturally with plugins in the builder:
 
 ```typescript
-const world = ECSpresso
-  .create<Components, Events, Resources>()
-  .withBundle(physicsBundle)
+const world = ECSpresso.create()
+  .withPlugin(physicsPlugin)
   .withResource('config', { debug: true, maxEntities: 1000 })
   .withResource('score', () => ({ value: 0 }))
   .withResource('cache', {
@@ -266,21 +266,20 @@ await world.disposeResources();              // All, in reverse dependency order
 
 ### Method Chaining
 
-Chain multiple systems using `.and()`. The `.and()` method returns the parent container (ECSpresso or Bundle), enabling fluent chaining:
+Systems use a fluent builder API: `world.addSystem().addQuery().setProcess()` -- systems are automatically registered via deferred finalization. No explicit termination call is needed.
 
 ```typescript
 world.addSystem('physics')
   .addQuery('moving', { with: ['position', 'velocity'] })
   .setProcess((queries, deltaTime) => {
     // Physics logic
-  })
-  .and() // Returns ECSpresso for continued chaining
-  .addSystem('rendering')
+  });
+
+world.addSystem('rendering')
   .addQuery('visible', { with: ['position', 'sprite'] })
   .setProcess((queries) => {
     // Rendering logic
-  })
-  .build();
+  });
 ```
 
 ### Query Type Utilities
@@ -311,8 +310,7 @@ world.addSystem('movement')
     for (const entity of queries.entities) {
       updatePosition(entity, deltaTime);
     }
-  })
-  .build();
+  });
 ```
 
 ### System Phases
@@ -328,33 +326,35 @@ Each phase's command buffer is played back before the next phase begins, so enti
 ```typescript
 world.addSystem('input')
   .inPhase('preUpdate')
-  .setProcess((queries, dt, ecs) => { /* Read input, update timers */ })
-  .and()
-  .addSystem('physics')
+  .setProcess((queries, dt, ecs) => { /* Read input, update timers */ });
+
+world.addSystem('physics')
   .inPhase('fixedUpdate')
   .setProcess((queries, dt, ecs) => {
     // dt is always fixedDt here (e.g. 1/60)
     // Runs 0..N times per frame based on accumulated time
-  })
-  .and()
-  .addSystem('gameplay')
+  });
+
+world.addSystem('gameplay')
   .inPhase('update')  // default phase
-  .setProcess((queries, dt, ecs) => { /* Game logic, AI */ })
-  .and()
-  .addSystem('transform-sync')
+  .setProcess((queries, dt, ecs) => { /* Game logic, AI */ });
+
+world.addSystem('transform-sync')
   .inPhase('postUpdate')
-  .setProcess((queries, dt, ecs) => { /* Transform propagation */ })
-  .and()
-  .addSystem('renderer')
+  .setProcess((queries, dt, ecs) => { /* Transform propagation */ });
+
+world.addSystem('renderer')
   .inPhase('render')
-  .setProcess((queries, dt, ecs) => { /* Visual output */ })
-  .build();
+  .setProcess((queries, dt, ecs) => { /* Visual output */ });
 ```
 
 **Fixed Timestep** -- The `fixedUpdate` phase uses a time accumulator for deterministic simulation. A spiral-of-death cap (8 steps) prevents runaway accumulation.
 
 ```typescript
-const world = ECSpresso.create<Components, Events, Resources>()
+const world = ECSpresso.create()
+  .withComponentTypes<Components>()
+  .withEventTypes<Events>()
+  .withResourceTypes<Resources>()
   .withFixedTimestep(1 / 60)  // 60Hz physics (default)
   .build();
 ```
@@ -371,13 +371,12 @@ Within each phase, systems execute in priority order (higher numbers first). Sys
 world.addSystem('physics')
   .inPhase('fixedUpdate')
   .setPriority(100) // Runs first within fixedUpdate
-  .setProcess(() => { /* physics */ })
-  .and()
-  .addSystem('constraints')
+  .setProcess(() => { /* physics */ });
+
+world.addSystem('constraints')
   .inPhase('fixedUpdate')
   .setPriority(50)  // Runs second within fixedUpdate
-  .setProcess(() => { /* constraints */ })
-  .build();
+  .setProcess(() => { /* constraints */ });
 ```
 
 ### System Groups
@@ -388,13 +387,12 @@ Organize systems into groups that can be enabled/disabled at runtime:
 world.addSystem('renderSprites')
   .inGroup('rendering')
   .addQuery('sprites', { with: ['position', 'sprite'] })
-  .setProcess((queries) => { /* ... */ })
-  .and()
-  .addSystem('renderParticles')
+  .setProcess((queries) => { /* ... */ });
+
+world.addSystem('renderParticles')
   .inGroup('rendering')
   .inGroup('effects')  // Systems can belong to multiple groups
-  .setProcess(() => { /* ... */ })
-  .build();
+  .setProcess(() => { /* ... */ });
 
 world.disableSystemGroup('rendering');              // All rendering systems skip
 world.enableSystemGroup('rendering');               // Resume rendering
@@ -415,8 +413,7 @@ world.addSystem('gameSystem')
   })
   .setOnDetach((ecs) => {
     console.log('System shutting down...');
-  })
-  .build();
+  });
 
 await world.initialize();
 ```
@@ -448,7 +445,10 @@ interface Events {
   };
 }
 
-const world = new ECSpresso<Components, Events>();
+const world = ECSpresso.create()
+  .withComponentTypes<Components>()
+  .withEventTypes<Events>()
+  .build();
 
 // Subscribe - returns unsubscribe function
 const unsubscribe = world.on('playerDied', (data) => {
@@ -464,19 +464,16 @@ world.off('levelComplete', handler);
 // Handle events in systems
 world.addSystem('gameLogic')
   .setEventHandlers({
-    playerDied: {
-      handler: (data, ecs) => {
-        // Respawn logic
-      }
+    playerDied: (data, ecs) => {
+      // Respawn logic
     }
-  })
-  .build();
+  });
 
 // Publish events from anywhere
 world.eventBus.publish('playerDied', { playerId: 1 });
 ```
 
-**Built-in events**: `hierarchyChanged` (entity parent changes), `assetLoaded` / `assetFailed` / `assetGroupProgress` / `assetGroupLoaded` (asset loading), and timer `onComplete` events (see [Bundles](#bundles)).
+**Built-in events**: `hierarchyChanged` (entity parent changes), `assetLoaded` / `assetFailed` / `assetGroupProgress` / `assetGroupLoaded` (asset loading), and timer `onComplete` events (see [Plugins](#plugins)).
 
 ## Entity Hierarchy
 
@@ -545,7 +542,7 @@ world.removeEntity(parent.id, { cascade: false });
 
 Hierarchy changes emit the `hierarchyChanged` event (see [Events](#events)).
 
-**World position pattern**: `worldPos = localPos + parent.worldPos`. A parent's world position already includes all grandparents, so each entity only needs to combine its local position with its immediate parent's world position. The Transform bundle implements this automatically.
+**World position pattern**: `worldPos = localPos + parent.worldPos`. A parent's world position already includes all grandparents, so each entity only needs to combine its local position with its immediate parent's world position. The Transform plugin implements this automatically.
 
 ## Change Detection
 
@@ -577,8 +574,7 @@ world.addSystem('render-sync')
     for (const entity of queries.moved) {
       syncSpritePosition(entity);
     }
-  })
-  .build();
+  });
 ```
 
 When multiple components are listed in `changed`, entities matching **any** of them are included (OR semantics).
@@ -602,7 +598,7 @@ if (em.getChangeSeq(entity.id, 'localTransform') > ecs.changeThreshold) {
 
 **Deferred marking**: `ecs.commands.markChanged(entity.id, 'position')` queues a mark for command buffer playback.
 
-**Built-in bundle usage**: Movement marks `localTransform` (fixedUpdate) → Transform propagation reads `localTransform` changed, writes+marks `worldTransform` (postUpdate) → Renderer reads `worldTransform` changed (render).
+**Built-in plugin usage**: Movement marks `localTransform` (fixedUpdate) → Transform propagation reads `localTransform` changed, writes+marks `worldTransform` (postUpdate) → Renderer reads `worldTransform` changed (render).
 
 ## Command Buffer
 
@@ -621,8 +617,7 @@ world.addSystem('combat')
         });
       }
     }
-  })
-  .build();
+  });
 ```
 
 ### Available Commands
@@ -653,68 +648,170 @@ ecs.commands.clear(); // Discard all queued commands
 
 Commands execute in FIFO order. If a command fails (e.g., entity doesn't exist), it logs a warning and continues with remaining commands.
 
-## Bundles
+## Plugins
 
-Organize related systems and resources into reusable bundles:
+Organize related systems and resources into reusable plugins:
 
 ```typescript
-import { Bundle } from 'ecspresso';
+import ECSpresso, { definePlugin, type WorldConfigFrom } from 'ecspresso';
 
-const physicsBundle = new Bundle<GameComponents, {}, GameResources>('physics')
-  .addSystem('applyVelocity')
-  .addQuery('moving', { with: ['position', 'velocity'] })
-  .setProcess((queries, deltaTime) => {
-    for (const entity of queries.moving) {
-      entity.components.position.x += entity.components.velocity.x * deltaTime;
-      entity.components.position.y += entity.components.velocity.y * deltaTime;
-    }
-  })
-  .and()
-  .addSystem('applyGravity')
-  .addQuery('falling', { with: ['velocity'] })
-  .setProcess((queries, deltaTime, ecs) => {
-    const gravity = ecs.getResource('gravity');
-    for (const entity of queries.falling) {
-      entity.components.velocity.y += gravity.value * deltaTime;
-    }
-  })
-  .and()
-  .addResource('gravity', { value: 9.8 });
+interface PhysicsComponents {
+  position: { x: number; y: number };
+  velocity: { x: number; y: number };
+}
+
+interface PhysicsResources {
+  gravity: { value: number };
+}
 
-// Register bundles with the world
-const game = ECSpresso.create<GameComponents, {}, GameResources>()
-  .withBundle(physicsBundle)
+const physicsPlugin = definePlugin<WorldConfigFrom<PhysicsComponents, {}, PhysicsResources>>({
+  id: 'physics',
+  install(world) {
+    world.addSystem('applyVelocity')
+      .addQuery('moving', { with: ['position', 'velocity'] })
+      .setProcess((queries, deltaTime) => {
+        for (const entity of queries.moving) {
+          entity.components.position.x += entity.components.velocity.x * deltaTime;
+          entity.components.position.y += entity.components.velocity.y * deltaTime;
+        }
+      });
+
+    world.addSystem('applyGravity')
+      .addQuery('falling', { with: ['velocity'] })
+      .setProcess((queries, deltaTime, ecs) => {
+        const gravity = ecs.getResource('gravity');
+        for (const entity of queries.falling) {
+          entity.components.velocity.y += gravity.value * deltaTime;
+        }
+      });
+
+    world.addResource('gravity', { value: 9.8 });
+  },
+});
+
+// Register plugins with the world — types merge automatically
+const game = ECSpresso.create()
+  .withPlugin(physicsPlugin)
   .build();
 ```
 
-### Built-in Bundles
+### Plugin Factory
+
+When multiple plugins share the same types (common in application code), use `pluginFactory()` on the builder or built world to capture types automatically:
+
+```typescript
+// types.ts — builder accumulates all types
+export const builder = ECSpresso.create()
+  .withPlugin(createPhysicsPlugin())
+  .withComponentTypes<{ player: boolean; enemy: EnemyData }>()
+  .withResourceTypes<{ score: number }>();
+
+// Types flow from the builder — no manual imports or extends chains
+export const definePlugin = builder.pluginFactory();
+
+// movement-plugin.ts — no type params needed
+import { definePlugin } from './types';
+
+export const movementPlugin = definePlugin({
+  id: 'movement',
+  install(world) {
+    world.addSystem('movement')
+      .addQuery('moving', { with: ['position', 'velocity'] })
+      .setProcess((queries, dt) => { /* ... */ });
+  },
+});
+```
+
+You can also pass a world type directly to `definePlugin` as a one-off alternative:
+
+```typescript
+type MyWorld = typeof ecs; // derive from a built world
+const plugin = definePlugin<MyWorld>({
+  id: 'my-plugin',
+  install(world) { /* world is fully typed */ },
+});
+```
+
+### Required Components
+
+Plugins can declare that certain components depend on others. When an entity gains a trigger component, any required components that aren't already present are auto-added with default values:
+
+```typescript
+const transformPlugin = definePlugin<WorldConfigFrom<TransformComponents>>({
+  id: 'transform',
+  install(world) {
+    world.registerRequired('localTransform', 'worldTransform', () => ({
+      x: 0, y: 0, rotation: 0, scaleX: 1, scaleY: 1,
+    }));
+  },
+});
+
+const world = ECSpresso.create()
+  .withPlugin(transformPlugin)
+  .build();
+
+// worldTransform is auto-added with defaults
+const entity = world.spawn({
+  localTransform: { x: 100, y: 200, rotation: 0, scaleX: 1, scaleY: 1 },
+});
+
+// Explicit values always win — no auto-add if already provided
+const entity2 = world.spawn({
+  localTransform: { x: 100, y: 200, rotation: 0, scaleX: 1, scaleY: 1 },
+  worldTransform: { x: 50, y: 50, rotation: 0, scaleX: 2, scaleY: 2 }, // used as-is
+});
+```
 
-| Bundle | Import | Default Phase | Description |
+Requirements can also be registered via the builder or at runtime:
+
+```typescript
+// Builder
+const world = ECSpresso.create()
+  .withComponentTypes<Components>()
+  .withRequired('rigidBody', 'velocity', () => ({ x: 0, y: 0 }))
+  .withRequired('rigidBody', 'force', () => ({ x: 0, y: 0 }))
+  .build();
+
+// Runtime
+world.registerRequired('position', 'velocity', () => ({ x: 0, y: 0 }));
+```
+
+**Behavior:**
+- Enforced at insertion time (`spawn`, `addComponent`, `addComponents`, `spawnChild`, command buffer)
+- Removal is unrestricted — removing a required component does not cascade
+- Transitive requirements resolve automatically (A requires B, B requires C → all three added)
+- Circular dependencies are detected and rejected at registration time
+- Auto-added components are marked as changed and trigger reactive queries
+- Component names and factory return types are fully type-checked
+
+**Built-in requirements:** The Transform plugin registers `localTransform` → `worldTransform`. The Physics 2D plugin registers `rigidBody` → `velocity` and `rigidBody` → `force`.
+
+### Built-in Plugins
+
+| Plugin | Import | Default Phase | Description |
 |--------|--------|---------------|-------------|
-| **Input** | `ecspresso/bundles/utils/input` | `preUpdate` | Frame-accurate keyboard/pointer input with action mapping |
-| **Timers** | `ecspresso/bundles/utils/timers` | `preUpdate` | ECS-native timers with event-based completion |
-| **Movement** | `ecspresso/bundles/utils/movement` | `fixedUpdate` | Velocity-based movement integration |
-| **Transform** | `ecspresso/bundles/utils/transform` | `postUpdate` | Hierarchical transform propagation (local/world transforms) |
-| **Bounds** | `ecspresso/bundles/utils/bounds` | `postUpdate` | Screen bounds enforcement (destroy, clamp, wrap) |
-| **Collision** | `ecspresso/bundles/utils/collision` | `postUpdate` | Layer-based AABB/circle collision detection with events |
-| **2D Renderer** | `ecspresso/bundles/renderers/renderer2D` | `render` | Automated PixiJS scene graph wiring |
+| **Input** | `ecspresso/plugins/input` | `preUpdate` | Frame-accurate keyboard/pointer input with action mapping |
+| **Timers** | `ecspresso/plugins/timers` | `preUpdate` | ECS-native timers with event-based completion |
+| **Movement** | `ecspresso/plugins/movement` | `fixedUpdate` | Velocity-based movement integration |
+| **Transform** | `ecspresso/plugins/transform` | `postUpdate` | Hierarchical transform propagation (local/world transforms) |
+| **Bounds** | `ecspresso/plugins/bounds` | `postUpdate` | Screen bounds enforcement (destroy, clamp, wrap) |
+| **Collision** | `ecspresso/plugins/collision` | `postUpdate` | Layer-based AABB/circle collision detection with events |
+| **2D Renderer** | `ecspresso/plugins/renderers/renderer2D` | `render` | Automated PixiJS scene graph wiring |
 
-Each bundle accepts a `phase` option to override its default.
+Each plugin accepts a `phase` option to override its default.
 
-### Input Bundle
+### Input Plugin
 
-The input bundle provides frame-accurate keyboard, pointer (mouse + touch via PointerEvent), and named action mapping. It's a resource-only bundle — input is polled via the `inputState` resource. DOM events are accumulated between frames and snapshotted once per frame, so all systems see consistent state.
+The input plugin provides frame-accurate keyboard, pointer (mouse + touch via PointerEvent), and named action mapping. It's a resource-only plugin — input is polled via the `inputState` resource. DOM events are accumulated between frames and snapshotted once per frame, so all systems see consistent state.
 
 ```typescript
 import {
-  createInputBundle,
+  createInputPlugin,
   type InputResourceTypes, type KeyCode
-} from 'ecspresso/bundles/utils/input';
-
-interface Resources extends InputResourceTypes {}
+} from 'ecspresso/plugins/input';
 
-const world = ECSpresso.create<Components, Events, Resources>()
-  .withBundle(createInputBundle({
+const world = ECSpresso.create()
+  .withPlugin(createInputPlugin({
     actions: {
       jump: { keys: [' ', 'ArrowUp'] },
       shoot: { keys: ['z'], buttons: [0] },
@@ -730,21 +827,28 @@ if (input.actions.justActivated('jump')) { /* ... */ }
 if (input.keyboard.isDown('ArrowRight')) { /* ... */ }
 if (input.pointer.justPressed(0)) { /* ... */ }
 
-// Runtime remapping
-input.setActionMap({ jump: { keys: ['w'] } });
+// Runtime remapping — must include all configured actions
+input.setActionMap({
+  jump: { keys: ['w'] },
+  shoot: { keys: ['z'], buttons: [0] },
+  moveLeft: { keys: ['a'] },
+  moveRight: { keys: ['d'] },
+});
 ```
 
+Action names are type-safe — `isActive`, `justActivated`, `justDeactivated`, `setActionMap`, and `getActionMap` only accept action names from the config. The type parameter `A` is inferred from the `actions` object keys passed to `createInputPlugin`. Defaults to `string` when no actions are configured.
+
 Key values use the `KeyCode` type — a union of all standard `KeyboardEvent.key` values — providing autocomplete and compile-time validation. Note that the space bar key is `' '` (a space character), not `'Space'`.
 
-### Timer Bundle
+### Timer Plugin
 
-The timer bundle provides ECS-native timers that follow the "data, not callbacks" philosophy. Timers are components processed each frame, with optional event-based completion notifications.
+The timer plugin provides ECS-native timers that follow the "data, not callbacks" philosophy. Timers are components processed each frame, with optional event-based completion notifications.
 
 ```typescript
 import {
-  createTimerBundle, createTimer, createRepeatingTimer,
+  createTimerPlugin, createTimer, createRepeatingTimer,
   type TimerComponentTypes, type TimerEventData
-} from 'ecspresso/bundles/utils/timers';
+} from 'ecspresso/plugins/timers';
 
 // Events used with onComplete must have TimerEventData payload
 interface Events {
@@ -752,21 +856,19 @@ interface Events {
   spawnWave: TimerEventData;
 }
 
-interface Components extends TimerComponentTypes<Events> {
-  position: { x: number; y: number };
-}
-
 const world = ECSpresso
-  .create<Components, Events>()
-  .withBundle(createTimerBundle<Events>())
+  .create()
+  .withPlugin(createTimerPlugin())
+  .withComponentTypes<{ position: { x: number; y: number } }>()
+  .withEventTypes<Events>()
   .build();
 
 // One-shot timer (poll justFinished or use onComplete event)
-world.spawn({ ...createTimer<Events>(2.0), position: { x: 0, y: 0 } });
-world.spawn({ ...createTimer<Events>(1.5, { onComplete: 'hideMessage' }) });
+world.spawn({ ...createTimer(2.0), position: { x: 0, y: 0 } });
+world.spawn({ ...createTimer(1.5, { onComplete: 'hideMessage' }) });
 
 // Repeating timer
-world.spawn({ ...createRepeatingTimer<Events>(5.0, { onComplete: 'spawnWave' }) });
+world.spawn({ ...createRepeatingTimer(5.0, { onComplete: 'spawnWave' }) });
 ```
 
 Timer components expose `elapsed`, `duration`, `repeat`, `active`, `justFinished`, and optional `onComplete` for runtime control.
@@ -782,7 +884,10 @@ type Assets = {
   level1Background: { data: ImageBitmap };
 };
 
-const game = ECSpresso.create<Components, Events, Resources, Assets>()
+const game = ECSpresso.create()
+  .withComponentTypes<Components>()
+  .withEventTypes<Events>()
+  .withResourceTypes<Resources>()
   .withAssets(assets => assets
     // Eager assets - loaded automatically during initialize()
     .add('playerTexture', async () => {
@@ -813,8 +918,7 @@ game.addSystem('gameplay')
   .requiresAssets(['playerTexture'])
   .setProcess((queries, dt, ecs) => {
     const player = ecs.getAsset('playerTexture');
-  })
-  .build();
+  });
 ```
 
 Asset events (`assetLoaded`, `assetFailed`, `assetGroupProgress`, `assetGroupLoaded`) are available through the event system -- see [Events](#events).
@@ -838,7 +942,10 @@ type Screens = {
   pause: ScreenDefinition<Record<string, never>, Record<string, never>>;
 };
 
-const game = ECSpresso.create<Components, Events, Resources, {}, Screens>()
+const game = ECSpresso.create()
+  .withComponentTypes<Components>()
+  .withEventTypes<Events>()
+  .withResourceTypes<Resources>()
   .withScreens(screens => screens
     .add('menu', {
       initialState: () => ({ selectedOption: 0 }),
@@ -876,13 +983,11 @@ game.addSystem('menuUI')
   .inScreens(['menu'])                         // Only runs in 'menu'
   .setProcess((queries, dt, ecs) => {
     renderMenu(ecs.getScreenState().selectedOption);
-  })
-  .build();
+  });
 
 game.addSystem('animations')
   .excludeScreens(['pause'])                   // Runs in all screens except 'pause'
-  .setProcess(() => { /* ... */ })
-  .build();
+  .setProcess(() => { /* ... */ });
 ```
 
 ### Screen Resource
@@ -900,8 +1005,7 @@ game.addSystem('ui')
     screen.stackDepth;     // Number of screens in stack
     screen.isCurrent('gameplay');   // Check current screen
     screen.isActive('menu');        // true if in current or stack
-  })
-  .build();
+  });
 ```
 
 ## Type Safety
@@ -926,15 +1030,19 @@ world.addSystem('example')
       entity.components.position.x;   // ✅ guaranteed
       entity.components.health.value; // ❌ not in query
     }
-  })
-  .build();
+  });
 
-// Bundle type compatibility - conflicting types error at compile time
-const bundle1 = new Bundle<{position: {x: number, y: number}}>('b1');
-const bundle2 = new Bundle<{velocity: {x: number, y: number}}>('b2');
+// Plugin type compatibility - conflicting types error at compile time
+const plugin1 = definePlugin<WorldConfigFrom<{ position: { x: number; y: number } }>>({
+  id: 'p1', install() {},
+});
+const plugin2 = definePlugin<WorldConfigFrom<{ velocity: { x: number; y: number } }>>({
+  id: 'p2', install() {},
+});
+// Builder merges plugin types automatically — no manual type params needed
 const world = ECSpresso.create()
-  .withBundle(bundle1)
-  .withBundle(bundle2)  // Types merge successfully
+  .withPlugin(plugin1)
+  .withPlugin(plugin2)
   .build();
 ```
 
@@ -949,8 +1057,8 @@ world.getResource('nonexistent');
 world.entityManager.addComponent(999, 'position', { x: 0, y: 0 });
 // → "Cannot add component 'position': Entity with ID 999 does not exist"
 
-// Component not found returns null (no throw)
-world.entityManager.getComponent(123, 'position'); // null
+// Component not found returns undefined (no throw)
+world.entityManager.getComponent(123, 'position'); // undefined
 ```
 
 ## Performance Tips
@@ -958,7 +1066,7 @@ world.entityManager.getComponent(123, 'position'); // null
 - Use `changed` query filters to skip unchanged entities in render sync, transform propagation, and similar systems
 - Call `markChanged` after in-place mutations so downstream systems can detect the change
 - Extract business logic into testable helper functions using query type utilities
-- Bundle related systems for better organization and reusability
+- Group related systems into plugins for better organization and reusability
 - Use system phases to separate concerns (physics in `fixedUpdate`, rendering in `render`) and priorities for ordering within a phase
 - Use resource factories for expensive initialization (textures, audio, etc.)
 - Consider component callbacks for immediate reactions to state changes