@microverse.ts/host-surface 0.1.0 → 0.2.0

package/dist/index.js

@@ -1,8 +1,8 @@
 import { buildDeclarativeBridgeTable } from "@microverse.ts/runtime-bridge";
 import { validateWithZodSchema } from "@microverse.ts/runtime-zod";
 import { z } from "zod";
+import { applyScriptPropertyChanges, assertValidScriptPropertyBag, cloneScriptPropertyBag, createMicroverseScript, createScriptInstanceContext, diffScriptProperties } from "@microverse.ts/runtime-core";
 import { InMemoryCapabilityRegistry, createAllowlist, createCapabilityId } from "@microverse.ts/runtime-capabilities";
-import { createMicroverseScript } from "@microverse.ts/runtime-core";
 //#region src/infrastructure/builders/bridgeMergeEnv.ts
 /**
 * Builds a frozen `mergeEnv` table: bridge name → API object, ready for `MicroverseSlot.run({ mergeEnv })`.
@@ -14,6 +14,10 @@ import { createMicroverseScript } from "@microverse.ts/runtime-core";
 function buildBridgeMergeEnvForHost(host, slotKey, surface) {
 	return buildDeclarativeBridgeTable(host, slotKey, [...surface.toBridgeDeclarations()]);
 }
+/** Bridge table names for `__microverse_bridge_names` in the slot env. */
+function bridgeNamesFromSurface(surface) {
+	return surface.toBridgeDeclarations().map((d) => d.name);
+}
 //#endregion
 //#region src/infrastructure/adapters/zodSchemaValidationAdapter.ts
 function createZodSchemaValidationPort() {
@@ -159,29 +163,45 @@ function asyncHandleClassName(bridgeName, methodName) {
 	const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
 	return `${cap(bridgeName)}${cap(methodName)}Handle`;
 }
-function buildWorkflowHookManifestFields(kinds, workflowHooks, selfType, fieldDescriptionSuffix) {
+/** LuaCATS class for runtime bridge key `audit` → `Audit` (distinct from field name for LuaLS). */
+function bridgeLuaClassName(bridgeTableName) {
+	return bridgeTableName.charAt(0).toUpperCase() + bridgeTableName.slice(1);
+}
+function pushMicroverseBridgesClass(bridgeNames, classes) {
+	if (bridgeNames.length === 0) return;
+	classes.push({
+		name: "MicroverseBridges",
+		description: "Capability-scoped host bridges for this component (`self.bridges` after `component:extend()`).",
+		fields: bridgeNames.map((name) => ({
+			name,
+			luaType: bridgeLuaClassName(name)
+		})),
+		emitSingleton: false
+	});
+}
+function buildComponentEventManifestFields(kinds, componentHooks) {
 	const out = [];
 	for (const kind of kinds) {
-		if (!(workflowHooks[kind] instanceof z.ZodObject)) throw new Error(`defineHostSurface workflowHooks: "${kind}" must be a z.object(...)`);
-		const payloadName = `MicroverseWorkflowEvt_${kind}`;
+		if (!(componentHooks[kind] instanceof z.ZodObject)) throw new Error(`defineHostSurface componentHooks: "${kind}" must be a z.object(...)`);
+		const payloadName = `MicroverseEvt_${kind}`;
 		const hookName = luaGlobalHookName(kind);
 		out.push({
 			name: hookName,
-			description: `${fieldDescriptionSuffix} Payload: \`${payloadName}\`.`,
-			luaType: `fun(self: ${selfType}, evt: ${payloadName})`
+			description: `Host invokes when \`${kind}\` is emitted. Payload: \`${payloadName}\`.`,
+			luaType: `fun(self: Component, evt: ${payloadName})`
 		});
 	}
 	return out;
 }
-function pushWorkflowPayloadManifestClasses(kinds, workflowHooks, classes) {
+function pushComponentEventPayloadClasses(kinds, componentHooks, classes) {
 	for (const kind of kinds) {
-		const schema = workflowHooks[kind];
-		if (!(schema instanceof z.ZodObject)) throw new Error(`defineHostSurface workflowHooks: "${kind}" must be a z.object(...)`);
-		const name = `MicroverseWorkflowEvt_${kind}`;
+		const schema = componentHooks[kind];
+		if (!(schema instanceof z.ZodObject)) throw new Error(`defineHostSurface componentHooks: "${kind}" must be a z.object(...)`);
+		const name = `MicroverseEvt_${kind}`;
 		const shape = schema.shape;
 		classes.push({
 			name,
-			description: `Workflow hook payload for \`${luaGlobalHookName(kind)}\` (Zod → LuaCATS fields).`,
+			description: `Domain event payload for \`${luaGlobalHookName(kind)}\` (Zod → LuaCATS fields).`,
 			fields: Object.keys(shape).map((k) => ({
 				name: k,
 				luaType: zodToLuaTypeRef(shape[k])
@@ -190,9 +210,63 @@ function pushWorkflowPayloadManifestClasses(kinds, workflowHooks, classes) {
 		});
 	}
 }
-function buildLuaDefManifestFromHostSurfaceSpec(spec, opts, workflowHooks) {
+function pushComponentManifestClasses(classes, bridgeNames, componentHooks) {
+	const eventKinds = componentHooks !== void 0 ? Object.keys(componentHooks).sort((a, b) => a.localeCompare(b)) : [];
+	if (componentHooks !== void 0) pushComponentEventPayloadClasses(eventKinds, componentHooks, classes);
+	const lifecycleFields = [
+		{
+			name: "properties",
+			luaType: "table",
+			description: "Host-synced props (proxy)."
+		},
+		{
+			name: "state",
+			luaType: "table",
+			description: "Lua-local state."
+		},
+		{
+			name: "bridges",
+			luaType: bridgeNames.length > 0 ? "MicroverseBridges" : "table",
+			description: "Host bridges allowed for this instance (not global in the slot)."
+		},
+		{
+			name: "init",
+			luaType: "fun(self: Component)",
+			description: "Called once after mount and initial props are applied."
+		},
+		{
+			name: "onPropsChanged",
+			luaType: "fun(self: Component, key: string, newValue: any)",
+			description: "Called when the host patches a property key."
+		},
+		{
+			name: "onDestroy",
+			luaType: "fun(self: Component)",
+			description: "Called before the script instance slot is disposed."
+		}
+	];
+	if (componentHooks !== void 0) lifecycleFields.push(...buildComponentEventManifestFields(eventKinds, componentHooks));
+	classes.push({
+		name: "Component",
+		description: "Component instance from `local C = component:extend()`. Use `self.bridges` for host APIs; define `on*` methods for domain events.",
+		fields: lifecycleFields,
+		emitSingleton: false
+	});
+	classes.push({
+		name: "component",
+		description: "Per-slot helper injected by the host. Use `component:extend()` to create the active component.",
+		methods: [{
+			name: "extend",
+			description: "Returns the component table with `properties`, `state`, and `bridges` wired for this slot.",
+			params: [],
+			returns: "Component"
+		}]
+	});
+}
+function buildLuaDefManifestFromHostSurfaceSpec(spec, opts, componentHooks) {
 	const classes = [];
-	for (const bridgeName of Object.keys(spec)) {
+	const bridgeNames = Object.keys(spec).sort((a, b) => a.localeCompare(b));
+	for (const bridgeName of bridgeNames) {
 		const methods = spec[bridgeName];
 		const manifestMethods = [];
 		for (const methodName of Object.keys(methods)) {
@@ -228,35 +302,17 @@ function buildLuaDefManifestFromHostSurfaceSpec(spec, opts, workflowHooks) {
 			});
 		}
 		classes.push({
-			name: bridgeName,
-			methods: manifestMethods
+			name: bridgeLuaClassName(bridgeName),
+			methods: manifestMethods,
+			emitSingleton: false
 		});
 	}
+	pushMicroverseBridgesClass(bridgeNames, classes);
 	const fromLuaType = collectLuaTypeAliasesFromHostSpec(spec);
 	const fromOverrides = inferLuaTypeAliasesFromHostSpec(spec);
 	const merged = new Map([...fromLuaType.map((a) => [a.name, a.definition]), ...fromOverrides.map((a) => [a.name, a.definition])]);
 	if (opts.luaTypeAliases !== void 0) for (const [k, v] of Object.entries(opts.luaTypeAliases)) merged.set(k, v);
-	if (workflowHooks !== void 0) {
-		const kinds = Object.keys(workflowHooks).sort((a, b) => a.localeCompare(b));
-		pushWorkflowPayloadManifestClasses(kinds, workflowHooks, classes);
-		const abstractFields = buildWorkflowHookManifestFields(kinds, workflowHooks, "Workflow", "Host invokes this method on your table (from `workflow:extend()`) when the matching domain event fires.");
-		classes.push({
-			name: "Workflow",
-			description: "Abstract workflow handler type. Call `local w = workflow:extend()` then define `function w:onOrderPlaced(evt) … end` (etc.). Each Lua slot has its own `workflow` helper and handler table.",
-			fields: abstractFields,
-			emitSingleton: false
-		});
-		classes.push({
-			name: "workflow",
-			description: "Per-slot helper injected by the host (not a TS bridge). Creates the active handler table for this sandbox slot.",
-			methods: [{
-				name: "extend",
-				description: "Returns a new handler table with default no-op hooks; registers it for host → Lua dispatch in this slot.",
-				params: [],
-				returns: "Workflow"
-			}]
-		});
-	}
+	pushComponentManifestClasses(classes, bridgeNames, componentHooks);
 	const aliases = merged.size === 0 ? void 0 : [...merged.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([name, definition]) => ({
 		name,
 		definition
@@ -429,6 +485,9 @@ function pickSurfaceCapabilities(surfaceCapabilities, ...capabilities) {
 */
 var MICROVERSE_CAPABILITY_REGISTRY = Symbol.for("microverse:capabilityRegistry");
 //#endregion
+//#region src/domain/scriptContextSymbol.ts
+var MICROVERSE_SCRIPT_CONTEXT = Symbol("microverse.scriptContext");
+//#endregion
 //#region src/application/useCases/compileBridgeDeclarationsFromHostSurfaceSpec.ts
 function isThenable(value) {
 	if (value === null || value === void 0) return false;
@@ -446,19 +505,26 @@ function createBridgeDeclarationsFromHostSurfaceSpec(schemaValidation, spec) {
 			name: bridgeName,
 			perEntity: true,
 			createApi: (host, slotKey) => {
+				const hostWithScript = host;
 				const api = {};
 				for (const methodName of Object.keys(methods)) {
 					const entry = methods[methodName];
 					api[methodName] = (...args) => {
 						const payload = args.length >= 2 ? args[1] : args[0];
-						const registry = host[MICROVERSE_CAPABILITY_REGISTRY];
+						const registry = hostWithScript[MICROVERSE_CAPABILITY_REGISTRY];
 						const capability = entry.capability;
 						if (!registry.isAllowed(capability)) throw new Error(`capability denied: ${String(capability)}`);
 						const parsedIn = schemaValidation.validateWithZodSchema(entry.input, payload);
 						if (parsedIn._tag === "err") throw new Error(parsedIn.error);
-						const raw = entry.handler({
-							host,
+						const script = hostWithScript[MICROVERSE_SCRIPT_CONTEXT] ?? createScriptInstanceContext({
+							instanceId: String(slotKey),
+							scriptId: "unknown",
 							slotKey: String(slotKey)
+						});
+						const raw = entry.handler({
+							host: hostWithScript,
+							slotKey: String(slotKey),
+							script
 						}, parsedIn.value);
 						if (isThenable(raw)) return raw.then((resolved) => {
 							const parsedOut = schemaValidation.validateWithZodSchema(entry.output, resolved);
@@ -478,29 +544,29 @@ function createBridgeDeclarationsFromHostSurfaceSpec(schemaValidation, spec) {
 }
 //#endregion
 //#region src/application/useCases/compileHostSurface.ts
-function buildHostSurfaceCore(schemaValidation, spec, workflowHooks) {
+function buildHostSurfaceCore(schemaValidation, spec, componentHooks) {
 	const capabilities = collectCapabilitiesFromHostSurfaceSpec(spec);
 	return {
 		toBridgeDeclarations: () => createBridgeDeclarationsFromHostSurfaceSpec(schemaValidation, spec),
-		toLuaDefManifest: (opts) => buildLuaDefManifestFromHostSurfaceSpec(spec, opts, workflowHooks),
+		toLuaDefManifest: (opts) => buildLuaDefManifestFromHostSurfaceSpec(spec, opts, componentHooks),
 		capabilities,
 		pickCapabilities: (...picked) => pickSurfaceCapabilities(capabilities, ...picked)
 	};
 }
-function compileHostSurface(ports, spec, workflowHooks) {
+function compileHostSurface(ports, spec, componentHooks) {
 	const [schemaValidation] = ports;
-	const core = buildHostSurfaceCore(schemaValidation, spec, workflowHooks);
-	if (workflowHooks === void 0) return core;
+	const core = buildHostSurfaceCore(schemaValidation, spec, componentHooks);
+	if (componentHooks === void 0) return core;
 	return {
 		...core,
-		workflowHooks
+		componentHooks
 	};
 }
 /**
 * Same as {@link compileHostSurface}, but requires every bridge method to be typed with the same `THost`.
 */
-function compileHostSurfaceFor(ports, spec, workflowHooks) {
-	return workflowHooks === void 0 ? compileHostSurface(ports, spec) : compileHostSurface(ports, spec, workflowHooks);
+function compileHostSurfaceFor(ports, spec, componentHooks) {
+	return componentHooks === void 0 ? compileHostSurface(ports, spec) : compileHostSurface(ports, spec, componentHooks);
 }
 //#endregion
 //#region src/domain/inferMethodAsync.ts
@@ -551,11 +617,11 @@ function createNullPrototypeRecord() {
 */
 var SurfaceBuilder = class SurfaceBuilder {
 	spec = createNullPrototypeRecord();
-	workflowHooksSpec;
+	componentHooksSpec;
 	ports;
-	constructor(ports, workflowHooks, initialSpec) {
+	constructor(ports, componentHooks, initialSpec) {
 		this.ports = ports;
-		this.workflowHooksSpec = workflowHooks;
+		this.componentHooksSpec = componentHooks;
 		if (initialSpec !== void 0) for (const bridgeName of Object.keys(initialSpec)) {
 			assertSafeObjectKey("bridge", bridgeName);
 			const srcBridge = initialSpec[bridgeName];
@@ -571,14 +637,14 @@ var SurfaceBuilder = class SurfaceBuilder {
 	bridge(name) {
 		return new BridgeBuilder(this, name);
 	}
-	/** Attaches workflow hook Zod schemas (emitted into `.d.lua` as `on*` methods). */
-	workflowHooks(hooks) {
+	/** Attaches component domain-event Zod schemas (emitted into `.d.lua` as `on*` methods on `Component`). */
+	componentHooks(hooks) {
 		return new SurfaceBuilder(this.ports, hooks, this.spec);
 	}
 	/** Compiles the accumulated spec into a {@link HostSurface}. */
 	build() {
 		const spec = this.spec;
-		return compileHostSurfaceFor(this.ports, spec, this.workflowHooksSpec);
+		return compileHostSurfaceFor(this.ports, spec, this.componentHooksSpec);
 	}
 	/** @internal */
 	addMethod(bridgeName, methodName, entry) {
@@ -654,6 +720,143 @@ function defineHostSurfaceFor() {
 	return createSurfaceBuilder();
 }
 //#endregion
+//#region src/domain/componentSlotPrelude.ts
+/** @see MICROVERSE_LUA_COMPONENT_SLOT_PRELUDE */
+var MICROVERSE_LUA_COMPONENT_SLOT_PRELUDE = `
+rawset(_ENV, "__microverse_component_rawProps", {})
+rawset(_ENV, "__microverse_component_dirty", {})
+
+local function rawProps()
+  return rawget(_ENV, "__microverse_component_rawProps")
+end
+
+local function dirty()
+  return rawget(_ENV, "__microverse_component_dirty")
+end
+
+local PropertiesMT = {
+  __index = function(t, k)
+    return rawget(t, "__raw")[k]
+  end,
+  __newindex = function(t, k, v)
+    rawget(t, "__raw")[k] = v
+    local d = dirty()
+    d[k] = v
+  end,
+}
+
+function __microverse_lua_attach_bridges(impl)
+  if type(impl) ~= "table" then
+    return
+  end
+  impl.bridges = impl.bridges or {}
+  local names = rawget(_ENV, "__microverse_bridge_names")
+  if type(names) ~= "table" then
+    return
+  end
+  for _, name in ipairs(names) do
+    if type(name) == "string" then
+      local g = rawget(_ENV, name)
+      if type(g) == "table" then
+        impl.bridges[name] = g
+        rawset(_ENV, name, nil)
+      end
+    end
+  end
+end
+
+rawset(_ENV, "__microverse_lua_attach_bridges", __microverse_lua_attach_bridges)
+
+rawset(_ENV, "component", {
+  extend = function()
+    local impl = { state = {}, bridges = {} }
+    local proxy = { __raw = rawProps() }
+    setmetatable(proxy, PropertiesMT)
+    impl.properties = proxy
+    local base = rawget(_ENV, "__microverse_component_hook_base")
+    if type(base) == "table" then
+      setmetatable(impl, { __index = base })
+    end
+    __microverse_lua_attach_bridges(impl)
+    rawset(_ENV, "__microverse_lua_ComponentImpl", impl)
+    return impl
+  end,
+})
+
+rawset(_ENV, "__microverse_lua_component_apply_incoming", function()
+  local incoming = rawget(_ENV, "__microverseIncomingProps")
+  if type(incoming) ~= "table" then
+    return
+  end
+  local rp = rawProps()
+  local impl = rawget(_ENV, "__microverse_lua_ComponentImpl")
+  if type(impl) ~= "table" or type(impl.properties) ~= "table" then
+    for k, v in pairs(incoming) do
+      rp[k] = v
+    end
+    return
+  end
+  for k, v in pairs(incoming) do
+    impl.properties[k] = v
+  end
+end)
+
+rawset(_ENV, "__microverse_lua_component_flush_to_sink", function()
+  local push = rawget(_ENV, "__microverseFlushPush")
+  local d = dirty()
+  for k, v in pairs(d) do
+    if type(push) == "function" then
+      push(k, v)
+    end
+    d[k] = nil
+  end
+end)
+`.trim();
+//#endregion
+//#region src/domain/scriptPropertyMergeEnv.ts
+function scriptPropertyBagToMergeEnv(bag) {
+	const out = {};
+	for (const [k, v] of Object.entries(bag)) out[k] = scriptPropertyValueToPlain(v);
+	return out;
+}
+function scriptPropertyValueToPlain(value) {
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map((item) => scriptPropertyValueToPlain(item));
+	const out = {};
+	for (const [k, v] of Object.entries(value)) out[k] = scriptPropertyValueToPlain(v);
+	return out;
+}
+function mergeEnvSinkToScriptPropertyBag(sink) {
+	const out = {};
+	for (const [k, v] of Object.entries(sink)) {
+		const converted = plainToScriptPropertyValue(v);
+		if (converted !== void 0) out[k] = converted;
+	}
+	return out;
+}
+function plainToScriptPropertyValue(value) {
+	if (value === null) return null;
+	const t = typeof value;
+	if (t === "string" || t === "boolean") return value;
+	if (typeof value === "number" && Number.isFinite(value)) return value;
+	if (Array.isArray(value)) {
+		const arr = [];
+		for (const item of value) {
+			const c = plainToScriptPropertyValue(item);
+			if (c !== void 0) arr.push(c);
+		}
+		return arr;
+	}
+	if (t === "object" && value !== null) {
+		const obj = {};
+		for (const [k, v] of Object.entries(value)) {
+			const c = plainToScriptPropertyValue(v);
+			if (c !== void 0) obj[k] = c;
+		}
+		return obj;
+	}
+}
+//#endregion
 //#region src/infrastructure/adapters/augmentHostWithCapabilityRegistry.ts
 /**
 * Returns a shallow copy of `host` with {@link MICROVERSE_CAPABILITY_REGISTRY} set to `registry`.
@@ -666,61 +869,124 @@ function augmentHostWithCapabilityRegistry(host, registry) {
 	return Object.assign(host, { [MICROVERSE_CAPABILITY_REGISTRY]: registry });
 }
 //#endregion
+//#region src/infrastructure/adapters/augmentHostWithScriptContext.ts
+function augmentHostWithScriptContext(host, script) {
+	return Object.assign(host, { [MICROVERSE_SCRIPT_CONTEXT]: script });
+}
+//#endregion
 //#region src/infrastructure/components/hostScriptSession.ts
-/**
-* Binds one **Lua slot** to a {@link HostSurface}: capability allowlist, Zod validation, and `mergeEnv` wiring.
-*
-* @remarks
-* - **Lua → host (bridges):** tables/methods from {@link defineHostSurface} on `_ENV` call into TypeScript with Zod validation.
-* - **Host → Lua (hooks):** when the surface defines `workflowHooks`, {@link HostScriptSession.openSession} installs
-*   a small `workflow` helper (`workflow:extend()` → handler table + slot registration) and
-*   {@link HostScriptSession.invokeGlobalHookIfPresent} dispatches `on…` methods on that table. Each session has its own
-*   slot env, so many workflows run concurrently without sharing Lua globals. Without `workflowHooks`, hooks are optional
-*   globals (`onSmoke`, …) invoked as plain functions.
-* - Call {@link HostScriptSession.openSession} once before running chunks or invocations; {@link HostScriptSession.dispose} when the slot is torn down.
-*
-* @typeParam THost - Same host type as your surface handlers.
-* @typeParam THooks - Align with {@link HostSurface} `workflowHooks` on the surface you pass in (or `undefined` when the surface has no workflow hooks).
-*/
 var HostScriptSession = class {
 	opts;
 	sandbox;
+	hostProps = {};
 	registry;
+	context;
 	constructor(opts) {
 		this.opts = opts;
 		this.registry = new InMemoryCapabilityRegistry(createAllowlist([...opts.allowedCapabilities]));
+		this.context = opts.script;
 	}
-	/**
-	* Allocates the underlying {@link MicroverseSlot} for this `slotKey` on the shared runtime.
-	*/
 	openSession = async () => {
 		this.sandbox = await this.opts.runtime.createMicroverse({ slotKey: this.opts.slotKey });
-		const hooks = readWorkflowHooks(this.opts.surface);
-		if (hooks !== void 0) {
-			const prelude = buildWorkflowStubPreludeLua(hooks);
-			await this.requireMicroverseSlot().run({
-				script: createMicroverseScript(prelude),
+		const sb = this.requireMicroverseSlot();
+		if (this.opts.enableComponentRuntime !== false) {
+			await sb.run({
+				script: createMicroverseScript(MICROVERSE_LUA_COMPONENT_SLOT_PRELUDE),
+				mergeEnv: this.mergeEnv(),
+				timeout: this.opts.defaultTimeout
+			});
+			await sb.run({
+				script: createMicroverseScript(buildBridgeNamesPreludeLua(bridgeNamesFromSurface(this.opts.surface))),
 				mergeEnv: this.mergeEnv(),
 				timeout: this.opts.defaultTimeout
 			});
+			const hooks = readComponentHooks(this.opts.surface);
+			if (hooks !== void 0) {
+				const prelude = buildComponentEventStubPreludeLua(hooks);
+				await sb.run({
+					script: createMicroverseScript(prelude),
+					mergeEnv: this.mergeEnv(),
+					timeout: this.opts.defaultTimeout
+				});
+			}
 		}
 	};
-	/**
-	* Exposes the in-memory registry (e.g. to mutate allowlists in advanced tests).
-	*/
 	getCapabilityRegistry = () => this.registry;
 	requireMicroverseSlot() {
 		if (this.sandbox === void 0) throw new Error("HostScriptSession: openSession() was not called");
 		return this.sandbox;
 	}
 	mergeEnv() {
-		return buildBridgeMergeEnvForHost(augmentHostWithCapabilityRegistry(this.opts.host, this.registry), String(this.opts.slotKey), this.opts.surface);
+		return buildBridgeMergeEnvForHost(augmentHostWithScriptContext(augmentHostWithCapabilityRegistry(this.opts.host, this.registry), this.opts.script), String(this.opts.slotKey), this.opts.surface);
+	}
+	emitAudit(event) {
+		this.opts.onScriptAudit?.(event);
+	}
+	validatePropsBag(bag) {
+		if (this.opts.propsSchema !== void 0) {
+			const parsed = this.opts.propsSchema.parse(bag);
+			assertValidScriptPropertyBag(parsed);
+			return parsed;
+		}
+		assertValidScriptPropertyBag(bag);
+		return bag;
 	}
-	/**
-	* Executes Lua source in the slot environment with surface bridges on `_ENV`.
-	*
-	* @param source - Full Lua chunk (compiled with `load(..., "t", env)` in the Wasm adapter).
-	*/
+	getProps = () => ({ ...this.hostProps });
+	setProps = async (bag) => {
+		const next = this.validatePropsBag(bag);
+		const changed = diffScriptProperties(this.hostProps, next);
+		applyScriptPropertyChanges(this.hostProps, next, changed);
+		await this.requireMicroverseSlot().run({
+			script: createMicroverseScript("local f = rawget(_ENV, \"__microverse_lua_component_apply_incoming\")\nif type(f) == \"function\" then f() end"),
+			mergeEnv: {
+				...this.mergeEnv(),
+				__microverseIncomingProps: scriptPropertyBagToMergeEnv(this.hostProps)
+			},
+			timeout: this.opts.defaultTimeout
+		});
+		if (changed.length > 0) {
+			this.emitAudit({
+				kind: "propsPatched",
+				context: this.opts.script,
+				changedKeys: changed
+			});
+			for (const key of changed) {
+				const value = next[key];
+				if (value !== void 0) await this.invokeComponentHook("onPropsChanged", key, value);
+			}
+		}
+	};
+	patchProps = async (partial) => {
+		await this.setProps({
+			...this.hostProps,
+			...partial
+		});
+	};
+	flushDirtyProps = async () => {
+		if (this.opts.enableComponentRuntime === false) return null;
+		const collected = {};
+		await this.requireMicroverseSlot().run({
+			script: createMicroverseScript("local f = rawget(_ENV, \"__microverse_lua_component_flush_to_sink\")\nif type(f) == \"function\" then f() end"),
+			mergeEnv: {
+				...this.mergeEnv(),
+				__microverseFlushPush: (key, value) => {
+					const converted = plainToScriptPropertyValue(value);
+					if (converted !== void 0) collected[key] = converted;
+				}
+			},
+			timeout: this.opts.defaultTimeout
+		});
+		const keys = Object.keys(collected);
+		if (keys.length === 0) return null;
+		const dirty = collected;
+		for (const key of keys) this.hostProps[key] = dirty[key];
+		this.emitAudit({
+			kind: "propsFlushed",
+			context: this.opts.script,
+			dirtyKeys: keys
+		});
+		return dirty;
+	};
 	runChunk = async (source) => {
 		return this.requireMicroverseSlot().run({
 			script: createMicroverseScript(source),
@@ -728,37 +994,46 @@ var HostScriptSession = class {
 			timeout: this.opts.defaultTimeout
 		});
 	};
-	/**
-	* Host → Lua: when the surface has `workflowHooks`, invokes `impl:onHook(evt)` on the handler table registered by
-	* `workflow:extend()` in this slot. Otherwise invokes `_ENV[globalName](evt)` when that entry is a function.
-	*
-	* @param globalName - Hook method name, e.g. `onOrderPlaced` (same as {@link luaGlobalHookName}).
-	* @param payload - Table fields: only string, finite number, or boolean (Lua literals).
-	*/
-	invokeGlobalHookIfPresent = (async (globalName, payload) => {
-		assertSafeLuaGlobalName(globalName);
+	invokeComponentHook = async (hookName, ...args) => {
+		assertSafeLuaGlobalName(hookName);
+		this.emitAudit({
+			kind: "hookInvoked",
+			context: this.opts.script,
+			hookName
+		});
 		const sb = this.requireMicroverseSlot();
-		const tbl = luaTableLiteralFromPlainRecord(payload);
-		const src = readWorkflowHooks(this.opts.surface) !== void 0 ? buildWorkflowHookInvokeLuaSource(globalName, tbl) : buildGlobalHookInvokeLuaSource(globalName, tbl);
+		const argLiterals = args.map((a) => {
+			if (typeof a === "object" && a !== null && !Array.isArray(a)) return luaTableLiteralFromPlainRecord(a);
+			return luaValueLiteral(a);
+		}).join(", ");
+		const src = [
+			`local impl = rawget(_ENV, "__microverse_lua_ComponentImpl")`,
+			`if type(impl) == "table" then`,
+			`  local attach = rawget(_ENV, "__microverse_lua_attach_bridges")`,
+			`  if type(attach) == "function" then attach(impl) end`,
+			`  local m = rawget(impl, ${JSON.stringify(hookName)})`,
+			`  if type(m) == "function" then`,
+			argLiterals.length > 0 ? `    m(impl, ${argLiterals})` : `    m(impl)`,
+			`  end`,
+			`end`
+		].join("\n");
 		return sb.run({
 			script: createMicroverseScript(src),
 			mergeEnv: this.mergeEnv(),
 			timeout: this.opts.defaultTimeout
 		});
+	};
+	invokeComponentEventHook = (async (hookName, payload) => {
+		assertSafeLuaGlobalName(hookName);
+		return this.invokeComponentHook(hookName, payload);
 	});
-	/**
-	* Host → Lua: invokes `_ENV[tableName][methodName](literalTable)` where `literalTable` is built only from
-	* string, finite number, or boolean fields in `payload`.
-	*
-	* @param tableName - Global table name in the slot env.
-	* @param methodName - Function field on that table.
-	* @param payload - Plain serializable fields for the Lua table literal.
-	*/
 	call = async (tableName, methodName, payload) => {
 		const sb = this.requireMicroverseSlot();
 		const tbl = luaTableLiteralFromUnknownRecord(payload);
 		const src = [
-			`local t = _ENV[${JSON.stringify(tableName)}]`,
+			`local impl = rawget(_ENV, "__microverse_lua_ComponentImpl")`,
+			`local bridges = type(impl) == "table" and impl.bridges or nil`,
+			`local t = type(bridges) == "table" and bridges[${JSON.stringify(tableName)}] or nil`,
 			`local f = type(t) == "table" and t[${JSON.stringify(methodName)}] or nil`,
 			`if type(f) == "function" then`,
 			`  f(${tbl})`,
@@ -770,61 +1045,54 @@ var HostScriptSession = class {
 			timeout: this.opts.defaultTimeout
 		});
 	};
-	/**
-	* Releases the slot in the runtime adapter and clears the session handle.
-	*/
 	dispose = async () => {
 		if (this.sandbox !== void 0) {
+			if (this.opts.enableComponentRuntime !== false) await this.invokeComponentHook("onDestroy");
 			await this.sandbox.dispose();
 			this.sandbox = void 0;
 		}
 	};
+	/** Seeds host props bag without Lua sync (call before setProps after mount). */
+	seedHostProps = (bag) => {
+		const cloned = cloneScriptPropertyBag(bag);
+		for (const k of Object.keys(this.hostProps)) delete this.hostProps[k];
+		Object.assign(this.hostProps, cloned);
+	};
 };
 function assertSafeLuaGlobalName(name) {
 	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`unsafe Lua global name: ${name}`);
 }
-function readWorkflowHooks(surface) {
-	if (!("workflowHooks" in surface)) return;
-	return surface.workflowHooks;
+function readComponentHooks(surface) {
+	if (!("componentHooks" in surface)) return;
+	return surface.componentHooks;
 }
-function buildWorkflowStubPreludeLua(hooks) {
+function buildBridgeNamesPreludeLua(bridgeNames) {
+	return `rawset(_ENV, "__microverse_bridge_names", { ${bridgeNames.map((n) => JSON.stringify(n)).join(", ")} })`;
+}
+function buildComponentEventStubPreludeLua(hooks) {
 	return [
 		"local Base = {}",
 		"for _, name in ipairs({",
 		...Object.keys(hooks).sort((a, b) => a.localeCompare(b)).map((kind) => {
-			if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(kind)) throw new Error(`unsafe workflow hook kind: ${kind}`);
+			if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(kind)) throw new Error(`unsafe component hook kind: ${kind}`);
 			return JSON.stringify(luaGlobalHookName(kind));
 		}).map((h) => `  ${h},`),
 		"}) do",
 		"  rawset(Base, name, function() end)",
 		"end",
-		"rawset(_ENV, \"workflow\", {",
-		"  extend = function(_)",
-		"    local w = setmetatable({}, { __index = Base })",
-		"    rawset(_ENV, \"__microverse_lua_WorkflowImpl\", w)",
-		"    return w",
-		"  end,",
-		"})"
+		"rawset(_ENV, \"__microverse_component_hook_base\", Base)"
 	].join("\n");
 }
-function buildWorkflowHookInvokeLuaSource(methodName, evtLiteral) {
-	return [
-		`local impl = rawget(_ENV, "__microverse_lua_WorkflowImpl")`,
-		`if type(impl) == "table" then`,
-		`  local m = rawget(impl, ${JSON.stringify(methodName)})`,
-		`  if type(m) == "function" then`,
-		`    m(impl, ${evtLiteral})`,
-		`  end`,
-		`end`
-	].join("\n");
-}
-function buildGlobalHookInvokeLuaSource(globalName, evtLiteral) {
-	return [
-		`local f = rawget(_ENV, ${JSON.stringify(globalName)})`,
-		`if type(f) == "function" then`,
-		`  f(${evtLiteral})`,
-		`end`
-	].join("\n");
+function luaValueLiteral(value) {
+	if (typeof value === "string") return JSON.stringify(value);
+	if (typeof value === "number" && Number.isFinite(value)) return String(value);
+	if (typeof value === "boolean") return value ? "true" : "false";
+	if (value === null) return "nil";
+	if (Array.isArray(value)) return `{ ${value.map((v) => luaValueLiteral(v)).join(", ")} }`;
+	const record = value;
+	const parts = [];
+	for (const k of Object.keys(record)) parts.push(`${k} = ${luaValueLiteral(record[k])}`);
+	return `{ ${parts.join(", ")} }`;
 }
 function luaTableLiteralFromPlainRecord(o) {
 	const parts = [];
@@ -843,6 +1111,6 @@ function luaTableLiteralFromUnknownRecord(o) {
 	return `{ ${parts.join(", ")} }`;
 }
 //#endregion
-export { BridgeBuilder, HostScriptSession, MICROVERSE_CAPABILITY_REGISTRY, SurfaceBuilder, augmentHostWithCapabilityRegistry, buildBridgeMergeEnvForHost, collectCapabilitiesFromHostSurfaceSpec, compileHostSurface, compileHostSurfaceFor, createBridgeDeclarationsFromHostSurfaceSpec, defineHostSurface, defineHostSurfaceFor, luaGlobalHookName, luaType, pickSurfaceCapabilities, zodToLuaTypeRef };
+export { BridgeBuilder, HostScriptSession, MICROVERSE_CAPABILITY_REGISTRY, MICROVERSE_LUA_COMPONENT_SLOT_PRELUDE, MICROVERSE_SCRIPT_CONTEXT, SurfaceBuilder, augmentHostWithCapabilityRegistry, augmentHostWithScriptContext, buildBridgeMergeEnvForHost, collectCapabilitiesFromHostSurfaceSpec, compileHostSurface, compileHostSurfaceFor, createBridgeDeclarationsFromHostSurfaceSpec, defineHostSurface, defineHostSurfaceFor, luaGlobalHookName, luaType, mergeEnvSinkToScriptPropertyBag, pickSurfaceCapabilities, scriptPropertyBagToMergeEnv, scriptPropertyValueToPlain, zodToLuaTypeRef };
 
 //# sourceMappingURL=index.js.map