@microverse.ts/host-surface 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QADRAX
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# `@microverse.ts/host-surface`
+
+Declare a **host surface** in TypeScript: Zod schemas, capabilities, and handlers that compile into:
+
+1. **Runtime bridge tables** for `mergeEnv` (what Lua calls at execution time).
+2. A **`LuaDefManifest`** for `@microverse.ts/lua-defs` (`.d.lua` stubs for LuaLS).
+
+Most applications import **`defineHostSurfaceFor`** from **`@microverse.ts/microverse-lua`** instead of this package directly. Use `@microverse.ts/host-surface` when you need `HostScriptSession` or custom runtime wiring.
+
+Monorepo overview: [root README](../../README.md). Lua microverse lifecycle: [`@microverse.ts/microverse-lua`](../microverse-lua/README.md).
+
+## Defining a surface
+
+```ts
+import { defineHostSurfaceFor } from '@microverse.ts/microverse-lua';
+import { z } from 'zod';
+
+export default defineHostSurfaceFor<MyHost>()
+  .bridge('orders')
+  .method('get', {
+    requires: 'orders:read',
+    input: z.object({ orderId: z.string() }),
+    output: orderDto,
+    description: 'Load order by id',
+    handler: ({ host }, { orderId }) => host.orders.get(orderId),
+  })
+  .workflowHooks(workflowHooks) // optional
+  .build();
+```
+
+| Step | Role |
+|------|------|
+| `defineHostSurfaceFor<THost>()` | Start builder; `handler` receives typed `host`. |
+| `.bridge('orders')` | Lua global table name. |
+| `.method('get', { … })` | One bridge method: `requires`, `input`, `output`, `handler`. |
+| `.workflowHooks(…)` | Optional Zod map → `on*` hooks in Lua. |
+| `.build()` | Compiled {@link HostSurface}. |
+
+`requires` is a `domain:action` capability string. `async` is inferred from `async function` handlers.
+
+Bridge names become **Lua global tables** (`orders`, `billing`, …). Do not use `workflow` as a bridge name when workflow hooks are enabled—that name is reserved for the injected `workflow:extend()` helper.
+
+### Host object
+
+The **host** is your engine context (services, repos, config). It is not generated here—you construct it in your app and pass it to `MicroverseLua.create({ host, surface })` or `HostScriptSession`.
+
+### Workflow hooks
+
+Call `.workflowHooks({ OrderPlaced: z.object({ … }), … })` before `.build()`.
+
+- TypeScript emits via `emitToAllScripts('OrderPlaced', payload)`.
+- Lua implements `onOrderPlaced` on the table from `workflow:extend()`.
+- Manifest includes `MicroverseWorkflowEvt_*` classes in `.d.lua`.
+
+## `HostScriptSession`
+
+Lower-level API when you manage slots yourself (one session = one env slot + capability allowlist):
+
+```ts
+const session = new HostScriptSession({
+  runtime,
+  surface,
+  host,
+  slotKey: createLuaEnvSlotKey('script:my-id'),
+  allowedCapabilities: surface.pickCapabilities('orders:read'),
+});
+await session.openSession();
+await session.runChunk(luaSource);
+```
+
+`MicroverseLua` in `@microverse.ts/microverse-lua` wraps this for the common case (shared VM, `registerScript`, broadcast hooks).
+
+## Generating `.d.lua`
+
+```bash
+microverse generate-lua-defs --surface src/mySurface.ts
+```
+
+Requires `export default` of the compiled surface (`.build()` result). See [`@microverse.ts/cli`](../cli/README.md) and [`@microverse.ts/lua-defs`](../lua-defs/README.md).
+
+Optional **Lua type names** on Zod schemas (`luaType('OrderDto', z.object({ … }))`) improve stub names—see `examples/business-scripting-engine/src/schemas/surface/bridgePayloads.ts`.
+
+## Async bridges and Lua patterns
+
+Bridge handlers are **synchronous at the Lua boundary**; Wasmoon does not auto-resolve `Promise` into Lua values. For async TypeScript work, use the async bridge pattern (`:await()` or `onComplete` callback) documented in:
+
+- [docs/async-subroutines-components.md](docs/async-subroutines-components.md)
+- [examples/business-scripting-engine/docs/COMPONENT_PATTERN.md](../../examples/business-scripting-engine/docs/COMPONENT_PATTERN.md)
+
+## Reference
+
+- Example surface: [`examples/business-scripting-engine/src/businessSurface.ts`](../../examples/business-scripting-engine/src/businessSurface.ts)
+- Tests: `src/domain/`, `src/application/`, `src/infrastructure/`

package/dist/application/ports/SchemaValidationPort.d.ts

