@microverse.ts/microverse-lua 0.1.0 → 0.2.0

package/README.md

@@ -2,17 +2,17 @@
 
 **Lua microverse** facade for TypeScript applications: `MicroverseLua.create`, Wasm VM, script slots, and the fluent host surface builder.
 
-Monorepo overview: [root README](../../README.md).
+Monorepo overview (protocol vision): [root README](../../README.md).
 
 ## What is a Lua microverse?
 
 One logical scripting universe in your process:
 
 - **One** Wasm-backed Lua VM (Wasmoon), shared for efficiency.
-- **Many** isolated **environment slots** — one per registered script.
-- **One** host **surface** (declarative bridges + optional workflow hooks).
+- **Many** isolated **environment slots** — one per mounted script instance.
+- **One** host **surface** (declarative bridges + optional component hooks).
 - **One** host **object** (your TypeScript services).
-- **Per-script capability allowlists** at registration.
+- **Per-instance capability allowlists** at mount.
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
@@ -24,7 +24,7 @@ One logical scripting universe in your process:
 │  │  │ caps: […]   │ │ caps: […]   │ │ caps: […]   │     │  │
 │  │  └─────────────┘ └─────────────┘ └─────────────┘     │  │
 │  └───────────────────────────────────────────────────────┘  │
-│         ▲ bridges from host surface + host services         │
+│         ▲ bridges via self.bridges (scoped per instance)    │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -36,7 +36,68 @@ pnpm add @microverse.ts/microverse-lua
 
 Workspace: `"@microverse.ts/microverse-lua": "workspace:*"`.
 
-## Quick start
+## Concepts
+
+| Term | Meaning |
+|------|---------|
+| **Microverse** | One shared Wasm Lua VM + catalog of script definitions + N mounted instances ([`LuaMicroverse`](src/infrastructure/facade/luaMicroverse.ts)). |
+| **Host** | Your typed services object passed to `MicroverseLua.create({ host })`. Handlers on the surface receive it; Lua never sees the raw host table. |
+| **Surface** | Result of `defineHostSurfaceFor<THost>().bridge(…).method(…).componentHooks(…).build()` — bridges, capability ids, and a manifest for `.d.lua`. |
+| **Bridge** | A named group of host methods exposed in Lua as `self.bridges.<name>:<method>(payload)`. **Not** a global in the script slot. |
+| **Capability** | A `domain:action` string declared on each bridge method (`requires`). Each instance mounts with an allowlist (`surface.pickCapabilities(…)`). |
+| **Script definition** | Catalog entry: `scriptId`, Lua source, optional `injectLuaChunks`, optional props schema / defaults. |
+| **Script instance** | A mounted slot: `instanceId`, `scriptId`, capabilities, props, and the active component table from `component:extend()`. |
+| **Component** | Lua table from `component:extend()` with `properties`, `state`, `bridges`, lifecycle (`init`, `onDestroy`, `onPropsChanged`), and domain `on*` hooks. |
+
+## Engine lifecycle
+
+When you mount an instance, the runtime runs this pipeline (see [`mountScriptInstance`](src/infrastructure/facade/luaMicroverse.ts)):
+
+```mermaid
+sequenceDiagram
+  participant App
+  participant MV as LuaMicroverse
+  participant Session as HostScriptSession
+  participant VM as Wasm Lua
+
+  App->>MV: registerScriptDefinition
+  App->>MV: mountScriptInstance
+  MV->>Session: openSession
+  Session->>VM: run shared + inject prelude chunks
+  Session->>VM: run main chunk
+  Session->>VM: setProps
+  Session->>VM: invoke init
+  App->>MV: emitToAllInstances
+  MV->>Session: invoke on* hooks
+  App->>MV: unmountScriptInstance
+  MV->>Session: onDestroy + dispose
+```
+
+1. **`registerScriptDefinition`** — Add source to the catalog (does not allocate a slot).
+2. **`mountScriptInstance`** — Open a slot, run preludes + main chunk, merge props, call `init`.
+3. **`emitToAllInstances`** — Broadcast a component hook (`OrderPlaced`, …) to every mounted instance.
+4. **`unmountScriptInstance`** — Call `onDestroy`, tear down the slot.
+5. **`dispose`** — Unmount all instances.
+
+## API
+
+| Export / method | Purpose |
+|-----------------|--------|
+| `MicroverseLua.create` | Create a Lua microverse (Wasm VM included). |
+| `registerScriptDefinition` | Catalog entry (source, optional preludes, props schema). |
+| `mountScriptInstance` | New Wasm slot for one instance (capabilities, props, audit). |
+| `unmountScriptInstance` | Tear down one instance. |
+| `emitToAllInstances` | Call `on{Kind}` on every mounted instance (component hooks). |
+| `setInstanceProps` / `patchInstanceProps` | Update host-synced props; may invoke `onPropsChanged`. |
+| `getInstanceProps` / `flushInstanceProps` | Read or flush props proxy state. |
+| `getSurfaceCapabilities` | All capability ids declared on the surface. |
+| `surface.pickCapabilities(…)` | Build an allowlist for `mountScriptInstance`. |
+| `dispose` | Unmount all instances. |
+| `defineHostSurfaceFor`, `defineHostSurface` | Fluent surface builder (`bridge` → `method` → `build`). |
+
+Re-exported from this package for convenience; lower-level session API lives in `@microverse.ts/host-surface`.
+
+## Quick start (minimal)
 
 ```ts
 import { MicroverseLua, defineHostSurfaceFor } from '@microverse.ts/microverse-lua';
@@ -60,38 +121,249 @@ const microverse = MicroverseLua.create({
   defaultTimeoutMs: 30_000,
 });
 
-await microverse.registerScript({
+microverse.registerScriptDefinition({
+  scriptId: 'welcome',
+  source: `local msg = greet:hello({ name = "world" })`,
+});
+await microverse.mountScriptInstance({
+  instanceId: 'welcome',
   scriptId: 'welcome',
-  script: `local msg = greet:hello({ name = "world" })`,
   capabilities: surface.pickCapabilities('demo:greet'),
 });
 
 await microverse.dispose();
 ```
 
