@microverse.ts/host-surface 0.1.0 → 0.3.0

package/dist/index.js

@@ -1,18 +1,404 @@
 import { buildDeclarativeBridgeTable } from "@microverse.ts/runtime-bridge";
-import { validateWithZodSchema } from "@microverse.ts/runtime-zod";
+import { applyScriptPropertyChanges, assertValidScriptPropertyBag, cloneScriptPropertyBag, createMicroverseScript, createScriptInstanceContext, diffScriptProperties } from "@microverse.ts/runtime-core";
+import { createCapabilityId } from "@microverse.ts/runtime-capabilities";
 import { z } from "zod";
-import { InMemoryCapabilityRegistry, createAllowlist, createCapabilityId } from "@microverse.ts/runtime-capabilities";
-import { createMicroverseScript } from "@microverse.ts/runtime-core";
+import { validateWithZodSchema } from "@microverse.ts/runtime-zod";
+//#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;
+	if (typeof value !== "object" && typeof value !== "function") return false;
+	return typeof value.then === "function";
+}
+/**
+* Builds declarative bridge declarations from a host surface spec, using the schema validation port for Lua ↔ host payloads.
+*/
+function createBridgeDeclarationsFromHostSurfaceSpec(schemaValidation, spec) {
+	const out = [];
+	for (const bridgeName of Object.keys(spec)) {
+		const methods = spec[bridgeName];
+		out.push({
+			name: bridgeName,
+			perEntity: true,
+			createApi: (host, slotKey) => {
+				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 parsedIn = schemaValidation.validateWithZodSchema(entry.input, payload);
+						if (parsedIn._tag === "err") throw new Error(parsedIn.error);
+						const script = host[MICROVERSE_SCRIPT_CONTEXT] ?? createScriptInstanceContext({
+							instanceId: String(slotKey),
+							scriptId: "unknown",
+							slotKey: String(slotKey)
+						});
+						const raw = entry.handler({
+							host,
+							slotKey: String(slotKey),
+							script
+						}, parsedIn.value);
+						if (isThenable(raw)) return raw.then((resolved) => {
+							const parsedOut = schemaValidation.validateWithZodSchema(entry.output, resolved);
+							if (parsedOut._tag === "err") throw new Error(parsedOut.error);
+							return parsedOut.value;
+						});
+						const parsedOut = schemaValidation.validateWithZodSchema(entry.output, raw);
+						if (parsedOut._tag === "err") throw new Error(parsedOut.error);
+						return parsedOut.value;
+					};
+				}
+				return Object.freeze(api);
+			}
+		});
+	}
+	return out;
+}
+//#endregion
+//#region src/infrastructure/builders/filterBridgeDeclarations.ts
+/**
+* Keeps bridge declarations (and methods) whose capability is in the allow set.
+*/
+function filterBridgeDeclarationsByCapabilities(declarations, spec, capabilities) {
+	const allowed = new Set(capabilities.map((c) => String(c)));
+	const bridgeNames = /* @__PURE__ */ new Set();
+	for (const bridgeName of Object.keys(spec)) {
+		const methods = spec[bridgeName];
+		for (const methodName of Object.keys(methods)) {
+			const entry = methods[methodName];
+			if (allowed.has(String(entry.capability))) {
+				bridgeNames.add(bridgeName);
+				break;
+			}
+		}
+	}
+	return declarations.filter((d) => bridgeNames.has(d.name)).map((d) => ({
+		...d,
+		createApi: (host, slotKey) => {
+			const api = d.createApi(host, slotKey);
+			const methods = spec[d.name];
+			const filtered = {};
+			for (const methodName of Object.keys(api)) {
+				const entry = methods[methodName];
+				if (entry !== void 0 && allowed.has(String(entry.capability))) filtered[methodName] = api[methodName];
+			}
+			return Object.freeze(filtered);
+		}
+	}));
+}
+function createFilteredBridgeDeclarations(schemaValidation, spec, capabilities) {
+	return filterBridgeDeclarationsByCapabilities(createBridgeDeclarationsFromHostSurfaceSpec(schemaValidation, spec), spec, capabilities);
+}
+//#endregion
 //#region src/infrastructure/builders/bridgeMergeEnv.ts
 /**
-* Builds a frozen `mergeEnv` table: bridge name → API object, ready for `MicroverseSlot.run({ mergeEnv })`.
-*
-* @param host - Your host context, already extended with the capability registry symbol from `@microverse.ts/host-surface`.
-* @param slotKey - Same slot key passed to `buildDeclarativeBridgeTable` (string form of `MicroverseId` is fine).
-* @param surface - Result of {@link defineHostSurface} (implements {@link HostSurfaceCore}).
+* Builds a frozen bridge table for a component profile capability set.
+*/
+function buildBridgeMergeEnvForProfile(schemaValidation, host, slotKey, spec, capabilities) {
+	return buildDeclarativeBridgeTable(host, slotKey, [...createFilteredBridgeDeclarations(schemaValidation, spec, capabilities)]);
+}
+//#endregion
+//#region src/domain/safeObjectKey.ts
+/** Keys that must not be used as dynamic property names on ordinary objects. */
+var FORBIDDEN_OBJECT_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+/**
+* Rejects bridge/method names that could trigger prototype pollution when used as object keys.
 */
