npm - freesail - Versions diffs - 0.0.1 → 0.1.0 - Mend

freesail 0.0.1 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (54) hide show

package/README.md +190 -5
package/docs/A2UX_Protocol.md +183 -0
package/docs/Agents.md +218 -0
package/docs/Architecture.md +285 -0
package/docs/CatalogReference.md +377 -0
package/docs/GettingStarted.md +230 -0
package/examples/demo/package.json +21 -0
package/examples/demo/public/index.html +381 -0
package/examples/demo/server.js +253 -0
package/package.json +38 -5
package/packages/core/package.json +48 -0
package/packages/core/src/functions.ts +403 -0
package/packages/core/src/index.ts +214 -0
package/packages/core/src/parser.ts +270 -0
package/packages/core/src/protocol.ts +254 -0
package/packages/core/src/store.ts +452 -0
package/packages/core/src/transport.ts +439 -0
package/packages/core/src/types.ts +209 -0
package/packages/core/tsconfig.json +10 -0
package/packages/lit-ui/package.json +44 -0
package/packages/lit-ui/src/catalogs/standard/catalog.json +405 -0
package/packages/lit-ui/src/catalogs/standard/elements/Badge.ts +96 -0
package/packages/lit-ui/src/catalogs/standard/elements/Button.ts +147 -0
package/packages/lit-ui/src/catalogs/standard/elements/Card.ts +78 -0
package/packages/lit-ui/src/catalogs/standard/elements/Checkbox.ts +94 -0
package/packages/lit-ui/src/catalogs/standard/elements/Column.ts +66 -0
package/packages/lit-ui/src/catalogs/standard/elements/Divider.ts +59 -0
package/packages/lit-ui/src/catalogs/standard/elements/Image.ts +54 -0
package/packages/lit-ui/src/catalogs/standard/elements/Input.ts +125 -0
package/packages/lit-ui/src/catalogs/standard/elements/Progress.ts +79 -0
package/packages/lit-ui/src/catalogs/standard/elements/Row.ts +68 -0
package/packages/lit-ui/src/catalogs/standard/elements/Select.ts +110 -0
package/packages/lit-ui/src/catalogs/standard/elements/Spacer.ts +37 -0
package/packages/lit-ui/src/catalogs/standard/elements/Spinner.ts +76 -0
package/packages/lit-ui/src/catalogs/standard/elements/Text.ts +86 -0
package/packages/lit-ui/src/catalogs/standard/elements/index.ts +18 -0
package/packages/lit-ui/src/catalogs/standard/index.ts +17 -0
package/packages/lit-ui/src/index.ts +84 -0
package/packages/lit-ui/src/renderer.ts +211 -0
package/packages/lit-ui/src/types.ts +49 -0
package/packages/lit-ui/src/utils/define-props.ts +157 -0
package/packages/lit-ui/src/utils/index.ts +2 -0
package/packages/lit-ui/src/utils/registry.ts +139 -0
package/packages/lit-ui/tsconfig.json +11 -0
package/packages/server/package.json +61 -0
package/packages/server/src/adapters/index.ts +5 -0
package/packages/server/src/adapters/langchain.ts +175 -0
package/packages/server/src/adapters/openai.ts +209 -0
package/packages/server/src/catalog-loader.ts +311 -0
package/packages/server/src/index.ts +142 -0
package/packages/server/src/stream.ts +329 -0
package/packages/server/tsconfig.json +11 -0
package/tsconfig.base.json +23 -0
package/index.js +0 -3

package/docs/GettingStarted.md ADDED Viewed

