@microverse.ts/host-surface 0.2.0 → 0.3.0

package/dist/index.js

@@ -1,22 +1,404 @@
 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 { createCapabilityId } from "@microverse.ts/runtime-capabilities";
+import { z } from "zod";
+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}`;
 }
-/** Bridge table names for `__microverse_bridge_names` in the slot env. */
-function bridgeNamesFromSurface(surface) {
-	return surface.toBridgeDeclarations().map((d) => d.name);
+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
@@ -167,19 +549,7 @@ function asyncHandleClassName(bridgeName, methodName) {
 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) {
+function buildComponentEventManifestFields(kinds, componentClassName, componentHooks) {
 	const out = [];
 	for (const kind of kinds) {
 		if (!(componentHooks[kind] instanceof z.ZodObject)) throw new Error(`defineHostSurface componentHooks: "${kind}" must be a z.object(...)`);
@@ -188,7 +558,7 @@ function buildComponentEventManifestFields(kinds, componentHooks) {
 		out.push({
 			name: hookName,
 			description: `Host invokes when \`${kind}\` is emitted. Payload: \`${payloadName}\`.`,
-			luaType: `fun(self: Component, evt: ${payloadName})`
+			luaType: `fun(self: ${componentClassName}, evt: ${payloadName})`
 		});
 	}
 	return out;
@@ -210,60 +580,112 @@ function pushComponentEventPayloadClasses(kinds, componentHooks, classes) {
 		});
 	}
 }
-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 = [
+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: "table",
+			luaType: propsAlias,
 			description: "Host-synced props (proxy)."
 		},
 		{
 			name: "state",
-			luaType: "table",
+			luaType: stateAlias,
 			description: "Lua-local state."
 		},
 		{
 			name: "bridges",
-			luaType: bridgeNames.length > 0 ? "MicroverseBridges" : "table",
-			description: "Host bridges allowed for this instance (not global in the slot)."
+			luaType: bridgesClass,
+			description: "Host bridges allowed for this component type."
 		},
 		{
 			name: "init",
-			luaType: "fun(self: Component)",
+			luaType: `fun(self: ${componentClass})`,
 			description: "Called once after mount and initial props are applied."
 		},
 		{
 			name: "onPropsChanged",
-			luaType: "fun(self: Component, key: string, newValue: any)",
+			luaType: `fun(self: ${componentClass}, key: string, newValue: any)`,
 			description: "Called when the host patches a property key."
 		},
 		{
 			name: "onDestroy",
-			luaType: "fun(self: Component)",
+			luaType: `fun(self: ${componentClass})`,
 			description: "Called before the script instance slot is disposed."
 		}
 	];
-	if (componentHooks !== void 0) lifecycleFields.push(...buildComponentEventManifestFields(eventKinds, componentHooks));
+	if (componentHooks !== void 0 && profile.hooks.length > 0) fields.push(...buildComponentEventManifestFields(profile.hooks, componentClass, 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,
+		name: componentClass,
+		extendsClass,
+		description: `Component instance from \`local C = ${typeName}:extend()\`.`,
+		fields,
 		emitSingleton: false
 	});
 	classes.push({
-		name: "component",
-		description: "Per-slot helper injected by the host. Use `component:extend()` to create the active component.",
+		name: typeName,
+		description: `Factory for \`${componentClass}\` in this slot.`,
 		methods: [{
 			name: "extend",
-			description: "Returns the component table with `properties`, `state`, and `bridges` wired for this slot.",
+			description: "Creates the active component with profile-scoped bridges.",
 			params: [],
-			returns: "Component"
-		}]
+			returns: componentClass
+		}],
+		emitSingleton: true
 	});
 }
