agentic-qe 3.3.4 → 3.4.0

package/v3/dist/adapters/a2ui/renderer/surface-generator.d.ts

@@ -0,0 +1,210 @@
+/**
+ * A2UI Surface Generator
+ *
+ * Generates A2UI surfaces with unique IDs, version tracking, and
+ * incremental updates. Manages component trees as flat adjacency lists.
+ *
+ * @module adapters/a2ui/renderer/surface-generator
+ */
+import { EventEmitter } from 'events';
+import type { ComponentNode, SurfaceUpdateMessage, DataModelUpdateMessage, BeginRenderingMessage, DeleteSurfaceMessage, UserActionMessage, A2UIServerMessage } from './message-types.js';
+import { ComponentBuilder } from './component-builder.js';
+/**
+ * Surface state representation
+ */
+export interface SurfaceState {
+    /** Surface identifier */
+    id: string;
+    /** Current version for optimistic updates */
+    version: number;
+    /** Component map (id -> component) */
+    components: Map<string, ComponentNode>;
+    /** Root component ID */
+    rootComponentId: string | null;
+    /** Surface title */
+    title: string | null;
+    /** Catalog ID */
+    catalogId: string | null;
+    /** Data model */
+    data: Record<string, unknown>;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+    /** Is surface currently rendered */
+    isRendered: boolean;
+}
+/**
+ * Surface generator configuration
+ */
+export interface SurfaceGeneratorConfig {
+    /** Custom ID generator */
+    idGenerator?: () => string;
+    /** Custom timestamp generator */
+    timestampGenerator?: () => string;
+    /** Default catalog ID */
+    defaultCatalogId?: string;
+    /** Emit events on changes */
+    emitEvents?: boolean;
+    /** Maximum surfaces to track */
+    maxSurfaces?: number;
+}
+/**
+ * Surface change event
+ */
+export interface SurfaceChangeEvent {
+    type: 'created' | 'updated' | 'deleted' | 'rendered';
+    surfaceId: string;
+    timestamp: string;
+    message?: A2UIServerMessage;
+}
+/**
+ * A2UI Surface Generator
+ *
+ * Manages surface lifecycle, component trees, and message generation
+ * for the A2UI protocol.
+ */
+export declare class SurfaceGenerator extends EventEmitter {
+    private config;
+    private surfaces;
+    constructor(config?: SurfaceGeneratorConfig);
+    /**
+     * Create a new surface
+     */
+    createSurface(surfaceId?: string, options?: {
+        title?: string;
+        catalogId?: string;
+        rootComponentId?: string;
+    }): SurfaceState;
+    /**
+     * Get a surface by ID
+     */
+    getSurface(surfaceId: string): SurfaceState | undefined;
+    /**
+     * Check if surface exists
+     */
+    hasSurface(surfaceId: string): boolean;
+    /**
+     * Get all surface IDs
+     */
+    getSurfaceIds(): string[];
+    /**
+     * Get surface count
+     */
+    getSurfaceCount(): number;
+    /**
+     * Delete a surface
+     */
+    deleteSurface(surfaceId: string): DeleteSurfaceMessage | null;
+    /**
+     * Add a component to a surface
+     */
+    addComponent(surfaceId: string, component: ComponentNode): SurfaceUpdateMessage | null;
+    /**
+     * Add multiple components at once
+     */
+    addComponents(surfaceId: string, components: ComponentNode[]): SurfaceUpdateMessage | null;
+    /**
+     * Update a component
+     */
+    updateComponent(surfaceId: string, componentId: string, updates: Partial<Omit<ComponentNode, 'id'>>): SurfaceUpdateMessage | null;
+    /**
+     * Remove a component
+     */
+    removeComponent(surfaceId: string, componentId: string): SurfaceUpdateMessage | null;
+    /**
+     * Get a component from a surface
+     */
+    getComponent(surfaceId: string, componentId: string): ComponentNode | undefined;
+    /**
+     * Get all components from a surface
+     */
+    getComponents(surfaceId: string): ComponentNode[];
+    /**
+     * Add a child to a parent component
+     */
+    addChild(surfaceId: string, parentId: string, childId: string): SurfaceUpdateMessage | null;
+    /**
+     * Remove a child from a parent component
+     */
+    removeChild(surfaceId: string, parentId: string, childId: string): SurfaceUpdateMessage | null;
+    /**
+     * Set children for a component
+     */
+    setChildren(surfaceId: string, parentId: string, childIds: string[]): SurfaceUpdateMessage | null;
+    /**
+     * Update surface data model
+     */
+    updateData(surfaceId: string, data: Record<string, unknown>): DataModelUpdateMessage | null;
+    /**
+     * Set surface data model (replace)
+     */
+    setData(surfaceId: string, data: Record<string, unknown>): DataModelUpdateMessage | null;
+    /**
+     * Get surface data model
+     */
+    getData(surfaceId: string): Record<string, unknown> | undefined;
+    /**
+     * Generate surfaceUpdate message
+     */
+    generateSurfaceUpdate(surfaceId: string): SurfaceUpdateMessage | null;
+    /**
+     * Generate incremental surfaceUpdate with specific components
+     */
+    generateIncrementalUpdate(surfaceId: string, componentIds: string[]): SurfaceUpdateMessage | null;
+    /**
+     * Generate dataModelUpdate message
+     */
+    generateDataModelUpdate(surfaceId: string, data?: Record<string, unknown>): DataModelUpdateMessage | null;
+    /**
+     * Generate beginRendering message
+     */
+    generateBeginRendering(surfaceId: string): BeginRenderingMessage | null;
+    /**
+     * Generate deleteSurface message
+     */
+    generateDeleteSurface(surfaceId: string): DeleteSurfaceMessage | null;
+    /**
+     * Create a userAction response message
+     */
+    createUserAction(surfaceId: string, componentId: string, actionId: string, payload?: Record<string, unknown>): UserActionMessage;
+    /**
+     * Handle incoming user action
+     */
+    handleUserAction(action: UserActionMessage, handler: (action: UserActionMessage) => void | Promise<void>): void;
+    /**
+     * Apply a builder's surface to this generator
+     */
+    applyBuilder(builder: ComponentBuilder): SurfaceUpdateMessage | null;
+    /**
+     * Create a builder for a surface
+     */
+    createBuilder(surfaceId?: string): ComponentBuilder;
+    /**
+     * Get all messages for a complete surface render
+     */
+    getAllMessages(surfaceId: string): {
+        beginRendering: BeginRenderingMessage;
+        surfaceUpdate: SurfaceUpdateMessage;
+        dataModelUpdate: DataModelUpdateMessage;
+    } | null;
+    /**
+     * Clear all surfaces
+     */
+    clear(): void;
+    /**
+     * Get generator statistics
+     */
+    getStats(): {
+        surfaceCount: number;
+        totalComponents: number;
+        averageComponentsPerSurface: number;
+        renderedSurfaces: number;
+    };
+}
+/**
+ * Create a new SurfaceGenerator instance
+ */
+export declare function createSurfaceGenerator(config?: SurfaceGeneratorConfig): SurfaceGenerator;
+export type { ComponentNode, SurfaceUpdateMessage, DataModelUpdateMessage, BeginRenderingMessage, DeleteSurfaceMessage, UserActionMessage, A2UIServerMessage, };
+//# sourceMappingURL=surface-generator.d.ts.map

package/v3/dist/adapters/a2ui/renderer/surface-generator.d.ts.map

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