freesail 0.0.1 → 0.1.0

package/docs/Architecture.md

@@ -0,0 +1,285 @@
+# Freesail Architecture
+
+This document describes the architectural design of Freesail, its core principles, and how the components work together.
+
+## Overview
+
+Freesail follows a **Schema-Driven, Transport-Agnostic** architecture that separates concerns across three main layers:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         AI Agent Layer                          │
+│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐    │
+│  │ LangChain │  │ LlamaIndex│  │  OpenAI   │  │  Custom   │    │
+│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘    │
+│        │              │              │              │           │
+│        └──────────────┴──────────────┴──────────────┘           │
+│                              │                                   │
+│                    ┌─────────▼─────────┐                        │
+│                    │   Adapter Layer   │                        │
+│                    │ (Tool Conversion) │                        │
+│                    └─────────┬─────────┘                        │
+└──────────────────────────────┼──────────────────────────────────┘
+                               │
+┌──────────────────────────────┼──────────────────────────────────┐
+│                        Protocol Layer                            │
+│                    ┌─────────▼─────────┐                        │
+│                    │   A2UX Protocol   │                        │
+│                    │   (JSON Schema)   │                        │
+│                    └─────────┬─────────┘                        │
+└──────────────────────────────┼──────────────────────────────────┘
+                               │
+┌──────────────────────────────┼──────────────────────────────────┐
+│                       Transport Layer                            │
+│                    ┌─────────▼─────────┐                        │
+│                    │    SSE Stream     │                        │
+│                    │  (HTTP/2, retry)  │                        │
+│                    └─────────┬─────────┘                        │
+└──────────────────────────────┼──────────────────────────────────┘
+                               │
+┌──────────────────────────────┼──────────────────────────────────┐
+│                         Client Layer                             │
+│                    ┌─────────▼─────────┐                        │
+│                    │  Surface Store    │                        │
+│                    │  (State Manager)  │                        │
+│                    └─────────┬─────────┘                        │
+│        ┌─────────────────────┼─────────────────────┐            │
+│        │                     │                     │            │
+│  ┌─────▼─────┐        ┌─────▼─────┐        ┌─────▼─────┐       │
+│  │   React   │        │    Lit    │        │  Angular  │       │
+│  │  Adapter  │        │   (Web)   │        │  Adapter  │       │
+│  └───────────┘        └───────────┘        └───────────┘       │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Core Principles
+
+### 1. The Contract is the Code
+
+The JSON Schema catalog is the **single source of truth** for:
+- Component properties and types
+- LLM tool definitions
+- UI property validation
+
+```typescript
+// BAD: Duplicating property definitions
+class MyButton extends LitElement {
+  @property({ type: String }) label = 'Click';  // Duplicates schema
+}
+
+// GOOD: Deriving from catalog
+class MyButton extends LitElement {
+  static properties = defineProps(catalog, 'Button');  // Single source
+}
+```
+
+### 2. Orchestrator Agnosticism
+
+Core logic never imports framework-specific code. Framework integration happens through **Adapters**:
+
+```
+@freesail/server/src/
+├── catalog-loader.ts    # Framework-agnostic tool generation
+└── adapters/
+    ├── langchain.ts     # LangChain DynamicStructuredTool
+    ├── openai.ts        # OpenAI Function Calling
+    └── llamaindex.ts    # LlamaIndex FunctionTool
+```
+
+### 3. Stateless Agent Communication
+
+The agent is stateless. Every user action includes the **full context**:
+
+```json
+{
+  "userAction": {
+    "surfaceId": "form_123",
+    "action": "submit",
+    "context": {
+      "user": { "name": "John", "email": "john@example.com" },
+      "form": { "valid": true, "touched": ["name", "email"] }
+    }
+  }
+}
+```
+
+### 4. Schema-First Components
+
+UI components hydrate their properties directly from the catalog:
+
+```
+/catalogs/standard/
+├── catalog.json         # Component definitions
+└── elements/
+    ├── Text.ts          # Uses defineProps(catalog, 'Text')
+    └── Button.ts        # Uses defineProps(catalog, 'Button')
+```
+
+## Package Architecture
+
+### @freesail/core
+
+The "brain" of the SDK - handles protocol, transport, and state.
+
+```
+src/
+├── types.ts        # A2UX Protocol TypeScript definitions
+├── protocol.ts     # Message processor and dispatcher
+├── parser.ts       # JSON/SSE stream parsing
+├── transport.ts    # SSE connection with retry/queue
+├── store.ts        # Reactive surface state management
+├── functions.ts    # Standard functions (formatCurrency, etc.)
+└── index.ts        # Public API exports
+```
+
+**Key Classes:**
+- `FreesailClient` - Main client entry point
+- `A2UXProtocolHandler` - Message routing
+- `FreesailTransport` - Connection management
+- `SurfaceStore` - State container
+
+### @freesail/lit-ui
+
+Web Components implementation using Lit.
+
+```
+src/
+├── types.ts              # Catalog type definitions
+├── renderer.ts           # Dynamic DOM renderer
+├── utils/
+│   ├── define-props.ts   # Catalog → Lit properties
+│   └── registry.ts       # Component registration
+└── catalogs/
+    └── standard/
+        ├── catalog.json  # A2UI Standard definitions
+        └── elements/     # Lit implementations
+            ├── Text.ts
+            ├── Button.ts
+            └── ...
+```
+
+**Key Functions:**
+- `defineProps()` - Generate Lit properties from catalog
+- `registerStandardCatalog()` - Register all standard components
+- `createSurfaceRenderer()` - Create reactive renderer
+
+### @freesail/server
+
+Server-side SSE streaming and framework adapters.
+
+```
+src/
+├── stream.ts           # SSE connection handler
+├── catalog-loader.ts   # Catalog → Tool converter
+└── adapters/
+    ├── langchain.ts    # LangChain integration
+    ├── openai.ts       # OpenAI integration
+    └── index.ts        # Adapter exports
+```
+
+**Key Classes:**
+- `FreesailStream` - SSE message writer
+- `CatalogToToolConverter` - Schema → LLM tools
+- `OpenAIAdapter` - OpenAI tool handling
+
+## Data Flow
+
+### 1. Agent → UI (Downstream)
+
+```
+Agent Decision
+      │
+      ▼
+Tool Call: render_ui({ surfaceId, components })
+      │
+      ▼
+Adapter converts to A2UX messages
+      │
+      ▼
+FreesailStream.send() → SSE write
+      │
+      ▼
+Client EventSource receives
+      │
+      ▼
+A2UXProtocolHandler processes
+      │
+      ▼
+SurfaceStore updates state
+      │
+      ▼
+SurfaceRenderer re-renders DOM
+```
+
+### 2. UI → Agent (Upstream)
+
+```
+User clicks Button
+      │
+      ▼
+Component dispatches fs-action event
+      │
+      ▼
+Client gathers full context from store
+      │
+      ▼
+POST /api/action { userAction }
+      │
+      ▼
+Server routes to agent
+      │
+      ▼
+Agent processes and decides next action
+```
+
+## Transport Resilience
+
+The transport layer handles:
+
+1. **Auto-Reconnection** - Exponential backoff on disconnect
+2. **Offline Queue** - IndexedDB-backed action queue
+3. **Idempotency** - Server handles duplicate messages
+4. **Keep-Alive** - Periodic heartbeats
+
+```typescript
+const transport = new FreesailTransport({
+  url: '/api/stream',
+  autoReconnect: true,
+  reconnectDelay: 1000,
+  maxReconnectDelay: 30000,
+  offlineQueue: true,
+});
+```
+
+## Multi-Catalog Support
+
+Different surfaces can use different component catalogs:
+
+```typescript
+// Finance dashboard with custom components
+stream.createSurface('dashboard', 'finance_v1');
+
+// Standard form
+stream.createSurface('settings', 'standard_catalog_v1');
+```
+
+The client registry maps catalog IDs to component bundles:
+
+```typescript
+registry.registerCatalog('finance_v1', financeCatalog, financeComponents, 'fin');
+// Components registered as: fin-ticker, fin-chart, etc.
+```
+
+## Security Considerations
+
+1. **Input Validation** - All properties validated against catalog schema
+2. **No innerHTML** - Rendering goes through component registry only
+3. **Action Context** - Full state ensures agent has context for decisions
+4. **Rate Limiting** - Implement at transport/server level
+
+## Performance Optimizations
+
+1. **Incremental Updates** - `updateDataModel` avoids full re-render
+2. **Component Caching** - Web Components are defined once
+3. **Stream Backpressure** - SSE handles flow control
+4. **Lazy Loading** - Catalogs can be loaded on demand

