agentic-qe 3.3.4 → 3.4.0

package/v3/dist/adapters/a2ui/integration/surface-state-bridge.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Surface State Bridge
+ *
+ * Bridges A2UI surfaces to AG-UI state by managing bound surfaces
+ * and applying state changes to surface components via data bindings.
+ *
+ * @module adapters/a2ui/integration/surface-state-bridge
+ */
+import { EventEmitter } from 'events';
+import type { JsonPatchOperation } from '../../ag-ui/index.js';
+import { SurfaceGenerator, ComponentBuilder, type SurfaceGeneratorConfig, type SurfaceUpdateMessage } from '../renderer/index.js';
+/**
+ * Component binding to state path
+ */
+export interface ComponentBinding {
+    /** Component ID within the surface */
+    readonly componentId: string;
+    /** Component property to bind */
+    readonly property: string;
+    /** AG-UI state path (JSON Pointer) */
+    readonly statePath: string;
+    /** Transform function for value conversion */
+    readonly transform?: (value: unknown) => unknown;
+}
+/**
+ * Bound surface configuration
+ */
+export interface BoundSurfaceConfig {
+    /** Surface identifier */
+    readonly surfaceId: string;
+    /** Template function to build surface components */
+    readonly template: (builder: ComponentBuilder) => ComponentBuilder;
+    /** Component bindings to state paths */
+    readonly bindings: ComponentBinding[];
+    /** Initial data for the surface */
+    readonly initialData?: Record<string, unknown>;
+    /** Surface title */
+    readonly title?: string;
+    /** Catalog ID */
+    readonly catalogId?: string;
+}
+/**
+ * Surface state bridge configuration
+ */
+export interface SurfaceStateBridgeConfig {
+    /** Custom ID generator */
+    readonly idGenerator?: () => string;
+    /** Custom timestamp generator */
+    readonly timestampGenerator?: () => string;
+    /** Surface generator config */
+    readonly surfaceGeneratorConfig?: SurfaceGeneratorConfig;
+    /** Enable debug logging */
+    readonly debug?: boolean;
+}
+/**
+ * Bridge update event
+ */
+export interface BridgeUpdateEvent {
+    readonly type: 'binding' | 'delta' | 'snapshot';
+    readonly surfaceId: string;
+    readonly componentId?: string;
+    readonly property?: string;
+    readonly statePath: string;
+    readonly value?: unknown;
+    readonly timestamp: string;
+}
+/**
+ * Surface State Bridge
+ *
+ * Manages A2UI surfaces bound to AG-UI state paths. When state changes,
+ * the bridge automatically updates the bound component properties.
+ */
+export declare class SurfaceStateBridge extends EventEmitter {
+    private config;
+    private surfaces;
+    private pathToSurfaces;
+    private currentState;
+    constructor(config?: SurfaceStateBridgeConfig);
+    /**
+     * Create a surface bound to AG-UI state
+     */
+    createBoundSurface(config: BoundSurfaceConfig): SurfaceGenerator;
+    /**
+     * Get surface generator by ID
+     */
+    getSurface(surfaceId: string): SurfaceGenerator | undefined;
+    /**
+     * Get all surfaces
+     */
+    getAllSurfaces(): Map<string, SurfaceGenerator>;
+    /**
+     * Get surface IDs
+     */
+    getSurfaceIds(): string[];
+    /**
+     * Remove a surface
+     */
+    removeSurface(surfaceId: string): void;
+    /**
+     * Get bindings for a surface
+     */
+    getBindings(surfaceId: string): readonly ComponentBinding[];
+    /**
+     * Add binding to existing surface
+     */
+    addBinding(surfaceId: string, binding: ComponentBinding): void;
+    /**
+     * Remove binding from surface
+     */
+    removeBinding(surfaceId: string, componentId: string, property: string): void;
+    /**
+     * Update all surfaces from full state snapshot
+     */
+    updateFromState(state: Record<string, unknown>): void;
+    /**
+     * Apply JSON Patch delta to surfaces
+     */
+    applyDelta(delta: JsonPatchOperation[]): void;
+    /**
+     * Get surfaces affected by a state path
+     */
+    getSurfacesForPath(path: string): string[];
+    /**
+     * Get current state
+     */
+    getCurrentState(): Record<string, unknown>;
+    /**
+     * Generate surface update message for a surface
+     */
+    generateSurfaceUpdate(surfaceId: string): SurfaceUpdateMessage | null;
+    /**
+     * Get all messages for a surface (beginRendering + surfaceUpdate + dataModelUpdate)
+     */
+    getAllMessages(surfaceId: string): ReturnType<SurfaceGenerator['getAllMessages']>;
+    /**
+     * Get bridge statistics
+     */
+    getStats(): {
+        surfaceCount: number;
+        totalBindings: number;
+        pathMappingCount: number;
+        averageBindingsPerSurface: number;
+    };
+    /**
+     * Clear all surfaces
+     */
+    clear(): void;
+    /**
+     * Register a path to surface mapping
+     */
+    private registerPathMapping;
+    /**
+     * Unregister a path to surface mapping
+     */
+    private unregisterPathMapping;
+    /**
+     * Initialize surface from current state
+     */
+    private initializeSurfaceFromState;
+    /**
+     * Apply binding update to surface component
+     */
+    private applyBindingUpdate;
+    /**
+     * Get bindings affected by a path change
+     */
+    private getBindingsForPath;
+    /**
+     * Resolve value for a binding from an operation
+     */
+    private resolveValueForBinding;
+    /**
+     * Apply operation to internal state
+     */
+    private applyOperationToState;
+    /**
+     * Get value at JSON Pointer path
+     */
+    private getValueAtPath;
+    /**
+     * Set value at JSON Pointer path
+     */
+    private setValueAtPath;
+    /**
+     * Delete value at JSON Pointer path
+     */
+    private deleteValueAtPath;
+    /**
+     * Debug logging
+     */
+    private log;
+}
+/**
+ * Create a new SurfaceStateBridge instance
+ */
+export declare function createSurfaceStateBridge(config?: SurfaceStateBridgeConfig): SurfaceStateBridge;
+/**
+ * Create a bound surface configuration
+ */
+export declare function boundSurface(surfaceId: string, template: (builder: ComponentBuilder) => ComponentBuilder, bindings: ComponentBinding[], options?: {
+    initialData?: Record<string, unknown>;
+    title?: string;
+    catalogId?: string;
+}): BoundSurfaceConfig;
+/**
+ * Create a component binding
+ */
+export declare function binding(componentId: string, property: string, statePath: string, transform?: (value: unknown) => unknown): ComponentBinding;
+//# sourceMappingURL=surface-state-bridge.d.ts.map

package/v3/dist/adapters/a2ui/integration/surface-state-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-state-bridge.d.ts","sourceRoot":"","sources":["../../../../src/adapters/a2ui/integration/surface-state-bridge.ts"],"names":[],"mappings":"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"}