@affectively/aeon-flux 0.3.0

package/README.md

@@ -0,0 +1,438 @@
+# @affectively/aeon-flux
+
+**The CMS IS the website.** Collaborative page framework with CRDT-based flux state and hyperpersonalized routing.
+
+```
+'use aeon';  // One directive enables everything
+```
+
+## What is Aeon Flux?
+
+Aeon Flux is a lightweight, collaborative page framework that unifies:
+
+- **CMS = Website** - No separate admin panel, edit in place
+- **Editor = Viewer** - Click to edit, changes are live
+- **Backend = Frontend** - One runtime, runs on edge
+- **Pages from D1** - No file system, pure database
+- **AI Everywhere** - Edge Side Inference (ESI) brings AI to any component
+
+The name comes from:
+1. **Flux** - CRDT-based data model for conflict-free collaboration
+2. **Aeon Flux** - The classic anime (a syzygy of human and machine)
+
+## Key Features
+
+| Feature | Description |
+|---------|-------------|
+| **Zero-Dependency Rendering** | Single HTML with inline CSS, assets, fonts |
+| **Hyperpersonalized Routing** | The website comes to the person |
+| **Edge Side Inference (ESI)** | AI inference at render time |
+| **Pages from D1** | No file system in production |
+| **~20KB WASM runtime** | vs 500KB+ Next.js |
+| **Multi-layer caching** | KV (1ms) → D1 (5ms) → Session (50ms) |
+| **Speculative pre-rendering** | Zero-latency navigation |
+| **Built-in collaboration** | Real-time editing with presence |
+| **GitHub PR Publishing** | Visual edits → TSX → Git → Deploy |
+| **Lazy hydration** | Only hydrate interactive components on visibility |
+
+## Live Infrastructure
+
+```
+https://aeon-flux.taylorbuley.workers.dev
+```
+
+| Endpoint | Description |
+|----------|-------------|
+| `/health` | Health check |
+| `/session/:id` | WebSocket for real-time collab |
+| `/session/:id/session` | Session state (GET/PUT) |
+| `/session/:id/presence` | Active users |
+| `/routes` | Route registry |
+
+## Quick Start
+
+```bash
+# Install
+bun add @affectively/aeon-pages-runtime
+
+# Or use the worker directly
+curl https://aeon-flux.taylorbuley.workers.dev/health
+```
+
+## Hyperpersonalized Routing
+
+**"The website comes to the person"** - Routes adapt based on user context.
+
+```typescript
+import { HeuristicAdapter, extractUserContext } from '@affectively/aeon-pages-runtime';
+
+const adapter = new HeuristicAdapter({
+  defaultPaths: ['/', '/chat', '/settings'],
+  signals: {
+    deriveTheme: (ctx) => ctx.localHour > 18 ? 'dark' : 'light',
+    deriveAccent: (ctx) => ctx.emotionState?.primary === 'happy' ? '#FFD700' : '#6366f1',
+  },
+});
+
+// Route decision includes personalization
+const decision = await adapter.route('/dashboard', userContext, componentTree);
+// { theme: 'dark', accent: '#FFD700', prefetch: ['/chat'], density: 'comfortable', ... }
+```
+
+### Performance
+
+| Operation | 100 nodes | 500 nodes |
+|-----------|-----------|-----------|
+| `route()` | 0.014ms | 0.05ms |
+| `speculate()` | 0.003ms | 0.007ms |
+| `personalizeTree()` | 0.026ms | 0.109ms |
+
+Sub-millisecond routing on every request.
+
+## Edge Side Inference (ESI)
+
+Bring AI to any component at render time. Like Varnish ESI, but for inference.
+
+```tsx
+import { ESI, ESIProvider } from '@affectively/aeon-pages-runtime/router';
+
+// Basic inference
+<ESI.Infer model="llm" cache={300}>
+  Summarize this page for {user.name}
+</ESI.Infer>
+
+// Structured output with Zod
+<ESI.Structured schema={z.object({ sentiment: z.enum(['positive', 'negative']) })}>
+  Analyze: {userMessage}
+</ESI.Structured>
+
+// Conditional rendering
+<ESI.If
+  prompt="Should we show a discount?"
+  schema={z.object({ show: z.boolean() })}
+  when={(r) => r.show}
+>
+  <DiscountBanner />
+</ESI.If>
+
+// Presence-aware (adapts for multiple viewers)
+<ESI.Collaborative schema={summarySchema}>
+  Summarize for {presence.length} viewers: {content}
+</ESI.Collaborative>
+
+// Self-optimizing (improves when user is alone)
+<ESI.Optimize
+  schema={contentSchema}
+  maxIterations={3}
+  goal="Improve clarity and engagement"
+>
+  {draftContent}
+</ESI.Optimize>
+```
+
+## Zero-Dependency Rendering
+
+Every page is a **completely self-contained HTML document**. No external requests needed.
+
+```
+Single Request → Instant Render
+├── Inline CSS (tree-shaken, only used classes)
+├── Inline assets (SVG, images as data URIs)
+├── Inline fonts (@font-face with embedded data)
+├── Minimal hydration script (lazy, on visibility)
+└── WASM-rendered at edge (~7ms total)
+```
+
+### Multi-Layer Caching
+
+```
+Request → KV Cache (1ms) → D1 Cache (5ms) → Session Render (50ms)
+                ↓                 ↓                  ↓
+           Return HTML       Cache to KV        Cache to KV + D1
+```
+
+All pages are pre-rendered at build time and cached. First request for any route is a cache hit.
+
+### Speculative Pre-Rendering
+
+Pages are pre-rendered **before the user clicks**, based on:
+- Link visibility (IntersectionObserver)
+- Hover intent
+- Navigation prediction (Markov chain, community patterns)
+- Browser Speculation Rules API
+
+```typescript
+import { initSpeculativeRendering } from '@affectively/aeon-pages-runtime';
+
+// Enable instant navigation
+initSpeculativeRendering({
+  maxCachedPages: 5,
+  prerenderOnHover: true,
+});
+```
+
+### Performance
+
+| Metric | Before | After |
+|--------|--------|-------|
+| Requests | 15-30 | 1 |
+| Total bytes | ~655KB | ~110KB |
+| TTFB | 100ms | 50ms |
+| First Paint | 500ms | <100ms |
+| Time to Interactive | 2000ms | <300ms |
+| CLS | 0.05 | 0 |
+
+## GitHub PR Publishing
+
+Visual edits compile to TSX and create PRs automatically.
+
+```
+Edit in browser → Durable Object → "Publish" → TSX → PR → CI deploys
+```
+
+### WebSocket Commands
+
+```javascript
+const ws = new WebSocket('wss://aeon-flux.taylorbuley.workers.dev/session/my-page?userId=user1');
+
+// Publish current tree → creates PR
+ws.send(JSON.stringify({ type: 'publish' }));
+// Response: { type: 'publish', payload: { prNumber: 123, autoMerged: false } }
+
+// Merge a PR
+ws.send(JSON.stringify({ type: 'merge', payload: { prNumber: 123 } }));
+```
+
+### Generated TSX
+
+```tsx
+'use aeon';
+
+/**
+ * AboutPage
+ * Route: /about
+ *
+ * @generated by aeon-flux visual editor
+ */
+
+import type { FC } from 'react';
+import { Hero } from '@/components/Hero';
+import { Section } from '@/components/Section';
+
+const AboutPage: FC = () => {
+  return (
+    <Page>
+      <Hero title="About Us" />
+      <Section>
+        <Text>We believe in...</Text>
+      </Section>
+    </Page>
+  );
+};
+
+export default AboutPage;
+```
+
+### Configuration
+
+```toml
+# wrangler.toml
+[vars]
+GITHUB_REPO = "owner/repo"
+GITHUB_TREE_PATH = "apps/web/pages"
+GITHUB_BASE_BRANCH = "staging"
+GITHUB_DEV_BRANCH = "development"
+GITHUB_AUTO_MERGE = "false"
+```
+
+## Production Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         AEON FLUX ARCHITECTURE                           │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│   Request + User Context                                                 │
+│          │                                                               │
+│          ▼                                                               │
+│   ┌──────────────────┐     ┌──────────────────┐                         │
+│   │ HeuristicAdapter │     │       ESI        │                         │
+│   │  (personalize)   │     │   (inference)    │                         │
+│   └────────┬─────────┘     └────────┬─────────┘                         │
+│            │                        │                                    │
+│            ▼                        ▼                                    │
+│   ┌──────────────────────────────────────────────────┐                  │
+│   │              Durable Objects                      │                  │
+│   │    (sessions, presence, real-time sync)          │                  │
+│   └──────────────────────────────────────────────────┘                  │
+│            │                        │                                    │
+│            ▼                        ▼                                    │
+│   ┌──────────────┐          ┌──────────────┐                            │
+│   │      D1      │          │    GitHub    │                            │
+│   │  (storage)   │          │  (publish)   │                            │
+│   └──────────────┘          └──────────────┘                            │
+│                                                                          │
+│   Edit visually → Sync via DO → Publish → TSX → PR → Deploy             │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Local-First with Dash
+
+Data lives client-side. No backend services needed.
+
+```typescript
+import { DashStorageAdapter } from '@affectively/aeon-pages-runtime';
+
+const storage = new DashStorageAdapter(dashClient, {
+  routesCollection: 'aeon-routes',
+  sessionsCollection: 'aeon-sessions',
+});
+
+// Reads: instant (local)
+// Writes: instant (local), syncs via DO
+// Collab: Durable Objects
+// AI: ESI at edge
+```
+
+## Speculation & Prefetching
+
+Predict and prefetch likely next pages.
+
+```typescript
+import { SpeculationManager, createSpeculationHook } from '@affectively/aeon-pages-runtime/router';
+
+// Client-side
+const manager = new SpeculationManager({
+  maxPrefetch: 5,
+  hoverDelay: 100,
+});
+
+// Prefetch on hover
+manager.observeLinks();
+
+// Or use the hook
+const useSpeculation = createSpeculationHook(manager);
+```
+
+Supports [Speculation Rules API](https://developer.chrome.com/docs/web-platform/prerender-pages) with link prefetch fallback.
+
+## The `'use aeon'` Directive
+
+```tsx
+'use aeon';
+
+export default function Page() {
+  const {
+    presence,    // Who's viewing/editing
+    sync,        // Sync state and controls
+    version,     // Schema version info
+    data,        // Collaborative data store
+    setData,     // Update data
+  } = useAeonPage();
+
+  return <div>...</div>;
+}
+```
+
+## Hooks
+
+| Hook | Purpose |
+|------|---------|
+| `useAeonPage()` | Full page context |
+| `usePresence()` | Who's here, cursors, editing |
+| `useAeonData<T>(key)` | Collaborative typed data |
+| `useCollaborativeInput(key)` | Ready-to-use collab input |
+| `useOfflineStatus()` | Offline awareness |
+| `useESI()` | ESI context |
+| `useESIInfer()` | Programmatic inference |
+
+## Configuration
+
+```typescript
+// aeon.config.ts
+export default {
+  pagesDir: './pages',
+  runtime: 'cloudflare',
+
+  router: {
+    adapter: 'heuristic',
+    speculation: {
+      enabled: true,
+      depth: 2,
+      prerenderTop: 1,
+    },
+    personalization: {
+      featureGating: true,
+      emotionTheming: true,
+      componentOrdering: true,
+    },
+  },
+
+  esi: {
+    enabled: true,
+    endpoint: process.env.ESI_ENDPOINT,
+    timeout: 5000,
+    defaultCacheTtl: 300,
+  },
+
+  github: {
+    repo: 'owner/repo',
+    treePath: 'apps/web/pages',
+    baseBranch: 'staging',
+    devBranch: 'development',
+    autoMerge: false,
+  },
+};
+```
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| `@affectively/aeon-pages-runtime` | Runtime (npm) |
+| `@affectively/aeon-pages-runtime/router` | Personalized routing + ESI |
+| `@affectively/aeon-pages-runtime/server` | Server utilities |
+
+## Deploy Your Own
+
+```bash
+cd packages/runtime
+
+# Deploy worker
+wrangler deploy
+
+# Set GitHub token
+wrangler secret put GITHUB_TOKEN
+
+# Create D1 database (optional)
+wrangler d1 create aeon-flux
+wrangler d1 execute aeon-flux --file=./schema.sql
+```
+
+## vs Next.js
+
+| | Next.js | Aeon Flux |
+|-|---------|-----------|
+| **Runtime** | ~500KB | ~187KB |
+| **Routing** | Static | Personalized |
+| **AI** | Add-on | ESI built-in |
+| **CMS** | Separate | It IS the site |
+| **Collaboration** | Add-on | Built-in |
+| **Publish** | Manual | Visual → PR |
+| **Edge** | Partial | Full |
+
+## Requirements
+
+- Bun >= 1.0.0
+- React >= 18.0.0
+- Zod >= 3.0.0
+- Cloudflare account (for production)
+
+## License
+
+MIT
+
+---
+
+*The CMS is the website. The website comes to the person. Visual edits become code.*

package/examples/basic/aeon.config.ts

@@ -0,0 +1,39 @@
+import type { AeonConfig } from '@affectively/aeon-pages';
+
+export default {
+  pagesDir: './pages',
+  componentsDir: './components',
+  runtime: 'bun',
+  port: 3000,
+
+  aeon: {
+    sync: {
+      mode: 'distributed',
+      replicationFactor: 3,
+      consistencyLevel: 'strong',
+    },
+    versioning: {
+      enabled: true,
+      autoMigrate: true,
+    },
+    presence: {
+      enabled: true,
+      cursorTracking: true,
+      inactivityTimeout: 60000,
+    },
+    offline: {
+      enabled: true,
+      maxQueueSize: 1000,
+    },
+  },
+
+  components: {
+    autoDiscover: true,
+  },
+
+  nextCompat: true,
+
+  output: {
+    dir: '.aeon',
+  },
+} satisfies AeonConfig;

package/examples/basic/components/Cursor.tsx

@@ -0,0 +1,88 @@
+import type { PresenceUser } from '@affectively/aeon-pages/react';
+
+interface CursorProps {
+  user: PresenceUser;
+}
+
+// Generate a color from user ID
+function userColor(userId: string): string {
+  const colors = [
+    '#ef4444', // red
+    '#f97316', // orange
+    '#eab308', // yellow
+    '#22c55e', // green
+    '#06b6d4', // cyan
+    '#3b82f6', // blue
+    '#8b5cf6', // violet
+    '#ec4899', // pink
+  ];
+  let hash = 0;
+  for (let i = 0; i < userId.length; i++) {
+    hash = ((hash << 5) - hash) + userId.charCodeAt(i);
+    hash = hash & hash;
+  }
+  return colors[Math.abs(hash) % colors.length];
+}
+
+export function Cursor({ user }: CursorProps) {
+  if (!user.cursor || user.status === 'offline') {
+    return null;
+  }
+
+  const color = userColor(user.userId);
+
+  return (
+    <div
+      style={{
+        position: 'fixed',
+        left: user.cursor.x,
+        top: user.cursor.y,
+        pointerEvents: 'none',
+        zIndex: 9999,
+        transition: 'left 0.1s ease-out, top 0.1s ease-out',
+      }}
+    >
+      {/* Cursor arrow */}
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        style={{ filter: 'drop-shadow(0 1px 2px rgba(0,0,0,0.3))' }}
+      >
+        <path
+          d="M5.5 3.21V20.8c0 .45.54.67.85.35l4.86-4.86a.5.5 0 0 1 .35-.15h6.87c.48 0 .72-.58.38-.92L5.92 2.53a.5.5 0 0 0-.42.68z"
+          fill={color}
+          stroke="white"
+          strokeWidth="1.5"
+        />
+      </svg>
+
+      {/* User label */}
+      <div
+        style={{
+          marginLeft: '16px',
+          marginTop: '-4px',
+          padding: '2px 8px',
+          backgroundColor: color,
+          color: 'white',
+          fontSize: '12px',
+          fontWeight: 500,
+          borderRadius: '4px',
+          whiteSpace: 'nowrap',
+          boxShadow: '0 1px 3px rgba(0,0,0,0.2)',
+        }}
+      >
+        {user.role === 'assistant' ? '🤖 ' : ''}
+        {user.userId.slice(0, 8)}
+        {user.editing && (
+          <span style={{ marginLeft: '4px', opacity: 0.8 }}>
+            editing
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}
+
+export default Cursor;

package/examples/basic/components/OfflineIndicator.tsx

@@ -0,0 +1,93 @@
+import { useOfflineStatus } from '@affectively/aeon-pages/react';
+
+export function OfflineIndicator() {
+  const { isOffline, isSyncing, pendingOperations, lastSyncAt } = useOfflineStatus();
+
+  if (!isOffline && !isSyncing && pendingOperations === 0) {
+    return null;
+  }
+
+  return (
+    <div className="fixed bottom-4 right-4 flex flex-col gap-2">
+      {/* Offline banner */}
+      {isOffline && (
+        <div className="flex items-center gap-2 bg-yellow-50 border border-yellow-200 rounded-lg px-4 py-2 shadow-lg">
+          <svg
+            className="w-5 h-5 text-yellow-500"
+            fill="none"
+            viewBox="0 0 24 24"
+            stroke="currentColor"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth={2}
+              d="M18.364 5.636a9 9 0 010 12.728m0 0l-2.829-2.829m2.829 2.829L21 21M15.536 8.464a5 5 0 010 7.072m0 0l-2.829-2.829m-4.243 2.829a4.978 4.978 0 01-1.414-2.83m-1.414 5.658a9 9 0 01-2.167-9.238m7.824 2.167a1 1 0 111.414 1.414m-1.414-1.414L3 3"
+            />
+          </svg>
+          <div>
+            <p className="text-sm font-medium text-yellow-800">You're offline</p>
+            <p className="text-xs text-yellow-600">Changes will sync when back online</p>
+          </div>
+        </div>
+      )}
+
+      {/* Pending operations */}
+      {pendingOperations > 0 && (
+        <div className="flex items-center gap-2 bg-blue-50 border border-blue-200 rounded-lg px-4 py-2 shadow-lg">
+          <div className="w-5 h-5">
+            <svg className="animate-spin text-blue-500" fill="none" viewBox="0 0 24 24">
+              <circle
+                className="opacity-25"
+                cx="12"
+                cy="12"
+                r="10"
+                stroke="currentColor"
+                strokeWidth="4"
+              />
+              <path
+                className="opacity-75"
+                fill="currentColor"
+                d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+              />
+            </svg>
+          </div>
+          <div>
+            <p className="text-sm font-medium text-blue-800">
+              {isSyncing ? 'Syncing...' : `${pendingOperations} pending`}
+            </p>
+            <p className="text-xs text-blue-600">
+              {pendingOperations} {pendingOperations === 1 ? 'change' : 'changes'} to sync
+            </p>
+          </div>
+        </div>
+      )}
+
+      {/* Last sync time */}
+      {lastSyncAt && !isOffline && pendingOperations === 0 && (
+        <div className="text-xs text-gray-400 text-right">
+          Last synced: {formatRelativeTime(lastSyncAt)}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function formatRelativeTime(isoString: string): string {
+  const date = new Date(isoString);
+  const now = new Date();
+  const diff = now.getTime() - date.getTime();
+
+  const seconds = Math.floor(diff / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+
+  if (seconds < 10) return 'just now';
+  if (seconds < 60) return `${seconds}s ago`;
+  if (minutes < 60) return `${minutes}m ago`;
+  if (hours < 24) return `${hours}h ago`;
+
+  return date.toLocaleDateString();
+}
+
+export default OfflineIndicator;