@@ -0,0 +1,9 @@
+import { Result } from '@microverse.ts/shared';
+import { z } from 'zod';
+/**
+ * Validates unknown payloads against Zod schemas (bridge IO, etc.).
+ */
+export type SchemaValidationPort = {
+    readonly validateWithZodSchema: <T>(schema: z.ZodType<T>, payload: unknown) => Result<T, string>;
+};
+//# sourceMappingURL=SchemaValidationPort.d.ts.map

package/dist/application/ports/SchemaValidationPort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaValidationPort.d.ts","sourceRoot":"","sources":["../../../src/application/ports/SchemaValidationPort.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,qBAAqB,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;CAClG,CAAC"}

package/dist/application/useCases/compileBridgeDeclarationsFromHostSurfaceSpec.d.ts

@@ -0,0 +1,9 @@
+import { DeclarativeBridgeDeclaration } from '@microverse.ts/runtime-bridge';
+import { WithMicroverseCapabilityRegistry } from '../../domain/capabilityRegistrySymbol.js';
+import { HostSurfaceSpec } from '../../domain/hostSurfaceTypes.js';
+import { SchemaValidationPort } from '../ports/SchemaValidationPort.js';
+/**
+ * Builds declarative bridge declarations from a host surface spec, using the schema validation port for Lua ↔ host payloads.
+ */
+export declare function createBridgeDeclarationsFromHostSurfaceSpec<TSpec extends HostSurfaceSpec>(schemaValidation: SchemaValidationPort, spec: TSpec): ReadonlyArray<DeclarativeBridgeDeclaration<WithMicroverseCapabilityRegistry, string>>;
+//# sourceMappingURL=compileBridgeDeclarationsFromHostSurfaceSpec.d.ts.map

package/dist/application/useCases/compileBridgeDeclarationsFromHostSurfaceSpec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compileBridgeDeclarationsFromHostSurfaceSpec.d.ts","sourceRoot":"","sources":["../../../src/application/useCases/compileBridgeDeclarationsFromHostSurfaceSpec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAGlF,OAAO,EAAkC,KAAK,gCAAgC,EAAE,MAAM,0CAA0C,CAAC;AAGjI,OAAO,KAAK,EAAwB,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAC9F,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAa7E;;GAEG;AACH,wBAAgB,2CAA2C,CAAC,KAAK,SAAS,eAAe,EACvF,gBAAgB,EAAE,oBAAoB,EACtC,IAAI,EAAE,KAAK,GACV,aAAa,CAAC,4BAA4B,CAAC,gCAAgC,EAAE,MAAM,CAAC,CAAC,CA+CvF"}

package/dist/application/useCases/compileHostSurface.d.ts

@@ -0,0 +1,13 @@
+import { InferSurfaceCapabilities } from '../../domain/surfaceCapabilities.js';
+import { HostSurface, HostSurfaceSpec, HostWorkflowHooksSpec } from '../../domain/hostSurfaceTypes.js';
+import { SchemaValidationPort } from '../ports/SchemaValidationPort.js';
+/**
+ * Compiles a host surface using the injected schema validation port (tuple matches `UseCase` conventions in `@microverse.ts/shared`).
+ */
+export declare function compileHostSurface<const TSpec extends HostSurfaceSpec>(ports: readonly [SchemaValidationPort], spec: TSpec): HostSurface<undefined, InferSurfaceCapabilities<TSpec>>;
+export declare function compileHostSurface<const TSpec extends HostSurfaceSpec, const THooks extends HostWorkflowHooksSpec>(ports: readonly [SchemaValidationPort], spec: TSpec, workflowHooks: THooks): HostSurface<THooks, InferSurfaceCapabilities<TSpec>>;
+/**
+ * Same as {@link compileHostSurface}, but requires every bridge method to be typed with the same `THost`.
+ */
+export declare function compileHostSurfaceFor<const TSpec extends HostSurfaceSpec, const THooks extends HostWorkflowHooksSpec | undefined = undefined>(ports: readonly [SchemaValidationPort], spec: TSpec, workflowHooks?: THooks): THooks extends HostWorkflowHooksSpec ? HostSurface<THooks, InferSurfaceCapabilities<TSpec>> : HostSurface<undefined, InferSurfaceCapabilities<TSpec>>;
+//# sourceMappingURL=compileHostSurface.d.ts.map

