@affectively/aeon-pages-runtime 0.1.0

package/dist/service-worker.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Aeon Service Worker - Total Preload Strategy
+ *
+ * The Aeon architecture is recursive:
+ * - This service worker caches the ENTIRE site as an Aeon
+ * - Each page session is an Aeon entity within the site Aeon
+ * - Federation would cache multiple sites as Aeons of Aeons
+ *
+ * With 8.4KB framework + ~2-5KB per page session, we can preload EVERYTHING.
+ * A site with 100 pages = ~315KB total (smaller than one hero image!)
+ */
+export {};

package/dist/storage.d.ts

@@ -0,0 +1,354 @@
+/**
+ * Aeon Flux Storage Adapters
+ *
+ * Pluggable backend storage for routes and page content.
+ *
+ * Supported backends:
+ * - Dash (recommended for AFFECTIVELY ecosystem)
+ * - File system (default, development)
+ * - Cloudflare D1 (production, distributed)
+ * - Cloudflare Durable Objects (strong consistency)
+ * - Hybrid (D1 + Durable Objects)
+ * - Custom adapters
+ */
+import type { RouteDefinition, PageSession, SerializedComponent } from './types';
+/**
+ * Storage adapter interface - implement this for custom backends
+ */
+export interface StorageAdapter {
+    /** Adapter name for logging */
+    name: string;
+    /** Initialize the storage (create tables, etc.) */
+    init(): Promise<void>;
+    /** Get a route by path */
+    getRoute(path: string): Promise<RouteDefinition | null>;
+    /** Get all routes */
+    getAllRoutes(): Promise<RouteDefinition[]>;
+    /** Save a route */
+    saveRoute(route: RouteDefinition): Promise<void>;
+    /** Delete a route */
+    deleteRoute(path: string): Promise<void>;
+    /** Get a page session */
+    getSession(sessionId: string): Promise<PageSession | null>;
+    /** Save a page session */
+    saveSession(session: PageSession): Promise<void>;
+    /** Get component tree for a session */
+    getTree(sessionId: string): Promise<SerializedComponent | null>;
+    /** Save component tree for a session */
+    saveTree(sessionId: string, tree: SerializedComponent): Promise<void>;
+}
+/**
+ * File system storage adapter (default for development)
+ */
+export declare class FileStorageAdapter implements StorageAdapter {
+    name: string;
+    private pagesDir;
+    private dataDir;
+    constructor(options: {
+        pagesDir: string;
+        dataDir?: string;
+    });
+    init(): Promise<void>;
+    getRoute(path: string): Promise<RouteDefinition | null>;
+    getAllRoutes(): Promise<RouteDefinition[]>;
+    saveRoute(route: RouteDefinition): Promise<void>;
+    deleteRoute(path: string): Promise<void>;
+    getSession(sessionId: string): Promise<PageSession | null>;
+    saveSession(session: PageSession): Promise<void>;
+    getTree(sessionId: string): Promise<SerializedComponent | null>;
+    saveTree(sessionId: string, tree: SerializedComponent): Promise<void>;
+    private pathToKey;
+}
+/**
+ * Cloudflare D1 storage adapter (production, distributed)
+ */
+export declare class D1StorageAdapter implements StorageAdapter {
+    name: string;
+    private db;
+    constructor(db: D1Database);
+    init(): Promise<void>;
+    getRoute(path: string): Promise<RouteDefinition | null>;
+    getAllRoutes(): Promise<RouteDefinition[]>;
+    saveRoute(route: RouteDefinition): Promise<void>;
+    deleteRoute(path: string): Promise<void>;
+    getSession(sessionId: string): Promise<PageSession | null>;
+    saveSession(session: PageSession): Promise<void>;
+    getTree(sessionId: string): Promise<SerializedComponent | null>;
+    saveTree(sessionId: string, tree: SerializedComponent): Promise<void>;
+    private routeToSessionId;
+}
+/**
+ * Cloudflare D1 database interface (matches Cloudflare Workers API)
+ */
+interface D1Database {
+    prepare(query: string): D1PreparedStatement;
+    exec(query: string): Promise<void>;
+}
+interface D1PreparedStatement {
+    bind(...values: unknown[]): D1PreparedStatement;
+    first(): Promise<Record<string, unknown> | null>;
+    all(): Promise<{
+        results: Record<string, unknown>[];
+    }>;
+    run(): Promise<void>;
+}
+interface DurableObjectId {
+    toString(): string;
+    equals(other: DurableObjectId): boolean;
+}
+interface DurableObjectNamespace {
+    get(id: DurableObjectId): DurableObjectStub;
+    idFromName(name: string): DurableObjectId;
+    idFromString(id: string): DurableObjectId;
+    newUniqueId(): DurableObjectId;
+}
+interface DurableObjectStub {
+    id: DurableObjectId;
+    fetch(input: RequestInfo, init?: RequestInit): Promise<Response>;
+}
+/**
+ * Cloudflare Durable Objects storage adapter (strong consistency)
+ *
+ * Each Aeon session maps to a Durable Object instance, providing:
+ * - Strong consistency for real-time collaborative editing
+ * - Automatic coalescing of WebSocket connections
+ * - Sub-millisecond latency within the same colo
+ *
+ * Use in combination with D1 for read replicas and historical data.
+ */
+export declare class DurableObjectStorageAdapter implements StorageAdapter {
+    name: string;
+    private namespace;
+    private routeCache;
+    constructor(namespace: DurableObjectNamespace);
+    init(): Promise<void>;
+    getRoute(path: string): Promise<RouteDefinition | null>;
+    getAllRoutes(): Promise<RouteDefinition[]>;
+    saveRoute(route: RouteDefinition): Promise<void>;
+    deleteRoute(path: string): Promise<void>;
+    getSession(sessionId: string): Promise<PageSession | null>;
+    saveSession(session: PageSession): Promise<void>;
+    getTree(sessionId: string): Promise<SerializedComponent | null>;
+    saveTree(sessionId: string, tree: SerializedComponent): Promise<void>;
+    /**
+     * Get a direct stub for WebSocket connections
+     * This allows real-time collaboration via Durable Object WebSockets
+     */
+    getSessionStub(sessionId: string): DurableObjectStub;
+    private routeToSessionId;
+}
+/**
+ * Hybrid storage adapter (D1 + Durable Objects)
+ *
+ * Combines the best of both:
+ * - Durable Objects for real-time collaborative editing (strong consistency)
+ * - D1 for read replicas and historical snapshots (eventual consistency)
+ *
+ * Write path: Durable Object → async propagate to D1
+ * Read path: Durable Object (real-time) or D1 (historical)
+ */
+export declare class HybridStorageAdapter implements StorageAdapter {
+    name: string;
+    private do;
+    private d1;
+    constructor(options: {
+        namespace: DurableObjectNamespace;
+        db: D1Database;
+    });
+    init(): Promise<void>;
+    getRoute(path: string): Promise<RouteDefinition | null>;
+    getAllRoutes(): Promise<RouteDefinition[]>;
+    saveRoute(route: RouteDefinition): Promise<void>;
+    deleteRoute(path: string): Promise<void>;
+    getSession(sessionId: string): Promise<PageSession | null>;
+    saveSession(session: PageSession): Promise<void>;
+    getTree(sessionId: string): Promise<SerializedComponent | null>;
+    saveTree(sessionId: string, tree: SerializedComponent): Promise<void>;
+    /**
+     * Get historical snapshots from D1
+     */
+    getHistoricalSession(sessionId: string): Promise<PageSession | null>;
+    /**
+     * Get direct Durable Object stub for WebSocket connections
+     */
+    getSessionStub(sessionId: string): DurableObjectStub;
+}
+/**
+ * Dash client interface
+ *
+ * Dash is AFFECTIVELY's real-time sync system built on Aeon.
+ * It provides:
+ * - Real-time subscriptions via WebSocket
+ * - Automatic conflict resolution (CRDT-based)
+ * - Offline-first with sync on reconnect
+ * - Cross-platform (web, mobile, edge)
+ *
+ * @example
+ * ```typescript
+ * import { createDashClient } from '@affectively/dash';
+ *
+ * const dash = createDashClient({
+ *   endpoint: 'wss://dash.affectively.com',
+ *   auth: { token: 'your-auth-token' },
+ * });
+ *
+ * const storage = new DashStorageAdapter(dash);
+ * ```
+ */
+interface DashClient {
+    /** Connect to Dash server */
+    connect(): Promise<void>;
+    /** Disconnect from Dash server */
+    disconnect(): Promise<void>;
+    /** Check connection status */
+    isConnected(): boolean;
+    /** Get a document by collection and id */
+    get<T>(collection: string, id: string): Promise<T | null>;
+    /** Query documents in a collection */
+    query<T>(collection: string, filter?: DashFilter): Promise<T[]>;
+    /** Set/update a document */
+    set<T>(collection: string, id: string, data: T): Promise<void>;
+    /** Delete a document */
+    delete(collection: string, id: string): Promise<void>;
+    /** Subscribe to real-time updates */
+    subscribe<T>(collection: string, filter: DashFilter | undefined, callback: (changes: DashChange<T>[]) => void): DashSubscription;
+    /** Batch operations */
+    batch(operations: DashOperation[]): Promise<void>;
+}
+interface DashFilter {
+    where?: Array<{
+        field: string;
+        op: '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'contains';
+        value: unknown;
+    }>;
+    orderBy?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    };
+    limit?: number;
+    offset?: number;
+}
+interface DashChange<T> {
+    type: 'added' | 'modified' | 'removed';
+    id: string;
+    data: T | null;
+    previousData?: T;
+}
+interface DashSubscription {
+    unsubscribe(): void;
+}
+interface DashOperation {
+    type: 'set' | 'delete';
+    collection: string;
+    id: string;
+    data?: unknown;
+}
+/**
+ * Dash storage adapter
+ *
+ * Uses AFFECTIVELY's Dash real-time sync system as the backend.
+ * This is the recommended adapter for the AFFECTIVELY ecosystem
+ * as it integrates seamlessly with other Dash-powered features.
+ *
+ * Features:
+ * - Real-time sync across all connected clients
+ * - CRDT-based conflict resolution (no data loss)
+ * - Offline-first with automatic sync on reconnect
+ * - Presence tracking built-in
+ * - Works with existing Dash infrastructure
+ *
+ * @example
+ * ```typescript
+ * import { createDashClient } from '@affectively/dash';
+ * import { DashStorageAdapter } from '@affectively/aeon-flux';
+ *
+ * const dash = createDashClient({
+ *   endpoint: process.env.DASH_ENDPOINT,
+ *   auth: { token: await getAuthToken() },
+ * });
+ *
+ * const storage = new DashStorageAdapter(dash, {
+ *   routesCollection: 'aeon-routes',
+ *   sessionsCollection: 'aeon-sessions',
+ *   presenceCollection: 'aeon-presence',
+ * });
+ *
+ * // Use with Aeon Flux server
+ * const server = await createAeonServer({
+ *   storage,
+ *   // ...
+ * });
+ * ```
+ */
+export declare class DashStorageAdapter implements StorageAdapter {
+    name: string;
+    private client;
+    private collections;
+    private subscriptions;
+    constructor(client: DashClient, options?: {
+        routesCollection?: string;
+        sessionsCollection?: string;
+        presenceCollection?: string;
+    });
+    init(): Promise<void>;
+    getRoute(path: string): Promise<RouteDefinition | null>;
+    getAllRoutes(): Promise<RouteDefinition[]>;
+    saveRoute(route: RouteDefinition): Promise<void>;
+    deleteRoute(path: string): Promise<void>;
+    getSession(sessionId: string): Promise<PageSession | null>;
+    saveSession(session: PageSession): Promise<void>;
+    getTree(sessionId: string): Promise<SerializedComponent | null>;
+    saveTree(sessionId: string, tree: SerializedComponent): Promise<void>;
+    /**
+     * Subscribe to real-time route changes
+     */
+    subscribeToRoutes(callback: (changes: DashChange<RouteDefinition>[]) => void): DashSubscription;
+    /**
+     * Subscribe to real-time session changes
+     */
+    subscribeToSession(sessionId: string, callback: (changes: DashChange<PageSession>[]) => void): DashSubscription;
+    /**
+     * Subscribe to presence updates for a session
+     */
+    subscribeToPresence(sessionId: string, callback: (changes: DashChange<PresenceRecord>[]) => void): DashSubscription;
+    /**
+     * Update presence for current user
+     */
+    updatePresence(sessionId: string, userId: string, presence: Partial<PresenceRecord>): Promise<void>;
+    /**
+     * Clean up subscriptions
+     */
+    destroy(): void;
+    private pathToId;
+    private routeToSessionId;
+}
+interface PresenceRecord {
+    sessionId: string;
+    userId: string;
+    role: 'user' | 'assistant' | 'monitor' | 'admin';
+    cursor?: {
+        x: number;
+        y: number;
+    };
+    editing?: string;
+    status: 'online' | 'away' | 'offline';
+    lastActivity: string;
+}
+/**
+ * Create a storage adapter based on configuration
+ */
+export declare function createStorageAdapter(config: {
+    type: 'file' | 'd1' | 'durable-object' | 'hybrid' | 'dash' | 'custom';
+    pagesDir?: string;
+    dataDir?: string;
+    d1?: D1Database;
+    durableObjectNamespace?: DurableObjectNamespace;
+    dash?: DashClient;
+    dashCollections?: {
+        routes?: string;
+        sessions?: string;
+        presence?: string;
+    };
+    custom?: StorageAdapter;
+}): StorageAdapter;
+export {};

