@allternit/ix 0.1.0

package/README.md

@@ -0,0 +1,320 @@
+# @allternit/ix
+
+A2R Interface eXecution - Declarative UI generation with Vercel Labs json-render compatibility.
+
+## Overview
+
+A2R-IX enables LLM-generated UI through a JSON Intermediate Representation (IR) with full compatibility for Vercel Labs json-render patterns. This allows AI agents to generate user interfaces declaratively, which are then rendered by the platform.
+
+## Features
+
+- **UI IR Schema**: Structured declarative UI definitions
+- **Component Catalog**: 15 built-in components with semantic versioning
+- **State Store**: Scoped state management with persistence
+- **JSON Patch Engine**: RFC 6902 compliant state synchronization
+- **json-render Adapter**: Bidirectional compatibility with Vercel Labs format
+- **React Renderer**: Full React component rendering
+- **Vue Renderer**: Vue 3 component generation
+- **Svelte Renderer**: Svelte component compilation
+- **IX Capsule Runtime**: Sandboxed execution with P3.9 integration
+- **Policy Gates**: Security controls (rate limiting, sanitization, validation)
+- **LLM-to-IX Pipeline**: Multi-format conversion from LLM outputs
+- **Real-time Collaboration**: Yjs/CRDT integration
+- **Visual Editor**: Fluent API for building UI IR
+
+## Installation
+
+```bash
+pnpm add @allternit/ix
+```
+
+## Quick Start
+
+### Basic React Usage
+
+```typescript
+import { createReactRenderer, createDefaultCatalog, createStateStore } from '@allternit/ix';
+
+const renderer = createReactRenderer({
+  catalog: createDefaultCatalog(),
+  stateStore: createStateStore(),
+});
+
+const ui = {
+  version: '1.0.0',
+  components: [
+    {
+      id: 'header',
+      type: 'Heading',
+      props: { children: 'Hello World', level: 1 },
+    },
+    {
+      id: 'input',
+      type: 'Input',
+      props: { placeholder: 'Enter name' },
+      bindings: [
+        { prop: 'value', statePath: 'name', direction: 'two-way' },
+      ],
+    },
+  ],
+  state: {
+    variables: [
+      { path: 'name', type: 'string', default: '' },
+    ],
+  },
+  actions: [],
+};
+
+// Render in React
+function App() {
+  return <renderer.UIRoot root={ui} />;
+}
+```
+
+### Vue Renderer
+
+```typescript
+import { createVueRenderer, compileToVue } from '@allternit/ix/vue';
+
+// Generate Vue component definition
+const vueComponent = compileToVue(uiDefinition);
+
+// Use with Vue compiler or runtime
+const { template, setup } = vueComponent;
+```
+
+### Svelte Renderer
+
+```typescript
+import { compileToSvelte } from '@allternit/ix/svelte';
+
+// Generate Svelte component code
+const svelteCode = compileToSvelte(uiDefinition);
+// Use with Svelte compiler
+```
+
+### Visual Editor
+
+```typescript
+import { ui } from '@allternit/ix';
+
+// Build UI programmatically
+const myUI = ui.create()
+  .state('count', 'number', 0)
+  .add(
+    ui.components.layout.Box({ padding: 4 })
+      .child(ui.components.typography.Heading('Counter', 1))
+      .child(
+        ui.components.input.Button('Increment')
+          .on('onClick', 'increment')
+      )
+  )
+  .build();
+```
+
+### Real-time Collaboration
+
+```typescript
+import { createYjsAdapter } from '@allternit/ix/collab';
+import * as Y from 'yjs';
+import { WebsocketProvider } from 'y-websocket';
+
+const doc = new Y.Doc();
+const provider = new WebsocketProvider('ws://localhost:1234', 'room', doc);
+
+const adapter = createYjsAdapter({
+  doc,
+  provider,
+  userId: 'user-1',
+  userInfo: { name: 'Alice', color: '#ff0000' },
+});
+
+// Collaborative state store
+const store = adapter.getStore();
+store.set('shared.value', 42); // Syncs to all connected clients
+```
+
+### JSON-Render Compatibility
+
+```typescript
+import { jsonRenderAdapter, llmToIX } from '@allternit/ix';
+
+// From json-render to A2R-IX
+const jsonRenderSchema = {
+  version: '1.0.0',
+  root: {
+    type: 'Fragment',
+    children: [
+      { type: 'Text', props: { children: 'Hello' } },
+    ],
+  },
+};
+
+const a2rUi = jsonRenderAdapter.fromJsonRender(jsonRenderSchema);
+
+// Auto-detect and convert
+const result = llmToIX.convert(jsonRenderSchema);
+```
+
+### IX Capsule Runtime
+
+```typescript
+import { 
+  createIXCapsule, 
+  globalCapsuleRegistry,
+  createRateLimitGate,
+  createPropSanitizationGate,
+} from '@allternit/ix';
+
+// Create capsule with security policies
+const capsule = globalCapsuleRegistry.create({
+  id: 'my-capsule',
+  ui: a2rUi,
+  stateStore: createStateStore(),
+  policyGates: [
+    createRateLimitGate({ maxActionsPerMinute: 60 }),
+    createPropSanitizationGate({ allowHTML: false }),
+  ],
+});
+
+// Subscribe to events
+capsule.subscribe((event) => {
+  console.log('Capsule event:', event);
+});
+
+// Apply state patches
+capsule.applyPatch([
+  { op: 'replace', path: '/count', value: 10 },
+]);
+```
+
+## Architecture
+
+```
+A2R-IX
+├── types/           # TypeScript interfaces
+├── schema/          # UI IR schema definitions
+├── catalog/         # Component registry with semver
+├── state/           # Store + JSON Patch engine (RFC 6902)
+├── adapters/        # Format converters (json-render)
+├── react/           # React renderer
+├── vue/             # Vue renderer
+├── svelte/          # Svelte renderer
+├── runtime/         # Capsule runtime + policy gates
+├── sdk/             # API client + React hooks
+├── pipeline/        # LLM-to-IX conversion
+└── collab/          # Yjs/CRDT + Visual Editor
+```
+
+## Component Catalog
+
+Built-in components:
+
+| Component | Category | Props |
+|-----------|----------|-------|
+| Box | layout | padding, margin, width, height, display, gap |
+| Stack | layout | direction, spacing, align, justify |
+| Text | typography | variant, size, weight, color, align |
+| Heading | typography | level, color |
+| Button | input | variant, size, disabled, onClick |
+| Input | input | value, placeholder, type, onChange |
+| TextArea | input | value, rows, onChange |
+| Select | input | value, options, onChange |
+| Card | display | padding, elevation, borderRadius |
+| List | display | items, renderItem, emptyText |
+| Table | display | data, columns, onRowClick |
+
+## API Reference
+
+### State Management
+
+```typescript
+import { createStateStore, applyPatch } from '@allternit/ix';
+
+const store = createStateStore({
+  initial: { count: 0 },
+  persist: true,
+  scopeId: 'my-app',
+});
+
+// Subscribe to changes
+const unsubscribe = store.subscribe('count', (value) => {
+  console.log('Count:', value);
+});
+
+// Apply JSON Patch
+const patch = [
+  { op: 'replace', path: '/count', value: 5 },
+];
+applyPatchToStore(store, patch);
+```
+
+### Policy Gates
+
+```typescript
+import {
+  createRateLimitGate,
+  createActionAllowlistGate,
+  createStateValidationGate,
+  composePolicyGates,
+} from '@allternit/ix';
+
+const policies = composePolicyGates(
+  createRateLimitGate({ maxActionsPerMinute: 60 }),
+  createActionAllowlistGate(['submit', 'cancel']),
+  createStateValidationGate({
+    email: {
+      type: 'string',
+      required: true,
+      validate: (v) => v.includes('@') || 'Invalid email',
+    },
+  })
+);
+```
+
+### LLM-to-IX Pipeline
+
+```typescript
+import { llmToIX } from '@allternit/ix';
+
+// From JSX-like string
+const result = llmToIX.fromJSX(`
+  <Card>
+    <Heading level={2}>Sign Up</Heading>
+    <Input $value={email} placeholder="Email" />
+    <Button onClick="submit">Submit</Button>
+  </Card>
+`);
+
+// Auto-detect format
+const detected = llmToIX.convert(unknownInput);
+console.log(detected.confidence); // 0.0 - 1.0
+```
+
+## Implementation Status
+
+### Week 1 ✅
+- UI IR Schema (UIRoot, UIComponent, UIState, UIAction)
+- Component Catalog (15 built-ins, semver support)
+- State Store (scoped state, persistence, bindings)
+- JSON Patch Engine (RFC 6902, full implementation)
+- json-render Adapter (bidirectional conversion)
+
+### Weeks 2-3 ✅
+- React Renderer (complete with all built-ins)
+- IX Capsule Runtime (sandboxed execution)
+- Policy Gates (7 gate types + composition)
+- LLM-to-IX Pipeline (multi-format conversion)
+- Rust API Integration (Axum routes)
+- TypeScript SDK (API client + React hooks)
+
+### Option 4: Enhancements ✅
+- Vue Renderer (component generation)
+- Svelte Renderer (component compilation)
+- Yjs/CRDT Integration (real-time collaboration)
+- Visual Editor (fluent API for UI building)
+- Awareness API (cursor positions, selections)
+
+## License
+
+MIT

