freesail 0.0.1 → 0.1.0

package/packages/core/src/transport.ts

@@ -0,0 +1,439 @@
+/**
+ * Transport Layer
+ * 
+ * Handles SSE connections with automatic reconnection,
+ * action queueing, and offline support.
+ */
+
+import type { A2UXMessage, UserActionMessage, WatchSurfaceResponseMessage } from './types.js';
+import { SSEParser } from './parser.js';
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface TransportOptions {
+  /** Base URL for the SSE endpoint */
+  url: string;
+  /** Custom headers for requests */
+  headers?: Record<string, string>;
+  /** Enable automatic reconnection (default: true) */
+  autoReconnect?: boolean;
+  /** Initial reconnect delay in ms (default: 1000) */
+  reconnectDelay?: number;
+  /** Maximum reconnect delay in ms (default: 30000) */
+  maxReconnectDelay?: number;
+  /** Maximum reconnection attempts (default: Infinity) */
+  maxReconnectAttempts?: number;
+  /** Enable offline action queueing (default: true) */
+  offlineQueue?: boolean;
+  /** Debug mode */
+  debug?: boolean;
+}
+
+export interface TransportEventMap {
+  'message': A2UXMessage;
+  'connected': { url: string };
+  'disconnected': { reason: string };
+  'reconnecting': { attempt: number; delay: number };
+  'error': { message: string; originalError?: Error };
+  'queuedAction': { action: UserActionMessage | WatchSurfaceResponseMessage };
+  'flushedActions': { count: number };
+}
+
+export type TransportEventHandler<K extends keyof TransportEventMap> = 
+  (data: TransportEventMap[K]) => void;
+
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+
+// =============================================================================
+// IndexedDB Action Queue (for offline support)
+// =============================================================================
+
+const DB_NAME = 'freesail_action_queue';
+const STORE_NAME = 'actions';
+
+class ActionQueue {
+  private db: IDBDatabase | null = null;
+  private memoryQueue: (UserActionMessage | WatchSurfaceResponseMessage)[] = [];
+
+  async init(): Promise<void> {
+    if (typeof indexedDB === 'undefined') {
+      // Fall back to memory queue in non-browser environments
+      return;
+    }
+
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(DB_NAME, 1);
+      
+      request.onerror = () => reject(request.error);
+      
+      request.onsuccess = () => {
+        this.db = request.result;
+        resolve();
+      };
+      
+      request.onupgradeneeded = (event) => {
+        const db = (event.target as IDBOpenDBRequest).result;
+        if (!db.objectStoreNames.contains(STORE_NAME)) {
+          db.createObjectStore(STORE_NAME, { keyPath: 'id', autoIncrement: true });
+        }
+      };
+    });
+  }
+
+  async enqueue(action: UserActionMessage | WatchSurfaceResponseMessage): Promise<void> {
+    if (!this.db) {
+      this.memoryQueue.push(action);
+      return;
+    }
+
+    return new Promise((resolve, reject) => {
+      const transaction = this.db!.transaction([STORE_NAME], 'readwrite');
+      const store = transaction.objectStore(STORE_NAME);
+      const request = store.add({ action, timestamp: Date.now() });
+      
+      request.onsuccess = () => resolve();
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async dequeueAll(): Promise<(UserActionMessage | WatchSurfaceResponseMessage)[]> {
+    if (!this.db) {
+      const actions = [...this.memoryQueue];
+      this.memoryQueue = [];
+      return actions;
+    }
+
+    return new Promise((resolve, reject) => {
+      const transaction = this.db!.transaction([STORE_NAME], 'readwrite');
+      const store = transaction.objectStore(STORE_NAME);
+      const request = store.getAll();
+      
+      request.onsuccess = () => {
+        const items = request.result as { id: number; action: UserActionMessage | WatchSurfaceResponseMessage }[];
+        const actions = items.map(item => item.action);
+        
+        // Clear the store
+        const clearRequest = store.clear();
+        clearRequest.onsuccess = () => resolve(actions);
+        clearRequest.onerror = () => reject(clearRequest.error);
+      };
+      
+      request.onerror = () => reject(request.error);
+    });
+  }
+
+  async getCount(): Promise<number> {
+    if (!this.db) {
+      return this.memoryQueue.length;
+    }
+
+    return new Promise((resolve, reject) => {
+      const transaction = this.db!.transaction([STORE_NAME], 'readonly');
+      const store = transaction.objectStore(STORE_NAME);
+      const request = store.count();
+      
+      request.onsuccess = () => resolve(request.result);
+      request.onerror = () => reject(request.error);
+    });
+  }
+}
+
+// =============================================================================
+// SSE Transport
+// =============================================================================
+
+/**
+ * FreesailTransport manages SSE connections with resilience features:
+ * - Automatic reconnection with exponential backoff
+ * - Offline action queueing via IndexedDB
+ * - Connection state management
+ */
+export class FreesailTransport {
+  private options: Required<TransportOptions>;
+  private eventSource: EventSource | null = null;
+  private parser: SSEParser;
+  private actionQueue: ActionQueue;
+  private listeners: Map<keyof TransportEventMap, Set<TransportEventHandler<keyof TransportEventMap>>> = new Map();
+  
+  private _state: ConnectionState = 'disconnected';
+  private reconnectAttempt: number = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(options: TransportOptions) {
+    this.options = {
+      url: options.url,
+      headers: options.headers ?? {},
+      autoReconnect: options.autoReconnect ?? true,
+      reconnectDelay: options.reconnectDelay ?? 1000,
+      maxReconnectDelay: options.maxReconnectDelay ?? 30000,
+      maxReconnectAttempts: options.maxReconnectAttempts ?? Infinity,
+      offlineQueue: options.offlineQueue ?? true,
+      debug: options.debug ?? false,
+    };
+
+    this.parser = new SSEParser();
+    this.actionQueue = new ActionQueue();
+  }
+
+  // ===========================================================================
+  // Connection Management
+  // ===========================================================================
+
+  /**
+   * Connect to the SSE endpoint
+   */
+  async connect(): Promise<void> {
+    if (this._state === 'connected' || this._state === 'connecting') {
+      return;
+    }
+
+    // Initialize action queue
+    if (this.options.offlineQueue) {
+      await this.actionQueue.init();
+    }
+
+    this.setState('connecting');
+    this.createEventSource();
+  }
+
+  /**
+   * Disconnect from the SSE endpoint
+   */
+  disconnect(): void {
+    this.cancelReconnect();
+    this.closeEventSource();
+    this.setState('disconnected');
+    this.emit('disconnected', { reason: 'manual' });
+  }
+
+  /**
+   * Get current connection state
+   */
+  get state(): ConnectionState {
+    return this._state;
+  }
+
+  /**
+   * Check if connected
+   */
+  get isConnected(): boolean {
+    return this._state === 'connected';
+  }
+
+  // ===========================================================================
+  // Sending Messages
+  // ===========================================================================
+
+  /**
+   * Send a user action to the server
+   */
+  async sendAction(action: UserActionMessage): Promise<void> {
+    await this.sendMessage(action);
+  }
+
+  /**
+   * Send a watch surface response
+   */
+  async sendWatchResponse(response: WatchSurfaceResponseMessage): Promise<void> {
+    await this.sendMessage(response);
+  }
+
+  private async sendMessage(message: UserActionMessage | WatchSurfaceResponseMessage): Promise<void> {
+    if (!this.isConnected) {
+      if (this.options.offlineQueue) {
+        await this.actionQueue.enqueue(message);
+        this.emit('queuedAction', { action: message });
+        this.log(`Action queued for later: ${JSON.stringify(message)}`);
+      } else {
+        throw new Error('Not connected and offline queue is disabled');
+      }
+      return;
+    }
+
+    try {
+      const response = await fetch(this.options.url, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...this.options.headers,
+        },
+        body: JSON.stringify(message),
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      
+      // Queue for retry if offline
+      if (this.options.offlineQueue) {
+        await this.actionQueue.enqueue(message);
+        this.emit('queuedAction', { action: message });
+      }
+      
+      this.emit('error', { message: err.message, originalError: err });
+      throw err;
+    }
+  }
+
+  // ===========================================================================
+  // Event Handling
+  // ===========================================================================
+
+  on<K extends keyof TransportEventMap>(
+    event: K, 
+    handler: TransportEventHandler<K>
+  ): () => void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, new Set());
+    }
+    this.listeners.get(event)!.add(handler as TransportEventHandler<keyof TransportEventMap>);
+    
+    return () => this.off(event, handler);
+  }
+
+  off<K extends keyof TransportEventMap>(
+    event: K, 
+    handler: TransportEventHandler<K>
+  ): void {
+    this.listeners.get(event)?.delete(handler as TransportEventHandler<keyof TransportEventMap>);
+  }
+
+  private emit<K extends keyof TransportEventMap>(event: K, data: TransportEventMap[K]): void {
+    this.listeners.get(event)?.forEach(handler => {
+      try {
+        (handler as TransportEventHandler<K>)(data);
+      } catch (error) {
+        console.error(`Error in transport event handler for ${event}:`, error);
+      }
+    });
+  }
+
+  // ===========================================================================
+  // Private: EventSource Management
+  // ===========================================================================
+
+  private createEventSource(): void {
+    try {
+      this.eventSource = new EventSource(this.options.url);
+
+      this.eventSource.onopen = () => {
+        this.setState('connected');
+        this.reconnectAttempt = 0;
+        this.emit('connected', { url: this.options.url });
+        this.log('Connected to SSE endpoint');
+        
+        // Flush queued actions
+        this.flushQueue();
+      };
+
+      this.eventSource.onmessage = (event) => {
+        const messages = this.parser.feed(event.data);
+        for (const message of messages) {
+          this.emit('message', message);
+        }
+      };
+
+      this.eventSource.onerror = () => {
+        this.closeEventSource();
+        
+        if (this.options.autoReconnect && 
+            this.reconnectAttempt < this.options.maxReconnectAttempts) {
+          this.scheduleReconnect();
+        } else {
+          this.setState('disconnected');
+          this.emit('disconnected', { reason: 'error' });
+        }
+      };
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.emit('error', { message: err.message, originalError: err });
+      this.setState('disconnected');
+    }
+  }
+
+  private closeEventSource(): void {
+    if (this.eventSource) {
+      this.eventSource.close();
+      this.eventSource = null;
+    }
+    this.parser.reset();
+  }
+
+  // ===========================================================================
+  // Private: Reconnection Logic
+  // ===========================================================================
+
+  private scheduleReconnect(): void {
+    this.setState('reconnecting');
+    this.reconnectAttempt++;
+
+    // Exponential backoff with jitter
+    const baseDelay = Math.min(
+      this.options.reconnectDelay * Math.pow(2, this.reconnectAttempt - 1),
+      this.options.maxReconnectDelay
+    );
+    const jitter = Math.random() * 0.3 * baseDelay;
+    const delay = baseDelay + jitter;
+
+    this.emit('reconnecting', { attempt: this.reconnectAttempt, delay });
+    this.log(`Reconnecting in ${Math.round(delay)}ms (attempt ${this.reconnectAttempt})`);
+
+    this.reconnectTimer = setTimeout(() => {
+      this.createEventSource();
+    }, delay);
+  }
+
+  private cancelReconnect(): void {
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+
+  // ===========================================================================
+  // Private: Queue Management
+  // ===========================================================================
+
+  private async flushQueue(): Promise<void> {
+    if (!this.options.offlineQueue) return;
+
+    try {
+      const actions = await this.actionQueue.dequeueAll();
+      
+      if (actions.length > 0) {
+        this.log(`Flushing ${actions.length} queued actions`);
+        
+        for (const action of actions) {
+          try {
+            await this.sendMessage(action);
+          } catch (error) {
+            // Re-queue on failure
+            this.log(`Failed to flush action, re-queueing: ${error}`);
+          }
+        }
+        
+        this.emit('flushedActions', { count: actions.length });
+      }
+    } catch (error) {
+      console.error('Failed to flush action queue:', error);
+    }
+  }
+
+  // ===========================================================================
+  // Private: State & Logging
+  // ===========================================================================
+
+  private setState(state: ConnectionState): void {
+    this._state = state;
+  }
+
+  private log(message: string): void {
+    if (this.options.debug) {
+      console.log(`[FreesailTransport] ${message}`);
+    }
+  }
+}