package/dist/application/useCases/compileHostSurface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compileHostSurface.d.ts","sourceRoot":"","sources":["../../../src/application/useCases/compileHostSurface.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EACV,WAAW,EAEX,eAAe,EACf,qBAAqB,EACtB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAoB7E;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,KAAK,SAAS,eAAe,EACpE,KAAK,EAAE,SAAS,CAAC,oBAAoB,CAAC,EACtC,IAAI,EAAE,KAAK,GACV,WAAW,CAAC,SAAS,EAAE,wBAAwB,CAAC,KAAK,CAAC,CAAC,CAAC;AAC3D,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,KAAK,SAAS,eAAe,EACnC,KAAK,CAAC,MAAM,SAAS,qBAAqB,EAE1C,KAAK,EAAE,SAAS,CAAC,oBAAoB,CAAC,EACtC,IAAI,EAAE,KAAK,EACX,aAAa,EAAE,MAAM,GACpB,WAAW,CAAC,MAAM,EAAE,wBAAwB,CAAC,KAAK,CAAC,CAAC,CAAC;AAcxD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,CAAC,KAAK,SAAS,eAAe,EACnC,KAAK,CAAC,MAAM,SAAS,qBAAqB,GAAG,SAAS,GAAG,SAAS,EAElE,KAAK,EAAE,SAAS,CAAC,oBAAoB,CAAC,EACtC,IAAI,EAAE,KAAK,EACX,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,SAAS,qBAAqB,GACnC,WAAW,CAAC,MAAM,EAAE,wBAAwB,CAAC,KAAK,CAAC,CAAC,GACpD,WAAW,CAAC,SAAS,EAAE,wBAAwB,CAAC,KAAK,CAAC,CAAC,CAQ1D"}

package/dist/domain/capabilityRegistrySymbol.d.ts

@@ -0,0 +1,14 @@
+import { CapabilityRegistryPort } from '@microverse.ts/runtime-capabilities';
+/**
+ * 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}.
+ */
+export declare const MICROVERSE_CAPABILITY_REGISTRY: unique symbol;
+/**
+ * Host object extended with the capability registry required by host-surface bridge wrappers.
+ */
+export type WithMicroverseCapabilityRegistry = {
+    readonly [MICROVERSE_CAPABILITY_REGISTRY]: CapabilityRegistryPort;
+};
+//# sourceMappingURL=capabilityRegistrySymbol.d.ts.map

package/dist/domain/capabilityRegistrySymbol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilityRegistrySymbol.d.ts","sourceRoot":"","sources":["../../src/domain/capabilityRegistrySymbol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,eAA8C,CAAC;AAE1F;;GAEG;AACH,MAAM,MAAM,gCAAgC,GAAG;IAC7C,QAAQ,CAAC,CAAC,8BAA8B,CAAC,EAAE,sBAAsB,CAAC;CACnE,CAAC"}

package/dist/domain/hostSurfaceManifest.d.ts

@@ -0,0 +1,8 @@
+import { LuaDefManifest } from '@microverse.ts/lua-defs';
+import { HostSurfaceSpec, HostWorkflowHooksSpec } from './hostSurfaceTypes.js';
+export declare function buildLuaDefManifestFromHostSurfaceSpec(spec: HostSurfaceSpec, opts: {
+    readonly output: string;
+    readonly headerNote?: string | undefined;
+    readonly luaTypeAliases?: Readonly<Record<string, string>> | undefined;
+}, workflowHooks?: HostWorkflowHooksSpec): LuaDefManifest;
+//# sourceMappingURL=hostSurfaceManifest.d.ts.map

package/dist/domain/hostSurfaceManifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostSurfaceManifest.d.ts","sourceRoot":"","sources":["../../src/domain/hostSurfaceManifest.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EAMf,MAAM,yBAAyB,CAAC;AAGjC,OAAO,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AA0DpF,wBAAgB,sCAAsC,CACpD,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE;IACJ,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;CACxE,EACD,aAAa,CAAC,EAAE,qBAAqB,GACpC,cAAc,CAiGhB"}

package/dist/domain/hostSurfaceTypes.d.ts

