@affectively/aeon-pages 1.3.0

package/packages/runtime/README.md

@@ -0,0 +1,399 @@
+# @affectively/aeon-pages-runtime
+
+Edge-first rendering runtime for Aeon-Flux with Edge Side Inference (ESI), hyperpersonalized routing, and real-time collaboration.
+
+## Installation
+
+```bash
+bun add @affectively/aeon-pages-runtime
+```
+
+## Features
+
+### Edge Side Inference (ESI)
+
+AI-powered personalization at render time. Components that adapt to user context before reaching the browser.
+
+```tsx
+import { ESI, ESIProvider } from '@affectively/aeon-pages-runtime/router';
+
+function App() {
+  return (
+    <ESIProvider>
+      {/* AI-generated personalized greeting */}
+      <ESI.Infer prompt="Greet the user based on time of day">
+        {(greeting) => <h1>{greeting}</h1>}
+      </ESI.Infer>
+
+      {/* Tier-gated content */}
+      <ESI.TierGate tier="premium">
+        <PremiumFeatures />
+      </ESI.TierGate>
+
+      {/* Emotion-aware content */}
+      <ESI.EmotionGate emotions={['calm', 'content']}>
+        <RelaxingContent />
+      </ESI.EmotionGate>
+    </ESIProvider>
+  );
+}
+```
+
+### AI Translation
+
+Automatic translation at the edge. Supports 33 languages with LLM-based translation.
+
+```tsx
+import { ESI, TranslationProvider } from '@affectively/aeon-pages-runtime/router';
+
+// App-wide translation with user's preferred language
+function App() {
+  return (
+    <TranslationProvider defaultLanguage="es">
+      <ESI.Translate>Welcome to our platform</ESI.Translate>
+      {/* Renders: "Bienvenido a nuestra plataforma" */}
+    </TranslationProvider>
+  );
+}
+
+// Explicit target language
+<ESI.Translate targetLanguage="ja">Hello world</ESI.Translate>
+// Renders: "こんにちは世界"
+
+// With context for better translation quality
+<ESI.Translate
+  targetLanguage="fr"
+  context="emotional wellness app"
+>
+  We're here to help you understand your feelings.
+</ESI.Translate>
+```
+
+#### Data-Attribute Translation
+
+Automatically translate any element with `data-translate`:
+
+```html
+<p data-translate data-target-lang="es">Hello world</p>
+<!-- Becomes: "Hola mundo" -->
+
+<span data-translate data-translate-context="formal, business">
+  Please review the attached document.
+</span>
+```
+
+```tsx
+import { useTranslationObserver } from '@affectively/aeon-pages-runtime/router';
+
+function App() {
+  // Automatically translates all data-translate elements
+  useTranslationObserver({ defaultTargetLanguage: 'es' });
+
+  return <div data-translate>Hello</div>;
+}
+```
+
+#### Language Configuration Priority
+
+1. `ESI.Translate` `targetLanguage` prop
+2. `TranslationProvider` context
+3. `window.__AEON_ESI_STATE__.preferences.language`
+4. `<meta name="aeon-language" content="es">`
+5. User preferences
+6. Browser `navigator.language`
+
+#### Supported Languages
+
+`en`, `es`, `fr`, `de`, `it`, `pt`, `nl`, `pl`, `ru`, `zh`, `ja`, `ko`, `ar`, `hi`, `bn`, `vi`, `th`, `tr`, `id`, `ms`, `tl`, `sv`, `da`, `no`, `fi`, `cs`, `el`, `he`, `uk`, `ro`, `hu`, `ca`, `hy`
+
+### Hyperpersonalized Routing
+
+Routes adapt to user context: time, location, emotion state, and tier.
+
+```tsx
+import { HeuristicAdapter } from '@affectively/aeon-pages-runtime/router';
+
+const adapter = new HeuristicAdapter({
+  tierFeatures: {
+    free: { maxAIInferences: 5 },
+    premium: { maxAIInferences: 100 },
+  },
+});
+
+// Route decision based on user context
+const decision = await adapter.decide(userContext, '/dashboard');
+// Returns: layout, theme, skeleton hints, prefetch suggestions
+```
+
+### Speculative Pre-rendering
+
+Pages render before you click. Zero perceived latency.
+
+```tsx
+import { SpeculationManager, autoInitSpeculation } from '@affectively/aeon-pages-runtime/router';
+
+// Auto-initialize based on browser support
+autoInitSpeculation();
+
+// Or manual control
+const speculation = new SpeculationManager({
+  prefetchUrls: ['/dashboard', '/settings'],
+  prerenderUrls: ['/about'],
+});
+speculation.start();
+```
+
+### ESI Control Components
+
+Declarative control flow with AI-powered conditions.
+
+```tsx
+import { ESI } from '@affectively/aeon-pages-runtime/router';
+
+// Conditional rendering
+<ESI.If condition="user.tier === 'premium'">
+  <PremiumBadge />
+</ESI.If>
+
+// Pattern matching
+<ESI.Match value={userEmotion}>
+  <ESI.Case when="happy"><HappyContent /></ESI.Case>
+  <ESI.Case when="sad"><SupportContent /></ESI.Case>
+  <ESI.Default><NeutralContent /></ESI.Default>
+</ESI.Match>
+
+// Time-based gates
+<ESI.TimeGate hours={{ start: 9, end: 17 }}>
+  <BusinessHoursContent />
+</ESI.TimeGate>
+
+// A/B Testing
+<ESI.ABTest variants={['control', 'variant-a', 'variant-b']}>
+  {(variant) => <Component variant={variant} />}
+</ESI.ABTest>
+```
+
+### Cyrano Whisper Channel
+
+AI assistant guidance with contextual awareness.
+
+```tsx
+import { esiCyrano, esiHalo } from '@affectively/aeon-pages-runtime/router';
+
+// Generate AI whisper for user guidance
+const whisper = esiCyrano({
+  intent: 'guide',
+  tone: 'warm',
+  context: sessionContext,
+});
+
+// Halo insights for behavioral patterns
+const insight = esiHalo({
+  observation: 'user-hesitation',
+  action: 'offer-help',
+});
+```
+
+### Merkle-Based UCAN Capabilities
+
+Fine-grained access control to component nodes using Merkle hashes. Integrates with UCAN tokens for cryptographic authorization.
+
+```tsx
+import {
+  createNodeCapabilityVerifier,
+  createNodeReadCapability,
+  createTreeCapability,
+  checkNodeAccess,
+} from '@affectively/aeon-pages-runtime';
+
+// Create capabilities for specific nodes by Merkle hash
+const readCapability = createNodeReadCapability('a1b2c3d4e5f6');
+// { can: 'aeon:node:read', with: 'merkle:a1b2c3d4e5f6' }
+
+// Create tree capability (grants access to node and all descendants)
+const treeCapability = createTreeCapability('a1b2c3d4e5f6');
+// { can: 'aeon:node:*', with: 'tree:a1b2c3d4e5f6' }
+
+// Create path-based capability (grants access to all nodes on a route)
+const pathCapability = createPathCapability('/dashboard/*');
+// { can: 'aeon:node:*', with: 'path:/dashboard/*' }
+
+// Verify access to a specific node
+const canAccess = checkNodeAccess(
+  userCapabilities,
+  { merkleHash: 'a1b2c3d4e5f6', routePath: '/dashboard' },
+  'read'
+);
+```
+
+#### Resource Formats
+
+| Format | Example | Description |
+|--------|---------|-------------|
+| `merkle:<hash>` | `merkle:a1b2c3d4e5f6` | Exact match on Merkle hash |
+| `tree:<hash>` | `tree:a1b2c3d4e5f6` | Match node or any ancestor |
+| `path:<route>` | `path:/dashboard/*` | All nodes on a route (wildcards) |
+| `*` | `*` | Match any node (wildcard) |
+
+#### Capability Actions
+
+| Action | Description |
+|--------|-------------|
+| `aeon:node:read` | Read access to node |
+| `aeon:node:write` | Write access to node |
+| `aeon:node:*` | Full access to node |
+
+#### Creating a Verifier from UCAN Token
+
+```tsx
+import { createNodeCapabilityVerifier } from '@affectively/aeon-pages-runtime';
+
+const verifier = createNodeCapabilityVerifier(token, {
+  extractCapabilities: async (t) => {
+    const decoded = await decodeUCAN(t);
+    return decoded.capabilities;
+  },
+  verifyToken: async (t) => {
+    return await verifyUCANSignature(t);
+  },
+});
+
+// Check if user can read a specific node
+const canRead = await verifier(
+  { merkleHash: 'a1b2c3d4e5f6' },
+  'read'
+);
+
+// Check with full tree path context
+const canWrite = await verifier(
+  {
+    merkleHash: 'a1b2c3d4e5f6',
+    treePath: ['root', 'layout', 'header', 'button'],
+    ancestorHashes: ['f1e2d3c4b5a6', 'b2c3d4e5f6a1'],
+    routePath: '/dashboard',
+  },
+  'write'
+);
+```
+
+#### Integration with Analytics
+
+Merkle capabilities integrate seamlessly with `@affectively/aeon-pages-analytics`:
+
+```tsx
+import { buildMerkleTreeSync } from '@affectively/aeon-pages-analytics';
+import { checkNodeAccess } from '@affectively/aeon-pages-runtime';
+
+// Build Merkle tree from component tree
+const merkleTree = buildMerkleTreeSync(componentTree);
+
+// Check access for each node
+for (const [nodeId, merkleNode] of merkleTree) {
+  const canEdit = checkNodeAccess(
+    userCapabilities,
+    {
+      merkleHash: merkleNode.hash,
+      treePath: merkleNode.path,
+      routePath: currentRoute,
+    },
+    'write'
+  );
+
+  if (canEdit) {
+    // Show edit controls for this node
+  }
+}
+```
+
+## API Reference
+
+### Components
+
+| Component | Description |
+|-----------|-------------|
+| `ESI.Provider` | Root ESI context provider |
+| `ESI.Infer` | AI inference at render time |
+| `ESI.Translate` | Automatic translation |
+| `ESI.TranslationProvider` | App-wide translation context |
+| `ESI.TierGate` | Tier-based content gating |
+| `ESI.EmotionGate` | Emotion-based content gating |
+| `ESI.TimeGate` | Time-based content gating |
+| `ESI.If` / `ESI.Show` / `ESI.Hide` | Conditional rendering |
+| `ESI.Match` / `ESI.Case` | Pattern matching |
+| `ESI.ABTest` | A/B testing |
+| `ESI.ForEach` | AI-powered iteration |
+| `ESI.Select` | AI-powered selection |
+
+### Hooks
+
+| Hook | Description |
+|------|-------------|
+| `useESI()` | Access ESI context and processing |
+| `useESIInfer()` | AI inference hook |
+| `useTranslation()` | Translation context access |
+| `useTranslationObserver()` | Auto-translate data-attribute elements |
+| `useGlobalESIState()` | Access global ESI state |
+| `useESITier()` | Get current user tier |
+| `useESIEmotionState()` | Get current emotion state |
+
+### Functions
+
+| Function | Description |
+|----------|-------------|
+| `esiTranslate()` | Create translation directive |
+| `translateWithAIGateway()` | Direct AI Gateway translation |
+| `normalizeLanguageCode()` | Normalize language code |
+| `getSupportedLanguages()` | Get list of supported languages |
+| `initTranslationObserver()` | Auto-init DOM translation observer |
+
+### Merkle Capability Functions
+
+| Function | Description |
+|----------|-------------|
+| `createNodeReadCapability(hash)` | Create read capability for a Merkle hash |
+| `createNodeWriteCapability(hash)` | Create write capability for a Merkle hash |
+| `createTreeCapability(hash, action)` | Create tree capability (node + descendants) |
+| `createPathCapability(path, action)` | Create path-based capability |
+| `createWildcardNodeCapability(action)` | Create wildcard capability (all nodes) |
+| `createNodeCapabilityVerifier(token, opts)` | Create verifier from UCAN token |
+| `checkNodeAccess(caps, request, action)` | Check if capabilities grant access |
+| `filterAccessibleNodes(nodes, caps, action)` | Filter nodes by access |
+| `getMostSpecificCapability(caps, request)` | Get most specific matching capability |
+| `parseResource(resource)` | Parse resource identifier |
+| `formatResource(type, value)` | Format resource identifier |
+| `capabilityGrantsAccess(cap, request, action)` | Check single capability |
+
+## Configuration
+
+### Head Meta Tags
+
+```html
+<!-- Default translation language -->
+<meta name="aeon-language" content="es">
+
+<!-- Translation endpoint -->
+<meta name="aeon-translation-endpoint" content="https://ai-gateway.example.com">
+
+<!-- Cache TTL in seconds -->
+<meta name="aeon-translation-cache-ttl" content="86400">
+```
+
+### ESI State
+
+Global state is available at `window.__AEON_ESI_STATE__`:
+
+```typescript
+interface GlobalESIState {
+  tier: 'free' | 'premium' | 'enterprise';
+  emotion: EmotionState;
+  preferences: {
+    language: string;
+    theme: 'light' | 'dark' | 'system';
+  };
+  features: Record<string, boolean>;
+}
+```
+
+## License
+
+MIT