-function buildLuaDefManifestFromHostSurfaceSpec(spec, opts, componentHooks) {
+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 = [];
 	const bridgeNames = Object.keys(spec).sort((a, b) => a.localeCompare(b));
 	for (const bridgeName of bridgeNames) {
@@ -307,12 +729,11 @@ function buildLuaDefManifestFromHostSurfaceSpec(spec, opts, componentHooks) {
 			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);
-	pushComponentManifestClasses(classes, bridgeNames, componentHooks);
+	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
@@ -452,110 +873,28 @@ 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/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 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 = 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 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);
-							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, componentHooks) {
+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, componentHooks),
+		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, componentHooks) {
+function compileHostSurface(ports, spec, componentTypeRegistry, componentHooks) {
 	const [schemaValidation] = ports;
-	const core = buildHostSurfaceCore(schemaValidation, spec, componentHooks);
+	const core = buildHostSurfaceCore(schemaValidation, spec, componentTypeRegistry, componentHooks);
 	if (componentHooks === void 0) return core;
 	return {
 		...core,
@@ -565,8 +904,8 @@ function compileHostSurface(ports, spec, componentHooks) {
 /**
 * Same as {@link compileHostSurface}, but requires every bridge method to be typed with the same `THost`.
 */
-function compileHostSurfaceFor(ports, spec, componentHooks) {
-	return componentHooks === void 0 ? compileHostSurface(ports, spec) : compileHostSurface(ports, spec, componentHooks);
+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
@@ -593,33 +932,16 @@ 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();
+	componentTypeRegistry = createNullPrototypeRecord();
 	componentHooksSpec;
 	ports;
-	constructor(ports, componentHooks, initialSpec) {
+	constructor(ports, componentHooks, initialSpec, initialComponentTypes) {
 		this.ports = ports;
 		this.componentHooksSpec = componentHooks;
 		if (initialSpec !== void 0) for (const bridgeName of Object.keys(initialSpec)) {
@@ -632,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 component domain-event Zod schemas (emitted into `.d.lua` as `on*` methods on `Component`). */
+	/** 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);
+		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.componentHooksSpec);
+		const registry = this.componentTypeRegistry;
+		return compileHostSurfaceFor(this.ports, spec, registry, this.componentHooksSpec);
 	}
 	/** @internal */
 	addMethod(bridgeName, methodName, entry) {
@@ -720,99 +1050,6 @@ 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 = {};
@@ -857,34 +1094,27 @@ function plainToScriptPropertyValue(value) {
 	}
 }
 //#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
 //#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
+var defaultSchemaValidation = createZodSchemaValidationPort();
 var HostScriptSession = class {
 	opts;
 	sandbox;
 	hostProps = {};
-	registry;
+	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;
 	}
 	openSession = async () => {
 		this.sandbox = await this.opts.runtime.createMicroverse({ slotKey: this.opts.slotKey });
@@ -895,11 +1125,25 @@ var HostScriptSession = class {
 				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 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);
@@ -911,25 +1155,82 @@ var HostScriptSession = class {
 			}
 		}
 	};
-	getCapabilityRegistry = () => this.registry;
 	requireMicroverseSlot() {
 		if (this.sandbox === void 0) throw new Error("HostScriptSession: openSession() was not called");
 		return this.sandbox;
 	}
 	mergeEnv() {
-		return buildBridgeMergeEnvForHost(augmentHostWithScriptContext(augmentHostWithCapabilityRegistry(this.opts.host, this.registry), this.opts.script), 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;
+	}
+	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);
 	}
-	validatePropsBag(bag) {
-		if (this.opts.propsSchema !== void 0) {
-			const parsed = this.opts.propsSchema.parse(bag);
-			assertValidScriptPropertyBag(parsed);
-			return parsed;
+	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;
 		}
-		assertValidScriptPropertyBag(bag);
-		return bag;
+	}
+	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) => {
@@ -1009,8 +1310,6 @@ var HostScriptSession = class {
 		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)`,
@@ -1058,7 +1357,11 @@ var HostScriptSession = class {
 		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}`);
 }
@@ -1066,9 +1369,6 @@ function readComponentHooks(surface) {
 	if (!("componentHooks" in surface)) return;
 	return surface.componentHooks;
 }
-function buildBridgeNamesPreludeLua(bridgeNames) {
-	return `rawset(_ENV, "__microverse_bridge_names", { ${bridgeNames.map((n) => JSON.stringify(n)).join(", ")} })`;
-}
 function buildComponentEventStubPreludeLua(hooks) {
 	return [
 		"local Base = {}",
@@ -1111,6 +1411,26 @@ function luaTableLiteralFromUnknownRecord(o) {
 	return `{ ${parts.join(", ")} }`;
 }
 //#endregion
-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 };
+//#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