@@ -0,0 +1,135 @@
+import { LuaDefManifest } from '@microverse.ts/lua-defs';
+import { DeclarativeBridgeDeclaration } from '@microverse.ts/runtime-bridge';
+import { CapabilityId } from '@microverse.ts/runtime-capabilities';
+import { z } from 'zod';
+import { SurfaceCapabilityString } from './surfaceCapabilityString.js';
+import { WithMicroverseCapabilityRegistry } from './capabilityRegistrySymbol.js';
+/**
+ * Context passed to every surface `handler`: your typed host plus the active Lua **slot key** (string form).
+ *
+ * @typeParam THost - Host services / world object you declare for bridge handlers.
+ */
+export type HostFnContext<THost> = {
+    readonly host: THost;
+    /** Stable slot identifier for this sandbox (same convention as `DeclarativeBridgeDeclaration`). */
+    readonly slotKey: string;
+};
+/**
+ * Strongly typed description of one bridge method (produced by the fluent `.method(…)` builder).
+ * TypeScript checks `handler` against `input` / `output` schemas.
+ *
+ * @typeParam THost - Host type available as `ctx.host` inside `handler`.
+ * @typeParam TIn - Payload type after Zod `input` parsing (Lua calls the bridge with one table argument).
+ * @typeParam TOut - Return type validated by Zod `output` before crossing back to Lua.
+ * @typeParam TCap - Capability id for this method (from fluent `requires: 'domain:action'`).
+ */
+export type HostSurfaceMethodEntry<THost, TIn, TOut, TCap extends CapabilityId = CapabilityId> = {
+    /** Capability required to invoke this method; checked against the session registry before the handler runs. */
+    readonly capability: TCap;
+    /** Zod schema for the single payload object from Lua (e.g. `z.object({ id: z.string() })`). */
+    readonly input: z.ZodType<TIn>;
+    /** Zod schema for the value returned to Lua. */
+    readonly output: z.ZodType<TOut>;
+    /**
+     * Host logic at the Lua↔JS boundary. May return `Promise<TOut>`; Lua must use `:await()` on the returned handle
+     * or pass an `onComplete` callback as the second argument (see `MICROVERSE_LUA_SLOT_VM_BOOTSTRAP` in `@microverse.ts/runtime-wasm`).
+     */
+    readonly handler: (ctx: HostFnContext<THost>, input: TIn) => TOut | Promise<TOut>;
+    /**
+     * When true, manifest and Lua runtime treat this method as async (`MethodHandle` + optional `onComplete`).
+     * Set automatically for `async function` handlers in the fluent builder.
+     */
+    readonly async?: boolean | undefined;
+    /** Optional description emitted into the LuaCATS manifest. */
+    readonly description?: string | undefined;
+    /**
+     * Advanced escape hatch for manifest emission. Prefer registering Zod schemas with {@link luaType}
+     * (see `bridgePayloads` in the business example) so `.d.lua` stays inferred from `input` / `output`.
+     * Does not replace async bridge typing (`async: true` emits handle + `onComplete` in `.d.lua`).
+     * `paramTypes` keys must match `input` object keys (or `value` for non-object inputs).
+     */
+    readonly lua?: {
+        readonly paramTypes?: Partial<Record<string, string>> | undefined;
+        readonly returns?: string | undefined;
+    };
+};
+/**
+ * Erased method entry stored inside a {@link HostSurfaceSpec}. Assignability widens at the spec boundary.
+ */
+export type AnyHostSurfaceMethod = {
+    readonly capability: CapabilityId;
+    readonly input: z.ZodTypeAny;
+    readonly output: z.ZodTypeAny;
+    readonly handler: (ctx: HostFnContext<any>, input: any) => unknown;
+    readonly async?: boolean | undefined;
+    readonly description?: string | undefined;
+    readonly lua?: {
+        readonly paramTypes?: Partial<Record<string, string>> | undefined;
+        readonly returns?: string | undefined;
+    };
+};
+/**
+ * Tree shape accepted by {@link defineHostSurface}: top-level keys become Lua global bridge **tables**
+ * (e.g. `orders`, `billing`); inner keys become **methods** on that table.
+ */
+export type HostSurfaceSpec = Readonly<Record<string, Readonly<Record<string, AnyHostSurfaceMethod | HostSurfaceMethodEntry<any, any, any, any>>>>>;
+/**
+ * Surface spec where every method entry uses the same host type as your engine context
+ * (the `THost` you pass as `host` into {@link HostScriptSession}).
+ */
+export type HostSurfaceSpecForHost<THost> = Readonly<{
+    readonly [bridge: string]: Readonly<{
+        readonly [method: string]: HostSurfaceMethodEntry<THost, any, any, any>;
+    }>;
+}>;
+/**
+ * Zod object schemas keyed by PascalCase event kind (`OrderPlaced` → Lua method `onOrderPlaced` on the handler from `workflow:extend()`).
+ * Passed as the second argument to {@link defineHostSurface} to emit workflow hook typings into `.d.lua`.
+ */
+export type HostWorkflowHooksSpec = Readonly<Record<string, z.ZodObject<any>>>;
+/**
+ * Bridge + manifest API shared by every {@link HostSurface} (with or without workflow hooks).
+ *
+ * @typeParam TCapabilities - Union of capability ids declared on the surface spec (see {@link InferSurfaceCapabilities}).
+ */
+export type HostSurfaceCore<TCapabilities extends CapabilityId = CapabilityId> = {
+    /**
+     * Declarative bridge declarations compatible with {@link buildDeclarativeBridgeTable}.
+     * The host must satisfy {@link WithMicroverseCapabilityRegistry} (see {@link HostScriptSession}).
+     */
+    readonly toBridgeDeclarations: () => ReadonlyArray<DeclarativeBridgeDeclaration<WithMicroverseCapabilityRegistry, string>>;
+    /**
+     * Builds a `LuaDefManifest` for `@microverse.ts/lua-defs` (`buildLuaCatsDocument`, `generateDefs`, CLI).
+     *
+     * @param opts.output - Default `.d.lua` output path recorded in the manifest.
+     * @param opts.headerNote - Optional banner comment in the generated file.
+       * @param opts.luaTypeAliases - Optional overrides / extra `---@alias` entries; by default aliases come from {@link luaType} on Zod schemas used in the surface.
+     */
+    readonly toLuaDefManifest: (opts: {
+        readonly output: string;
+        readonly headerNote?: string | undefined;
+        /**
+         * Optional extra `---@alias` entries, or overrides for inferred aliases (same key replaces inferred).
+         */
+        readonly luaTypeAliases?: Readonly<Record<string, string>> | undefined;
+    }) => LuaDefManifest;
+    /** Every capability id referenced by a method on this surface (deduplicated). */
+    readonly capabilities: readonly TCapabilities[];
+    /**
+     * Subset allowlist for a script session. Only capabilities declared on this surface are accepted.
+     */
+    pickCapabilities<const T extends readonly SurfaceCapabilityString<TCapabilities>[]>(...capabilities: T): ReadonlyArray<Extract<T[number], TCapabilities>>;
+};
+/**
+ * Compiled host surface: bridge factories for `mergeEnv` plus manifest builder for `.d.lua` generation.
+ *
+ * @typeParam THooks - When you pass `workflowHooks` to {@link defineHostSurface}, the returned surface includes
+ * `workflowHooks` so callers can type workflow events from the surface object alone.
+ * @typeParam TCapabilities - Capability ids declared on the surface (for script allowlists).
+ */
+export type HostSurface<THooks extends HostWorkflowHooksSpec | undefined = undefined, TCapabilities extends CapabilityId = CapabilityId> = [undefined] extends [THooks] ? HostSurfaceCore<TCapabilities> : HostSurfaceCore<TCapabilities> & {
+    readonly workflowHooks: THooks;
+};
+/** Options passed to {@link HostSurfaceCore.toLuaDefManifest}. */
+export type LuaDefManifestGeneratorOpts = Parameters<HostSurfaceCore['toLuaDefManifest']>[0];
+//# sourceMappingURL=hostSurfaceTypes.d.ts.map