-## API
+> The minimal sample uses a global `greet` table for brevity. In production, use **`component:extend()`** and **`self.bridges`** (see [Lua authoring](#lua-authoring) and [Integrating in your app](#integrating-in-your-app)).
 
-| Export | Purpose |
-|--------|---------|
-| `MicroverseLua.create` | Create a Lua microverse (Wasm VM included). |
-| `registerScript` | New slot + optional preludes + main chunk. |
-| `emitToAllScripts` | Call `on{Kind}` on every script (workflow hooks). |
-| `defineHostSurfaceFor`, `defineHostSurface` | Fluent surface builder (`bridge` → `method` → `build`). |
+## Integrating in your app
+
+The reference layout is [`examples/business-scripting-engine`](../../examples/business-scripting-engine). File tour: [example README](../../examples/business-scripting-engine/README.md).
+
+### 1. Define the host
+
+Aggregate your real services into one object the surface handlers receive:
+
+```ts
+// examples/business-scripting-engine/src/services/businessEngineHost.ts
+export type BusinessEngineHost = {
+  readonly orders: OrdersService;
+  readonly billing: BillingService;
+  // …
+};
+```
+
+Construct it in your app and pass it to `MicroverseLua.create({ host, surface })`.
+
+### 2. Define the surface
+
+Declare bridges (Lua → host), Zod payloads, capabilities, and optional component hooks (host → Lua):
+
+```ts
+// examples/business-scripting-engine/src/businessSurface.ts
+import { defineHostSurfaceFor } from '@microverse.ts/microverse-lua';
+import { businessComponentHooks } from './schemas/components/businessComponentHooks';
+
+export default defineHostSurfaceFor<BusinessEngineHost>()
+  .bridge('orders')
+  .method('get', {
+    requires: 'orders:read',
+    input: z.object({ orderId }),
+    output: orderDto.optional(),
+    handler: ({ host }, { orderId }) => host.orders.get(orderId),
+  })
+  // … more bridges …
+  .componentHooks(businessComponentHooks)
+  .build();
+```
+
+- **`requires`** — Capability id enforced at runtime for this method.
+- **`handler`** — Runs in TypeScript with `{ host, script }` context.
+- **`componentHooks`** — Map of event kind → Zod object; generates `onOrderPlaced`, `MicroverseEvt_OrderPlaced`, etc. in `.d.lua`.
+
+Default-export the built surface for `microverse generate-lua-defs --surface …`.
+
+### 3. Wrap the engine (optional)
+
+A thin façade keeps app code free of microverse details:
+
+```ts
+// examples/business-scripting-engine/src/BusinessScriptingEngine.ts
+this.microverse = MicroverseLua.create({ host, surface, defaultTimeoutMs: 30_000 });
+
+await this.microverse.mountScriptInstance({
+  instanceId: 'promo-1',
+  scriptId: 'promotions',
+  capabilities: surface.pickCapabilities('orders:read', 'audit:record'),
+  props: { label: 'summer-sale' },
+});
+
+await this.microverse.emitToAllInstances('OrderPlaced', { orderId, amountCents, customerId });
+```
+
+Map your domain events to `emitToAllInstances` (see `dispatch` in the example).
+
+### 4. Load Lua sources
+
+Keep scripts in `.lua` files and register by `scriptId`:
+
+```ts
+import { readComponentLua } from './services/components/loadComponentScript';
+
+engine.registerScriptDefinition('order_echo', readComponentLua('components/order_echo.lua'));
+```
+
+Or inline strings for tests. Use **`sharedLuaChunks`** on `create` for libraries shared by every instance (e.g. `lua/lib/math_helpers.lua`), and **`injectLuaChunks`** per definition or mount for one-off preludes.
+
+### 5. Mount instances
 
-## IDE stubs
+Each instance needs a **capability allowlist** — only declared methods on allowed bridges are callable from Lua:
+
+```ts
+await engine.mountScriptInstance({
+  scriptId: 'billing_denied',
+  capabilities: surface.pickCapabilities('billing:charge', 'audit:record'),
+  props: { maxCents: 1000 },
+});
+```
+
+Optional **`audit`** metadata is passed to script audit callbacks for observability.
+
+### 6. Dispatch events and shut down
+
+```ts
+await engine.emitHook('OrderPlaced', payload);
+// or engine.dispatch(domainEvent)
+
+await engine.dispose();
+```
+
+## Lua authoring
+
+### Component pattern
+
+Scripts use the injected **`component`** helper and implement hooks on the returned table:
+
+```lua
+-- examples/business-scripting-engine/lua/components/order_echo.lua
+local C = component:extend()
+
+function C:onOrderPlaced(evt)
+  self.bridges.notifications:send({
+    channel = "echo",
+    message = "order:" .. evt.orderId,
+  })
+end
+```
+
+- **`component:extend()`** — Builds the instance with `properties`, `state`, and `bridges` for this slot.
+- **Domain events** — Implement `onOrderPlaced`, `onInventoryLow`, … matching `.componentHooks()` on the surface.
+- **Lifecycle** — `init`, `onDestroy`, `onPropsChanged` (see `props_demo.lua`).
+
+### Bridges (scoped, not global)
+
+Call host APIs through **`self.bridges.<bridgeName>:<method>(payload)`**:
+
+```lua
+local order = self.bridges.orders:get({ orderId = evt.orderId })
+self.bridges.audit:record({ line = "seen:" .. evt.orderId })
+```
+
+Bridge names match `.bridge('orders')` in TypeScript (camelCase field on `MicroverseBridges` in `.d.lua`).
+
+### Props and state
+
+```lua
+-- examples/business-scripting-engine/lua/components/props_demo.lua
+function C:init()
+  self.state = { hits = 0 }
+end
+
+function C:onPropsChanged(key, newValue)
+  self.state.lastKey = key
+end
+
+function C:onOrderPlaced(evt)
+  local label = self.properties.label or "?"
+  self.state.hits = (self.state.hits or 0) + 1
+end
+```
+
+Host patches props via `setInstanceProps` / `patchInstanceProps` on the microverse.
+
+### Shared Lua libraries
+
+| Mechanism | Scope |
+|-----------|--------|
+| `sharedLuaChunks` on `MicroverseLua.create` | Every instance, every mount |
+| `injectLuaChunks` on `registerScriptDefinition` | All mounts of that `scriptId` |
+| `injectLuaChunks` on `mountScriptInstance` | Single instance |
+
+Run order: shared → definition → mount preludes → main script chunk.
+
+### Async bridges
+
+Mark a handler `async` in TypeScript; Lua may use a completion callback or `:await()` on the returned handle:
+
+```lua
+-- examples/business-scripting-engine/lua/components/order_asyncio_tick.lua
+self.bridges.asyncio:tick({ delayMs = 5, seed = evt.amountCents }, function(r)
+  self.bridges.audit:record({ line = "asyncio-value:" .. tostring(r.value) })
+end)
+```
+
+Generated stubs document `AsyncioTickHandle` and `AsyncioTickResult` for LuaLS.
+
+## IDE typing (LuaCATS)
+
+Generate stubs from the same surface module that drives runtime:
 
 ```bash
 pnpm add -D @microverse.ts/cli
-pnpm exec microverse generate-lua-defs --surface src/mySurface.ts
+pnpm exec microverse generate-lua-defs --surface src/businessSurface.ts
 ```
 
-Requires `export default` on the surface module (typically the result of `.build()`). Details: [`@microverse.ts/cli`](../cli/README.md).
+The manifest emits **type-only** bridge classes (`---@class Orders` + `---@field get fun(…)`) so LuaLS does not treat `Orders` as a runtime global. Use:
 
-## Reference example
+- `self.bridges.orders` — field name (camelCase) on `MicroverseBridges`
+- Types like `Orders`, `OrderDto` — PascalCase classes in the stub file
+
+Point LuaLS at the generated folder:
+
+```json
+{
+  "workspace.library": ["./generated"],
+  "diagnostics.globals": ["component"]
+}
+```
+
+See [`examples/business-scripting-engine/.luarc.json`](../../examples/business-scripting-engine/.luarc.json) and [`generated/businessSurface.d.lua`](../../examples/business-scripting-engine/generated/businessSurface.d.lua).
+
+Details: [`@microverse.ts/cli`](../cli/README.md), [`@microverse.ts/lua-defs`](../lua-defs/README.md).
+
+## Security model
 
-[`examples/business-scripting-engine`](../../examples/business-scripting-engine) — rules engine with orders, billing, workflow Lua, and `BusinessScriptingEngine` wrapping this package.
+| Layer | Behavior |
+|-------|----------|
+| **Capabilities** | Each bridge method declares `requires`. Calls from Lua are denied unless the instance’s allowlist includes that capability. |
+| **Per-instance allowlist** | `mountScriptInstance({ capabilities: surface.pickCapabilities(…) })` — principle of least privilege per script. |
+| **Host isolation** | The TypeScript `host` object is not injected into Lua; only bridge tables built from the surface are visible (via `self.bridges`). |
+| **Timeouts** | `defaultTimeoutMs` or `defaultTimeout` on `create`; Wasm instruction budget in `@microverse.ts/runtime-wasm`. |
+| **Validation** | Zod validates bridge inputs and outputs at the TS boundary (`@microverse.ts/runtime-zod`). |
 
-## Related
+## Related packages
 
-- Async bridges: [`host-surface/docs/async-subroutines-components.md`](../host-surface/docs/async-subroutines-components.md)
-- Component-style Lua: [`examples/.../COMPONENT_PATTERN.md`](../../examples/business-scripting-engine/docs/COMPONENT_PATTERN.md)
+| Package | Use when |
+|---------|----------|
+| [`@microverse.ts/host-surface`](../host-surface/README.md) | Surface builder details, `HostScriptSession`, custom slot wiring. |
+| [`@microverse.ts/lua-defs`](../lua-defs/README.md) | Manifest → LuaCATS document (library use). |
+| [`@microverse.ts/cli`](../cli/README.md) | `microverse generate-lua-defs` in CI or locally. |
+| `runtime-wasm`, `runtime-bridge`, `runtime-capabilities` | Advanced runtime customization (usually via host-surface). |
+
+## Reference example
+
+[`examples/business-scripting-engine`](../../examples/business-scripting-engine) — orders, billing, notifications, audit, inventory, jobs, component Lua, and `BusinessScriptingEngine` wrapping this package.
+
+```bash
+pnpm --filter @microverse.ts/business-scripting-engine test
+```

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * Plug-and-play Lua scripting: **{@link MicroverseLua.create}** (built-in Wasm VM) and the fluent
  * **{@link defineHostSurfaceFor}** builder (`bridge` → `method` → `build`).
  */
-export { augmentHostWithCapabilityRegistry, BridgeBuilder, buildBridgeMergeEnvForHost, collectCapabilitiesFromHostSurfaceSpec, compileHostSurface, compileHostSurfaceFor, createBridgeDeclarationsFromHostSurfaceSpec, defineHostSurface, defineHostSurfaceFor, HostScriptSession, luaGlobalHookName, luaType, MICROVERSE_CAPABILITY_REGISTRY, pickSurfaceCapabilities, SurfaceBuilder, zodToLuaTypeRef, type AnyHostSurfaceMethod, type HostFnContext, type HostScriptSessionOptions, type HostSurface, type HostSurfaceCore, type HostSurfaceMethodEntry, type HostSurfaceSpec, type HostSurfaceSpecForHost, type HostWorkflowHooksSpec, type InferSurfaceCapabilities, type LuaDefManifestGeneratorOpts, type LuaGlobalHookName, type SchemaValidationPort, type SurfaceCapabilityString, type SurfaceMethodDef, type WithMicroverseCapabilityRegistry, type WorkflowHookInvokeArgs, type ZodToLuaTypeRefOptions, } from '@microverse.ts/host-surface';
+export { augmentHostWithCapabilityRegistry, BridgeBuilder, buildBridgeMergeEnvForHost, collectCapabilitiesFromHostSurfaceSpec, compileHostSurface, compileHostSurfaceFor, createBridgeDeclarationsFromHostSurfaceSpec, defineHostSurface, defineHostSurfaceFor, HostScriptSession, luaGlobalHookName, luaType, MICROVERSE_CAPABILITY_REGISTRY, pickSurfaceCapabilities, SurfaceBuilder, zodToLuaTypeRef, type AnyHostSurfaceMethod, type HostFnContext, type HostScriptSessionOptions, type HostSurface, type HostSurfaceCore, type HostSurfaceMethodEntry, type HostSurfaceSpec, type HostSurfaceSpecForHost, type HostComponentHooksSpec, type InferSurfaceCapabilities, type LuaDefManifestGeneratorOpts, type LuaGlobalHookName, type SchemaValidationPort, type SurfaceCapabilityString, type SurfaceMethodDef, type WithMicroverseCapabilityRegistry, type ComponentEventHookInvokeArgs, type ZodToLuaTypeRefOptions, } from '@microverse.ts/host-surface';
 export * from '@microverse.ts/shared';
 export * from '@microverse.ts/runtime-core';
 export * from '@microverse.ts/runtime-lua';
@@ -12,6 +12,6 @@ export * from '@microverse.ts/runtime-wasm';
 export * from '@microverse.ts/runtime-bridge';
 export * from '@microverse.ts/runtime-capabilities';
 export * from '@microverse.ts/runtime-zod';
-export { MicroverseLua } from './infrastructure/facade/microverseLuaNamespace.js';
-export { createLuaMicroverse, LuaMicroverse, type LuaMicroverseConfig, type InferScriptHooksFromHost, type InferScriptHooksFromSurface, type InferSurfaceCapabilitiesFromSurface, type TaggedLuaMicroverseHost, } from './infrastructure/facade/luaMicroverse.js';
+export { MicroverseLua } from './infrastructure/facade/microverseLuaNamespace';
+export { createLuaMicroverse, LuaMicroverse, type LuaMicroverseConfig, type InferScriptHooksFromHost, type InferScriptHooksFromSurface, type InferSurfaceCapabilitiesFromSurface, type TaggedLuaMicroverseHost, } from './infrastructure/facade/luaMicroverse';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,iCAAiC,EACjC,aAAa,EACb,0BAA0B,EAC1B,sCAAsC,EACtC,kBAAkB,EAClB,qBAAqB,EACrB,2CAA2C,EAC3C,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,OAAO,EACP,8BAA8B,EAC9B,uBAAuB,EACvB,cAAc,EACd,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAC7B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,KAAK,gCAAgC,EACrC,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,GAC5B,MAAM,6BAA6B,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,4BAA4B,CAAC;AAE3C,OAAO,EAAE,aAAa,EAAE,MAAM,mDAAmD,CAAC;AAClF,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,mCAAmC,EACxC,KAAK,uBAAuB,GAC7B,MAAM,0CAA0C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,iCAAiC,EACjC,aAAa,EACb,0BAA0B,EAC1B,sCAAsC,EACtC,kBAAkB,EAClB,qBAAqB,EACrB,2CAA2C,EAC3C,iBAAiB,EACjB,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,OAAO,EACP,8BAA8B,EAC9B,uBAAuB,EACvB,cAAc,EACd,eAAe,EACf,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,wBAAwB,EAC7B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,KAAK,gCAAgC,EACrC,KAAK,4BAA4B,EACjC,KAAK,sBAAsB,GAC5B,MAAM,6BAA6B,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,4BAA4B,CAAC;AAC3C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,qCAAqC,CAAC;AACpD,cAAc,4BAA4B,CAAC;AAE3C,OAAO,EAAE,aAAa,EAAE,MAAM,gDAAgD,CAAC;AAC/E,OAAO,EACL,mBAAmB,EACnB,aAAa,EACb,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC7B,KAAK,2BAA2B,EAChC,KAAK,mCAAmC,EACxC,KAAK,uBAAuB,GAC7B,MAAM,uCAAuC,CAAC"}

package/dist/index.js

@@ -1,5 +1,5 @@
 import { BridgeBuilder, HostScriptSession, HostScriptSession as HostScriptSession$1, MICROVERSE_CAPABILITY_REGISTRY, SurfaceBuilder, augmentHostWithCapabilityRegistry, buildBridgeMergeEnvForHost, collectCapabilitiesFromHostSurfaceSpec, compileHostSurface, compileHostSurfaceFor, createBridgeDeclarationsFromHostSurfaceSpec, defineHostSurface, defineHostSurfaceFor, luaGlobalHookName, luaGlobalHookName as luaGlobalHookName$1, luaType, pickSurfaceCapabilities, zodToLuaTypeRef } from "@microverse.ts/host-surface";
-import { createLuaEnvSlotKey, fixedTimeout } from "@microverse.ts/runtime-core";
+import { createLuaEnvSlotKey, createScriptInstanceContext, fixedTimeout, mergeScriptPropertyBags, resolveLuaScriptSource } from "@microverse.ts/runtime-core";
 import { createWasmMicroverseRuntime } from "@microverse.ts/runtime-wasm";
 export * from "@microverse.ts/shared";
 export * from "@microverse.ts/runtime-core";
@@ -13,87 +13,151 @@ function resolveDefaultTimeout(config) {
 	if (config.defaultTimeout !== void 0) return config.defaultTimeout;
 	if (config.defaultTimeoutMs !== void 0) return fixedTimeout(config.defaultTimeoutMs);
 }
-/**
-* One **Lua microverse**: a shared built-in Wasm Lua VM, {@link HostScriptSession}s keyed by `scriptId`, and helpers to
-* register scripts and broadcast hook events. Capabilities per script come from the host surface
-* ({@link HostSurfaceCore.pickCapabilities} / {@link HostSurfaceCore.capabilities}). Created via {@link MicroverseLua.create}
-* or {@link createLuaMicroverse}.
-*/
 var LuaMicroverse = class {
 	config;
 	runtime;
-	sessions = /* @__PURE__ */ new Map();
+	definitions = /* @__PURE__ */ new Map();
+	instances = /* @__PURE__ */ new Map();
 	host;
 	surface;
 	envSlotScope;
 	defaultTimeout;
 	sharedLuaChunks;
+	onScriptAudit;
 	constructor(config) {
 		this.config = config;
 		this.host = config.host;
 		this.surface = config.surface;
 		this.defaultTimeout = resolveDefaultTimeout(config);
 		this.sharedLuaChunks = config.sharedLuaChunks ?? [];
+		this.onScriptAudit = config.onScriptAudit;
 		this.runtime = createWasmMicroverseRuntime(this.defaultTimeout !== void 0 ? { defaultTimeout: this.defaultTimeout } : {});
 		this.envSlotScope = config.envSlotScope ?? "script";
 	}
-	/** Capability ids declared on the bound host surface. */
 	getSurfaceCapabilities = () => this.surface.capabilities;
-	/**
-	* Loads one Lua chunk in an isolated env slot; `scriptId` must be unique within this microverse.
-	*
-	* @param args.capabilities - Subset of {@link getSurfaceCapabilities}; use `surface.pickCapabilities(…)` at the call site.
-	*/
-	registerScript = async (args) => {
-		const { scriptId, script, capabilities, injectLuaChunks } = args;
-		const preludeChunks = [...this.sharedLuaChunks, ...injectLuaChunks ?? []];
-		if (this.sessions.has(scriptId)) throw new Error(`script already registered: ${scriptId}`);
+	registerScriptDefinition = (def) => {
+		if (this.definitions.has(def.scriptId)) throw new Error(`script definition already registered: ${def.scriptId}`);
+		this.definitions.set(def.scriptId, def);
+	};
+	hasScriptDefinition = (scriptId) => this.definitions.has(scriptId);
+	getScriptDefinition = (scriptId) => this.definitions.get(scriptId);
+	mountScriptInstance = async (args) => {
+		const { instanceId, scriptId, capabilities, audit, injectLuaChunks } = args;
+		if (this.instances.has(instanceId)) throw new Error(`script instance already mounted: ${instanceId}`);
+		let def = this.definitions.get(scriptId);
+		if (def === void 0) {
+			if (args.script === void 0) throw new Error(`unknown scriptId "${scriptId}" and no inline script provided`);
+			def = {
+				scriptId,
+				source: args.script
+			};
+			this.definitions.set(scriptId, def);
+		} else if (args.script !== void 0) def = {
+			...def,
+			source: args.script
+		};
+		const slotKey = createLuaEnvSlotKey(`${this.envSlotScope}:${instanceId}`);
+		const scriptContext = createScriptInstanceContext({
+			instanceId,
+			scriptId,
+			slotKey: String(slotKey),
+			audit
+		});
 		const session = new HostScriptSession$1({
 			runtime: this.runtime,
 			surface: this.surface,
 			host: this.host,
-			slotKey: createLuaEnvSlotKey(`${this.envSlotScope}:${scriptId}`),
+			slotKey,
 			allowedCapabilities: capabilities,
-			defaultTimeout: this.defaultTimeout
+			defaultTimeout: this.defaultTimeout,
+			script: scriptContext,
+			propsSchema: def.propsSchema,
+			onScriptAudit: this.onScriptAudit
 		});
-		await session.openSession();
-		for (const [index, chunk] of preludeChunks.entries()) {
-			const injected = await session.runChunk(chunk);
-			if (injected._tag !== "ok") {
-				await session.dispose();
-				const detail = injected._tag === "err" && injected.error._tag === "AdapterError" ? injected.error.message : JSON.stringify(injected.error);
-				const which = index < this.sharedLuaChunks.length ? `shared Lua prelude [${index}]` : `script injectLuaChunks [${index - this.sharedLuaChunks.length}]`;
-				throw new Error(`script "${scriptId}" failed injecting ${which}: ${detail}`);
+		try {
+			await session.openSession();
+			const preludeChunks = [
+				...this.sharedLuaChunks,
+				...def.injectLuaChunks ?? [],
+				...injectLuaChunks ?? []
+			];
+			for (const [index, chunk] of preludeChunks.entries()) {
+				const injected = await session.runChunk(chunk);
+				if (injected._tag !== "ok") throw new Error(formatRunError(instanceId, `prelude [${index}]`, injected));
 			}
-		}
-		const loaded = await session.runChunk(script);
-		if (loaded._tag !== "ok") {
+			const source = await resolveLuaScriptSource(def.source);
+			const loaded = await session.runChunk(source);
+			if (loaded._tag !== "ok") throw new Error(formatRunError(instanceId, "main chunk", loaded));
+			const mergedProps = mergeScriptPropertyBags(def.defaultProps ?? {}, args.props ?? {});
+			await session.setProps(mergedProps);
+			const initResult = await session.invokeComponentHook("init");
+			if (initResult._tag !== "ok") throw new Error(formatRunError(instanceId, "init hook", initResult));
+			this.instances.set(instanceId, { session });
+			this.onScriptAudit?.({
+				kind: "mounted",
+				context: scriptContext
+			});
+		} catch (e) {
 			await session.dispose();
-			const detail = loaded._tag === "err" && loaded.error._tag === "AdapterError" ? loaded.error.message : JSON.stringify(loaded.error);
-			throw new Error(`script "${scriptId}" failed to load: ${detail}`);
+			const message = e instanceof Error ? e.message : String(e);
+			this.onScriptAudit?.({
+				kind: "scriptError",
+				context: scriptContext,
+				phase: "mount",
+				message
+			});
+			throw e;
 		}
-		this.sessions.set(scriptId, session);
 	};
-	/** Invokes `on{Kind}` on every registered script with the same payload table (Lua literals only). */
-	emitToAllScripts = (async (kind, payload) => {
+	unmountScriptInstance = async (instanceId) => {
+		const mounted = this.instances.get(instanceId);
+		if (mounted === void 0) throw new Error(`script instance not mounted: ${instanceId}`);
+		const ctx = mounted.session.context;
+		await mounted.session.dispose();
+		this.instances.delete(instanceId);
+		this.onScriptAudit?.({
+			kind: "unmounted",
+			context: ctx
+		});
+	};
+	setInstanceProps = async (instanceId, bag) => {
+		await this.requireInstance(instanceId).setProps(bag);
+	};
+	patchInstanceProps = async (instanceId, partial) => {
+		await this.requireInstance(instanceId).patchProps(partial);
+	};
+	getInstanceProps = (instanceId) => {
+		return this.requireInstance(instanceId).getProps();
+	};
+	flushInstanceProps = async (instanceId) => {
+		return this.requireInstance(instanceId).flushDirtyProps();
+	};
+	getInstance = (instanceId) => {
+		return this.instances.get(instanceId)?.session;
+	};
+	emitToAllInstances = (async (kind, payload) => {
 		const hook = luaGlobalHookName$1(kind);
-		for (const [id, session] of this.sessions) {
-			const r = await session.invokeGlobalHookIfPresent(hook, payload);
+		for (const [id, { session }] of this.instances) {
+			const r = await session.invokeComponentEventHook(hook, payload);
 			if (r._tag !== "ok") {
 				const detail = r._tag === "err" && r.error._tag === "AdapterError" ? r.error.message : JSON.stringify(r.error);
-				throw new Error(`script "${id}" failed on emit: ${detail}`);
+				throw new Error(`instance "${id}" failed on emit: ${detail}`);
 			}
 		}
 	});
 	dispose = async () => {
-		for (const s of this.sessions.values()) await s.dispose();
-		this.sessions.clear();
+		for (const id of [...this.instances.keys()]) await this.unmountScriptInstance(id);
+		this.instances.clear();
 	};
+	requireInstance(instanceId) {
+		const mounted = this.instances.get(instanceId);
+		if (mounted === void 0) throw new Error(`script instance not mounted: ${instanceId}`);
+		return mounted.session;
+	}
 };
-/**
-* Creates a {@link LuaMicroverse} with a **built-in** Wasm Lua VM (Wasmoon). Type `host` with
-* {@link TaggedLuaMicroverseHost} so hook emits narrow correctly.
-*/
+function formatRunError(instanceId, phase, result) {
+	return `instance "${instanceId}" failed ${phase}: ${result._tag === "err" && result.error?._tag === "AdapterError" ? result.error.message : JSON.stringify(result.error)}`;
+}
 function createLuaMicroverse(config) {
 	return new LuaMicroverse({
 		host: config.host,
@@ -101,7 +165,8 @@ function createLuaMicroverse(config) {
 		envSlotScope: config.envSlotScope,
 		defaultTimeout: config.defaultTimeout,
 		defaultTimeoutMs: config.defaultTimeoutMs,
-		sharedLuaChunks: config.sharedLuaChunks
+		sharedLuaChunks: config.sharedLuaChunks,
+		onScriptAudit: config.onScriptAudit
 	});
 }
 //#endregion
@@ -119,7 +184,8 @@ function createLuaMicroverse(config) {
 *   surface: mySurface,
 *   defaultTimeoutMs: 30_000,
 * });
-* await microverse.registerScript({ scriptId: 'ai', script: lua, capabilities: surface.pickCapabilities('demo:tick') });
+* microverse.registerScriptDefinition({ scriptId: 'ai', source: lua });
+* await microverse.mountScriptInstance({ instanceId: 'ai', scriptId: 'ai', capabilities: surface.pickCapabilities('demo:tick') });
 * ```
 */
 var MicroverseLua = { 

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/infrastructure/facade/luaMicroverse.ts","../src/infrastructure/facade/microverseLuaNamespace.ts"],"sourcesContent":["import type { z } from 'zod';\n\nimport {\n  HostScriptSession,\n  luaGlobalHookName,\n  type HostSurface,\n  type HostSurfaceCore,\n  type HostWorkflowHooksSpec,\n} from '@microverse.ts/host-surface';\nimport type { CapabilityId } from '@microverse.ts/runtime-capabilities';\nimport {\n  createLuaEnvSlotKey,\n  fixedTimeout,\n  type MicroverseRuntime,\n  type TimeoutPolicy,\n} from '@microverse.ts/runtime-core';\nimport { createWasmMicroverseRuntime } from '@microverse.ts/runtime-wasm';\n\n/** Phantom key: optional on the host **type** so {@link InferScriptHooksFromHost} can recover hook Zod map typing. Never set at runtime. */\ndeclare const SCRIPT_HOOKS_TYPE: unique symbol;\n\n/**\n * Intersects `TBase` with an optional phantom field carrying `THooks` for {@link LuaMicroverse} / {@link createLuaMicroverse} inference.\n */\nexport type TaggedLuaMicroverseHost<\n  THooks extends HostWorkflowHooksSpec,\n  TBase = unknown,\n> = TBase & { readonly [SCRIPT_HOOKS_TYPE]?: THooks };\n\nexport type InferScriptHooksFromHost<THost> = THost extends TaggedLuaMicroverseHost<infer H, unknown>\n  ? H extends HostWorkflowHooksSpec\n    ? H\n    : undefined\n  : undefined;\n\nexport type InferScriptHooksFromSurface<S extends HostSurfaceCore> =\n  S extends HostSurfaceCore<CapabilityId> & { readonly workflowHooks: infer H extends HostWorkflowHooksSpec }\n    ? H\n    : S extends HostSurface<infer H extends HostWorkflowHooksSpec, CapabilityId>\n      ? H\n      : undefined;\n\nexport type InferSurfaceCapabilitiesFromSurface<S extends HostSurfaceCore> = S extends HostSurfaceCore<\n  infer C extends CapabilityId\n>\n  ? C\n  : CapabilityId;\n\ntype EffectiveScriptHooks<THost extends object, TSurface extends HostSurfaceCore> = [InferScriptHooksFromHost<THost>] extends [\n  undefined,\n]\n  ? InferScriptHooksFromSurface<TSurface>\n  : InferScriptHooksFromHost<THost>;\n\nexport type LuaMicroverseConfig<\n  THost extends object = object,\n  THooks extends HostWorkflowHooksSpec | undefined = InferScriptHooksFromHost<THost>,\n  TCapabilities extends CapabilityId = CapabilityId,\n> = {\n  readonly host: THost;\n  /** From {@link defineHostSurface} / {@link defineHostSurfaceFor}; hooks live on `surface.workflowHooks` when present. */\n  readonly surface: HostSurface<THooks, TCapabilities>;\n  /** Prefix for internal Lua env slot ids, default `script` (ids look like `script:my-id`). */\n  readonly envSlotScope?: string | undefined;\n  /** Wall-clock limit per `runChunk` / hook invocation (Wasm adapter + session forwarding). */\n  readonly defaultTimeout?: TimeoutPolicy | undefined;\n  /**\n   * Shorthand for {@link defaultTimeout} as `fixedTimeout(ms)`. Ignored when `defaultTimeout` is set.\n   */\n  readonly defaultTimeoutMs?: number | undefined;\n  /**\n   * Lua sources run in **every** script slot after {@link HostScriptSession.openSession} and before that\n   * script's main chunk. Define shared helpers/libraries here once instead of per {@link registerScript}.\n   */\n  readonly sharedLuaChunks?: readonly string[] | undefined;\n};\n\nfunction resolveDefaultTimeout<\n  THost extends object,\n  THooks extends HostWorkflowHooksSpec | undefined,\n  TCapabilities extends CapabilityId,\n>(config: LuaMicroverseConfig<THost, THooks, TCapabilities>): TimeoutPolicy | undefined {\n  if (config.defaultTimeout !== undefined) {\n    return config.defaultTimeout;\n  }\n  if (config.defaultTimeoutMs !== undefined) {\n    return fixedTimeout(config.defaultTimeoutMs);\n  }\n  return undefined;\n}\n\ntype EmitToAllScriptsFn<THooks extends HostWorkflowHooksSpec | undefined> = THooks extends HostWorkflowHooksSpec\n  ? <const K extends keyof THooks & string>(kind: K, payload: Readonly<z.infer<THooks[K]>>) => Promise<void>\n  : (\n      kind: string,\n      payload: Readonly<Record<string, string | number | boolean>>,\n    ) => Promise<void>;\n\n/**\n * One **Lua microverse**: a shared built-in Wasm Lua VM, {@link HostScriptSession}s keyed by `scriptId`, and helpers to\n * register scripts and broadcast hook events. Capabilities per script come from the host surface\n * ({@link HostSurfaceCore.pickCapabilities} / {@link HostSurfaceCore.capabilities}). Created via {@link MicroverseLua.create}\n * or {@link createLuaMicroverse}.\n */\nexport class LuaMicroverse<\n  THost extends object = object,\n  THooks extends HostWorkflowHooksSpec | undefined = InferScriptHooksFromHost<THost>,\n  TCapabilities extends CapabilityId = CapabilityId,\n> {\n  private readonly runtime: MicroverseRuntime;\n\n  private readonly sessions = new Map<string, HostScriptSession<THost, THooks>>();\n\n  private readonly host: THost;\n\n  private readonly surface: HostSurface<THooks, TCapabilities>;\n\n  private readonly envSlotScope: string;\n\n  private readonly defaultTimeout: TimeoutPolicy | undefined;\n\n  private readonly sharedLuaChunks: readonly string[];\n\n  constructor(private readonly config: LuaMicroverseConfig<THost, THooks, TCapabilities>) {\n    this.host = config.host;\n    this.surface = config.surface;\n    this.defaultTimeout = resolveDefaultTimeout(config);\n    this.sharedLuaChunks = config.sharedLuaChunks ?? [];\n    this.runtime = createWasmMicroverseRuntime(\n      this.defaultTimeout !== undefined ? { defaultTimeout: this.defaultTimeout } : {},\n    );\n    this.envSlotScope = config.envSlotScope ?? 'script';\n  }\n\n  /** Capability ids declared on the bound host surface. */\n  readonly getSurfaceCapabilities = (): readonly TCapabilities[] => this.surface.capabilities;\n\n  /**\n   * Loads one Lua chunk in an isolated env slot; `scriptId` must be unique within this microverse.\n   *\n   * @param args.capabilities - Subset of {@link getSurfaceCapabilities}; use `surface.pickCapabilities(…)` at the call site.\n   */\n  readonly registerScript = async (args: {\n    readonly scriptId: string;\n    readonly script: string;\n    readonly capabilities: readonly TCapabilities[];\n    readonly injectLuaChunks?: readonly string[] | undefined;\n  }): Promise<void> => {\n    const { scriptId, script, capabilities, injectLuaChunks } = args;\n    const preludeChunks = [...this.sharedLuaChunks, ...(injectLuaChunks ?? [])];\n    if (this.sessions.has(scriptId)) {\n      throw new Error(`script already registered: ${scriptId}`);\n    }\n    const session = new HostScriptSession<THost, THooks>({\n      runtime: this.runtime,\n      surface: this.surface,\n      host: this.host,\n      slotKey: createLuaEnvSlotKey(`${this.envSlotScope}:${scriptId}`),\n      allowedCapabilities: capabilities,\n      defaultTimeout: this.defaultTimeout,\n    });\n    await session.openSession();\n    for (const [index, chunk] of preludeChunks.entries()) {\n      const injected = await session.runChunk(chunk);\n      if (injected._tag !== 'ok') {\n        await session.dispose();\n        const detail =\n          injected._tag === 'err' && injected.error._tag === 'AdapterError'\n            ? injected.error.message\n            : JSON.stringify(injected.error);\n        const which =\n          index < this.sharedLuaChunks.length\n            ? `shared Lua prelude [${index}]`\n            : `script injectLuaChunks [${index - this.sharedLuaChunks.length}]`;\n        throw new Error(`script \"${scriptId}\" failed injecting ${which}: ${detail}`);\n      }\n    }\n    const loaded = await session.runChunk(script);\n    if (loaded._tag !== 'ok') {\n      await session.dispose();\n      const detail =\n        loaded._tag === 'err' && loaded.error._tag === 'AdapterError'\n          ? loaded.error.message\n          : JSON.stringify(loaded.error);\n      throw new Error(`script \"${scriptId}\" failed to load: ${detail}`);\n    }\n    this.sessions.set(scriptId, session);\n  };\n\n  /** Invokes `on{Kind}` on every registered script with the same payload table (Lua literals only). */\n  readonly emitToAllScripts = (async (\n    kind: string,\n    payload: Readonly<Record<string, string | number | boolean>>,\n  ) => {\n    const hook = luaGlobalHookName(kind);\n    for (const [id, session] of this.sessions) {\n      const r = await session.invokeGlobalHookIfPresent(hook, payload);\n      if (r._tag !== 'ok') {\n        const detail =\n          r._tag === 'err' && r.error._tag === 'AdapterError' ? r.error.message : JSON.stringify(r.error);\n        throw new Error(`script \"${id}\" failed on emit: ${detail}`);\n      }\n    }\n  }) as EmitToAllScriptsFn<THooks>;\n\n  readonly dispose = async (): Promise<void> => {\n    for (const s of this.sessions.values()) {\n      await s.dispose();\n    }\n    this.sessions.clear();\n  };\n}\n\n/**\n * Creates a {@link LuaMicroverse} with a **built-in** Wasm Lua VM (Wasmoon). Type `host` with\n * {@link TaggedLuaMicroverseHost} so hook emits narrow correctly.\n */\nexport function createLuaMicroverse<\n  THost extends object,\n  const TSurface extends HostSurfaceCore<CapabilityId>,\n>(config: {\n  readonly host: THost;\n  readonly surface: TSurface;\n  readonly envSlotScope?: string | undefined;\n  readonly defaultTimeout?: TimeoutPolicy | undefined;\n  readonly defaultTimeoutMs?: number | undefined;\n  readonly sharedLuaChunks?: readonly string[] | undefined;\n}): LuaMicroverse<THost, EffectiveScriptHooks<THost, TSurface>, InferSurfaceCapabilitiesFromSurface<TSurface>> {\n  type H = EffectiveScriptHooks<THost, TSurface>;\n  type C = InferSurfaceCapabilitiesFromSurface<TSurface>;\n  return new LuaMicroverse<THost, H, C>({\n    host: config.host,\n    surface: config.surface as unknown as HostSurface<H, C>,\n    envSlotScope: config.envSlotScope,\n    defaultTimeout: config.defaultTimeout,\n    defaultTimeoutMs: config.defaultTimeoutMs,\n    sharedLuaChunks: config.sharedLuaChunks,\n  });\n}\n","import { createLuaMicroverse } from './luaMicroverse.js';\n\n/**\n * Plug-and-play **Lua microverse** entry point.\n *\n * A Wasmoon-backed VM is always created for you — pass only `host`, `surface`, and optional timeouts /\n * shared Lua preludes. Define bridges with {@link defineHostSurfaceFor} (`bridge` → `method` → `build`).\n *\n * @example\n * ```ts\n * const microverse = MicroverseLua.create({\n *   host: myHost,\n *   surface: mySurface,\n *   defaultTimeoutMs: 30_000,\n * });\n * await microverse.registerScript({ scriptId: 'ai', script: lua, capabilities: surface.pickCapabilities('demo:tick') });\n * ```\n */\nexport const MicroverseLua = {\n  /** Creates a {@link LuaMicroverse} with a built-in Wasm Lua runtime. */\n  create: createLuaMicroverse,\n} as const;\n"],"mappings":"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"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/infrastructure/facade/luaMicroverse.ts","../src/infrastructure/facade/microverseLuaNamespace.ts"],"sourcesContent":["import type { z } from 'zod';\n\nimport {\n  HostScriptSession,\n  luaGlobalHookName,\n  type HostSurface,\n  type HostSurfaceCore,\n  type HostComponentHooksSpec,\n} from '@microverse.ts/host-surface';\nimport type { CapabilityId } from '@microverse.ts/runtime-capabilities';\nimport {\n  createLuaEnvSlotKey,\n  createScriptInstanceContext,\n  fixedTimeout,\n  mergeScriptPropertyBags,\n  resolveLuaScriptSource,\n  type LuaScriptDefinition,\n  type MicroverseRuntime,\n  type ScriptAuditEvent,\n  type ScriptPropertyBag,\n  type TimeoutPolicy,\n} from '@microverse.ts/runtime-core';\nimport { createWasmMicroverseRuntime } from '@microverse.ts/runtime-wasm';\n\n/** Phantom key: optional on the host **type** so {@link InferScriptHooksFromHost} can recover hook Zod map typing. Never set at runtime. */\ndeclare const SCRIPT_HOOKS_TYPE: unique symbol;\n\nexport type TaggedLuaMicroverseHost<\n  THooks extends HostComponentHooksSpec,\n  TBase = unknown,\n> = TBase & { readonly [SCRIPT_HOOKS_TYPE]?: THooks };\n\nexport type InferScriptHooksFromHost<THost> = THost extends TaggedLuaMicroverseHost<infer H, unknown>\n  ? H extends HostComponentHooksSpec\n    ? H\n    : undefined\n  : undefined;\n\nexport type InferScriptHooksFromSurface<S extends HostSurfaceCore> =\n  S extends HostSurfaceCore<CapabilityId> & { readonly componentHooks: infer H extends HostComponentHooksSpec }\n    ? H\n    : S extends HostSurface<infer H extends HostComponentHooksSpec, CapabilityId>\n      ? H\n      : undefined;\n\nexport type InferSurfaceCapabilitiesFromSurface<S extends HostSurfaceCore> = S extends HostSurfaceCore<\n  infer C extends CapabilityId\n>\n  ? C\n  : CapabilityId;\n\ntype EffectiveScriptHooks<THost extends object, TSurface extends HostSurfaceCore> = [InferScriptHooksFromHost<THost>] extends [\n  undefined,\n]\n  ? InferScriptHooksFromSurface<TSurface>\n  : InferScriptHooksFromHost<THost>;\n\nexport type LuaMicroverseConfig<\n  THost extends object = object,\n  THooks extends HostComponentHooksSpec | undefined = InferScriptHooksFromHost<THost>,\n  TCapabilities extends CapabilityId = CapabilityId,\n> = {\n  readonly host: THost;\n  readonly surface: HostSurface<THooks, TCapabilities>;\n  readonly envSlotScope?: string | undefined;\n  readonly defaultTimeout?: TimeoutPolicy | undefined;\n  readonly defaultTimeoutMs?: number | undefined;\n  readonly sharedLuaChunks?: readonly string[] | undefined;\n  readonly onScriptAudit?: ((event: ScriptAuditEvent) => void) | undefined;\n};\n\nfunction resolveDefaultTimeout<\n  THost extends object,\n  THooks extends HostComponentHooksSpec | undefined,\n  TCapabilities extends CapabilityId,\n>(config: LuaMicroverseConfig<THost, THooks, TCapabilities>): TimeoutPolicy | undefined {\n  if (config.defaultTimeout !== undefined) {\n    return config.defaultTimeout;\n  }\n  if (config.defaultTimeoutMs !== undefined) {\n    return fixedTimeout(config.defaultTimeoutMs);\n  }\n  return undefined;\n}\n\ntype EmitToAllInstancesFn<THooks extends HostComponentHooksSpec | undefined> = THooks extends HostComponentHooksSpec\n  ? <const K extends keyof THooks & string>(kind: K, payload: Readonly<z.infer<THooks[K]>>) => Promise<void>\n  : (\n      kind: string,\n      payload: Readonly<Record<string, string | number | boolean>>,\n    ) => Promise<void>;\n\ntype MountedInstance = {\n  readonly session: HostScriptSession<unknown, HostComponentHooksSpec | undefined>;\n};\n\nexport class LuaMicroverse<\n  THost extends object = object,\n  THooks extends HostComponentHooksSpec | undefined = InferScriptHooksFromHost<THost>,\n  TCapabilities extends CapabilityId = CapabilityId,\n> {\n  private readonly runtime: MicroverseRuntime;\n\n  private readonly definitions = new Map<string, LuaScriptDefinition>();\n\n  private readonly instances = new Map<string, MountedInstance>();\n\n  private readonly host: THost;\n\n  private readonly surface: HostSurface<THooks, TCapabilities>;\n\n  private readonly envSlotScope: string;\n\n  private readonly defaultTimeout: TimeoutPolicy | undefined;\n\n  private readonly sharedLuaChunks: readonly string[];\n\n  private readonly onScriptAudit: ((event: ScriptAuditEvent) => void) | undefined;\n\n  constructor(private readonly config: LuaMicroverseConfig<THost, THooks, TCapabilities>) {\n    this.host = config.host;\n    this.surface = config.surface;\n    this.defaultTimeout = resolveDefaultTimeout(config);\n    this.sharedLuaChunks = config.sharedLuaChunks ?? [];\n    this.onScriptAudit = config.onScriptAudit;\n    this.runtime = createWasmMicroverseRuntime(\n      this.defaultTimeout !== undefined ? { defaultTimeout: this.defaultTimeout } : {},\n    );\n    this.envSlotScope = config.envSlotScope ?? 'script';\n  }\n\n  readonly getSurfaceCapabilities = (): readonly TCapabilities[] => this.surface.capabilities;\n\n  readonly registerScriptDefinition = (def: LuaScriptDefinition): void => {\n    if (this.definitions.has(def.scriptId)) {\n      throw new Error(`script definition already registered: ${def.scriptId}`);\n    }\n    this.definitions.set(def.scriptId, def);\n  };\n\n  readonly hasScriptDefinition = (scriptId: string): boolean => this.definitions.has(scriptId);\n\n  readonly getScriptDefinition = (scriptId: string): LuaScriptDefinition | undefined =>\n    this.definitions.get(scriptId);\n\n  readonly mountScriptInstance = async (args: {\n    readonly instanceId: string;\n    readonly scriptId: string;\n    readonly script?: string | undefined;\n    readonly props?: ScriptPropertyBag | undefined;\n    readonly capabilities: readonly TCapabilities[];\n    readonly audit?: Readonly<Record<string, string | number | boolean>> | undefined;\n    readonly injectLuaChunks?: readonly string[] | undefined;\n  }): Promise<void> => {\n    const { instanceId, scriptId, capabilities, audit, injectLuaChunks } = args;\n    if (this.instances.has(instanceId)) {\n      throw new Error(`script instance already mounted: ${instanceId}`);\n    }\n\n    let def = this.definitions.get(scriptId);\n    if (def === undefined) {\n      if (args.script === undefined) {\n        throw new Error(`unknown scriptId \"${scriptId}\" and no inline script provided`);\n      }\n      def = {\n        scriptId,\n        source: args.script,\n      };\n      this.definitions.set(scriptId, def);\n    } else if (args.script !== undefined) {\n      def = { ...def, source: args.script };\n    }\n\n    const slotKey = createLuaEnvSlotKey(`${this.envSlotScope}:${instanceId}`);\n    const scriptContext = createScriptInstanceContext({\n      instanceId,\n      scriptId,\n      slotKey: String(slotKey),\n      audit,\n    });\n\n    const session = new HostScriptSession<THost, THooks>({\n      runtime: this.runtime,\n      surface: this.surface,\n      host: this.host,\n      slotKey,\n      allowedCapabilities: capabilities,\n      defaultTimeout: this.defaultTimeout,\n      script: scriptContext,\n      propsSchema: def.propsSchema,\n      onScriptAudit: this.onScriptAudit,\n    });\n\n    try {\n      await session.openSession();\n      const preludeChunks = [\n        ...this.sharedLuaChunks,\n        ...(def.injectLuaChunks ?? []),\n        ...(injectLuaChunks ?? []),\n      ];\n      for (const [index, chunk] of preludeChunks.entries()) {\n        const injected = await session.runChunk(chunk);\n        if (injected._tag !== 'ok') {\n          throw new Error(formatRunError(instanceId, `prelude [${index}]`, injected));\n        }\n      }\n\n      const source = await resolveLuaScriptSource(def.source);\n      const loaded = await session.runChunk(source);\n      if (loaded._tag !== 'ok') {\n        throw new Error(formatRunError(instanceId, 'main chunk', loaded));\n      }\n\n      const mergedProps = mergeScriptPropertyBags(def.defaultProps ?? {}, args.props ?? {});\n      await session.setProps(mergedProps);\n      const initResult = await session.invokeComponentHook('init');\n      if (initResult._tag !== 'ok') {\n        throw new Error(formatRunError(instanceId, 'init hook', initResult));\n      }\n\n      this.instances.set(instanceId, { session });\n      this.onScriptAudit?.({ kind: 'mounted', context: scriptContext });\n    } catch (e) {\n      await session.dispose();\n      const message = e instanceof Error ? e.message : String(e);\n      this.onScriptAudit?.({\n        kind: 'scriptError',\n        context: scriptContext,\n        phase: 'mount',\n        message,\n      });\n      throw e;\n    }\n  };\n\n  readonly unmountScriptInstance = async (instanceId: string): Promise<void> => {\n    const mounted = this.instances.get(instanceId);\n    if (mounted === undefined) {\n      throw new Error(`script instance not mounted: ${instanceId}`);\n    }\n    const ctx = mounted.session.context;\n    await mounted.session.dispose();\n    this.instances.delete(instanceId);\n    this.onScriptAudit?.({ kind: 'unmounted', context: ctx });\n  };\n\n  readonly setInstanceProps = async (instanceId: string, bag: ScriptPropertyBag): Promise<void> => {\n    const session = this.requireInstance(instanceId);\n    await session.setProps(bag);\n  };\n\n  readonly patchInstanceProps = async (\n    instanceId: string,\n    partial: ScriptPropertyBag,\n  ): Promise<void> => {\n    const session = this.requireInstance(instanceId);\n    await session.patchProps(partial);\n  };\n\n  readonly getInstanceProps = (instanceId: string): Readonly<ScriptPropertyBag> => {\n    return this.requireInstance(instanceId).getProps();\n  };\n\n  readonly flushInstanceProps = async (instanceId: string): Promise<ScriptPropertyBag | null> => {\n    return this.requireInstance(instanceId).flushDirtyProps();\n  };\n\n  readonly getInstance = (instanceId: string): HostScriptSession<THost, THooks> | undefined => {\n    return this.instances.get(instanceId)?.session as HostScriptSession<THost, THooks> | undefined;\n  };\n\n  readonly emitToAllInstances = (async (\n    kind: string,\n    payload: Readonly<Record<string, string | number | boolean>>,\n  ) => {\n    const hook = luaGlobalHookName(kind);\n    for (const [id, { session }] of this.instances) {\n      const r = await session.invokeComponentEventHook(hook, payload);\n      if (r._tag !== 'ok') {\n        const detail =\n          r._tag === 'err' && r.error._tag === 'AdapterError' ? r.error.message : JSON.stringify(r.error);\n        throw new Error(`instance \"${id}\" failed on emit: ${detail}`);\n      }\n    }\n  }) as EmitToAllInstancesFn<THooks>;\n\n  readonly dispose = async (): Promise<void> => {\n    for (const id of [...this.instances.keys()]) {\n      await this.unmountScriptInstance(id);\n    }\n    this.instances.clear();\n  };\n\n  private requireInstance(instanceId: string): HostScriptSession<THost, THooks> {\n    const mounted = this.instances.get(instanceId);\n    if (mounted === undefined) {\n      throw new Error(`script instance not mounted: ${instanceId}`);\n    }\n    return mounted.session as HostScriptSession<THost, THooks>;\n  }\n}\n\nfunction formatRunError(\n  instanceId: string,\n  phase: string,\n  result: { _tag: string; error?: { _tag?: string; message?: string } },\n): string {\n  const detail =\n    result._tag === 'err' && result.error?._tag === 'AdapterError'\n      ? result.error.message\n      : JSON.stringify(result.error);\n  return `instance \"${instanceId}\" failed ${phase}: ${detail}`;\n}\n\nexport function createLuaMicroverse<\n  THost extends object,\n  const TSurface extends HostSurfaceCore<CapabilityId>,\n>(config: {\n  readonly host: THost;\n  readonly surface: TSurface;\n  readonly envSlotScope?: string | undefined;\n  readonly defaultTimeout?: TimeoutPolicy | undefined;\n  readonly defaultTimeoutMs?: number | undefined;\n  readonly sharedLuaChunks?: readonly string[] | undefined;\n  readonly onScriptAudit?: ((event: ScriptAuditEvent) => void) | undefined;\n}): LuaMicroverse<THost, EffectiveScriptHooks<THost, TSurface>, InferSurfaceCapabilitiesFromSurface<TSurface>> {\n  type H = EffectiveScriptHooks<THost, TSurface>;\n  type C = InferSurfaceCapabilitiesFromSurface<TSurface>;\n  return new LuaMicroverse<THost, H, C>({\n    host: config.host,\n    surface: config.surface as unknown as HostSurface<H, C>,\n    envSlotScope: config.envSlotScope,\n    defaultTimeout: config.defaultTimeout,\n    defaultTimeoutMs: config.defaultTimeoutMs,\n    sharedLuaChunks: config.sharedLuaChunks,\n    onScriptAudit: config.onScriptAudit,\n  });\n}\n","import { createLuaMicroverse } from './luaMicroverse';\n\n/**\n * Plug-and-play **Lua microverse** entry point.\n *\n * A Wasmoon-backed VM is always created for you — pass only `host`, `surface`, and optional timeouts /\n * shared Lua preludes. Define bridges with {@link defineHostSurfaceFor} (`bridge` → `method` → `build`).\n *\n * @example\n * ```ts\n * const microverse = MicroverseLua.create({\n *   host: myHost,\n *   surface: mySurface,\n *   defaultTimeoutMs: 30_000,\n * });\n * microverse.registerScriptDefinition({ scriptId: 'ai', source: lua });\n * await microverse.mountScriptInstance({ instanceId: 'ai', scriptId: 'ai', capabilities: surface.pickCapabilities('demo:tick') });\n * ```\n */\nexport const MicroverseLua = {\n  /** Creates a {@link LuaMicroverse} with a built-in Wasm Lua runtime. */\n  create: createLuaMicroverse,\n} as const;\n"],"mappings":"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"}

package/dist/infrastructure/facade/luaMicroverse.d.ts

@@ -1,79 +1,65 @@
 import { z } from 'zod';
-import { HostSurface, HostSurfaceCore, HostWorkflowHooksSpec } from '@microverse.ts/host-surface';
+import { HostScriptSession, HostSurface, HostSurfaceCore, HostComponentHooksSpec } from '@microverse.ts/host-surface';
 import { CapabilityId } from '@microverse.ts/runtime-capabilities';
-import { TimeoutPolicy } from '@microverse.ts/runtime-core';
+import { LuaScriptDefinition, ScriptAuditEvent, ScriptPropertyBag, TimeoutPolicy } from '@microverse.ts/runtime-core';
 /** Phantom key: optional on the host **type** so {@link InferScriptHooksFromHost} can recover hook Zod map typing. Never set at runtime. */
 declare const SCRIPT_HOOKS_TYPE: unique symbol;
-/**
- * Intersects `TBase` with an optional phantom field carrying `THooks` for {@link LuaMicroverse} / {@link createLuaMicroverse} inference.
- */
-export type TaggedLuaMicroverseHost<THooks extends HostWorkflowHooksSpec, TBase = unknown> = TBase & {
+export type TaggedLuaMicroverseHost<THooks extends HostComponentHooksSpec, TBase = unknown> = TBase & {
     readonly [SCRIPT_HOOKS_TYPE]?: THooks;
 };
-export type InferScriptHooksFromHost<THost> = THost extends TaggedLuaMicroverseHost<infer H, unknown> ? H extends HostWorkflowHooksSpec ? H : undefined : undefined;
+export type InferScriptHooksFromHost<THost> = THost extends TaggedLuaMicroverseHost<infer H, unknown> ? H extends HostComponentHooksSpec ? H : undefined : undefined;
 export type InferScriptHooksFromSurface<S extends HostSurfaceCore> = S extends HostSurfaceCore<CapabilityId> & {
-    readonly workflowHooks: infer H extends HostWorkflowHooksSpec;
-} ? H : S extends HostSurface<infer H extends HostWorkflowHooksSpec, CapabilityId> ? H : undefined;
+    readonly componentHooks: infer H extends HostComponentHooksSpec;
+} ? H : S extends HostSurface<infer H extends HostComponentHooksSpec, CapabilityId> ? H : undefined;
 export type InferSurfaceCapabilitiesFromSurface<S extends HostSurfaceCore> = S extends HostSurfaceCore<infer C extends CapabilityId> ? C : CapabilityId;
 type EffectiveScriptHooks<THost extends object, TSurface extends HostSurfaceCore> = [InferScriptHooksFromHost<THost>] extends [
     undefined
 ] ? InferScriptHooksFromSurface<TSurface> : InferScriptHooksFromHost<THost>;
-export type LuaMicroverseConfig<THost extends object = object, THooks extends HostWorkflowHooksSpec | undefined = InferScriptHooksFromHost<THost>, TCapabilities extends CapabilityId = CapabilityId> = {
+export type LuaMicroverseConfig<THost extends object = object, THooks extends HostComponentHooksSpec | undefined = InferScriptHooksFromHost<THost>, TCapabilities extends CapabilityId = CapabilityId> = {
     readonly host: THost;
-    /** From {@link defineHostSurface} / {@link defineHostSurfaceFor}; hooks live on `surface.workflowHooks` when present. */
     readonly surface: HostSurface<THooks, TCapabilities>;
-    /** Prefix for internal Lua env slot ids, default `script` (ids look like `script:my-id`). */
     readonly envSlotScope?: string | undefined;
-    /** Wall-clock limit per `runChunk` / hook invocation (Wasm adapter + session forwarding). */
     readonly defaultTimeout?: TimeoutPolicy | undefined;
-    /**
-     * Shorthand for {@link defaultTimeout} as `fixedTimeout(ms)`. Ignored when `defaultTimeout` is set.
-     */
     readonly defaultTimeoutMs?: number | undefined;
-    /**
-     * Lua sources run in **every** script slot after {@link HostScriptSession.openSession} and before that
-     * script's main chunk. Define shared helpers/libraries here once instead of per {@link registerScript}.
-     */
     readonly sharedLuaChunks?: readonly string[] | undefined;
+    readonly onScriptAudit?: ((event: ScriptAuditEvent) => void) | undefined;
 };
-type EmitToAllScriptsFn<THooks extends HostWorkflowHooksSpec | undefined> = THooks extends HostWorkflowHooksSpec ? <const K extends keyof THooks & string>(kind: K, payload: Readonly<z.infer<THooks[K]>>) => Promise<void> : (kind: string, payload: Readonly<Record<string, string | number | boolean>>) => Promise<void>;
-/**
- * One **Lua microverse**: a shared built-in Wasm Lua VM, {@link HostScriptSession}s keyed by `scriptId`, and helpers to
- * register scripts and broadcast hook events. Capabilities per script come from the host surface
- * ({@link HostSurfaceCore.pickCapabilities} / {@link HostSurfaceCore.capabilities}). Created via {@link MicroverseLua.create}
- * or {@link createLuaMicroverse}.
- */
-export declare class LuaMicroverse<THost extends object = object, THooks extends HostWorkflowHooksSpec | undefined = InferScriptHooksFromHost<THost>, TCapabilities extends CapabilityId = CapabilityId> {
+type EmitToAllInstancesFn<THooks extends HostComponentHooksSpec | undefined> = THooks extends HostComponentHooksSpec ? <const K extends keyof THooks & string>(kind: K, payload: Readonly<z.infer<THooks[K]>>) => Promise<void> : (kind: string, payload: Readonly<Record<string, string | number | boolean>>) => Promise<void>;
+export declare class LuaMicroverse<THost extends object = object, THooks extends HostComponentHooksSpec | undefined = InferScriptHooksFromHost<THost>, TCapabilities extends CapabilityId = CapabilityId> {
     private readonly config;
     private readonly runtime;
-    private readonly sessions;
+    private readonly definitions;
+    private readonly instances;
     private readonly host;
     private readonly surface;
     private readonly envSlotScope;
     private readonly defaultTimeout;
     private readonly sharedLuaChunks;
+    private readonly onScriptAudit;
     constructor(config: LuaMicroverseConfig<THost, THooks, TCapabilities>);
-    /** Capability ids declared on the bound host surface. */
     readonly getSurfaceCapabilities: () => readonly TCapabilities[];
-    /**
-     * Loads one Lua chunk in an isolated env slot; `scriptId` must be unique within this microverse.
-     *
-     * @param args.capabilities - Subset of {@link getSurfaceCapabilities}; use `surface.pickCapabilities(…)` at the call site.
-     */
-    readonly registerScript: (args: {
+    readonly registerScriptDefinition: (def: LuaScriptDefinition) => void;
+    readonly hasScriptDefinition: (scriptId: string) => boolean;
+    readonly getScriptDefinition: (scriptId: string) => LuaScriptDefinition | undefined;
+    readonly mountScriptInstance: (args: {
+        readonly instanceId: string;
         readonly scriptId: string;
-        readonly script: string;
+        readonly script?: string | undefined;
+        readonly props?: ScriptPropertyBag | undefined;
         readonly capabilities: readonly TCapabilities[];
+        readonly audit?: Readonly<Record<string, string | number | boolean>> | undefined;
         readonly injectLuaChunks?: readonly string[] | undefined;
     }) => Promise<void>;
-    /** Invokes `on{Kind}` on every registered script with the same payload table (Lua literals only). */
-    readonly emitToAllScripts: EmitToAllScriptsFn<THooks>;
+    readonly unmountScriptInstance: (instanceId: string) => Promise<void>;
+    readonly setInstanceProps: (instanceId: string, bag: ScriptPropertyBag) => Promise<void>;
+    readonly patchInstanceProps: (instanceId: string, partial: ScriptPropertyBag) => Promise<void>;
+    readonly getInstanceProps: (instanceId: string) => Readonly<ScriptPropertyBag>;
+    readonly flushInstanceProps: (instanceId: string) => Promise<ScriptPropertyBag | null>;
+    readonly getInstance: (instanceId: string) => HostScriptSession<THost, THooks> | undefined;
+    readonly emitToAllInstances: EmitToAllInstancesFn<THooks>;
     readonly dispose: () => Promise<void>;
+    private requireInstance;
 }
-/**
- * Creates a {@link LuaMicroverse} with a **built-in** Wasm Lua VM (Wasmoon). Type `host` with
- * {@link TaggedLuaMicroverseHost} so hook emits narrow correctly.
- */
 export declare function createLuaMicroverse<THost extends object, const TSurface extends HostSurfaceCore<CapabilityId>>(config: {
     readonly host: THost;
     readonly surface: TSurface;
@@ -81,6 +67,7 @@ export declare function createLuaMicroverse<THost extends object, const TSurface
     readonly defaultTimeout?: TimeoutPolicy | undefined;
     readonly defaultTimeoutMs?: number | undefined;
     readonly sharedLuaChunks?: readonly string[] | undefined;
+    readonly onScriptAudit?: ((event: ScriptAuditEvent) => void) | undefined;
 }): LuaMicroverse<THost, EffectiveScriptHooks<THost, TSurface>, InferSurfaceCapabilitiesFromSurface<TSurface>>;
 export {};
 //# sourceMappingURL=luaMicroverse.d.ts.map

package/dist/infrastructure/facade/luaMicroverse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"luaMicroverse.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/facade/luaMicroverse.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"luaMicroverse.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/facade/luaMicroverse.ts"],"names":[],"mappings":"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"}

package/dist/infrastructure/facade/microverseLuaNamespace.d.ts

@@ -1,4 +1,4 @@
-import { createLuaMicroverse } from './luaMicroverse.js';
+import { createLuaMicroverse } from './luaMicroverse';
 /**
  * Plug-and-play **Lua microverse** entry point.
  *
@@ -12,7 +12,8 @@ import { createLuaMicroverse } from './luaMicroverse.js';
  *   surface: mySurface,
  *   defaultTimeoutMs: 30_000,
  * });
- * await microverse.registerScript({ scriptId: 'ai', script: lua, capabilities: surface.pickCapabilities('demo:tick') });
+ * microverse.registerScriptDefinition({ scriptId: 'ai', source: lua });
+ * await microverse.mountScriptInstance({ instanceId: 'ai', scriptId: 'ai', capabilities: surface.pickCapabilities('demo:tick') });
  * ```
  */
 export declare const MicroverseLua: {

package/dist/infrastructure/facade/microverseLuaNamespace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"microverseLuaNamespace.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/facade/microverseLuaNamespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa;IACxB,wEAAwE;;CAEhE,CAAC"}
+{"version":3,"file":"microverseLuaNamespace.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/facade/microverseLuaNamespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAEtD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa;IACxB,wEAAwE;;CAEhE,CAAC"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@microverse.ts/microverse-lua",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "sideEffects": false,
-  "description": "Plug-and-play Lua microverse facade: Wasm VM, MicroverseLua, and re-exports for host surfaces and bridges.",
+  "description": "Main entry for Microverse Lua: MicroverseLua.create (Wasm sandbox, mounts, events) and defineHostSurfaceFor—re-exports the stack.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/QADRAX/Microverse.ts.git",
@@ -30,14 +30,14 @@
   ],
   "dependencies": {
     "zod": "^3.24.0",
-    "@microverse.ts/host-surface": "0.1.0",
-    "@microverse.ts/runtime-bridge": "0.1.0",
-    "@microverse.ts/runtime-capabilities": "0.1.0",
-    "@microverse.ts/runtime-core": "0.1.0",
-    "@microverse.ts/runtime-lua": "0.1.0",
-    "@microverse.ts/runtime-wasm": "0.1.0",
-    "@microverse.ts/runtime-zod": "0.1.0",
-    "@microverse.ts/shared": "0.1.0"
+    "@microverse.ts/host-surface": "0.2.0",
+    "@microverse.ts/runtime-bridge": "0.2.0",
+    "@microverse.ts/runtime-capabilities": "0.2.0",
+    "@microverse.ts/runtime-core": "0.2.0",
+    "@microverse.ts/runtime-lua": "0.2.0",
+    "@microverse.ts/runtime-wasm": "0.2.0",
+    "@microverse.ts/runtime-zod": "0.2.0",
+    "@microverse.ts/shared": "0.2.0"
   },
   "devDependencies": {
     "typescript": "^5.8.3",