package/packages/core/src/types.ts

@@ -0,0 +1,209 @@
+/**
+ * A2UX Protocol Types
+ * 
+ * Defines the complete type system for the A2UX protocol,
+ * an extension of Google A2UI for generative UI communication.
+ */
+
+// =============================================================================
+// Component Types
+// =============================================================================
+
+/**
+ * Base component definition used in updateComponents messages
+ */
+export interface A2UXComponent {
+  /** Unique identifier for this component within the surface */
+  id: string;
+  /** The component type from the catalog (e.g., 'Text', 'Button', 'Column') */
+  component: string;
+  /** Child component IDs (for container components) */
+  children?: string[];
+  /** Any additional properties defined in the catalog */
+  [key: string]: unknown;
+}
+
+// =============================================================================
+// Server to Client Messages (Downstream)
+// =============================================================================
+
+/**
+ * createSurface - Initializes a UI container and loads a specific Catalog
+ */
+export interface CreateSurfaceMessage {
+  createSurface: {
+    /** Unique identifier for the UI surface */
+    surfaceId: string;
+    /** Catalog identifier for component definitions */
+    catalogId: string;
+  };
+}
+
+/**
+ * updateComponents - Streams structural UI definitions
+ */
+export interface UpdateComponentsMessage {
+  updateComponents: {
+    /** Target surface ID */
+    surfaceId: string;
+    /** Array of component definitions (flat adjacency list) */
+    components: A2UXComponent[];
+  };
+}
+
+/**
+ * updateDataModel - Pushes data/state changes to the UI
+ */
+export interface UpdateDataModelMessage {
+  updateDataModel: {
+    /** Target surface ID */
+    surfaceId: string;
+    /** JSON Pointer path for partial updates (optional) */
+    path?: string;
+    /** Operation type: 'add', 'replace', or 'remove' */
+    op?: 'add' | 'replace' | 'remove';
+    /** The data value (required for 'add' and 'replace') */
+    value?: unknown;
+  };
+}
+
+/**
+ * deleteSurface - Removes a surface and all its components
+ */
+export interface DeleteSurfaceMessage {
+  deleteSurface: {
+    /** Surface ID to delete */
+    surfaceId: string;
+  };
+}
+
+/**
+ * watchSurface - Configures automatic state reporting
+ */
+export interface WatchSurfaceMessage {
+  watchSurface: {
+    /** Target surface ID */
+    surfaceId: string;
+    /** Reporting interval in seconds (default: 10) */
+    interval?: number;
+    /** Watch expiration in seconds (default: 300) */
+    expiresIn?: number;
+  };
+}
+
+/**
+ * unwatchSurface - Removes a surface watcher
+ */
+export interface UnwatchSurfaceMessage {
+  unwatchSurface: {
+    /** Surface ID to unwatch */
+    surfaceId: string;
+  };
+}
+
+// =============================================================================
+// Client to Server Messages (Upstream)
+// =============================================================================
+
+/**
+ * userAction - Reports user interactions to the server
+ */
+export interface UserActionMessage {
+  userAction: {
+    /** Source surface ID */
+    surfaceId: string;
+    /** Semantic action label (e.g., 'submit_form', 'button_click') */
+    action: string;
+    /** Full context/state relevant to the action */
+    context: Record<string, unknown>;
+  };
+}
+
+/**
+ * watchSurfaceResponse - Automatic state report from watch
+ */
+export interface WatchSurfaceResponseMessage {
+  watchSurfaceResponse: {
+    /** Source surface ID */
+    surfaceId: string;
+    /** Current data model state (JSON Pointer paths as keys) */
+    data: Record<string, unknown>;
+  };
+}
+
+// =============================================================================
+// Union Types
+// =============================================================================
+
+/** All server-to-client message types */
+export type ServerToClientMessage =
+  | CreateSurfaceMessage
+  | UpdateComponentsMessage
+  | UpdateDataModelMessage
+  | DeleteSurfaceMessage
+  | WatchSurfaceMessage
+  | UnwatchSurfaceMessage;
+
+/** All client-to-server message types */
+export type ClientToServerMessage =
+  | UserActionMessage
+  | WatchSurfaceResponseMessage;
+
+/** Any A2UX protocol message */
+export type A2UXMessage = ServerToClientMessage | ClientToServerMessage;
+
+// =============================================================================
+// Type Guards
+// =============================================================================
+
+export function isCreateSurface(msg: A2UXMessage): msg is CreateSurfaceMessage {
+  return 'createSurface' in msg;
+}
+
+export function isUpdateComponents(msg: A2UXMessage): msg is UpdateComponentsMessage {
+  return 'updateComponents' in msg;
+}
+
+export function isUpdateDataModel(msg: A2UXMessage): msg is UpdateDataModelMessage {
+  return 'updateDataModel' in msg;
+}
+
+export function isDeleteSurface(msg: A2UXMessage): msg is DeleteSurfaceMessage {
+  return 'deleteSurface' in msg;
+}
+
+export function isWatchSurface(msg: A2UXMessage): msg is WatchSurfaceMessage {
+  return 'watchSurface' in msg;
+}
+
+export function isUnwatchSurface(msg: A2UXMessage): msg is UnwatchSurfaceMessage {
+  return 'unwatchSurface' in msg;
+}
+
+export function isUserAction(msg: A2UXMessage): msg is UserActionMessage {
+  return 'userAction' in msg;
+}
+
+export function isWatchSurfaceResponse(msg: A2UXMessage): msg is WatchSurfaceResponseMessage {
+  return 'watchSurfaceResponse' in msg;
+}
+
+// =============================================================================
+// Message Utilities
+// =============================================================================
+
+/**
+ * Gets the message type from an A2UX message
+ */
+export function getMessageType(msg: A2UXMessage): string {
+  return Object.keys(msg)[0];
+}
+
+/**
+ * Gets the surfaceId from any A2UX message
+ */
+export function getSurfaceId(msg: A2UXMessage): string {
+  const key = getMessageType(msg);
+  const payload = (msg as unknown as Record<string, { surfaceId: string }>)[key];
+  return payload.surfaceId;
+}

package/packages/core/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "composite": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

package/packages/lit-ui/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@freesail/lit-ui",
+  "version": "0.1.0",
+  "description": "Freesail Lit UI - Web Components for A2UX Protocol",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./standard": {
+      "types": "./dist/catalogs/standard/index.d.ts",
+      "import": "./dist/catalogs/standard/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts"
+  },
+  "dependencies": {
+    "@freesail/core": "^0.1.0",
+    "lit": "^3.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.0"
+  },
+  "keywords": [
+    "web-components",
+    "lit",
+    "a2ux",
+    "generative-ui"
+  ],
+  "license": "MIT"
+}