package/dist/domain/hostSurfaceTypes.d.ts.map

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

package/dist/domain/inferMethodAsync.d.ts

@@ -0,0 +1,10 @@
+/** Infers {@link HostSurfaceMethodEntry.async} from handler shape unless overridden explicitly. */
+export declare function inferMethodAsync(def: {
+    readonly handler: {
+        constructor: {
+            readonly name: string;
+        };
+    };
+    readonly async?: boolean | undefined;
+}): boolean;
+//# sourceMappingURL=inferMethodAsync.d.ts.map

package/dist/domain/inferMethodAsync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inferMethodAsync.d.ts","sourceRoot":"","sources":["../../src/domain/inferMethodAsync.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,wBAAgB,gBAAgB,CAAC,GAAG,EAAE;IACpC,QAAQ,CAAC,OAAO,EAAE;QAAE,WAAW,EAAE;YAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACtC,GAAG,OAAO,CAQV"}

package/dist/domain/luaGlobalHook.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Lua convention for domain hooks: PascalCase event kind → method name `on{Kind}` on the workflow
+ * handler table from `workflow:extend()` in each Lua slot (e.g. `OrderPlaced` → `onOrderPlaced`).
+ */
+export type LuaGlobalHookName<Kind extends string> = `on${Kind}`;
+/**
+ * Builds the `on{Kind}` method name dispatched on the slot’s workflow handler for a PascalCase event `kind`
+ * (e.g. `InventoryLow` → `onInventoryLow`).
+ * Throws if `kind` is not a safe Lua identifier fragment.
+ */
+export declare function luaGlobalHookName<const Kind extends string>(kind: Kind): LuaGlobalHookName<Kind>;
+//# sourceMappingURL=luaGlobalHook.d.ts.map

package/dist/domain/luaGlobalHook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"luaGlobalHook.d.ts","sourceRoot":"","sources":["../../src/domain/luaGlobalHook.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,iBAAiB,CAAC,IAAI,SAAS,MAAM,IAAI,KAAK,IAAI,EAAE,CAAC;AAEjE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,IAAI,SAAS,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAMhG"}

package/dist/domain/luaTypeAtoms.d.ts

@@ -0,0 +1,4 @@
+/** Lua / LuaCATS type atoms: never emit `---@alias` for these names from `lua.paramTypes` / `lua.returns` tokens. */
+export declare const LUA_TYPE_ATOMS: Set<string>;
+export declare function isLuaTypeAtom(name: string): boolean;
+//# sourceMappingURL=luaTypeAtoms.d.ts.map

package/dist/domain/luaTypeAtoms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"luaTypeAtoms.d.ts","sourceRoot":"","sources":["../../src/domain/luaTypeAtoms.ts"],"names":[],"mappings":"AAAA,qHAAqH;AACrH,eAAO,MAAM,cAAc,aAazB,CAAC;AAEH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEnD"}

