@microverse.ts/host-surface 0.1.0 → 0.2.0

package/dist/infrastructure/components/hostScriptSession.d.ts

@@ -1,94 +1,49 @@
 import { CapabilityId, InMemoryCapabilityRegistry } from '@microverse.ts/runtime-capabilities';
 import { Result } from '@microverse.ts/shared';
 import { z } from 'zod';
-import { ExecutionFailure, RunScriptResult, MicroverseId, MicroverseRuntime, TimeoutPolicy } from '@microverse.ts/runtime-core';
-import { HostSurface, HostWorkflowHooksSpec } from '../../domain/hostSurfaceTypes.js';
-import { LuaGlobalHookName } from '../../domain/luaGlobalHook.js';
-/**
- * Tuple accepted by {@link HostScriptSession.invokeGlobalHookIfPresent} when the session is specialised with
- * the same Zod map as {@link HostSurface} `workflowHooks` on the surface you pass in.
- */
-export type WorkflowHookInvokeArgs<TH extends HostWorkflowHooksSpec> = {
+import { ExecutionFailure, RunScriptResult, MicroverseId, MicroverseRuntime, ScriptAuditEvent, ScriptInstanceContext, ScriptPropertyBag, ScriptPropertyValue, TimeoutPolicy } from '@microverse.ts/runtime-core';
+import { HostSurface, HostComponentHooksSpec } from '../../domain/hostSurfaceTypes';
+import { LuaGlobalHookName } from '../../domain/luaGlobalHook';
+export type ComponentEventHookInvokeArgs<TH extends HostComponentHooksSpec> = {
     [K in keyof TH & string]: readonly [hook: LuaGlobalHookName<K>, payload: Readonly<z.infer<TH[K]>>];
 }[keyof TH & string];
-type InvokeGlobalHookIfPresentFn<THooks extends HostWorkflowHooksSpec | undefined> = THooks extends HostWorkflowHooksSpec ? (...args: WorkflowHookInvokeArgs<THooks>) => Promise<Result<RunScriptResult, ExecutionFailure>> : (globalName: string, payload: Readonly<Record<string, string | number | boolean>>) => Promise<Result<RunScriptResult, ExecutionFailure>>;
-/**
- * Options for {@link HostScriptSession}: one Wasm (or other) slot, a surface, host services, and a capability allowlist.
- *
- * @typeParam THost - Your engine context; must match the `THost` used in {@link defineHostSurfaceFor} (or {@link defineHostSurface}).
- * @typeParam THooks - When the surface was built with workflow hooks, pass the same `THooks` so {@link HostScriptSession.invokeGlobalHookIfPresent} narrows to those payloads (match `surface`’s `workflowHooks` typing).
- */
-export type HostScriptSessionOptions<THost, THooks extends HostWorkflowHooksSpec | undefined = undefined> = {
-    /** Shared runtime (typically one Wasmoon VM for many slots). */
+type InvokeComponentEventHookFn<THooks extends HostComponentHooksSpec | undefined> = THooks extends HostComponentHooksSpec ? (...args: ComponentEventHookInvokeArgs<THooks>) => Promise<Result<RunScriptResult, ExecutionFailure>> : (hookName: string, payload: Readonly<Record<string, string | number | boolean>>) => Promise<Result<RunScriptResult, ExecutionFailure>>;
+export type HostScriptSessionOptions<THost, THooks extends HostComponentHooksSpec | undefined = undefined> = {
     readonly runtime: MicroverseRuntime;
-    /** Surface produced by {@link defineHostSurface}. */
     readonly surface: HostSurface<THooks>;
-    /** Host services passed into bridge handlers (orders, clock, …). */
     readonly host: THost;
-    /** Stable sandbox id for this script / workflow / entity. */
     readonly slotKey: MicroverseId;
-    /** Exact capability ids this session may invoke on any bridge method. */
     readonly allowedCapabilities: readonly CapabilityId[];
-    /** Optional default timeout forwarded to {@link MicroverseSlot.run}. */
     readonly defaultTimeout?: TimeoutPolicy | undefined;
+    readonly script: ScriptInstanceContext;
+    readonly enableComponentRuntime?: boolean | undefined;
+    readonly propsSchema?: z.ZodObject<z.ZodRawShape> | undefined;
+    readonly onScriptAudit?: ((event: ScriptAuditEvent) => void) | undefined;
 };
-/**
- * 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).
- */
-export declare class HostScriptSession<THost, THooks extends HostWorkflowHooksSpec | undefined = undefined> {
+export declare class HostScriptSession<THost, THooks extends HostComponentHooksSpec | undefined = undefined> {
     private readonly opts;
     private sandbox;
+    private readonly hostProps;
     private readonly registry;
+    readonly context: ScriptInstanceContext;
     constructor(opts: HostScriptSessionOptions<THost, THooks>);
-    /**
-     * Allocates the underlying {@link MicroverseSlot} for this `slotKey` on the shared runtime.
-     */
     readonly openSession: () => Promise<void>;
-    /**
-     * Exposes the in-memory registry (e.g. to mutate allowlists in advanced tests).
-     */
     readonly getCapabilityRegistry: () => InMemoryCapabilityRegistry;
     private requireMicroverseSlot;
     private mergeEnv;
-    /**
-     * 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).
-     */
+    private emitAudit;
+    private validatePropsBag;
+    readonly getProps: () => Readonly<ScriptPropertyBag>;
+    readonly setProps: (bag: ScriptPropertyBag) => Promise<void>;
+    readonly patchProps: (partial: ScriptPropertyBag) => Promise<void>;
+    readonly flushDirtyProps: () => Promise<ScriptPropertyBag | null>;
     readonly runChunk: (source: string) => Promise<Result<RunScriptResult, ExecutionFailure>>;
-    /**
-     * 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).
-     */
-    readonly invokeGlobalHookIfPresent: InvokeGlobalHookIfPresentFn<THooks>;
-    /**
-     * 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.
-     */
+    readonly invokeComponentHook: (hookName: string, ...args: (string | ScriptPropertyValue | Readonly<Record<string, string | number | boolean>>)[]) => Promise<Result<RunScriptResult, ExecutionFailure>>;
+    readonly invokeComponentEventHook: InvokeComponentEventHookFn<THooks>;
     readonly call: (tableName: string, methodName: string, payload: Record<string, unknown>) => Promise<Result<RunScriptResult, ExecutionFailure>>;
-    /**
-     * Releases the slot in the runtime adapter and clears the session handle.
-     */
     readonly dispose: () => Promise<void>;
+    /** Seeds host props bag without Lua sync (call before setProps after mount). */
+    readonly seedHostProps: (bag: ScriptPropertyBag) => void;
 }
 export {};
 //# sourceMappingURL=hostScriptSession.d.ts.map

package/dist/infrastructure/components/hostScriptSession.d.ts.map

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

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@microverse.ts/host-surface",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "license": "MIT",
   "sideEffects": false,
-  "description": "Declarative host surface (Zod + capabilities) → bridge tables and LuaDefManifest for .d.lua.",
+  "description": "Fluent host surface DSL: Zod bridges, capability checks, component hooks, and LuaDefManifest for runtime + LuaLS stubs.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/QADRAX/Microverse.ts.git",
@@ -27,18 +27,19 @@
   ],
   "dependencies": {
     "zod": "^3.24.0",
-    "@microverse.ts/lua-defs": "0.1.0",
-    "@microverse.ts/runtime-capabilities": "0.1.0",
-    "@microverse.ts/runtime-bridge": "0.1.0",
-    "@microverse.ts/runtime-core": "0.1.0",
-    "@microverse.ts/shared": "0.1.0",
-    "@microverse.ts/runtime-zod": "0.1.0"
+    "@microverse.ts/lua-defs": "0.2.0",
+    "@microverse.ts/runtime-bridge": "0.2.0",
+    "@microverse.ts/runtime-capabilities": "0.2.0",
+    "@microverse.ts/runtime-core": "0.2.0",
+    "@microverse.ts/runtime-zod": "0.2.0",
+    "@microverse.ts/shared": "0.2.0"
   },
   "devDependencies": {
     "typescript": "^5.8.3",
     "vite": "^8.0.0",
     "vite-plugin-dts": "^4.5.4",
-    "vitest": "^3.1.4"
+    "vitest": "^3.1.4",
+    "@microverse.ts/runtime-wasm": "0.2.0"
   },
   "scripts": {
     "build": "vite build",