package/dist/types.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Aeon Pages Type Definitions
+ */
+export interface AeonConfig {
+    /** Directory containing pages (default: './pages') */
+    pagesDir: string;
+    /** Directory containing components (default: './components') */
+    componentsDir?: string;
+    /** Runtime target: 'bun' or 'cloudflare' */
+    runtime: 'bun' | 'cloudflare';
+    /** Server port (default: 3000) */
+    port?: number;
+    /** Aeon-specific configuration */
+    aeon?: AeonOptions;
+    /** Component configuration */
+    components?: ComponentOptions;
+    /** Next.js compatibility mode */
+    nextCompat?: boolean;
+    /** Build output configuration */
+    output?: OutputOptions;
+}
+export interface AeonOptions {
+    /** Distributed sync configuration */
+    sync?: SyncOptions;
+    /** Schema versioning configuration */
+    versioning?: VersioningOptions;
+    /** Presence tracking configuration */
+    presence?: PresenceOptions;
+    /** Offline support configuration */
+    offline?: OfflineOptions;
+    /** Allow dynamic route creation for unclaimed paths */
+    dynamicRoutes?: boolean;
+}
+export interface SyncOptions {
+    /** Sync mode: 'distributed' for multi-node, 'local' for single-node */
+    mode: 'distributed' | 'local';
+    /** Number of replicas for distributed mode */
+    replicationFactor?: number;
+    /** Consistency level for reads/writes */
+    consistencyLevel?: 'strong' | 'eventual' | 'read-after-write';
+}
+export interface VersioningOptions {
+    /** Enable schema versioning */
+    enabled: boolean;
+    /** Automatically run migrations */
+    autoMigrate?: boolean;
+}
+export interface PresenceOptions {
+    /** Enable presence tracking */
+    enabled: boolean;
+    /** Track cursor positions */
+    cursorTracking?: boolean;
+    /** Inactivity timeout in milliseconds */
+    inactivityTimeout?: number;
+}
+export interface OfflineOptions {
+    /** Enable offline support */
+    enabled: boolean;
+    /** Maximum operations to queue offline */
+    maxQueueSize?: number;
+}
+export interface ComponentOptions {
+    /** Auto-discover components from componentsDir */
+    autoDiscover?: boolean;
+    /** Explicit list of components to include */
+    include?: string[];
+    /** Components to exclude from auto-discovery */
+    exclude?: string[];
+}
+export interface OutputOptions {
+    /** Output directory for built assets */
+    dir?: string;
+}
+/** Route definition */
+export interface RouteDefinition {
+    /** Pattern like "/blog/[slug]" */
+    pattern: string;
+    /** Session ID template */
+    sessionId: string;
+    /** Component ID */
+    componentId: string;
+    /** Layout wrapper */
+    layout?: string;
+    /** Whether this route uses 'use aeon' */
+    isAeon: boolean;
+}
+/** Route match result */
+export interface RouteMatch {
+    /** The matched route */
+    route: RouteDefinition;
+    /** Extracted parameters */
+    params: Record<string, string>;
+    /** Resolved session ID */
+    sessionId: string;
+    /** Component ID shorthand */
+    componentId: string;
+    /** Is this an Aeon page? */
+    isAeon: boolean;
+}
+/** Route metadata for registry */
+export interface RouteMetadata {
+    createdAt: string;
+    createdBy: string;
+    updatedAt?: string;
+    updatedBy?: string;
+}
+/** Route operation for sync */
+export interface RouteOperation {
+    type: 'route-add' | 'route-update' | 'route-remove';
+    path: string;
+    component?: string;
+    metadata?: RouteMetadata;
+    timestamp: string;
+    nodeId: string;
+}
+/** Serialized component tree */
+export interface SerializedComponent {
+    type: string;
+    props?: Record<string, unknown>;
+    children?: (SerializedComponent | string)[];
+}
+/** Page session stored in Aeon */
+export interface PageSession {
+    /** Route this session serves */
+    route: string;
+    /** Current component state */
+    tree: SerializedComponent;
+    /** Page data */
+    data: Record<string, unknown>;
+    /** Schema version */
+    schema: {
+        version: string;
+    };
+    /** Active presence info */
+    presence: PresenceInfo[];
+}
+/** Presence info for a user/agent */
+export interface PresenceInfo {
+    /** User or agent ID */
+    userId: string;
+    /** User or agent role */
+    role: 'user' | 'assistant' | 'monitor' | 'admin';
+    /** Cursor position */
+    cursor?: {
+        x: number;
+        y: number;
+    };
+    /** Currently editing element path */
+    editing?: string;
+    /** Online/away/offline status */
+    status: 'online' | 'away' | 'offline';
+    /** Last activity timestamp */
+    lastActivity: string;
+}
+/** UCAN capability for Aeon pages */
+export interface AeonCapability {
+    can: 'aeon:read' | 'aeon:write' | 'aeon:admin' | 'aeon:*';
+    with: string;
+}
+/** Alias for PresenceInfo - used by react package */
+export type PresenceUser = PresenceInfo;

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@affectively/aeon-pages-runtime",
+  "version": "0.1.0",
+  "description": "Bun/Cloudflare runtime for @affectively/aeon-pages",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.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 build ./src/index.ts ./src/server.ts ./src/router/index.ts --outdir ./dist --target bun && tsc --declaration --emitDeclarationOnly",
+    "dev": "bun --watch ./src/index.ts",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "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"
+  ]
+}