package/dist/domain/safeObjectKey.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Rejects bridge/method names that could trigger prototype pollution when used as object keys.
+ */
+export declare function assertSafeObjectKey(kind: 'bridge' | 'method', name: string): void;
+/** Record with no inherited prototype — safe for dynamic string keys at runtime. */
+export declare function createNullPrototypeRecord<T extends object>(): T;
+//# sourceMappingURL=safeObjectKey.d.ts.map

package/dist/domain/safeObjectKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safeObjectKey.d.ts","sourceRoot":"","sources":["../../src/domain/safeObjectKey.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,QAAQ,GAAG,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAIjF;AAED,oFAAoF;AACpF,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,MAAM,KAAK,CAAC,CAE/D"}

package/dist/domain/surfaceCapabilities.d.ts

@@ -0,0 +1,21 @@
+import { CapabilityId } from '@microverse.ts/runtime-capabilities';
+import { HostSurfaceMethodEntry, HostSurfaceSpec } from './hostSurfaceTypes.js';
+type InferMethodCapability<M> = M extends {
+    readonly capability: infer C extends CapabilityId;
+} ? C : never;
+type InferBridgeCapabilities<B> = B extends Readonly<Record<string, unknown>> ? InferMethodCapability<B[keyof B]> : never;
+/**
+ * Union of every {@link CapabilityId} declared on methods in a {@link HostSurfaceSpec}
+ * (via `requires: 'domain:action'` on each fluent `.method(…)` entry).
+ */
+export type InferSurfaceCapabilities<TSpec extends HostSurfaceSpec> = InferBridgeCapabilities<TSpec[keyof TSpec]>;
+/** Runtime list of capability ids declared on a compiled surface spec. */
+export declare function collectCapabilitiesFromHostSurfaceSpec<const TSpec extends HostSurfaceSpec>(spec: TSpec): readonly InferSurfaceCapabilities<TSpec>[];
+/** Narrows `capabilities` to those declared on the surface (runtime check). */
+export declare function pickSurfaceCapabilities<const TSurface extends readonly CapabilityId[], const T extends readonly `${string}:${string}`[]>(surfaceCapabilities: TSurface, ...capabilities: T): ReadonlyArray<Extract<TSurface[number], CapabilityId>>;
+/** Helper type for method entries that preserve a specific capability literal. */
+export type SurfaceCapabilityEntry<TCap extends CapabilityId> = HostSurfaceMethodEntry<unknown, unknown, unknown> & {
+    readonly capability: TCap;
+};
+export {};
+//# sourceMappingURL=surfaceCapabilities.d.ts.map

package/dist/domain/surfaceCapabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceCapabilities.d.ts","sourceRoot":"","sources":["../../src/domain/surfaceCapabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAExE,OAAO,KAAK,EAAwB,sBAAsB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE3G,KAAK,qBAAqB,CAAC,CAAC,IAAI,CAAC,SAAS;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,SAAS,YAAY,CAAA;CAAE,GAC3F,CAAC,GACD,KAAK,CAAC;AAEV,KAAK,uBAAuB,CAAC,CAAC,IAAI,CAAC,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACzE,qBAAqB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GACjC,KAAK,CAAC;AAEV;;;GAGG;AACH,MAAM,MAAM,wBAAwB,CAAC,KAAK,SAAS,eAAe,IAAI,uBAAuB,CAC3F,KAAK,CAAC,MAAM,KAAK,CAAC,CACnB,CAAC;AAEF,0EAA0E;AAC1E,wBAAgB,sCAAsC,CAAC,KAAK,CAAC,KAAK,SAAS,eAAe,EACxF,IAAI,EAAE,KAAK,GACV,SAAS,wBAAwB,CAAC,KAAK,CAAC,EAAE,CAgB5C;AAED,+EAA+E;AAC/E,wBAAgB,uBAAuB,CACrC,KAAK,CAAC,QAAQ,SAAS,SAAS,YAAY,EAAE,EAC9C,KAAK,CAAC,CAAC,SAAS,SAAS,GAAG,MAAM,IAAI,MAAM,EAAE,EAAE,EAEhD,mBAAmB,EAAE,QAAQ,EAC7B,GAAG,YAAY,EAAE,CAAC,GACjB,aAAa,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,YAAY,CAAC,CAAC,CAUxD;AAED,kFAAkF;AAClF,MAAM,MAAM,sBAAsB,CAAC,IAAI,SAAS,YAAY,IAAI,sBAAsB,CACpF,OAAO,EACP,OAAO,EACP,OAAO,CACR,GAAG;IAAE,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAA;CAAE,CAAC"}

package/dist/domain/surfaceCapabilityString.d.ts

@@ -0,0 +1,6 @@
+import { CapabilityId } from '@microverse.ts/runtime-capabilities';
+/**
+ * Unbranded string literal(s) for capabilities on a surface — use as {@link HostSurfaceCore.pickCapabilities} arguments.
+ */
+export type SurfaceCapabilityString<TCap extends CapabilityId> = TCap extends CapabilityId & (infer S extends `${string}:${string}`) ? S : TCap extends CapabilityId ? `${string}:${string}` : never;
+//# sourceMappingURL=surfaceCapabilityString.d.ts.map

