@boa-framework/ui 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+export type { UIBlockLayer, UIBlockRuntime, UIBlockManifest, UIBlockModule, UIBlockDef, } from "./types/ui-block.js";
+export type { UIWorkflowDefinition, UIWorkflowStep, UIWorkflowContext, UIWorkflowResult, UIErrorOutput, } from "./types/ui-workflow.js";
+export { JSRuntime } from "./runtime/js-runtime.js";
+export type { IUIRuntimeAdapter } from "./runtime/js-runtime.js";
+export { WASMRuntime } from "./runtime/wasm-runtime.js";
+export { getRuntimeForBlock } from "./runtime/runtime-registry.js";
+export { MemoCache } from "./runtime/memoize.js";
+export { runInSandbox } from "./sandbox/sandbox.js";
+export type { BlockPermissions } from "./sandbox/permissions.js";
+export { PURE_BLOCK_PERMISSIONS, CAPABILITY_BLOCK_PERMISSIONS } from "./sandbox/permissions.js";
+export { UIBlockRegistry } from "./registry/ui-block-registry.js";
+export { UIWorkflowEngine } from "./workflows/workflow-engine.js";
+export type { WorkflowEngineConfig } from "./workflows/workflow-engine.js";
+export { deepResolve, evalCondition } from "./workflows/utils/resolve.js";
+export { createBoaUI } from "./sdk/boa-ui.js";
+export type { BoaUI, BoaUIOptions } from "./sdk/boa-ui.js";
+export { createBoaHooks } from "./sdk/hooks.js";
+export { consoleLogger } from "./observability/logger.js";
+export { parseBlockBoa, parseWorkflowBoa, parseRegistryBoa, parseProjectBoa } from "@boa-framework/core";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,21 @@
+// Runtime
+export { JSRuntime } from "./runtime/js-runtime.js";
+export { WASMRuntime } from "./runtime/wasm-runtime.js";
+export { getRuntimeForBlock } from "./runtime/runtime-registry.js";
+export { MemoCache } from "./runtime/memoize.js";
+// Sandbox
+export { runInSandbox } from "./sandbox/sandbox.js";
+export { PURE_BLOCK_PERMISSIONS, CAPABILITY_BLOCK_PERMISSIONS } from "./sandbox/permissions.js";
+// Registry
+export { UIBlockRegistry } from "./registry/ui-block-registry.js";
+// Workflow Engine
+export { UIWorkflowEngine } from "./workflows/workflow-engine.js";
+export { deepResolve, evalCondition } from "./workflows/utils/resolve.js";
+// SDK
+export { createBoaUI } from "./sdk/boa-ui.js";
+export { createBoaHooks } from "./sdk/hooks.js";
+// Observability
+export { consoleLogger } from "./observability/logger.js";
+// Re-export backend parser functions used for .boa registration
+export { parseBlockBoa, parseWorkflowBoa, parseRegistryBoa, parseProjectBoa } from "@boa-framework/core";
+//# sourceMappingURL=index.js.map

package/dist/observability/index.d.ts

@@ -0,0 +1,2 @@
+export { consoleLogger } from "./logger.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/observability/index.js

@@ -0,0 +1,2 @@
+export { consoleLogger } from "./logger.js";
+//# sourceMappingURL=index.js.map

package/dist/observability/logger.d.ts

@@ -0,0 +1,5 @@
+import type { WorkflowEngineConfig } from "../workflows/workflow-engine.js";
+type LoggerCallbacks = Pick<WorkflowEngineConfig, "onStepStart" | "onStepEnd" | "onStepSkip" | "onStepError">;
+export declare function consoleLogger(prefix?: string): LoggerCallbacks;
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/observability/logger.js