package/docs/CatalogReference.md

@@ -0,0 +1,377 @@
+# Standard Catalog Reference
+
+This document describes all components available in the Freesail Standard Catalog (`standard_catalog_v1`), which implements the A2UI Standard for cross-compatible generative UI.
+
+## Layout Components
+
+### Column
+
+A vertical flex container that stacks children vertically.
+
+**Tag:** `<fs-column>`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `gap` | string | `"8px"` | Gap between child elements (CSS value) |
+| `align` | string | `"stretch"` | Alignment: `start`, `center`, `end`, `stretch` |
+| `justify` | string | `"start"` | Justification: `start`, `center`, `end`, `between`, `around` |
+| `padding` | string | `"0"` | Padding inside the column |
+
+**Example:**
+```json
+{
+  "id": "container",
+  "component": "Column",
+  "gap": "16px",
+  "padding": "24px",
+  "children": ["header", "content", "footer"]
+}
+```
+
+---
+
+### Row
+
+A horizontal flex container that arranges children horizontally.
+
+**Tag:** `<fs-row>`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `gap` | string | `"8px"` | Gap between child elements |
+| `align` | string | `"center"` | Alignment: `start`, `center`, `end`, `stretch` |
+| `justify` | string | `"start"` | Justification: `start`, `center`, `end`, `between`, `around` |
+| `wrap` | boolean | `false` | Whether children should wrap |
+| `padding` | string | `"0"` | Padding inside the row |
+
+---
+
+### Card
+
+A card container with optional title and elevation.
+
+**Tag:** `<fs-card>`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `title` | string | - | Card title |
+| `subtitle` | string | - | Card subtitle |
+| `padding` | string | `"16px"` | Content padding |
+| `elevated` | boolean | `true` | Show elevation shadow |
+
+**Example:**
+```json
+{
+  "id": "profile-card",
+  "component": "Card",
+  "title": "User Profile",
+  "subtitle": "Manage your account settings",
+  "children": ["form-fields"]
+}
+```
+
+---
+
+### Spacer
+
+A flexible space component for layout.
+
+**Tag:** `<fs-spacer>`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `size` | string | `"flex"` | Fixed size (CSS value) or `"flex"` for flexible |
+
+---
+
+### Divider
+
+A horizontal or vertical divider line.
+
+**Tag:** `<fs-divider>`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `orientation` | string | `"horizontal"` | `horizontal` or `vertical` |
+| `thickness` | string | `"1px"` | Line thickness |
+| `color` | string | `"#e0e0e0"` | Line color |
+
+---
+
+## Text Components
+
+### Text
+
+A text display component with variant styles.
+
+**Tag:** `<fs-text>`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `text` | string | `""` | **Required.** The text content |
+| `variant` | string | `"body"` | Style: `h1`-`h6`, `body`, `caption`, `overline` |
+| `color` | string | `"inherit"` | Text color |
+| `weight` | string | `"normal"` | Weight: `light`, `normal`, `medium`, `semibold`, `bold` |
+| `align` | string | `"left"` | Alignment: `left`, `center`, `right`, `justify` |
+
+**Variant Sizes:**
+- `h1`: 2.5rem
+- `h2`: 2rem
+- `h3`: 1.75rem
+- `h4`: 1.5rem
+- `h5`: 1.25rem
+- `h6`: 1rem
+- `body`: 1rem
+- `caption`: 0.875rem
+- `overline`: 0.75rem (uppercase)
+
+---
+
+## Input Components
+
+### Input
+
+A text input field with label and validation.
+
+**Tag:** `<fs-input>`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | string | `""` | Current value |
+| `placeholder` | string | `""` | Placeholder text |
+| `label` | string | - | Input label |
+| `type` | string | `"text"` | Type: `text`, `email`, `password`, `number`, `tel`, `url` |
+| `disabled` | boolean | `false` | Disabled state |
+| `required` | boolean | `false` | Required state |
+| `error` | string | - | Error message |
+| `bindPath` | string | - | JSON Pointer path for data binding |
+
+**Events:**
+- `fs-change`: Fired when value changes. Detail: `{ value, bindPath, componentId }`
+
+---
+
+### Select
+
+A dropdown select component.
+
+**Tag:** `<fs-select>`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | string | - | Selected value |
+| `options` | array | `[]` | Options: `[{ value, label }]` |
+| `placeholder` | string | `"Select an option"` | Placeholder |
+| `label` | string | - | Select label |
+| `disabled` | boolean | `false` | Disabled state |
+| `bindPath` | string | - | JSON Pointer for binding |
+
+---
+
+### Checkbox
+
+A checkbox input with label.
+
+**Tag:** `<fs-checkbox>`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `checked` | boolean | `false` | Checked state |
+| `label` | string | - | Checkbox label |
+| `disabled` | boolean | `false` | Disabled state |
+| `bindPath` | string | - | JSON Pointer for binding |
+
+---
+
+## Action Components
+
+### Button
+
+An interactive button component.
+
+**Tag:** `<fs-button>`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `label` | string | `"Button"` | Button text |
+| `variant` | string | `"primary"` | Style: `primary`, `secondary`, `outline`, `ghost`, `destructive` |
+| `size` | string | `"medium"` | Size: `small`, `medium`, `large` |
+| `disabled` | boolean | `false` | Disabled state |
+| `action` | string | - | Action identifier sent on click |
+| `fullWidth` | boolean | `false` | Full width button |
+
+**Events:**
+- `fs-action`: Fired on click. Detail: `{ action, componentId }`
+
+**Variant Styles:**
+- `primary`: Blue background, white text
+- `secondary`: Gray background, white text
+- `outline`: Transparent with blue border
+- `ghost`: Transparent, dark text
+- `destructive`: Red background, white text
+
+---
+
+## Feedback Components
+
+### Badge
+
+A badge/chip component for status or labels.
+
+**Tag:** `<fs-badge>`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `text` | string | - | **Required.** Badge text |
+| `variant` | string | `"default"` | Style: `default`, `primary`, `success`, `warning`, `error`, `info` |
+| `size` | string | `"medium"` | Size: `small`, `medium`, `large` |
+
+---
+
+### Spinner
+
+A loading spinner indicator.
+
+**Tag:** `<fs-spinner>`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `size` | string | `"medium"` | Size: `small`, `medium`, `large` |
+| `color` | string | `"currentColor"` | Spinner color |
+
+---
+
+### Progress
+
+A progress bar indicator.
+
+**Tag:** `<fs-progress>`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | number | `0` | Current value (0-100) |
+| `max` | number | `100` | Maximum value |
+| `showLabel` | boolean | `false` | Show percentage label |
+| `color` | string | `"#2563eb"` | Bar color |
+
+---
+
+## Media Components
+
+### Image
+
+An image display component.
+
+**Tag:** `<fs-image>`
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `src` | string | - | **Required.** Image source URL |
+| `alt` | string | `""` | Alt text for accessibility |
+| `width` | string | - | Image width (CSS) |
+| `height` | string | - | Image height (CSS) |
+| `fit` | string | `"cover"` | Object fit: `contain`, `cover`, `fill`, `none`, `scale-down` |
+| `borderRadius` | string | `"0"` | Border radius |
+
+---
+
+## Usage Examples
+
+### Simple Form
+
+```json
+{
+  "updateComponents": {
+    "surfaceId": "form",
+    "components": [
+      {
+        "id": "root",
+        "component": "Card",
+        "title": "Contact Us",
+        "children": ["form-fields", "actions"]
+      },
+      {
+        "id": "form-fields",
+        "component": "Column",
+        "gap": "16px",
+        "children": ["name-input", "email-input", "message-input"]
+      },
+      {
+        "id": "name-input",
+        "component": "Input",
+        "label": "Name",
+        "placeholder": "Your name",
+        "required": true,
+        "bindPath": "/form/name"
+      },
+      {
+        "id": "email-input",
+        "component": "Input",
+        "type": "email",
+        "label": "Email",
+        "placeholder": "your@email.com",
+        "required": true,
+        "bindPath": "/form/email"
+      },
+      {
+        "id": "message-input",
+        "component": "Input",
+        "label": "Message",
+        "placeholder": "Your message...",
+        "bindPath": "/form/message"
+      },
+      {
+        "id": "actions",
+        "component": "Row",
+        "justify": "end",
+        "gap": "12px",
+        "children": ["submit-btn"]
+      },
+      {
+        "id": "submit-btn",
+        "component": "Button",
+        "label": "Send Message",
+        "variant": "primary",
+        "action": "submit_contact"
+      }
+    ]
+  }
+}
+```
+
+### Dashboard Card
+
+```json
+{
+  "id": "stats-card",
+  "component": "Card",
+  "title": "Monthly Stats",
+  "children": ["stats-row"]
+},
+{
+  "id": "stats-row",
+  "component": "Row",
+  "justify": "between",
+  "children": ["users-stat", "revenue-stat", "orders-stat"]
+},
+{
+  "id": "users-stat",
+  "component": "Column",
+  "align": "center",
+  "children": ["users-value", "users-label"]
+},
+{
+  "id": "users-value",
+  "component": "Text",
+  "text": "1,234",
+  "variant": "h3",
+  "weight": "bold"
+},
+{
+  "id": "users-label",
+  "component": "Text",
+  "text": "Active Users",
+  "variant": "caption",
+  "color": "#6b7280"
+}
+```