package/packages/runtime/build.ts

@@ -0,0 +1,48 @@
+/**
+ * Build script for aeon-pages-runtime
+ *
+ * Marks React as external to prevent duplicate React instances
+ * when consumers bundle this package.
+ */
+
+const entrypoints = [
+  './src/index.ts',
+  './src/server.ts',
+  './src/router/index.ts',
+];
+
+async function build() {
+  const result = await Bun.build({
+    entrypoints,
+    outdir: './dist',
+    target: 'browser', // Changed from 'bun' to 'browser' for client compatibility
+    splitting: true,
+    format: 'esm',
+    external: [
+      // Mark React as external - consumers provide their own React
+      'react',
+      'react-dom',
+      'react/jsx-runtime',
+      'react/jsx-dev-runtime',
+      // Also mark peer dependencies as external
+      'zod',
+      '@affectively/aeon',
+      '@affectively/auth',
+    ],
+  });
+
+  if (!result.success) {
+    console.error('Build failed:');
+    for (const log of result.logs) {
+      console.error(log);
+    }
+    process.exit(1);
+  }
+
+  console.log('Build successful:');
+  for (const output of result.outputs) {
+    console.log(`  ${output.path}`);
+  }
+}
+
+build();

package/packages/runtime/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@affectively/aeon-pages-runtime",
+  "version": "0.8.0",
+  "description": "Bun/Cloudflare runtime for @affectively/aeon-pages",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/types.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./server": {
+      "import": "./dist/server.js",
+      "types": "./dist/server.d.ts"
+    },
+    "./router": {
+      "import": "./dist/router/index.js",
+      "types": "./dist/router/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "bun run build.ts && tsc --declaration --emitDeclarationOnly",
+    "dev": "bun --watch ./src/index.ts",
+    "test": "bun test",
+    "prepublishOnly": "bun run build",
+    "deploy": "wrangler deploy",
+    "deploy:staging": "wrangler deploy --env staging",
+    "dev:worker": "wrangler dev",
+    "db:create": "wrangler d1 create aeon-pages",
+    "db:migrate": "wrangler d1 execute aeon-pages --file=./schema.sql",
+    "db:migrate:local": "wrangler d1 execute aeon-pages --local --file=./schema.sql",
+    "tail": "wrangler tail"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "bun": ">=1.0.0",
+    "react": ">=18.0.0",
+    "zod": ">=3.0.0",
+    "@affectively/aeon": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@affectively/aeon": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/bun": "latest",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "zod": "^3.24.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/affectively/aeon-pages"
+  },
+  "keywords": [
+    "aeon",
+    "pages",
+    "framework",
+    "collaborative",
+    "bun",
+    "cloudflare"
+  ]
+}