-function buildBridgeMergeEnvForHost(host, slotKey, surface) {
-	return buildDeclarativeBridgeTable(host, slotKey, [...surface.toBridgeDeclarations()]);
+function assertSafeObjectKey(kind, name) {
+	if (FORBIDDEN_OBJECT_KEYS.has(name)) throw new Error(`Invalid surface ${kind} name "${name}": reserved key`);
+}
+/** Record with no inherited prototype — safe for dynamic string keys at runtime. */
+function createNullPrototypeRecord() {
+	return Object.create(null);
+}
+//#endregion
+//#region src/domain/surfaceCapabilities.ts
+/** Runtime list of capability ids declared on a compiled surface spec. */
+function collectCapabilitiesFromHostSurfaceSpec(spec) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const bridgeName of Object.keys(spec)) {
+		const methods = spec[bridgeName];
+		for (const methodName of Object.keys(methods)) {
+			const id = methods[methodName].capability;
+			const key = String(id);
+			if (!seen.has(key)) {
+				seen.add(key);
+				out.push(id);
+			}
+		}
+	}
+	return out;
+}
+/** Narrows `capabilities` to those declared on the surface (runtime check). */
+function pickSurfaceCapabilities(surfaceCapabilities, ...capabilities) {
+	const allowed = new Set(surfaceCapabilities.map((c) => String(c)));
+	for (const id of capabilities) if (!allowed.has(String(id))) throw new Error(`capability not declared on host surface: ${String(id)} (surface has: ${[...allowed].join(", ")})`);
+	return capabilities;
+}
+z.object({});
+var EMPTY_STATE = z.object({});
+function scriptProfileComponentClassName(profileName) {
+	return `${profileName}Component`;
+}
+function scriptProfilePropsAlias(profileName) {
+	return `${profileName}Props`;
+}
+function scriptProfileStateAlias(profileName) {
+	return `${profileName}State`;
+}
+function scriptProfileBridgesClassName(profileName) {
+	return `${profileName}Bridges`;
+}
+/** Bridge table names whose methods include at least one capability from the profile. */
+function bridgeNamesForCapabilities(spec, capabilities) {
+	const allowed = new Set(capabilities.map((c) => String(c)));
+	const names = [];
+	for (const bridgeName of Object.keys(spec)) {
+		const methods = spec[bridgeName];
+		for (const methodName of Object.keys(methods)) {
+			const entry = methods[methodName];
+			if (allowed.has(String(entry.capability))) {
+				names.push(bridgeName);
+				break;
+			}
+		}
+	}
+	return names.sort((a, b) => a.localeCompare(b));
+}
+function resolveScriptProfile(registry, name, spec) {
+	const def = registry[name];
+	if (def === void 0) throw new Error(`unknown script profile: ${name}`);
+	const capabilities = def.capabilities.map((c) => createCapabilityId(c));
+	let props = def.props;
+	let state = def.state ?? EMPTY_STATE;
+	const hooks = [...def.hooks ?? []];
+	let parentName = def.extends;
+	const visited = new Set([name]);
+	while (parentName !== void 0) {
+		if (visited.has(parentName)) throw new Error(`script profile inheritance cycle: ${name}`);
+		visited.add(parentName);
+		const parent = registry[parentName];
+		if (parent === void 0) throw new Error(`script profile "${name}" extends unknown profile "${parentName}"`);
+		const parentCaps = parent.capabilities.map((c) => createCapabilityId(c));
+		for (const cap of parentCaps) if (!capabilities.some((c) => String(c) === String(cap))) capabilities.push(cap);
+		props = parent.props.merge(props);
+		state = (parent.state ?? EMPTY_STATE).merge(state);
+		const parentHooks = parent.hooks ?? [];
+		for (const h of parentHooks) if (!hooks.includes(h)) hooks.push(h);
+		parentName = parent.extends;
+	}
+	hooks.sort((a, b) => a.localeCompare(b));
+	const bridgeNames = bridgeNamesForCapabilities(spec, capabilities);
+	return {
+		name,
+		extends: def.extends,
+		capabilities,
+		props,
+		state,
+		hooks,
+		bridgeNames,
+		references: def.references
+	};
+}
+function buildResolvedScriptProfileRegistry(registry, spec) {
+	const out = {};
+	for (const name of Object.keys(registry)) out[name] = resolveScriptProfile(registry, name, spec);
+	return out;
+}
+function validateScriptProfileRegistry(registry, spec, componentHooks, opts) {
+	if ((opts?.requireAtLeastOne ?? false) && Object.keys(registry).length === 0) throw new Error("host surface: at least one script profile or .componentType() is required");
+	const surfaceCaps = new Set(collectCapabilitiesFromHostSurfaceSpec(spec).map((c) => String(c)));
+	const hookKinds = componentHooks !== void 0 ? new Set(Object.keys(componentHooks)) : /* @__PURE__ */ new Set();
+	for (const name of Object.keys(registry)) {
+		assertSafeObjectKey("componentType", name);
+		const def = registry[name];
+		if (def.extends !== void 0) assertSafeObjectKey("componentType", def.extends);
+		for (const cap of def.capabilities) {
+			const id = createCapabilityId(cap);
+			if (!surfaceCaps.has(String(id))) throw new Error(`script profile "${name}": capability not declared on surface: ${String(cap)}`);
+		}
+		for (const hook of def.hooks ?? []) if (!hookKinds.has(hook)) throw new Error(`script profile "${name}": hook "${hook}" not declared in .componentHooks()`);
+		if (def.extends !== void 0 && registry[def.extends] === void 0) throw new Error(`script profile "${name}" extends unknown profile "${def.extends}"`);
+	}
+	for (const name of Object.keys(registry)) resolveScriptProfile(registry, name, spec);
+}
+//#endregion
+//#region src/domain/scriptCatalogManifest.ts
+/** LuaCATS aliases per catalog scriptId → resolved component class (for `---@type` in `.lua` files). */
+function buildScriptCatalogLuaDefManifest(entries) {
+	return {
+		schemaVersion: 1,
+		output: "generated/scriptCatalog.d.lua",
+		classes: [],
+		aliases: entries.filter((entry) => entry.localComponentClass !== true).slice().sort((a, b) => a.scriptId.localeCompare(b.scriptId)).map((entry) => {
+			const componentClass = scriptProfileComponentClassName(entry.profileId);
+			return {
+				name: scriptCatalogComponentAlias(entry.scriptId),
+				definition: componentClass
+			};
+		}),
+		globals: [],
+		luaHooks: []
+	};
+}
+function scriptCatalogComponentAlias(scriptId) {
+	return `${scriptId.replace(/[^A-Za-z0-9_]/g, "_")}ScriptComponent`;
+}
+//#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,
+}
+
+local ReferencesMT = {
+  __index = function(t, k)
+    local wrap = rawget(_ENV, "__microverse_reference_wrap")
+    local raw = rawget(t, "__raw")
+    local val = raw[k]
+    if type(wrap) == "function" then
+      return wrap(k, val)
+    end
+    return val
+  end,
+}
+
+function __microverse_lua_build_component_impl(bridges)
+  local impl = { state = {}, bridges = type(bridges) == "table" and bridges or {} }
+  local proxy = { __raw = rawProps() }
+  setmetatable(proxy, PropertiesMT)
+  impl.properties = proxy
+  local refProxy = { __raw = rawProps() }
+  setmetatable(refProxy, ReferencesMT)
+  impl.references = refProxy
+  local base = rawget(_ENV, "__microverse_component_hook_base")
+  if type(base) == "table" then
+    setmetatable(impl, { __index = base })
+  end
+  rawset(_ENV, "__microverse_lua_ComponentImpl", impl)
+  return impl
+end
+
+rawset(_ENV, "__microverse_lua_build_component_impl", __microverse_lua_build_component_impl)
+
+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();
+/** Lua prelude that registers `TypeName:extend()` singletons for each component type. */
+function profileBridgeSlotKey(typeName, bridgeName) {
+	return `__mv_${typeName}_${bridgeName}`;
+}
+function profileBridgeNamesMergeEnvKey(typeName) {
+	return `__microverse_profile_bridge_names_${typeName}`;
+}
+function buildComponentTypeBridgeNamesPreludeLua(componentTypes) {
+	const lines = [];
+	for (const typeName of Object.keys(componentTypes).sort((a, b) => a.localeCompare(b))) {
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(typeName)) throw new Error(`unsafe component type name for bridge names prelude: ${typeName}`);
+		const entries = componentTypes[typeName].bridgeNames.map((n) => JSON.stringify(n)).join(", ");
+		lines.push(`rawset(_ENV, ${JSON.stringify(profileBridgeNamesMergeEnvKey(typeName))}, { ${entries} })`);
+	}
+	return lines.join("\n");
+}
+function buildComponentTypeSingletonsPreludeLua(typeNames) {
+	const lines = [
+		"local function __microverse_collect_profile_bridges(typeName)",
+		"  local names = rawget(_ENV, \"__microverse_profile_bridge_names_\" .. typeName)",
+		"  local bridges = {}",
+		"  if type(names) ~= \"table\" then",
+		"    return bridges",
+		"  end",
+		"  for _, name in ipairs(names) do",
+		"    if type(name) == \"string\" then",
+		"      local b = rawget(_ENV, \"__mv_\" .. typeName .. \"_\" .. name)",
+		"      if type(b) == \"table\" then",
+		"        bridges[name] = b",
+		"      end",
+		"    end",
+		"  end",
+		"  return bridges",
+		"end",
+		"local function __microverse_make_type_extend(typeName)",
+		"  return function(self)",
+		"    local ext = rawget(_ENV, \"__microverse_lua_extend_component\")",
+		"    if type(ext) == \"function\" then",
+		"      ext(typeName)",
+		"    end",
+		"    local build = rawget(_ENV, \"__microverse_lua_build_component_impl\")",
+		"    if type(build) ~= \"function\" then",
+		"      error(\"component type extend: build impl missing\")",
+		"    end",
+		"    return build(__microverse_collect_profile_bridges(typeName))",
+		"  end",
+		"end"
+	];
+	for (const name of typeNames) {
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`unsafe component type name for Lua singleton: ${name}`);
+		lines.push(`rawset(_ENV, ${JSON.stringify(name)}, { extend = __microverse_make_type_extend(${JSON.stringify(name)}) })`);
+	}
+	return lines.join("\n");
+}
+/** Applies host-selected profile (same as `Type:extend()` without requiring Lua to call it). */
+function buildApplyHostScriptProfileChunkLua(profileName) {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(profileName)) throw new Error(`unsafe script profile name: ${profileName}`);
+	return [
+		`local T = ${profileName}`,
+		"if type(T) == \"table\" and type(T.extend) == \"function\" then",
+		"  T:extend()",
+		"end"
+	].join("\n");
 }
 //#endregion
 //#region src/infrastructure/adapters/zodSchemaValidationAdapter.ts