@@ -0,0 +1,17 @@
+export function consoleLogger(prefix = "[boa-ui]") {
+    return {
+        onStepStart(stepId, input) {
+            console.log(`${prefix} STEP START: ${stepId}`, input);
+        },
+        onStepEnd(stepId, output, durationMs) {
+            console.log(`${prefix} STEP END: ${stepId} (${durationMs.toFixed(1)}ms)`, output);
+        },
+        onStepSkip(stepId, reason) {
+            console.log(`${prefix} STEP SKIP: ${stepId} — ${reason}`);
+        },
+        onStepError(stepId, error) {
+            console.error(`${prefix} STEP ERROR: ${stepId}`, error);
+        },
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/registry/index.d.ts

@@ -0,0 +1,2 @@
+export { UIBlockRegistry } from "./ui-block-registry.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/registry/index.js

@@ -0,0 +1,2 @@
+export { UIBlockRegistry } from "./ui-block-registry.js";
+//# sourceMappingURL=index.js.map

package/dist/registry/ui-block-registry.d.ts

@@ -0,0 +1,14 @@
+import type { UIBlockDef } from "../types/ui-block.js";
+import type { UIWorkflowDefinition } from "../types/ui-workflow.js";
+export declare class UIBlockRegistry {
+    private blocks;
+    private workflows;
+    registerBlock(blockDef: UIBlockDef): void;
+    registerBlockFromBoa(boaText: string, entry: string): void;
+    registerWorkflow(workflow: UIWorkflowDefinition): void;
+    getBlock(nameOrRef: string): UIBlockDef;
+    getWorkflow(name: string): UIWorkflowDefinition;
+    listBlocks(): UIBlockDef[];
+    listWorkflows(): UIWorkflowDefinition[];
+}
+//# sourceMappingURL=ui-block-registry.d.ts.map

package/dist/registry/ui-block-registry.js

@@ -0,0 +1,50 @@
+import { parseBlockBoa } from "@boa-framework/core";
+export class UIBlockRegistry {
+    blocks = new Map();
+    workflows = new Map();
+    registerBlock(blockDef) {
+        this.blocks.set(`${blockDef.name}@${blockDef.version}`, blockDef);
+    }
+    registerBlockFromBoa(boaText, entry) {
+        const parsed = parseBlockBoa(boaText);
+        const blockDef = {
+            name: parsed.name,
+            version: parsed.version,
+            layer: parsed.layer,
+            runtime: (parsed.runtime === "node" ? "js" : parsed.runtime),
+            entry,
+            manifest: {
+                ...parsed,
+                layer: parsed.layer,
+                runtime: (parsed.runtime === "node" ? "js" : parsed.runtime),
+            },
+        };
+        this.registerBlock(blockDef);
+    }
+    registerWorkflow(workflow) {
+        this.workflows.set(workflow.name, workflow);
+    }
+    getBlock(nameOrRef) {
+        const exact = this.blocks.get(nameOrRef);
+        if (exact)
+            return exact;
+        for (const [ref, def] of this.blocks) {
+            if (ref.startsWith(nameOrRef + "@") || def.name === nameOrRef)
+                return def;
+        }
+        throw new Error(`UI block not found: "${nameOrRef}"`);
+    }
+    getWorkflow(name) {
+        const wf = this.workflows.get(name);
+        if (!wf)
+            throw new Error(`UI workflow not found: "${name}"`);
+        return wf;
+    }
+    listBlocks() {
+        return Array.from(this.blocks.values());
+    }
+    listWorkflows() {
+        return Array.from(this.workflows.values());
+    }
+}
+//# sourceMappingURL=ui-block-registry.js.map

package/dist/runtime/index.d.ts

@@ -0,0 +1,6 @@
+export { JSRuntime } from "./js-runtime.js";
+export type { IUIRuntimeAdapter } from "./js-runtime.js";
+export { WASMRuntime } from "./wasm-runtime.js";
+export { getRuntimeForBlock } from "./runtime-registry.js";
+export { MemoCache } from "./memoize.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.js

@@ -0,0 +1,5 @@
+export { JSRuntime } from "./js-runtime.js";
+export { WASMRuntime } from "./wasm-runtime.js";
+export { getRuntimeForBlock } from "./runtime-registry.js";
+export { MemoCache } from "./memoize.js";
+//# sourceMappingURL=index.js.map

package/dist/runtime/js-runtime.d.ts

@@ -0,0 +1,10 @@
+import type { UIBlockDef } from "../types/ui-block.js";
+export interface IUIRuntimeAdapter {
+    execute(blockDef: UIBlockDef, input: Record<string, unknown>): Promise<unknown>;
+}
+export declare class JSRuntime implements IUIRuntimeAdapter {
+    private moduleCache;
+    execute(blockDef: UIBlockDef, input: Record<string, unknown>): Promise<unknown>;
+    clearCache(): void;
+}
+//# sourceMappingURL=js-runtime.d.ts.map

package/dist/runtime/js-runtime.js

@@ -0,0 +1,15 @@
+export class JSRuntime {
+    moduleCache = new Map();
+    async execute(blockDef, input) {
+        let mod = this.moduleCache.get(blockDef.entry);
+        if (!mod) {
+            mod = await import(/* @vite-ignore */ blockDef.entry);
+            this.moduleCache.set(blockDef.entry, mod);
+        }
+        return mod.default(input);
+    }
+    clearCache() {
+        this.moduleCache.clear();
+    }
+}
+//# sourceMappingURL=js-runtime.js.map

package/dist/runtime/memoize.d.ts

@@ -0,0 +1,11 @@
+export declare class MemoCache {
+    private cache;
+    private maxEntries;
+    constructor(maxEntries?: number);
+    private makeKey;
+    get(blockName: string, input: Record<string, unknown>): unknown | undefined;
+    set(blockName: string, input: Record<string, unknown>, output: unknown): void;
+    clear(): void;
+    get size(): number;
+}
+//# sourceMappingURL=memoize.d.ts.map

package/dist/runtime/memoize.js

@@ -0,0 +1,29 @@
+export class MemoCache {
+    cache = new Map();
+    maxEntries;
+    constructor(maxEntries = 100) {
+        this.maxEntries = maxEntries;
+    }
+    makeKey(blockName, input) {
+        return blockName + ":" + JSON.stringify(input);
+    }
+    get(blockName, input) {
+        const entry = this.cache.get(this.makeKey(blockName, input));
+        return entry?.output;
+    }
+    set(blockName, input, output) {
+        if (this.cache.size >= this.maxEntries) {
+            const oldest = this.cache.keys().next().value;
+            if (oldest)
+                this.cache.delete(oldest);
+        }
+        this.cache.set(this.makeKey(blockName, input), { output, timestamp: Date.now() });
+    }
+    clear() {
+        this.cache.clear();
+    }
+    get size() {
+        return this.cache.size;
+    }
+}
+//# sourceMappingURL=memoize.js.map

package/dist/runtime/runtime-registry.d.ts

@@ -0,0 +1,4 @@
+import type { UIBlockRuntime } from "../types/ui-block.js";
+import type { IUIRuntimeAdapter } from "./js-runtime.js";
+export declare function getRuntimeForBlock(runtime: UIBlockRuntime): IUIRuntimeAdapter;
+//# sourceMappingURL=runtime-registry.d.ts.map

package/dist/runtime/runtime-registry.js

@@ -0,0 +1,17 @@
+import { JSRuntime } from "./js-runtime.js";
+import { WASMRuntime } from "./wasm-runtime.js";
+const instances = new Map();
+export function getRuntimeForBlock(runtime) {
+    let instance = instances.get(runtime);
+    if (!instance) {
+        if (runtime === "js")
+            instance = new JSRuntime();
+        else if (runtime === "wasm")
+            instance = new WASMRuntime();
+        else
+            throw new Error(`No UI runtime for "${runtime}"`);
+        instances.set(runtime, instance);
+    }
+    return instance;
+}
+//# sourceMappingURL=runtime-registry.js.map

package/dist/runtime/wasm-runtime.d.ts

@@ -0,0 +1,6 @@
+import type { UIBlockDef } from "../types/ui-block.js";
+import type { IUIRuntimeAdapter } from "./js-runtime.js";
+export declare class WASMRuntime implements IUIRuntimeAdapter {
+    execute(_blockDef: UIBlockDef, _input: Record<string, unknown>): Promise<unknown>;
+}
+//# sourceMappingURL=wasm-runtime.d.ts.map

package/dist/runtime/wasm-runtime.js

@@ -0,0 +1,6 @@
+export class WASMRuntime {
+    async execute(_blockDef, _input) {
+        throw new Error("WASM runtime not yet implemented");
+    }
+}
+//# sourceMappingURL=wasm-runtime.js.map

package/dist/sandbox/index.d.ts

@@ -0,0 +1,4 @@
+export { runInSandbox } from "./sandbox.js";
+export type { BlockPermissions } from "./permissions.js";
+export { PURE_BLOCK_PERMISSIONS, CAPABILITY_BLOCK_PERMISSIONS } from "./permissions.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/sandbox/index.js

@@ -0,0 +1,3 @@
+export { runInSandbox } from "./sandbox.js";
+export { PURE_BLOCK_PERMISSIONS, CAPABILITY_BLOCK_PERMISSIONS } from "./permissions.js";
+//# sourceMappingURL=index.js.map

package/dist/sandbox/permissions.d.ts

@@ -0,0 +1,9 @@
+export interface BlockPermissions {
+    allowFetch: boolean;
+    allowStorage: boolean;
+    allowClipboard: boolean;
+    allowDom: boolean;
+}
+export declare const PURE_BLOCK_PERMISSIONS: BlockPermissions;
+export declare const CAPABILITY_BLOCK_PERMISSIONS: BlockPermissions;
+//# sourceMappingURL=permissions.d.ts.map

package/dist/sandbox/permissions.js

@@ -0,0 +1,13 @@
+export const PURE_BLOCK_PERMISSIONS = {
+    allowFetch: false,
+    allowStorage: false,
+    allowClipboard: false,
+    allowDom: false,
+};
+export const CAPABILITY_BLOCK_PERMISSIONS = {
+    allowFetch: true,
+    allowStorage: true,
+    allowClipboard: true,
+    allowDom: false,
+};
+//# sourceMappingURL=permissions.js.map

package/dist/sandbox/sandbox.d.ts

@@ -0,0 +1,5 @@
+import type { IUIRuntimeAdapter } from "../runtime/js-runtime.js";
+import type { UIBlockDef, UIBlockLayer } from "../types/ui-block.js";
+import type { MemoCache } from "../runtime/memoize.js";
+export declare function runInSandbox(runtime: IUIRuntimeAdapter, blockDef: UIBlockDef, input: Record<string, unknown>, blockType: UIBlockLayer, memoCache?: MemoCache): Promise<unknown>;
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox/sandbox.js

@@ -0,0 +1,37 @@
+export async function runInSandbox(runtime, blockDef, input, blockType, memoCache) {
+    if (blockType === "ui-block") {
+        // Check memo cache first
+        if (memoCache) {
+            const cached = memoCache.get(blockDef.name, input);
+            if (cached !== undefined)
+                return cached;
+        }
+        const frozenInput = deepFreeze({ ...input });
+        const globalObj = typeof globalThis !== "undefined" ? globalThis : {};
+        const beforeKeys = new Set(Object.keys(globalObj));
+        const result = await runtime.execute(blockDef, frozenInput);
+        const afterKeys = Object.keys(globalObj);
+        const newKeys = afterKeys.filter((k) => !beforeKeys.has(k));
+        if (newKeys.length > 0) {
+            throw new Error(`Pure block "${blockDef.name}" modified global state. New globals: ${newKeys.join(", ")}`);
+        }
+        // Store in memo cache
+        if (memoCache)
+            memoCache.set(blockDef.name, input, result);
+        return result;
+    }
+    // Capability block — side effects allowed
+    return runtime.execute(blockDef, input);
+}
+function deepFreeze(obj) {
+    if (obj === null || typeof obj !== "object")
+        return obj;
+    Object.freeze(obj);
+    for (const value of Object.values(obj)) {
+        if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+            deepFreeze(value);
+        }
+    }
+    return obj;
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/sdk/boa-ui.d.ts

@@ -0,0 +1,22 @@
+import { UIBlockRegistry } from "../registry/ui-block-registry.js";
+import { UIWorkflowEngine } from "../workflows/workflow-engine.js";
+import type { WorkflowEngineConfig } from "../workflows/workflow-engine.js";
+import type { UIBlockDef } from "../types/ui-block.js";
+import type { UIWorkflowDefinition, UIWorkflowResult } from "../types/ui-workflow.js";
+export interface BoaUIOptions extends Omit<WorkflowEngineConfig, "memoCache"> {
+    maxMemoEntries?: number;
+    blocks?: UIBlockDef[];
+    workflows?: UIWorkflowDefinition[];
+}
+export declare function createBoaUI(options?: BoaUIOptions): {
+    run(workflowName: string, input?: Record<string, unknown>): Promise<UIWorkflowResult>;
+    registerBlock(blockDef: UIBlockDef): void;
+    registerWorkflow(workflow: UIWorkflowDefinition): void;
+    registerBlockFromBoa(boaText: string, entry: string): void;
+    registerWorkflowFromBoa(boaText: string): void;
+    clearMemoCache(): void;
+    registry: UIBlockRegistry;
+    engine: UIWorkflowEngine;
+};
+export type BoaUI = ReturnType<typeof createBoaUI>;
+//# sourceMappingURL=boa-ui.d.ts.map

package/dist/sdk/boa-ui.js

@@ -0,0 +1,59 @@
+import { UIBlockRegistry } from "../registry/ui-block-registry.js";
+import { MemoCache } from "../runtime/memoize.js";
+import { UIWorkflowEngine } from "../workflows/workflow-engine.js";
+import { parseWorkflowBoa } from "@boa-framework/core";
+export function createBoaUI(options = {}) {
+    const registry = new UIBlockRegistry();
+    const memoCache = new MemoCache(options.maxMemoEntries ?? 100);
+    const engine = new UIWorkflowEngine(registry, { ...options, memoCache });
+    // Pre-register blocks and workflows from options
+    if (options.blocks) {
+        for (const block of options.blocks) {
+            registry.registerBlock(block);
+        }
+    }
+    if (options.workflows) {
+        for (const wf of options.workflows) {
+            registry.registerWorkflow(wf);
+        }
+    }
+    return {
+        run(workflowName, input = {}) {
+            return engine.run(workflowName, input);
+        },
+        registerBlock(blockDef) {
+            registry.registerBlock(blockDef);
+        },
+        registerWorkflow(workflow) {
+            registry.registerWorkflow(workflow);
+        },
+        registerBlockFromBoa(boaText, entry) {
+            registry.registerBlockFromBoa(boaText, entry);
+        },
+        registerWorkflowFromBoa(boaText) {
+            const parsed = parseWorkflowBoa(boaText);
+            const wfDef = {
+                name: parsed.workflow,
+                version: parsed.version,
+                description: parsed.description,
+                config: parsed.config,
+                onError: parsed.onErrorBlock ? { block: parsed.onErrorBlock } : undefined,
+                steps: parsed.steps.map((s) => ({
+                    id: s.id ?? s.block,
+                    block: s.sub ? undefined : s.block,
+                    sub: s.sub,
+                    input: s.inputMap,
+                    when: s.condition,
+                    parallel: s.parallel,
+                })),
+            };
+            registry.registerWorkflow(wfDef);
+        },
+        clearMemoCache() {
+            memoCache.clear();
+        },
+        registry,
+        engine,
+    };
+}
+//# sourceMappingURL=boa-ui.js.map

package/dist/sdk/hooks.d.ts

@@ -0,0 +1,16 @@
+import type { BoaUI } from "./boa-ui.js";
+import type { UIWorkflowResult } from "../types/ui-workflow.js";
+/**
+ * Creates React hooks for BOA UI workflows.
+ * Uses lazy React import so the core library doesn't depend on React.
+ */
+export declare function createBoaHooks(boa: BoaUI): {
+    useWorkflow(workflowName: string, input?: Record<string, unknown>): {
+        result: UIWorkflowResult | null;
+        loading: boolean;
+        error: Error | null;
+        run: any;
+    };
+    ensureReact: () => Promise<void>;
+};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/sdk/hooks.js

@@ -0,0 +1,55 @@
+/**
+ * Creates React hooks for BOA UI workflows.
+ * Uses lazy React import so the core library doesn't depend on React.
+ */
+export function createBoaHooks(boa) {
+    /* eslint-disable @typescript-eslint/no-explicit-any */
+    let R = null;
+    async function ensureReact() {
+        if (!R) {
+            try {
+                R = await Function("return import('react')")();
+            }
+            catch {
+                throw new Error("React is required for createBoaHooks(). Install react as a dependency.");
+            }
+        }
+    }
+    return {
+        useWorkflow(workflowName, input) {
+            if (!R) {
+                throw new Error("Call await ensureReact() before using hooks, or import react before createBoaHooks().");
+            }
+            const { useState, useEffect, useCallback } = R;
+            const [result, setResult] = useState(null);
+            const [loading, setLoading] = useState(false);
+            const [error, setError] = useState(null);
+            const run = useCallback(async (overrideInput) => {
+                setLoading(true);
+                setError(null);
+                try {
+                    const res = await boa.run(workflowName, overrideInput ?? input ?? {});
+                    setResult(res);
+                    return res;
+                }
+                catch (err) {
+                    const e = err instanceof Error ? err : new Error(String(err));
+                    setError(e);
+                    throw e;
+                }
+                finally {
+                    setLoading(false);
+                }
+            }, [workflowName, input]);
+            useEffect(() => {
+                if (input) {
+                    run();
+                }
+            }, []);
+            return { result, loading, error, run };
+        },
+        ensureReact,
+    };
+    /* eslint-enable @typescript-eslint/no-explicit-any */
+}
+//# sourceMappingURL=hooks.js.map

package/dist/sdk/index.d.ts

@@ -0,0 +1,4 @@
+export { createBoaUI } from "./boa-ui.js";
+export type { BoaUI, BoaUIOptions } from "./boa-ui.js";
+export { createBoaHooks } from "./hooks.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/sdk/index.js

@@ -0,0 +1,3 @@
+export { createBoaUI } from "./boa-ui.js";
+export { createBoaHooks } from "./hooks.js";
+//# sourceMappingURL=index.js.map

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export type { UIBlockLayer, UIBlockRuntime, UIBlockManifest, UIBlockModule, UIBlockDef, } from "./ui-block.js";
+export type { UIWorkflowDefinition, UIWorkflowStep, UIWorkflowContext, UIWorkflowResult, UIErrorOutput, } from "./ui-workflow.js";
+export type { BlockManifest, BlockFixture, BlockLayer, BlockRuntime, BlockFieldSchema, } from "@boa-framework/core";
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/types/ui-block.d.ts

@@ -0,0 +1,21 @@
+import type { BlockManifest, BlockFixture } from "@boa-framework/core";
+export type UIBlockLayer = "ui-block" | "ui-capability";
+export type UIBlockRuntime = "js" | "wasm";
+export interface UIBlockManifest extends Omit<BlockManifest, "layer" | "runtime"> {
+    layer: UIBlockLayer;
+    runtime: UIBlockRuntime;
+    mocks: BlockFixture[];
+}
+export interface UIBlockModule {
+    default: (input: Record<string, unknown>) => unknown | Promise<unknown>;
+}
+export interface UIBlockDef {
+    name: string;
+    version: string;
+    layer: UIBlockLayer;
+    runtime: UIBlockRuntime;
+    entry: string;
+    wasmPath?: string;
+    manifest: UIBlockManifest;
+}
+//# sourceMappingURL=ui-block.d.ts.map

package/dist/types/ui-block.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ui-block.js.map

package/dist/types/ui-workflow.d.ts

@@ -0,0 +1,42 @@
+export interface UIWorkflowDefinition {
+    name: string;
+    version: string;
+    description?: string;
+    config?: Record<string, unknown>;
+    steps: UIWorkflowStep[];
+    onError?: {
+        block: string;
+    };
+}
+export interface UIWorkflowStep {
+    id: string;
+    block?: string;
+    capability?: string;
+    sub?: string;
+    input?: Record<string, string>;
+    when?: string;
+    parallel?: boolean;
+}
+export interface UIWorkflowContext {
+    input: Record<string, unknown>;
+    steps: Record<string, {
+        output: unknown;
+    }>;
+    config: Record<string, unknown>;
+}
+export interface UIWorkflowResult {
+    success: boolean;
+    steps: Record<string, {
+        output: unknown;
+    }>;
+    error?: UIErrorOutput;
+    durationMs: number;
+}
+export interface UIErrorOutput {
+    step: string;
+    userMessage: string;
+    code: string;
+    recoverable: boolean;
+    originalError?: unknown;
+}
+//# sourceMappingURL=ui-workflow.d.ts.map

package/dist/types/ui-workflow.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ui-workflow.js.map

package/dist/workflows/index.d.ts

@@ -0,0 +1,4 @@
+export { UIWorkflowEngine } from "./workflow-engine.js";
+export type { WorkflowEngineConfig } from "./workflow-engine.js";
+export { deepResolve, evalCondition } from "./utils/resolve.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/workflows/index.js

@@ -0,0 +1,3 @@
+export { UIWorkflowEngine } from "./workflow-engine.js";
+export { deepResolve, evalCondition } from "./utils/resolve.js";
+//# sourceMappingURL=index.js.map

package/dist/workflows/utils/resolve.d.ts

@@ -0,0 +1,9 @@
+import type { UIWorkflowContext } from "../../types/ui-workflow.js";
+export declare function deepResolve(inputMap: Record<string, string>, context: UIWorkflowContext): Record<string, unknown>;
+/**
+ * Evaluate a simple condition expression against workflow context.
+ * Supports: $path.to.value > number, $path.to.value < number,
+ *           $path.to.value === value, $path.to.value !== value
+ */
+export declare function evalCondition(condition: string, context: UIWorkflowContext): boolean;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/workflows/utils/resolve.js

@@ -0,0 +1,77 @@
+export function deepResolve(inputMap, context) {
+    const resolved = {};
+    for (const [key, pathExpr] of Object.entries(inputMap)) {
+        if (typeof pathExpr === "string" && pathExpr.startsWith("$")) {
+            resolved[key] = resolveReference(pathExpr, context);
+        }
+        else {
+            resolved[key] = pathExpr;
+        }
+    }
+    return resolved;
+}
+function resolveReference(path, context) {
+    const segments = path.slice(1).split(".");
+    let current = context;
+    for (const segment of segments) {
+        if (current === null || current === undefined || typeof current !== "object")
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * Evaluate a simple condition expression against workflow context.
+ * Supports: $path.to.value > number, $path.to.value < number,
+ *           $path.to.value === value, $path.to.value !== value
+ */
+export function evalCondition(condition, context) {
+    const operators = ["!==", "===", ">=", "<=", "!=", "==", ">", "<"];
+    for (const op of operators) {
+        const idx = condition.indexOf(op);
+        if (idx === -1)
+            continue;
+        const left = condition.slice(0, idx).trim();
+        const right = condition.slice(idx + op.length).trim();
+        const leftVal = left.startsWith("$") ? resolveReference(left, context) : parseValue(left);
+        const rightVal = right.startsWith("$") ? resolveReference(right, context) : parseValue(right);
+        switch (op) {
+            case "===":
+            case "==":
+                return leftVal === rightVal;
+            case "!==":
+            case "!=":
+                return leftVal !== rightVal;
+            case ">":
+                return Number(leftVal) > Number(rightVal);
+            case "<":
+                return Number(leftVal) < Number(rightVal);
+            case ">=":
+                return Number(leftVal) >= Number(rightVal);
+            case "<=":
+                return Number(leftVal) <= Number(rightVal);
+        }
+    }
+    // Truthiness check on a single reference
+    if (condition.startsWith("$")) {
+        return Boolean(resolveReference(condition, context));
+    }
+    return false;
+}
+function parseValue(raw) {
+    if (raw === "true")
+        return true;
+    if (raw === "false")
+        return false;
+    if (raw === "null")
+        return null;
+    if (raw === "undefined")
+        return undefined;
+    if (/^".*"$/.test(raw) || /^'.*'$/.test(raw))
+        return raw.slice(1, -1);
+    const num = Number(raw);
+    if (!isNaN(num))
+        return num;
+    return raw;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/workflows/workflow-engine.d.ts

@@ -0,0 +1,21 @@
+import type { UIBlockRegistry } from "../registry/ui-block-registry.js";
+import type { UIWorkflowDefinition, UIWorkflowResult } from "../types/ui-workflow.js";
+import type { MemoCache } from "../runtime/memoize.js";
+export interface WorkflowEngineConfig {
+    config?: Record<string, unknown>;
+    memoCache?: MemoCache;
+    onStepStart?: (stepId: string, input: Record<string, unknown>) => void;
+    onStepEnd?: (stepId: string, output: unknown, durationMs: number) => void;
+    onStepSkip?: (stepId: string, reason: string) => void;
+    onStepError?: (stepId: string, error: unknown) => void;
+}
+export declare class UIWorkflowEngine {
+    private registry;
+    private config;
+    constructor(registry: UIBlockRegistry, config?: WorkflowEngineConfig);
+    run(workflowName: string, input: Record<string, unknown>): Promise<UIWorkflowResult>;
+    execute(workflow: UIWorkflowDefinition, input: Record<string, unknown>): Promise<UIWorkflowResult>;
+    private executeStep;
+    private runErrorHandler;
+}
+//# sourceMappingURL=workflow-engine.d.ts.map

package/dist/workflows/workflow-engine.js

@@ -0,0 +1,149 @@
+import { getRuntimeForBlock } from "../runtime/runtime-registry.js";
+import { runInSandbox } from "../sandbox/sandbox.js";
+import { deepResolve, evalCondition } from "./utils/resolve.js";
+export class UIWorkflowEngine {
+    registry;
+    config;
+    constructor(registry, config = {}) {
+        this.registry = registry;
+        this.config = config;
+    }
+    async run(workflowName, input) {
+        const workflow = this.registry.getWorkflow(workflowName);
+        return this.execute(workflow, input);
+    }
+    async execute(workflow, input) {
+        const startTime = performance.now();
+        const context = {
+            input,
+            steps: {},
+            config: { ...workflow.config, ...this.config.config },
+        };
+        const stepResults = {};
+        try {
+            const steps = workflow.steps;
+            let i = 0;
+            while (i < steps.length) {
+                // Collect parallel group
+                if (steps[i].parallel) {
+                    const parallelSteps = [];
+                    while (i < steps.length && steps[i].parallel) {
+                        parallelSteps.push(steps[i]);
+                        i++;
+                    }
+                    const results = await Promise.all(parallelSteps.map((step) => this.executeStep(step, context, workflow)));
+                    for (let j = 0; j < parallelSteps.length; j++) {
+                        if (results[j] !== undefined) {
+                            stepResults[parallelSteps[j].id] = { output: results[j] };
+                            context.steps[parallelSteps[j].id] = { output: results[j] };
+                        }
+                    }
+                }
+                else {
+                    const step = steps[i];
+                    const result = await this.executeStep(step, context, workflow);
+                    if (result !== undefined) {
+                        stepResults[step.id] = { output: result };
+                        context.steps[step.id] = { output: result };
+                    }
+                    i++;
+                }
+            }
+            return {
+                success: true,
+                steps: stepResults,
+                durationMs: performance.now() - startTime,
+            };
+        }
+        catch (err) {
+            // ON_ERROR handler
+            if (workflow.onError?.block) {
+                try {
+                    const errorOutput = await this.runErrorHandler(workflow.onError.block, err, context);
+                    return {
+                        success: false,
+                        steps: stepResults,
+                        error: errorOutput,
+                        durationMs: performance.now() - startTime,
+                    };
+                }
+                catch {
+                    // Error handler itself failed — fall through
+                }
+            }
+            return {
+                success: false,
+                steps: stepResults,
+                error: {
+                    step: "unknown",
+                    userMessage: err instanceof Error ? err.message : String(err),
+                    code: "UNHANDLED_ERROR",
+                    recoverable: false,
+                    originalError: err,
+                },
+                durationMs: performance.now() - startTime,
+            };
+        }
+    }
+    async executeStep(step, context, workflow) {
+        // WHEN conditional
+        if (step.when) {
+            const shouldRun = evalCondition(step.when, context);
+            if (!shouldRun) {
+                this.config.onStepSkip?.(step.id, `Condition not met: ${step.when}`);
+                return undefined;
+            }
+        }
+        // SUB workflow
+        if (step.sub) {
+            const resolvedInput = step.input ? deepResolve(step.input, context) : context.input;
+            this.config.onStepStart?.(step.id, resolvedInput);
+            const stepStart = performance.now();
+            const subResult = await this.run(step.sub, resolvedInput);
+            this.config.onStepEnd?.(step.id, subResult.steps, performance.now() - stepStart);
+            if (!subResult.success) {
+                throw new Error(`Sub-workflow "${step.sub}" failed: ${subResult.error?.userMessage}`);
+            }
+            return subResult.steps;
+        }
+        // Regular block execution
+        const blockRef = step.block || step.capability;
+        if (!blockRef) {
+            throw new Error(`Step "${step.id}" has no block, capability, or sub reference`);
+        }
+        const blockDef = this.registry.getBlock(blockRef);
+        const runtime = getRuntimeForBlock(blockDef.runtime);
+        const resolvedInput = step.input ? deepResolve(step.input, context) : context.input;
+        this.config.onStepStart?.(step.id, resolvedInput);
+        const stepStart = performance.now();
+        try {
+            const output = await runInSandbox(runtime, blockDef, resolvedInput, blockDef.layer, this.config.memoCache);
+            const durationMs = performance.now() - stepStart;
+            this.config.onStepEnd?.(step.id, output, durationMs);
+            return output;
+        }
+        catch (err) {
+            this.config.onStepError?.(step.id, err);
+            throw err;
+        }
+    }
+    async runErrorHandler(blockRef, error, context) {
+        const blockDef = this.registry.getBlock(blockRef);
+        const runtime = getRuntimeForBlock(blockDef.runtime);
+        const errorInput = {
+            error: {
+                message: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack : undefined,
+            },
+        };
+        const result = (await runtime.execute(blockDef, errorInput));
+        return {
+            step: "error-handler",
+            userMessage: String(result.userMessage ?? "An error occurred"),
+            code: String(result.code ?? "UNKNOWN_ERROR"),
+            recoverable: Boolean(result.recoverable ?? false),
+            originalError: error,
+        };
+    }
+}
+//# sourceMappingURL=workflow-engine.js.map

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@boa-framework/ui",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./react": {
+      "import": "./dist/sdk/hooks.js",
+      "types": "./dist/sdk/hooks.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@boa-framework/core": "*"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^1.6.0",
+    "@types/node": "^20.0.0"
+  }
+}