package/packages/runtime/schema.sql

@@ -0,0 +1,40 @@
+-- Aeon Pages D1 Schema
+-- Run with: wrangler d1 execute aeon-pages --file=./schema.sql
+
+-- Sessions table (async propagation from Durable Objects)
+CREATE TABLE IF NOT EXISTS sessions (
+  session_id TEXT PRIMARY KEY,
+  route TEXT NOT NULL,
+  tree TEXT NOT NULL,  -- JSON serialized component tree
+  data TEXT,           -- JSON serialized session data
+  schema_version TEXT NOT NULL,
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Routes table (backup for route registry)
+CREATE TABLE IF NOT EXISTS routes (
+  pattern TEXT PRIMARY KEY,
+  session_id TEXT,
+  component_id TEXT,
+  is_aeon BOOLEAN DEFAULT FALSE,
+  metadata TEXT,  -- JSON
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Presence snapshots (for analytics)
+CREATE TABLE IF NOT EXISTS presence_snapshots (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id TEXT NOT NULL,
+  user_count INTEGER NOT NULL,
+  users TEXT,  -- JSON array of user IDs
+  snapshot_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+);
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_sessions_route ON sessions(route);
+CREATE INDEX IF NOT EXISTS idx_sessions_updated ON sessions(updated_at);
+CREATE INDEX IF NOT EXISTS idx_presence_session ON presence_snapshots(session_id);
+CREATE INDEX IF NOT EXISTS idx_presence_time ON presence_snapshots(snapshot_at);