@@ -159,29 +545,33 @@ 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 buildComponentEventManifestFields(kinds, componentClassName, 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: ${componentClassName}, 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 +580,115 @@ function pushWorkflowPayloadManifestClasses(kinds, workflowHooks, classes) {
 		});
 	}
 }
-function buildLuaDefManifestFromHostSurfaceSpec(spec, opts, workflowHooks) {
+function pushBaseComponentClass(classes) {
+	classes.push({
+		name: "Component",
+		description: "Base component lifecycle (extended by typed component profiles).",
+		fields: [
+			{
+				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."
+			}
+		],
+		emitSingleton: false
+	});
+}
+function pushProfileBridgesClass(typeName, bridgeNames, classes) {
+	if (bridgeNames.length === 0) return;
+	const bridgesName = scriptProfileBridgesClassName(typeName);
+	classes.push({
+		name: bridgesName,
+		description: `Host bridges for \`${typeName}\` components (\`self.bridges\` after \`${typeName}:extend()\`).`,
+		fields: bridgeNames.map((name) => ({
+			name,
+			luaType: bridgeLuaClassName(name)
+		})),
+		emitSingleton: false
+	});
+}
+function pushComponentTypeManifest(classes, aliases, typeName, profile, componentHooks) {
+	const propsAlias = scriptProfilePropsAlias(typeName);
+	const stateAlias = scriptProfileStateAlias(typeName);
+	aliases.set(propsAlias, zodToLuaTypeRef(profile.props));
+	aliases.set(stateAlias, zodToLuaTypeRef(profile.state));
+	pushProfileBridgesClass(typeName, profile.bridgeNames, classes);
+	const componentClass = scriptProfileComponentClassName(typeName);
+	const bridgesClass = profile.bridgeNames.length > 0 ? scriptProfileBridgesClassName(typeName) : "table";
+	const extendsClass = profile.extends !== void 0 ? scriptProfileComponentClassName(profile.extends) : "Component";
+	const fields = [
+		{
+			name: "properties",
+			luaType: propsAlias,
+			description: "Host-synced props (proxy)."
+		},
+		{
+			name: "state",
+			luaType: stateAlias,
+			description: "Lua-local state."
+		},
+		{
+			name: "bridges",
+			luaType: bridgesClass,
+			description: "Host bridges allowed for this component type."
+		},
+		{
+			name: "init",
+			luaType: `fun(self: ${componentClass})`,
+			description: "Called once after mount and initial props are applied."
+		},
+		{
+			name: "onPropsChanged",
+			luaType: `fun(self: ${componentClass}, key: string, newValue: any)`,
+			description: "Called when the host patches a property key."
+		},
+		{
+			name: "onDestroy",
+			luaType: `fun(self: ${componentClass})`,
+			description: "Called before the script instance slot is disposed."
+		}
+	];
+	if (componentHooks !== void 0 && profile.hooks.length > 0) fields.push(...buildComponentEventManifestFields(profile.hooks, componentClass, componentHooks));
+	classes.push({
+		name: componentClass,
+		extendsClass,
+		description: `Component instance from \`local C = ${typeName}:extend()\`.`,
+		fields,
+		emitSingleton: false
+	});
+	classes.push({
+		name: typeName,
+		description: `Factory for \`${componentClass}\` in this slot.`,
+		methods: [{
+			name: "extend",
+			description: "Creates the active component with profile-scoped bridges.",
+			params: [],
+			returns: componentClass
+		}],
+		emitSingleton: true
+	});
+}
+function pushComponentManifestClasses(classes, aliases, componentTypes, componentHooks) {
+	const eventKinds = componentHooks !== void 0 ? Object.keys(componentHooks).sort((a, b) => a.localeCompare(b)) : [];
+	if (componentHooks !== void 0) pushComponentEventPayloadClasses(eventKinds, componentHooks, classes);
+	pushBaseComponentClass(classes);
+	const typeNames = Object.keys(componentTypes).sort((a, b) => a.localeCompare(b));
+	for (const typeName of typeNames) pushComponentTypeManifest(classes, aliases, typeName, componentTypes[typeName], componentHooks);
+}
+function buildLuaDefManifestFromHostSurfaceSpec(spec, opts, componentHooks, componentTypes) {
 	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 +724,16 @@ function buildLuaDefManifestFromHostSurfaceSpec(spec, opts, workflowHooks) {
 			});
 		}
 		classes.push({
-			name: bridgeName,
-			methods: manifestMethods
+			name: bridgeLuaClassName(bridgeName),
+			methods: manifestMethods,
+			emitSingleton: false
 		});
 	}
 	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"