package/dist/domain/surfaceCapabilityString.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceCapabilityString.d.ts","sourceRoot":"","sources":["../../src/domain/surfaceCapabilityString.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAExE;;GAEG;AACH,MAAM,MAAM,uBAAuB,CAAC,IAAI,SAAS,YAAY,IAAI,IAAI,SAAS,YAAY,GACxF,CAAC,MAAM,CAAC,SAAS,GAAG,MAAM,IAAI,MAAM,EAAE,CAAC,GACrC,CAAC,GACD,IAAI,SAAS,YAAY,GACvB,GAAG,MAAM,IAAI,MAAM,EAAE,GACrB,KAAK,CAAC"}

package/dist/domain/surfaceMethodDef.d.ts

@@ -0,0 +1,25 @@
+import { CapabilityId } from '@microverse.ts/runtime-capabilities';
+import { z } from 'zod';
+import { HostFnContext, HostSurfaceMethodEntry } from './hostSurfaceTypes.js';
+/**
+ * Consumer-facing method definition for the fluent {@link SurfaceBuilder} API.
+ * Use `requires: 'domain:action'` for the capability id.
+ */
+export type SurfaceMethodDef<THost, TIn, TOut, TCap extends `${string}:${string}` = `${string}:${string}`> = {
+    /** Capability id required to invoke this method (`domain:action`). */
+    readonly requires: TCap;
+    readonly input: z.ZodType<TIn>;
+    readonly output: z.ZodType<TOut>;
+    readonly handler: (ctx: HostFnContext<THost>, input: TIn) => TOut | Promise<TOut>;
+    readonly async?: boolean | undefined;
+    readonly description?: string | undefined;
+    readonly lua?: {
+        readonly paramTypes?: Partial<Record<string, string>> | undefined;
+        readonly returns?: string | undefined;
+    };
+};
+/**
+ * Converts a {@link SurfaceMethodDef} into a compiled {@link HostSurfaceMethodEntry}.
+ */
+export declare function normalizeMethodDef<THost, TIn, TOut, const TCap extends `${string}:${string}`>(def: SurfaceMethodDef<THost, TIn, TOut, TCap>): HostSurfaceMethodEntry<THost, TIn, TOut, CapabilityId & TCap>;
+//# sourceMappingURL=surfaceMethodDef.d.ts.map

package/dist/domain/surfaceMethodDef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaceMethodDef.d.ts","sourceRoot":"","sources":["../../src/domain/surfaceMethodDef.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,qCAAqC,CAAC;AAC5F,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B,OAAO,KAAK,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAEnF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAC1B,KAAK,EACL,GAAG,EACH,IAAI,EACJ,IAAI,SAAS,GAAG,MAAM,IAAI,MAAM,EAAE,GAAG,GAAG,MAAM,IAAI,MAAM,EAAE,IACxD;IACF,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,GAAG,CAAC,EAAE;QACb,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;QAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACvC,CAAC;CACH,CAAC;AAEF;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EACL,GAAG,EACH,IAAI,EACJ,KAAK,CAAC,IAAI,SAAS,GAAG,MAAM,IAAI,MAAM,EAAE,EAExC,GAAG,EAAE,gBAAgB,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,GAC5C,sBAAsB,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC,CAW/D"}

package/dist/domain/zodLuaType.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+/**
+ * Registers a nominal LuaCATS name for a Zod schema. {@link zodToLuaTypeRef} emits the name;
+ * `.d.lua` generation adds a matching `---@alias` with the structural shape.
+ *
+ * @example
+ * ```ts
+ * export const orderDto = luaType('OrderDto', z.object({ id: z.string() }));
+ * // bridge: output: orderDto.optional()  →  returns `OrderDto|nil` in manifest
+ * ```
+ */
+export declare function luaType<T extends z.ZodTypeAny>(name: string, schema: T): T;
+/** @internal Root schema that carries a {@link luaType} registration (after unwrapping optional/nullable/…). */
+export declare function getLuaTypeRegistrationRoot(schema: z.ZodTypeAny): z.ZodTypeAny | undefined;
+/** @internal Nominal LuaCATS name for this schema, if registered via {@link luaType}. */
+export declare function resolveZodLuaTypeAlias(schema: z.ZodTypeAny): string | undefined;
+export declare function getRegisteredLuaTypeName(root: z.ZodTypeAny): string | undefined;
+//# sourceMappingURL=zodLuaType.d.ts.map