package/dist/adapters/json-render.d.ts

@@ -0,0 +1,211 @@
+/**
+ * Vercel Labs json-render Adapter
+ *
+ * Converts between A2R-IX UI IR and Vercel Labs json-render format.
+ *
+ * json-render is a declarative UI format where components are expressed as JSON.
+ * This adapter enables A2R-IX to render UIs generated by LLMs trained on
+ * json-render patterns.
+ *
+ * @see https://github.com/vercel-labs/json-render
+ */
+import type { UIRoot } from '../types';
+/**
+ * json-render node format
+ */
+export interface JsonRenderNode {
+    /** Component type */
+    type: string;
+    /** Component props */
+    props?: Record<string, unknown>;
+    /** Child nodes */
+    children?: JsonRenderNode[];
+    /** Text content (for text nodes) */
+    text?: string;
+}
+/**
+ * json-render component registry entry
+ */
+export interface JsonRenderComponent {
+    /** Component name */
+    name: string;
+    /** React component or element type */
+    component: string;
+    /** Prop mapping (json-render prop -> component prop) */
+    propMapping?: Record<string, string>;
+    /** Transform props before passing */
+    transformProps?: (props: Record<string, unknown>) => Record<string, unknown>;
+    /** Whether component accepts children */
+    acceptsChildren?: boolean;
+}
+/**
+ * json-render schema
+ */
+export interface JsonRenderSchema {
+    /** Schema version */
+    version: string;
+    /** Component tree */
+    root: JsonRenderNode;
+    /** State definitions */
+    state?: Record<string, {
+        type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+        default?: unknown;
+    }>;
+    /** Event handlers */
+    events?: Record<string, {
+        type: string;
+        target?: string;
+        payload?: unknown;
+    }>;
+}
+/**
+ * Custom handler function type
+ */
+export type CustomHandlerFn = (context: {
+    state: Record<string, unknown>;
+    params?: Record<string, unknown>;
+    event?: unknown;
+}) => void | Promise<void>;
+/**
+ * Handler registry entry metadata
+ */
+export interface HandlerRegistryEntry {
+    /** Handler name/identifier */
+    name: string;
+    /** Handler function */
+    handler: CustomHandlerFn;
+    /** Handler description */
+    description?: string;
+    /** Handler version */
+    version?: string;
+    /** Handler tags for discovery */
+    tags?: string[];
+    /** Input schema for validation */
+    inputSchema?: Record<string, unknown>;
+    /** Output schema */
+    outputSchema?: Record<string, unknown>;
+}
+/**
+ * Global handler registry for custom action handlers
+ *
+ * GAP-59: Custom Handler System
+ * Implements a singleton registry for dynamic handler registration
+ */
+declare class HandlerRegistry {
+    private handlers;
+    private tagsIndex;
+    /**
+     * Register a custom handler
+     * @param entry Handler registry entry
+     */
+    register(entry: HandlerRegistryEntry): void;
+    /**
+     * Unregister a handler
+     * @param name Handler name
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get a handler by name
+     * @param name Handler name
+     */
+    get(name: string): HandlerRegistryEntry | undefined;
+    /**
+     * Check if a handler exists
+     * @param name Handler name
+     */
+    has(name: string): boolean;
+    /**
+     * Execute a handler by name
+     * @param name Handler name
+     * @param context Execution context
+     */
+    execute(name: string, context: {
+        state: Record<string, unknown>;
+        params?: Record<string, unknown>;
+        event?: unknown;
+    }): Promise<void>;
+    /**
+     * GAP-61: Handler Discovery
+     * Find handlers by tags
+     * @param tags Tags to search for
+     */
+    findByTags(tags: string[]): HandlerRegistryEntry[];
+    /**
+     * GAP-61: Handler Discovery
+     * Search handlers by name pattern or description
+     * @param query Search query
+     */
+    search(query: string): HandlerRegistryEntry[];
+    /**
+     * Get all registered handlers
+     */
+    listAll(): HandlerRegistryEntry[];
+    /**
+     * Get all available tags
+     */
+    getAllTags(): string[];
+    /**
+     * Clear all handlers
+     */
+    clear(): void;
+    /**
+     * Get registry statistics
+     */
+    getStats(): {
+        total: number;
+        tags: number;
+    };
+}
+/** Global handler registry instance */
+export declare const globalHandlerRegistry: HandlerRegistry;
+/**
+ * Convert A2R-IX UIRoot to json-render format
+ */
+export declare function convertToJsonRender(root: UIRoot): JsonRenderSchema;
+/**
+ * Convert json-render format to A2R-IX UIRoot
+ */
+export declare function convertFromJsonRender(schema: JsonRenderSchema): UIRoot;
+/**
+ * json-render adapter configuration
+ */
+export declare const jsonRenderAdapter: {
+    name: string;
+    version: string;
+    /**
+     * Standard json-render components mapped to A2R-IX catalog
+     */
+    components: Record<string, string>;
+    /**
+     * Convert from json-render
+     */
+    fromJsonRender: typeof convertFromJsonRender;
+    /**
+     * Convert to json-render
+     */
+    toJsonRender: typeof convertToJsonRender;
+    /**
+     * Check if value is a valid json-render schema
+     */
+    isValidSchema(value: unknown): value is JsonRenderSchema;
+    /**
+     * Check if node is a valid json-render node
+     */
+    isValidNode(value: unknown): value is JsonRenderNode;
+    /**
+     * GAP-59/61: Handler Registry Access
+     * Get the global handler registry for custom action handlers
+     */
+    readonly handlerRegistry: HandlerRegistry;
+    /**
+     * GAP-60: Execute custom handler
+     * Execute a registered custom handler by name
+     */
+    executeHandler(name: string, context: {
+        state: Record<string, unknown>;
+        params?: Record<string, unknown>;
+        event?: unknown;
+    }): Promise<void>;
+};
+export {};
+//# sourceMappingURL=json-render.d.ts.map