-			}]
-		});
-	}
+	if (componentTypes !== void 0) pushComponentManifestClasses(classes, merged, componentTypes, componentHooks);
 	const aliases = merged.size === 0 ? void 0 : [...merged.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([name, definition]) => ({
 		name,
 		definition
@@ -396,111 +873,39 @@ function unwrapInputSchema(schema) {
 	return cur;
 }
 //#endregion
-//#region src/domain/surfaceCapabilities.ts
-/** Runtime list of capability ids declared on a compiled surface spec. */
-function collectCapabilitiesFromHostSurfaceSpec(spec) {
-	const out = [];
-	const seen = /* @__PURE__ */ new Set();
-	for (const bridgeName of Object.keys(spec)) {
-		const methods = spec[bridgeName];
-		for (const methodName of Object.keys(methods)) {
-			const id = methods[methodName].capability;
-			const key = String(id);
-			if (!seen.has(key)) {
-				seen.add(key);
-				out.push(id);
-			}
-		}
-	}
-	return out;
-}
-/** Narrows `capabilities` to those declared on the surface (runtime check). */
-function pickSurfaceCapabilities(surfaceCapabilities, ...capabilities) {
-	const allowed = new Set(surfaceCapabilities.map((c) => String(c)));
-	for (const id of capabilities) if (!allowed.has(String(id))) throw new Error(`capability not declared on host surface: ${String(id)} (surface has: ${[...allowed].join(", ")})`);
-	return capabilities;
-}
-//#endregion
-//#region src/domain/capabilityRegistrySymbol.ts
-/**
-* Well-known symbol key used to attach a {@link CapabilityRegistryPort} on the host object
-* while surface bridge methods run. Populated by {@link augmentHostWithCapabilityRegistry} or
-* internally by {@link HostScriptSession}.
-*/
-var MICROVERSE_CAPABILITY_REGISTRY = Symbol.for("microverse:capabilityRegistry");
-//#endregion
-//#region src/application/useCases/compileBridgeDeclarationsFromHostSurfaceSpec.ts
-function isThenable(value) {
-	if (value === null || value === void 0) return false;
-	if (typeof value !== "object" && typeof value !== "function") return false;
-	return typeof value.then === "function";
-}
-/**
-* Builds declarative bridge declarations from a host surface spec, using the schema validation port for Lua ↔ host payloads.
-*/
-function createBridgeDeclarationsFromHostSurfaceSpec(schemaValidation, spec) {
-	const out = [];
-	for (const bridgeName of Object.keys(spec)) {
-		const methods = spec[bridgeName];
-		out.push({
-			name: bridgeName,
-			perEntity: true,
-			createApi: (host, slotKey) => {
-				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 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,
-							slotKey: String(slotKey)
-						}, parsedIn.value);
-						if (isThenable(raw)) return raw.then((resolved) => {
-							const parsedOut = schemaValidation.validateWithZodSchema(entry.output, resolved);
-							if (parsedOut._tag === "err") throw new Error(parsedOut.error);
-							return parsedOut.value;
-						});
-						const parsedOut = schemaValidation.validateWithZodSchema(entry.output, raw);
-						if (parsedOut._tag === "err") throw new Error(parsedOut.error);
-						return parsedOut.value;
-					};
-				}
-				return Object.freeze(api);
-			}
-		});
-	}
-	return out;
-}
-//#endregion
 //#region src/application/useCases/compileHostSurface.ts