package/dist/domain/zodLuaType.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zodLuaType.d.ts","sourceRoot":"","sources":["../../src/domain/zodLuaType.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,CAM1E;AAED,gHAAgH;AAChH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,GAAG,SAAS,CAazF;AAED,yFAAyF;AACzF,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,GAAG,MAAM,GAAG,SAAS,CAG/E;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,CAAC,CAAC,UAAU,GAAG,MAAM,GAAG,SAAS,CAE/E"}

package/dist/domain/zodToLuaTypeRef.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export type ZodToLuaTypeRefOptions = {
+    /**
+     * When `false`, expands {@link luaType} registrations to structural shapes (for `---@alias` bodies).
+     * Default `true` emits registered nominal names at use sites.
+     */
+    readonly emitAliasNames?: boolean | undefined;
+};
+/**
+ * Maps a Zod schema to a LuaCATS type reference string for manifest emission.
+ *
+ * @remarks
+ * Register nominal types with {@link luaType} on shared Zod schemas (e.g. `orderDto`, `orderId`).
+ * Prefer that over per-method `lua.paramTypes` / `lua.returns` escape hatches on bridge methods.
+ */
+export declare function zodToLuaTypeRef(schema: z.ZodTypeAny, options?: ZodToLuaTypeRefOptions): string;
+//# sourceMappingURL=zodToLuaTypeRef.d.ts.map

package/dist/domain/zodToLuaTypeRef.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zodToLuaTypeRef.d.ts","sourceRoot":"","sources":["../../src/domain/zodToLuaTypeRef.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB,MAAM,MAAM,sBAAsB,GAAG;IACnC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/C,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,sBAAsB,GAAG,MAAM,CA0G9F"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Declarative **host surface** for Lua sandboxes: Zod-validated bridge methods, capability checks,
+ * `LuaDefManifest` generation for `.d.lua`, and {@link HostScriptSession} helpers.
+ *
+ * @packageDocumentation
+ */
+export { buildBridgeMergeEnvForHost, } from './infrastructure/builders/bridgeMergeEnv.js';
+export { BridgeBuilder, defineHostSurface, defineHostSurfaceFor, SurfaceBuilder, type AnyHostSurfaceMethod, type HostFnContext, type HostSurface, type HostSurfaceCore, type HostSurfaceMethodEntry, type HostSurfaceSpec, type HostSurfaceSpecForHost, type HostWorkflowHooksSpec, type LuaDefManifestGeneratorOpts, type SurfaceMethodDef, } from './infrastructure/builders/defineHostSurfaceFacade.js';
+export { compileHostSurface, compileHostSurfaceFor, } from './application/useCases/compileHostSurface.js';
+export { createBridgeDeclarationsFromHostSurfaceSpec } from './application/useCases/compileBridgeDeclarationsFromHostSurfaceSpec.js';
+export type { SchemaValidationPort } from './application/ports/SchemaValidationPort.js';
+export { HostScriptSession, type HostScriptSessionOptions, type WorkflowHookInvokeArgs, } from './infrastructure/components/hostScriptSession.js';
+export { luaGlobalHookName, type LuaGlobalHookName } from './domain/luaGlobalHook.js';
+export { luaType } from './domain/zodLuaType.js';
+export { zodToLuaTypeRef, type ZodToLuaTypeRefOptions } from './domain/zodToLuaTypeRef.js';
+export { MICROVERSE_CAPABILITY_REGISTRY, type WithMicroverseCapabilityRegistry } from './domain/capabilityRegistrySymbol.js';
+export { augmentHostWithCapabilityRegistry } from './infrastructure/adapters/augmentHostWithCapabilityRegistry.js';
+export type { InferSurfaceCapabilities } from './domain/surfaceCapabilities.js';
+export type { SurfaceCapabilityString } from './domain/surfaceCapabilityString.js';
+export { collectCapabilitiesFromHostSurfaceSpec, pickSurfaceCapabilities } from './domain/surfaceCapabilities.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,0BAA0B,GAC3B,MAAM,6CAA6C,CAAC;AACrD,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,oBAAoB,EACpB,cAAc,EACd,KAAK,oBAAoB,EACzB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,2BAA2B,EAChC,KAAK,gBAAgB,GACtB,MAAM,sDAAsD,CAAC;AAC9D,OAAO,EACL,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,8CAA8C,CAAC;AACtD,OAAO,EAAE,2CAA2C,EAAE,MAAM,wEAAwE,CAAC;AACrI,YAAY,EAAE,oBAAoB,EAAE,MAAM,6CAA6C,CAAC;AACxF,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,GAC5B,MAAM,kDAAkD,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AACtF,OAAO,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAC3F,OAAO,EAAE,8BAA8B,EAAE,KAAK,gCAAgC,EAAE,MAAM,sCAAsC,CAAC;AAC7H,OAAO,EAAE,iCAAiC,EAAE,MAAM,gEAAgE,CAAC;AACnH,YAAY,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAChF,YAAY,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AACnF,OAAO,EAAE,sCAAsC,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC"}