@@ -0,0 +1,230 @@
+# Getting Started with Freesail
+This guide walks you through setting up a Freesail-powered generative UI application from scratch.
+## Prerequisites
+- Node.js 18+
+- npm or yarn
+## Installation
+### 1. Create a new project
+```bash
+mkdir my-freesail-app
+cd my-freesail-app
+npm init -y
+```
+### 2. Install Freesail packages
+```bash
+# Core packages
+npm install @freesail/core @freesail/server
+# Optional: Lit UI components
+npm install @freesail/lit-ui
+# Server dependencies
+npm install express
+```
+## Basic Server Setup
+Create a simple Express server with SSE streaming:
+```typescript
+// server.ts
+import express from 'express';
+import { FreesailStream, CatalogToToolConverter } from '@freesail/server';
+const app = express();
+// SSE endpoint
+app.get('/api/stream', (req, res) => {
+  const stream = new FreesailStream({ response: res });
+  // Create a UI surface
+  stream.createSurface('main', 'standard_catalog_v1');
+  // Send initial UI
+  stream.send({
+    updateComponents: {
+      surfaceId: 'main',
+      components: [
+        {
+          id: 'root',
+          component: 'Column',
+          gap: '16px',
+          padding: '24px',
+          children: ['title', 'content']
+        },
+        {
+          id: 'title',
+          component: 'Text',
+          text: 'Welcome!',
+          variant: 'h1'
+        },
+        {
+          id: 'content',
+          component: 'Text',
+          text: 'This UI was generated by an AI agent.'
+        }
+      ]
+    }
+  });
+});
+app.listen(3000, () => {
+  console.log('Server running at http://localhost:3000');
+});
+```
+## Basic Client Setup
+Create an HTML page that connects to the SSE stream:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Freesail App</title>
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module">
+    import { FreesailClient } from '@freesail/core';
+    import { registerStandardCatalog, createSurfaceRenderer } from '@freesail/lit-ui';
+    // Register the standard component catalog
+    registerStandardCatalog();
+    // Create client and connect
+    const client = new FreesailClient({
+      url: '/api/stream',
+      debug: true
+    });
+    // Listen for surface creation
+    client.getProtocol().on('createSurface', ({ surfaceId, catalogId }) => {
+      // Create a renderer for this surface
+      createSurfaceRenderer({
+        container: document.getElementById('app'),
+        surfaceId,
+        store: client.getStore(),
+        debug: true
+      });
+    });
+    // Connect to server
+    await client.connect();
+  </script>
+</body>
+</html>
+```
+## Understanding the A2UX Protocol
+### Surface Lifecycle
+1. **Create Surface**: Agent initializes a UI container
+2. **Update Components**: Agent streams component definitions
+3. **Update Data**: Agent pushes data changes
+4. **User Action**: Client reports user interactions
+5. **Delete Surface**: Agent removes the UI
+### Component Structure
+Components are defined as a flat list with parent-child relationships:
+```json
+{
+  "updateComponents": {
+    "surfaceId": "main",
+    "components": [
+      { "id": "root", "component": "Column", "children": ["child1", "child2"] },
+      { "id": "child1", "component": "Text", "text": "Hello" },
+      { "id": "child2", "component": "Button", "label": "Click me", "action": "button_click" }
+    ]
+  }
+}
+```
+### Data Model
+Separate UI structure from data using `updateDataModel`:
+```json
+{
+  "updateDataModel": {
+    "surfaceId": "main",
+    "path": "/user",
+    "value": { "name": "John", "email": "john@example.com" }
+  }
+}
+```
+Bind components to data using `$data:` prefix:
+```json
+{ "id": "greeting", "component": "Text", "text": "$data:/user/name" }
+```
+## Handling User Actions
+When users interact with the UI, the client sends `userAction` messages:
+```typescript
+// Server-side action handler
+app.post('/api/action', express.json(), (req, res) => {
+  const { userAction } = req.body;
+  console.log('Action:', userAction.action);
+  console.log('Context:', userAction.context);
+  // Process action and update UI...
+  res.json({ success: true });
+});
+```
+The client automatically includes the full data model state in the `context` field.
+## Using with LLMs
+### OpenAI Integration
+```typescript
+import OpenAI from 'openai';
+import { createOpenAIAdapter, CatalogToToolConverter } from '@freesail/server';
+const openai = new OpenAI();
+const converter = new CatalogToToolConverter();
+converter.addCatalog(standardCatalog);
+app.get('/api/stream', (req, res) => {
+  const stream = new FreesailStream({ response: res });
+  const adapter = createOpenAIAdapter({ stream, catalogId, converter });
+  // Chat with OpenAI using UI tools
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [
+      { role: 'system', content: converter.generateSystemPromptSection(catalogId) },
+      { role: 'user', content: 'Show me a welcome form' }
+    ],
+    tools: adapter.getTools()
+  });
+  // Process tool calls to render UI
+  processOpenAIResponse(response, adapter);
+});
+```
+## Next Steps
+- [Architecture Guide](./Architecture.md) - Deep dive into system design
+- [Catalog Reference](./CatalogReference.md) - Standard component documentation
+- [A2UX Protocol](./A2UX_Protocol.md) - Complete protocol specification

package/examples/demo/package.json ADDED Viewed

@@ -0,0 +1,21 @@
+{
+  "name": "@freesail/demo",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Freesail Demo - Example application showcasing the SDK",
+  "type": "module",
+  "scripts": {
+    "dev": "node server.js",
+    "build": "echo 'Demo does not require build'",
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "@freesail/core": "^0.1.0",
+    "@freesail/server": "^0.1.0",
+    "express": "^4.18.2"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.10.0"
+  }
+}

package/examples/demo/public/index.html ADDED Viewed

@@ -0,0 +1,381 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Freesail Demo</title>
+  <style>
+    * {
+      box-sizing: border-box;
+    }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
+      margin: 0;
+      padding: 0;
+      background: #f5f5f5;
+      min-height: 100vh;
+    }
+    .app-container {
+      max-width: 800px;
+      margin: 0 auto;
+      padding: 20px;
+    }
+    .status-bar {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+      padding: 12px 16px;
+      background: white;
+      border-radius: 8px;
+      margin-bottom: 20px;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+    }
+    .status-dot {
+      width: 10px;
+      height: 10px;
+      border-radius: 50%;
+      background: #ccc;
+    }
+    .status-dot.connected {
+      background: #22c55e;
+    }
+    .status-dot.connecting {
+      background: #eab308;
+      animation: pulse 1s infinite;
+    }
+    @keyframes pulse {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.5; }
+    }
+    #surface-container {
+      background: white;
+      border-radius: 12px;
+      box-shadow: 0 4px 6px rgba(0,0,0,0.1);
+      min-height: 400px;
+    }
+    .loading {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      height: 400px;
+      color: #666;
+    }
+    .error-message {
+      padding: 20px;
+      background: #fee2e2;
+      border-radius: 8px;
+      color: #b91c1c;
+    }
+  </style>
+</head>
+<body>
+  <div class="app-container">
+    <div class="status-bar">
+      <div class="status-dot" id="status-dot"></div>
+      <span id="status-text">Connecting...</span>
+    </div>
+    <div id="surface-container">
+      <div class="loading">
+        <span>Loading UI...</span>
+      </div>
+    </div>
+  </div>
+  <!-- Import Lit for Web Components -->
+  <script type="module">
+    import { html, render } from 'https://cdn.jsdelivr.net/npm/lit@3/+esm';
+    // Simple A2UX Client Implementation (minimal version)
+    class FreesailClient {
+      constructor(options) {
+        this.url = options.url;
+        this.container = options.container;
+        this.surfaces = new Map();
+        this.components = new Map();
+        this.dataModels = new Map();
+        this.eventSource = null;
+        this.onStatusChange = options.onStatusChange || (() => {});
+      }
+      connect() {
+        this.onStatusChange('connecting');
+        this.eventSource = new EventSource(this.url);
+        this.eventSource.onopen = () => {
+          this.onStatusChange('connected');
+        };
+        this.eventSource.onmessage = (event) => {
+          if (event.data === '[DONE]') {
+            return;
+          }
+          try {
+            const message = JSON.parse(event.data);
+            this.processMessage(message);
+          } catch (e) {
+            console.error('Failed to parse message:', e);
+          }
+        };
+        this.eventSource.onerror = () => {
+          this.onStatusChange('disconnected');
+        };
+      }
+      processMessage(message) {
+        if (message.createSurface) {
+          this.handleCreateSurface(message.createSurface);
+        } else if (message.updateComponents) {
+          this.handleUpdateComponents(message.updateComponents);
+        } else if (message.updateDataModel) {
+          this.handleUpdateDataModel(message.updateDataModel);
+        } else if (message.deleteSurface) {
+          this.handleDeleteSurface(message.deleteSurface);
+        }
+      }
+      handleCreateSurface({ surfaceId, catalogId }) {
+        console.log('Creating surface:', surfaceId, catalogId);
+        this.surfaces.set(surfaceId, { catalogId, components: new Map() });
+        this.dataModels.set(surfaceId, {});
+      }
+      handleUpdateComponents({ surfaceId, components }) {
+        console.log('Updating components:', surfaceId, components);
+        const surface = this.surfaces.get(surfaceId);
+        if (!surface) {
+          console.warn('Surface not found:', surfaceId);
+          return;
+        }
+        // Store components
+        for (const component of components) {
+          surface.components.set(component.id, component);
+        }
+        // Render
+        this.render(surfaceId);
+      }
+      handleUpdateDataModel({ surfaceId, path, op, value }) {
+        console.log('Updating data model:', surfaceId, path, value);
+        if (path === '/' || !path) {
+          this.dataModels.set(surfaceId, value);
+        } else {
+          const model = this.dataModels.get(surfaceId) || {};
+          this.setByPath(model, path, value);
+          this.dataModels.set(surfaceId, model);
+        }
+      }
+      handleDeleteSurface({ surfaceId }) {
+        this.surfaces.delete(surfaceId);
+        this.dataModels.delete(surfaceId);
+        this.container.innerHTML = '';
+      }
+      setByPath(obj, path, value) {
+        const keys = path.split('/').filter(Boolean);
+        let current = obj;
+        for (let i = 0; i < keys.length - 1; i++) {
+          if (!(keys[i] in current)) {
+            current[keys[i]] = {};
+          }
+          current = current[keys[i]];
+        }
+        if (keys.length > 0) {
+          current[keys[keys.length - 1]] = value;
+        }
+      }
+      render(surfaceId) {
+        const surface = this.surfaces.get(surfaceId);
+        if (!surface) return;
+        const root = surface.components.get('root');
+        if (!root) return;
+        const html = this.renderComponent(root, surface.components);
+        this.container.innerHTML = html;
+        // Attach event listeners
+        this.attachEventListeners(surfaceId);
+      }
+      renderComponent(component, components) {
+        const { id, component: type, children = [], ...props } = component;
+        let childrenHtml = '';
+        if (children.length > 0) {
+          childrenHtml = children
+            .map(childId => {
+              const child = components.get(childId);
+              return child ? this.renderComponent(child, components) : '';
+            })
+            .join('');
+        }
+        // Map component types to HTML (simplified renderer)
+        switch (type) {
+          case 'Column':
+            return `<div id="${id}" style="display:flex;flex-direction:column;gap:${props.gap || '8px'};padding:${props.padding || '0'};align-items:${this.mapAlign(props.align)};justify-content:${this.mapJustify(props.justify)}">${childrenHtml}</div>`;
+          case 'Row':
+            return `<div id="${id}" style="display:flex;flex-direction:row;gap:${props.gap || '8px'};padding:${props.padding || '0'};align-items:${this.mapAlign(props.align)};justify-content:${this.mapJustify(props.justify)}">${childrenHtml}</div>`;
+          case 'Text':
+            const textStyles = `color:${props.color || 'inherit'};text-align:${props.align || 'left'}`;
+            switch (props.variant) {
+              case 'h1': return `<h1 id="${id}" style="${textStyles}">${props.text}</h1>`;
+              case 'h2': return `<h2 id="${id}" style="${textStyles}">${props.text}</h2>`;
+              case 'h3': return `<h3 id="${id}" style="${textStyles}">${props.text}</h3>`;
+              default: return `<p id="${id}" style="${textStyles}">${props.text}</p>`;
+            }
+          case 'Button':
+            const btnStyle = this.getButtonStyle(props.variant);
+            return `<button id="${id}" data-action="${props.action || ''}" style="${btnStyle}" ${props.disabled ? 'disabled' : ''}>${props.label}</button>`;
+          case 'Input':
+            return `
+              <div id="${id}" style="display:flex;flex-direction:column;gap:4px">
+                ${props.label ? `<label style="font-size:0.875rem;font-weight:500;color:#374151">${props.label}</label>` : ''}
+                <input type="${props.type || 'text'}" placeholder="${props.placeholder || ''}" data-bind="${props.bindPath || ''}" style="padding:10px 12px;border:1px solid #d1d5db;border-radius:6px;font-size:1rem" />
+              </div>
+            `;
+          case 'Card':
+            return `
+              <div id="${id}" style="background:white;border-radius:8px;box-shadow:0 1px 3px rgba(0,0,0,0.1);overflow:hidden">
+                ${props.title ? `<div style="padding:16px;border-bottom:1px solid #e5e7eb"><h3 style="margin:0;font-size:1.125rem">${props.title}</h3>${props.subtitle ? `<p style="margin:4px 0 0;color:#6b7280;font-size:0.875rem">${props.subtitle}</p>` : ''}</div>` : ''}
+                <div style="padding:${props.padding || '16px'}">${childrenHtml}</div>
+              </div>
+            `;
+          case 'Badge':
+            return `<span id="${id}" style="${this.getBadgeStyle(props.variant)}">${props.text}</span>`;
+          case 'Checkbox':
+            return `
+              <label id="${id}" style="display:flex;align-items:center;gap:8px;cursor:pointer">
+                <input type="checkbox" data-bind="${props.bindPath || ''}" ${props.checked ? 'checked' : ''} style="width:18px;height:18px" />
+                <span>${props.label || ''}</span>
+              </label>
+            `;
+          default:
+            return `<div id="${id}">${childrenHtml}</div>`;
+        }
+      }
+      mapAlign(align) {
+        const map = { start: 'flex-start', center: 'center', end: 'flex-end', stretch: 'stretch' };
+        return map[align] || 'stretch';
+      }
+      mapJustify(justify) {
+        const map = { start: 'flex-start', center: 'center', end: 'flex-end', between: 'space-between', around: 'space-around' };
+        return map[justify] || 'flex-start';
+      }
+      getButtonStyle(variant) {
+        const base = 'padding:10px 20px;border:none;border-radius:6px;font-size:1rem;font-weight:500;cursor:pointer;';
+        switch (variant) {
+          case 'primary': return base + 'background:#2563eb;color:white;';
+          case 'secondary': return base + 'background:#6b7280;color:white;';
+          case 'outline': return base + 'background:transparent;color:#2563eb;border:2px solid #2563eb;';
+          case 'ghost': return base + 'background:transparent;color:#374151;';
+          default: return base + 'background:#2563eb;color:white;';
+        }
+      }
+      getBadgeStyle(variant) {
+        const base = 'display:inline-flex;padding:4px 12px;border-radius:9999px;font-size:0.875rem;font-weight:500;';
+        switch (variant) {
+          case 'primary': return base + 'background:#dbeafe;color:#1d4ed8;';
+          case 'success': return base + 'background:#dcfce7;color:#15803d;';
+          case 'warning': return base + 'background:#fef3c7;color:#b45309;';
+          case 'error': return base + 'background:#fee2e2;color:#b91c1c;';
+          default: return base + 'background:#e5e7eb;color:#374151;';
+        }
+      }
+      attachEventListeners(surfaceId) {
+        // Button clicks
+        this.container.querySelectorAll('button[data-action]').forEach(btn => {
+          btn.addEventListener('click', () => {
+            const action = btn.dataset.action;
+            if (action) {
+              this.sendAction(surfaceId, action);
+            }
+          });
+        });
+        // Input changes
+        this.container.querySelectorAll('input[data-bind]').forEach(input => {
+          input.addEventListener('change', (e) => {
+            const path = input.dataset.bind;
+            if (path) {
+              const value = input.type === 'checkbox' ? input.checked : input.value;
+              const model = this.dataModels.get(surfaceId) || {};
+              this.setByPath(model, path, value);
+            }
+          });
+        });
+      }
+      sendAction(surfaceId, action) {
+        const context = this.dataModels.get(surfaceId) || {};
+        fetch('/api/action', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            userAction: { surfaceId, action, context }
+          })
+        });
+      }
+      disconnect() {
+        if (this.eventSource) {
+          this.eventSource.close();
+          this.eventSource = null;
+        }
+      }
+    }
+    // Initialize client
+    const statusDot = document.getElementById('status-dot');
+    const statusText = document.getElementById('status-text');
+    const client = new FreesailClient({
+      url: '/api/stream',
+      container: document.getElementById('surface-container'),
+      onStatusChange: (status) => {
+        statusDot.className = 'status-dot ' + status;
+        statusText.textContent = status.charAt(0).toUpperCase() + status.slice(1);
+      }
+    });
+    client.connect();
+  </script>
+</body>
+</html>