-function buildHostSurfaceCore(schemaValidation, spec, workflowHooks) {
+function buildHostSurfaceCore(schemaValidation, spec, componentTypeRegistry, componentHooks) {
+	validateScriptProfileRegistry(componentTypeRegistry, spec, componentHooks, { requireAtLeastOne: false });
+	const componentTypes = buildResolvedScriptProfileRegistry(componentTypeRegistry, spec);
 	const capabilities = collectCapabilitiesFromHostSurfaceSpec(spec);
 	return {
+		getHostSurfaceSpec: () => spec,
 		toBridgeDeclarations: () => createBridgeDeclarationsFromHostSurfaceSpec(schemaValidation, spec),
-		toLuaDefManifest: (opts) => buildLuaDefManifestFromHostSurfaceSpec(spec, opts, workflowHooks),
+		toLuaDefManifest: (opts) => buildLuaDefManifestFromHostSurfaceSpec(spec, opts, componentHooks, componentTypes),
 		capabilities,
+		componentTypes,
+		getComponentType: (name) => {
+			const profile = componentTypes[name];
+			if (profile === void 0) throw new Error(`unknown component type: ${name}`);
+			return profile;
+		},
 		pickCapabilities: (...picked) => pickSurfaceCapabilities(capabilities, ...picked)
 	};
 }
-function compileHostSurface(ports, spec, workflowHooks) {
+function compileHostSurface(ports, spec, componentTypeRegistry, componentHooks) {
 	const [schemaValidation] = ports;
-	const core = buildHostSurfaceCore(schemaValidation, spec, workflowHooks);
-	if (workflowHooks === void 0) return core;
+	const core = buildHostSurfaceCore(schemaValidation, spec, componentTypeRegistry, 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, componentTypeRegistry, componentHooks) {
+	return componentHooks === void 0 ? compileHostSurface(ports, spec, componentTypeRegistry) : compileHostSurface(ports, spec, componentTypeRegistry, componentHooks);
 }
 //#endregion
 //#region src/domain/inferMethodAsync.ts
@@ -527,35 +932,18 @@ function normalizeMethodDef(def) {
 	};
 }
 //#endregion
-//#region src/domain/safeObjectKey.ts
-/** Keys that must not be used as dynamic property names on ordinary objects. */
-var FORBIDDEN_OBJECT_KEYS = new Set([
-	"__proto__",
-	"constructor",
-	"prototype"
-]);
-/**
-* Rejects bridge/method names that could trigger prototype pollution when used as object keys.
-*/
-function assertSafeObjectKey(kind, name) {
-	if (FORBIDDEN_OBJECT_KEYS.has(name)) throw new Error(`Invalid surface ${kind} name "${name}": reserved key`);
-}
-/** Record with no inherited prototype — safe for dynamic string keys at runtime. */
-function createNullPrototypeRecord() {
-	return Object.create(null);
-}
-//#endregion
 //#region src/infrastructure/builders/surfaceBuilder.ts
 /**
 * Fluent builder for a host surface. Created via {@link defineHostSurfaceFor} / {@link defineHostSurface} factory overloads.
 */
 var SurfaceBuilder = class SurfaceBuilder {
 	spec = createNullPrototypeRecord();
-	workflowHooksSpec;
+	componentTypeRegistry = createNullPrototypeRecord();
+	componentHooksSpec;
 	ports;
-	constructor(ports, workflowHooks, initialSpec) {
+	constructor(ports, componentHooks, initialSpec, initialComponentTypes) {
 		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];
@@ -566,19 +954,27 @@ var SurfaceBuilder = class SurfaceBuilder {
 			}
 			this.spec[bridgeName] = bridge;
 		}
+		if (initialComponentTypes !== void 0) for (const name of Object.keys(initialComponentTypes)) this.componentTypeRegistry[name] = initialComponentTypes[name];
+	}
+	/** Declares a typed Lua component profile (props, state, capabilities, hooks). */
+	componentType(name, def) {
+		assertSafeObjectKey("componentType", name);
+		this.componentTypeRegistry[name] = def;
+		return this;
 	}
 	/** Opens a Lua bridge table (e.g. `orders`, `greet`). */
 	bridge(name) {
 		return new BridgeBuilder(this, name);
 	}
-	/** Attaches workflow hook Zod schemas (emitted into `.d.lua` as `on*` methods). */
-	workflowHooks(hooks) {
-		return new SurfaceBuilder(this.ports, hooks, this.spec);
+	/** Attaches component domain-event Zod schemas (emitted into `.d.lua` as `on*` methods on component types). */
+	componentHooks(hooks) {
+		return new SurfaceBuilder(this.ports, hooks, this.spec, this.componentTypeRegistry);
 	}
 	/** Compiles the accumulated spec into a {@link HostSurface}. */
 	build() {
 		const spec = this.spec;
-		return compileHostSurfaceFor(this.ports, spec, this.workflowHooksSpec);
+		const registry = this.componentTypeRegistry;
+		return compileHostSurfaceFor(this.ports, spec, registry, this.componentHooksSpec);
 	}
 	/** @internal */
 	addMethod(bridgeName, methodName, entry) {
@@ -654,73 +1050,244 @@ function defineHostSurfaceFor() {
 	return createSurfaceBuilder();
 }
 //#endregion
-//#region src/infrastructure/adapters/augmentHostWithCapabilityRegistry.ts
-/**
-* Returns a shallow copy of `host` with {@link MICROVERSE_CAPABILITY_REGISTRY} set to `registry`.
-* Bridge handlers read the registry to enforce per-session capability allowlists.
-*
-* @param host - Your engine / service context passed into `buildDeclarativeBridgeTable`.
-* @param registry - Typically an {@link InMemoryCapabilityRegistry} from `@microverse.ts/runtime-capabilities`.
-*/
-function augmentHostWithCapabilityRegistry(host, registry) {
-	return Object.assign(host, { [MICROVERSE_CAPABILITY_REGISTRY]: registry });
+//#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/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 defaultSchemaValidation = createZodSchemaValidationPort();
 var HostScriptSession = class {
 	opts;
 	sandbox;
-	registry;
+	hostProps = {};
+	schemaValidation;
+	activeComponentType;
+	hostProfileApplied = false;
+	context;
 	constructor(opts) {
 		this.opts = opts;
-		this.registry = new InMemoryCapabilityRegistry(createAllowlist([...opts.allowedCapabilities]));
+		this.schemaValidation = opts.schemaValidation ?? defaultSchemaValidation;
+		this.context = opts.script;
+		if (opts.resolvedProfile !== void 0) this.activeComponentType = opts.resolvedProfile.name;
+		else if (opts.profileId !== void 0) this.activeComponentType = opts.profileId;
 	}
-	/**
-	* 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
 			});
+			const activeProfile = this.tryGetActiveProfile();
+			const singletonName = this.profileSingletonName();
+			const typeNames = this.singletonTypeNames();
+			if (typeNames.length > 0) {
+				const bridgeRegistry = activeProfile !== void 0 ? { [activeProfile.name]: activeProfile } : this.opts.surface.componentTypes;
+				await sb.run({
+					script: createMicroverseScript([buildComponentTypeBridgeNamesPreludeLua(bridgeRegistry), buildComponentTypeSingletonsPreludeLua(typeNames)].join("\n")),
+					mergeEnv: this.mergeEnv(),
+					timeout: this.opts.defaultTimeout
+				});
+				if (singletonName !== void 0) {
+					await sb.run({
+						script: createMicroverseScript(buildApplyHostScriptProfileChunkLua(singletonName)),
+						mergeEnv: this.mergeEnv(),
+						timeout: this.opts.defaultTimeout
+					});
+					this.hostProfileApplied = true;
+				}
+			}
+			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);
+		const host = augmentHostWithScriptContext(this.opts.host, this.opts.script);
+		const spec = this.opts.surface.getHostSurfaceSpec();
+		const env = { __microverse_lua_extend_component: (typeName) => {
+			if (this.opts.resolvedProfile !== void 0 && typeName === this.profileSingletonName()) {
+				this.activeComponentType = this.opts.resolvedProfile.name;
+				return;
+			}
+			this.opts.surface.getComponentType(typeName);
+			this.activeComponentType = typeName;
+		} };
+		const activeProfile = this.tryGetActiveProfile();
+		const typeNames = activeProfile !== void 0 ? [activeProfile.name] : Object.keys(this.opts.surface.componentTypes);
+		for (const typeName of typeNames) {
+			const profile = activeProfile !== void 0 && typeName === activeProfile.name ? activeProfile : this.opts.surface.getComponentType(typeName);
+			const bridgeTable = buildBridgeMergeEnvForProfile(this.schemaValidation, host, String(this.opts.slotKey), spec, profile.capabilities);
+			for (const bridgeName of profile.bridgeNames) env[profileBridgeSlotKey(typeName, bridgeName)] = bridgeTable[bridgeName];
+		}
+		const profileForRefs = this.tryGetActiveProfile();
+		if (profileForRefs?.references !== void 0 && this.opts.referenceResolver !== void 0) {
+			const profile = profileForRefs;
+			env.__microverse_reference_wrap = (field, raw) => this.wrapReference(field, raw, profile);
+		}
+		return env;
 	}
-	/**
-	* 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).
-	*/
+	wrapReference(field, raw, profile) {
+		const resolver = this.opts.referenceResolver;
+		const refs = profile.references;
+		if (resolver === void 0 || refs === void 0) return raw;
+		const def = refs[field];
+		if (def === void 0) return raw;
+		const rawId = raw === null || raw === void 0 ? null : typeof raw === "string" ? raw : typeof raw === "number" || typeof raw === "boolean" ? String(raw) : null;
+		return resolver.wrap({
+			slotKey: String(this.opts.slotKey),
+			field,
+			raw: rawId,
+			kind: def.kind,
+			componentType: referenceComponentType(def)
+		});
+	}
+	emitAudit(event) {
+		this.opts.onScriptAudit?.(event);
+	}
+	getActiveProfileName() {
+		return this.activeComponentType ?? this.opts.profileId;
+	}
+	profileSingletonName() {
+		return this.opts.profileSingleton ?? this.opts.profileId ?? this.opts.resolvedProfile?.name;
+	}
+	singletonTypeNames() {
+		const singleton = this.profileSingletonName();
+		const fromSurface = Object.keys(this.opts.surface.componentTypes);
+		const names = new Set(fromSurface);
+		if (singleton !== void 0) names.add(singleton);
+		return [...names].sort((a, b) => a.localeCompare(b));
+	}
+	tryGetActiveProfile() {
+		if (this.opts.resolvedProfile !== void 0) return this.opts.resolvedProfile;
+		const name = this.getActiveProfileName();
+		if (name === void 0) return;
+		try {
+			return this.opts.surface.getComponentType(name);
+		} catch {
+			return;
+		}
+	}
+	validatePropsBag(bag) {
+		const profile = this.tryGetActiveProfile();
+		if (profile === void 0) throw new Error("HostScriptSession: set profileId or resolvedProfile before props or host sync");
+		const parsed = profile.props.parse(bag);
+		assertValidScriptPropertyBag(parsed);
+		return parsed;
+	}
+	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 +1295,44 @@ 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 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 +1344,55 @@ 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);
+	};
+	getHostProfileApplied = () => this.hostProfileApplied;
 };
+function referenceComponentType(def) {
+	if (def.kind === "entityComponentRef" || def.kind === "entityComponentRefArray") return def.componentType;
+}
 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 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 +1411,26 @@ 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 };
+//#region src/domain/capabilityRegistrySymbol.ts
+/**
+* Well-known symbol key used to attach a {@link CapabilityRegistryPort} on the host object
+* while surface bridge methods run. Populated by {@link augmentHostWithCapabilityRegistry} or
+* internally by {@link HostScriptSession}.
+*/
+var MICROVERSE_CAPABILITY_REGISTRY = Symbol.for("microverse:capabilityRegistry");
+//#endregion
+//#region src/infrastructure/adapters/augmentHostWithCapabilityRegistry.ts
+/**
+* Returns a shallow copy of `host` with {@link MICROVERSE_CAPABILITY_REGISTRY} set to `registry`.
+* Bridge handlers read the registry to enforce per-session capability allowlists.
+*
+* @param host - Your engine / service context passed into `buildDeclarativeBridgeTable`.
+* @param registry - Typically an {@link InMemoryCapabilityRegistry} from `@microverse.ts/runtime-capabilities`.
+*/
+function augmentHostWithCapabilityRegistry(host, registry) {
+	return Object.assign(host, { [MICROVERSE_CAPABILITY_REGISTRY]: registry });
+}
+//#endregion
+export { BridgeBuilder, HostScriptSession, MICROVERSE_CAPABILITY_REGISTRY, MICROVERSE_LUA_COMPONENT_SLOT_PRELUDE, MICROVERSE_SCRIPT_CONTEXT, SurfaceBuilder, augmentHostWithCapabilityRegistry, augmentHostWithScriptContext, buildBridgeMergeEnvForProfile, buildComponentTypeSingletonsPreludeLua, buildResolvedScriptProfileRegistry, buildScriptCatalogLuaDefManifest, collectCapabilitiesFromHostSurfaceSpec, compileHostSurface, compileHostSurfaceFor, createBridgeDeclarationsFromHostSurfaceSpec, defineHostSurface, defineHostSurfaceFor, luaGlobalHookName, luaType, mergeEnvSinkToScriptPropertyBag, pickSurfaceCapabilities, resolveScriptProfile, scriptCatalogComponentAlias, scriptProfileBridgesClassName, scriptProfileComponentClassName, scriptProfilePropsAlias, scriptProfileStateAlias, scriptPropertyBagToMergeEnv, scriptPropertyValueToPlain, zodToLuaTypeRef };
 
 //# sourceMappingURL=index.js.map