@sylphx/lens-server 1.11.2 → 2.0.1

package/dist/index.d.ts

@@ -1,210 +1,441 @@
-import { InferRouterContext as InferRouterContext2, MutationDef as MutationDef2, mutation, QueryDef as QueryDef2, query, ResolverContext, ResolverFn, RouterDef as RouterDef2, RouterRoutes, router } from "@sylphx/lens-core";
-import { ContextValue, EntityDef, InferRouterContext, MutationDef, QueryDef, Resolvers, RouterDef } from "@sylphx/lens-core";
-import { ArrayOperation, EmitCommand, EntityKey, InternalFieldUpdate, Update } from "@sylphx/lens-core";
-/** Client connection interface */
-interface StateClient {
-	id: string;
-	send: (message: StateUpdateMessage) => void;
+import { InferRouterContext as InferRouterContext3, MutationDef as MutationDef2, mutation, QueryDef as QueryDef2, query, ResolverContext, ResolverFn, RouterDef as RouterDef3, RouterRoutes, router } from "@sylphx/lens-core";
+import { ContextStore, ContextValue } from "@sylphx/lens-core";
+/**
+* Create a typed context reference.
+* This doesn't create a new AsyncLocalStorage, but provides type information.
+*/
+declare function createContext<T extends ContextValue>(): ContextStore<T>;
+/**
+* Get the current context value.
+* Throws if called outside of runWithContext.
+*/
+declare function useContext<T extends ContextValue = ContextValue>(): T;
+/**
+* Try to get the current context value.
+* Returns undefined if called outside of runWithContext.
+*/
+declare function tryUseContext<T extends ContextValue = ContextValue>(): T | undefined;
+/**
+* Run a function with the given context.
+*/
+declare function runWithContext<
+	T extends ContextValue,
+	R
+>(_context: ContextStore<T>, value: T, fn: () => R): R;
+/**
+* Run an async function with the given context.
+*/
+declare function runWithContextAsync<
+	T extends ContextValue,
+	R
+>(context: ContextStore<T>, value: T, fn: () => Promise<R>): Promise<R>;
+/**
+* Check if currently running within a context.
+*/
+declare function hasContext(): boolean;
+/**
+* Extend the current context with additional values.
+*/
+declare function extendContext<
+	T extends ContextValue,
+	E extends ContextValue
+>(current: T, extension: E): T & E;
+import { ContextValue as ContextValue3, InferRouterContext as InferRouterContext2, RouterDef as RouterDef2 } from "@sylphx/lens-core";
+import { ContextValue as ContextValue2, EntityDef, InferRouterContext, MutationDef, OptimisticDSL, QueryDef, Resolvers, RouterDef } from "@sylphx/lens-core";
+/**
+* @sylphx/lens-server - Plugin System Types
+*
+* Server-side plugin system with lifecycle hooks.
+* Plugins can intercept, modify, or extend server behavior.
+*/
+/**
+* Context passed to onSubscribe hook.
+*/
+interface SubscribeContext2 {
+	/** Client ID */
+	clientId: string;
+	/** Subscription ID (unique per client) */
+	subscriptionId: string;
+	/** Operation path (e.g., 'user.get') */
+	operation: string;
+	/** Operation input */
+	input: unknown;
+	/** Fields being subscribed to */
+	fields: string[] | "*";
+	/** Entity type (if determined) */
+	entity?: string;
+	/** Entity ID (if determined) */
+	entityId?: string;
+}
+/**
+* Context passed to onUnsubscribe hook.
+*/
+interface UnsubscribeContext2 {
+	/** Client ID */
+	clientId: string;
+	/** Subscription ID */
+	subscriptionId: string;
+	/** Operation path */
+	operation: string;
+	/** Entity keys that were being tracked */
+	entityKeys: string[];
+}
+/**
+* Context passed to beforeSend hook.
+*
+* The beforeSend hook is the key integration point for optimization plugins.
+* Plugins can intercept the data and return an optimized payload (e.g., diff).
+*/
+interface BeforeSendContext {
+	/** Client ID */
+	clientId: string;
+	/** Subscription ID (unique per client subscription) */
+	subscriptionId: string;
+	/** Entity type */
+	entity: string;
+	/** Entity ID */
+	entityId: string;
+	/** Data to be sent (full entity data) */
+	data: Record<string, unknown>;
+	/** Whether this is the first send (initial subscription data) */
+	isInitial: boolean;
+	/** Fields the client is subscribed to */
+	fields: string[] | "*";
 }
-/** Update message sent to clients */
-interface StateUpdateMessage {
-	type: "update";
+/**
+* Context passed to afterSend hook.
+*/
+interface AfterSendContext {
+	/** Client ID */
+	clientId: string;
+	/** Subscription ID */
+	subscriptionId: string;
+	/** Entity type */
 	entity: string;
-	id: string;
-	/** Field-level updates with strategy */
-	updates: Record<string, Update>;
+	/** Entity ID */
+	entityId: string;
+	/** Data that was sent (may be optimized/transformed by beforeSend) */
+	data: Record<string, unknown>;
+	/** Whether this was the first send */
+	isInitial: boolean;
+	/** Fields the client is subscribed to */
+	fields: string[] | "*";
+	/** Timestamp of send */
+	timestamp: number;
+}
+/**
+* Context passed to onConnect hook.
+*/
+interface ConnectContext {
+	/** Client ID */
+	clientId: string;
+	/** Request object (if available) */
+	request?: Request;
+	/** Function to send messages to this client */
+	send?: (message: unknown) => void;
 }
-/** Full entity update message */
-interface StateFullMessage {
-	type: "data";
+/**
+* Context passed to onBroadcast hook.
+*/
+interface BroadcastContext {
+	/** Entity type name */
 	entity: string;
-	id: string;
+	/** Entity ID */
+	entityId: string;
+	/** Entity data */
 	data: Record<string, unknown>;
 }
-/** Subscription info */
-interface Subscription {
+/**
+* Context passed to onDisconnect hook.
+*/
+interface DisconnectContext {
+	/** Client ID */
 	clientId: string;
-	fields: Set<string> | "*";
+	/** Number of active subscriptions at disconnect */
+	subscriptionCount: number;
+}
+/**
+* Context passed to beforeMutation hook.
+*/
+interface BeforeMutationContext {
+	/** Mutation name */
+	name: string;
+	/** Mutation input */
+	input: unknown;
+	/** Client ID (if from WebSocket) */
+	clientId?: string;
+}
+/**
+* Context passed to afterMutation hook.
+*/
+interface AfterMutationContext {
+	/** Mutation name */
+	name: string;
+	/** Mutation input */
+	input: unknown;
+	/** Mutation result */
+	result: unknown;
+	/** Client ID (if from WebSocket) */
+	clientId?: string;
+	/** Duration in milliseconds */
+	duration: number;
 }
-/** Configuration */
-interface GraphStateManagerConfig {
-	/** Called when an entity has no more subscribers */
-	onEntityUnsubscribed?: (entity: string, id: string) => void;
+/**
+* Context passed to onReconnect hook.
+*/
+interface ReconnectContext2 {
+	/** Client ID */
+	clientId: string;
+	/** Subscriptions to restore */
+	subscriptions: Array<{
+		id: string;
+		entity: string;
+		entityId: string;
+		fields: string[] | "*";
+		version: number;
+		dataHash?: string;
+		input?: unknown;
+	}>;
+	/** Client-generated reconnect ID */
+	reconnectId: string;
 }
 /**
-* Manages server-side canonical state and syncs to clients.
+* Result from onReconnect hook.
+*/
+interface ReconnectHookResult2 {
+	/** Subscription ID */
+	id: string;
+	/** Entity type */
+	entity: string;
+	/** Entity ID */
+	entityId: string;
+	/** Sync status */
+	status: "current" | "patched" | "snapshot" | "deleted" | "error";
+	/** Current server version */
+	version: number;
+	/** For "patched": ordered patches to apply */
+	patches?: Array<Array<{
+		op: string;
+		path: string;
+		value?: unknown;
+	}>>;
+	/** For "snapshot": full current state */
+	data?: Record<string, unknown>;
+	/** Error message if status is "error" */
+	error?: string;
+}
+/**
+* Context passed to onUpdateFields hook.
+*/
+interface UpdateFieldsContext2 {
+	/** Client ID */
+	clientId: string;
+	/** Subscription ID */
+	subscriptionId: string;
+	/** Entity type */
+	entity: string;
+	/** Entity ID */
+	entityId: string;
+	/** New fields after update */
+	fields: string[] | "*";
+	/** Previous fields */
+	previousFields: string[] | "*";
+}
+/**
+* Context passed to enhanceOperationMeta hook.
+* Called for each operation when building handshake metadata.
+*/
+interface EnhanceOperationMetaContext {
+	/** Operation path (e.g., 'user.create') */
+	path: string;
+	/** Operation type */
+	type: "query" | "mutation";
+	/** Current metadata (can be modified) */
+	meta: Record<string, unknown>;
+	/** Operation definition (MutationDef or QueryDef) */
+	definition: unknown;
+}
+/**
+* Server plugin interface.
+*
+* Plugins receive lifecycle hooks to extend server behavior.
+* All hooks are optional - implement only what you need.
 *
 * @example
 * ```typescript
-* const manager = new GraphStateManager();
-*
-* // Add client
-* manager.addClient({
-*   id: "client-1",
-*   send: (msg) => ws.send(JSON.stringify(msg)),
-* });
-*
-* // Subscribe client to entity
-* manager.subscribe("client-1", "Post", "123", ["title", "content"]);
-*
-* // Emit updates (from resolvers)
-* manager.emit("Post", "123", { content: "Updated content" });
-* // → Automatically computes diff and sends to subscribed clients
+* const loggingPlugin: ServerPlugin = {
+*   name: 'logging',
+*   onSubscribe: (ctx) => {
+*     console.log(`Client ${ctx.clientId} subscribed to ${ctx.operation}`);
+*   },
+*   beforeSend: (ctx) => {
+*     console.log(`Sending ${Object.keys(ctx.data).length} fields to ${ctx.clientId}`);
+*     return ctx.data; // Can modify data
+*   },
+* };
 * ```
 */
-declare class GraphStateManager {
-	/** Connected clients */
-	private clients;
-	/** Canonical state per entity (server truth) */
-	private canonical;
-	/** Canonical array state per entity (server truth for array outputs) */
-	private canonicalArrays;
-	/** Per-client state tracking */
-	private clientStates;
-	/** Per-client array state tracking */
-	private clientArrayStates;
-	/** Entity → subscribed client IDs */
-	private entitySubscribers;
-	/** Configuration */
-	private config;
-	constructor(config?: GraphStateManagerConfig);
+interface ServerPlugin {
+	/** Plugin name (for debugging) */
+	name: string;
 	/**
-	* Add a client connection
+	* Called when a client connects.
+	* Can return false to reject the connection.
 	*/
-	addClient(client: StateClient): void;
+	onConnect?: (ctx: ConnectContext) => void | boolean | Promise<void | boolean>;
 	/**
-	* Remove a client and cleanup all subscriptions
+	* Called when a client disconnects.
 	*/
-	removeClient(clientId: string): void;
+	onDisconnect?: (ctx: DisconnectContext) => void | Promise<void>;
 	/**
-	* Subscribe a client to an entity
+	* Called when a client subscribes to an operation.
+	* Can modify the context or return false to reject.
 	*/
-	subscribe(clientId: string, entity: string, id: string, fields?: string[] | "*"): void;
+	onSubscribe?: (ctx: SubscribeContext2) => void | boolean | Promise<void | boolean>;
 	/**
-	* Unsubscribe a client from an entity
+	* Called when a client unsubscribes.
 	*/
-	unsubscribe(clientId: string, entity: string, id: string): void;
+	onUnsubscribe?: (ctx: UnsubscribeContext2) => void | Promise<void>;
 	/**
-	* Update subscription fields for a client
+	* Called before sending data to a client.
+	* Can modify the data to be sent.
+	*
+	* @returns Modified data, or undefined to use original
 	*/
-	updateSubscription(clientId: string, entity: string, id: string, fields: string[] | "*"): void;
+	beforeSend?: (ctx: BeforeSendContext) => Record<string, unknown> | void | Promise<Record<string, unknown> | void>;
 	/**
-	* Emit data for an entity.
-	* This is the core method called by resolvers.
-	*
-	* @param entity - Entity name
-	* @param id - Entity ID
-	* @param data - Full or partial entity data
-	* @param options - Emit options
+	* Called after data is sent to a client.
 	*/
-	emit(entity: string, id: string, data: Record<string, unknown>, options?: {
-		replace?: boolean;
-	}): void;
+	afterSend?: (ctx: AfterSendContext) => void | Promise<void>;
 	/**
-	* Emit a field-level update with a specific strategy.
-	* Applies the update to canonical state and pushes to clients.
-	*
-	* @param entity - Entity name
-	* @param id - Entity ID
-	* @param field - Field name to update
-	* @param update - Update with strategy (value/delta/patch)
+	* Called before a mutation is executed.
+	* Can modify the input or return false to reject.
 	*/
-	emitField(entity: string, id: string, field: string, update: Update): void;
+	beforeMutation?: (ctx: BeforeMutationContext) => void | boolean | Promise<void | boolean>;
 	/**
-	* Emit multiple field updates in a batch.
-	* More efficient than multiple emitField calls.
-	*
-	* @param entity - Entity name
-	* @param id - Entity ID
-	* @param updates - Array of field updates
+	* Called after a mutation is executed.
 	*/
-	emitBatch(entity: string, id: string, updates: InternalFieldUpdate[]): void;
+	afterMutation?: (ctx: AfterMutationContext) => void | Promise<void>;
 	/**
-	* Process an EmitCommand from the Emit API.
-	* Routes to appropriate emit method.
+	* Called when a client reconnects with subscription state.
+	* Plugin can return sync results for each subscription.
 	*
-	* @param entity - Entity name
-	* @param id - Entity ID
-	* @param command - Emit command from resolver
+	* @returns Array of sync results, or null to let other plugins handle
 	*/
-	processCommand(entity: string, id: string, command: EmitCommand): void;
+	onReconnect?: (ctx: ReconnectContext2) => ReconnectHookResult2[] | null | Promise<ReconnectHookResult2[] | null>;
 	/**
-	* Emit array data (replace entire array).
+	* Called when a client updates subscribed fields for an entity.
+	*/
+	onUpdateFields?: (ctx: UpdateFieldsContext2) => void | Promise<void>;
+	/**
+	* Called for each operation when building handshake metadata.
+	* Plugin can add fields to meta (e.g., optimistic config).
 	*
-	* @param entity - Entity name
-	* @param id - Entity ID
-	* @param items - Array items
+	* @example
+	* ```typescript
+	* enhanceOperationMeta: (ctx) => {
+	*   if (ctx.type === 'mutation' && ctx.definition._optimistic) {
+	*     ctx.meta.optimistic = convertToExecutable(ctx.definition._optimistic);
+	*   }
+	* }
+	* ```
 	*/
-	emitArray(entity: string, id: string, items: unknown[]): void;
+	enhanceOperationMeta?: (ctx: EnhanceOperationMetaContext) => void;
 	/**
-	* Apply an array operation to the canonical state.
+	* Called when broadcasting data to subscribers of an entity.
+	* Plugin updates canonical state and returns patch info.
+	* Handler is responsible for routing to subscribers.
 	*
-	* @param entity - Entity name
-	* @param id - Entity ID
-	* @param operation - Array operation to apply
+	* @returns BroadcastResult with version, patch, and data
 	*/
-	emitArrayOperation(entity: string, id: string, operation: ArrayOperation): void;
+	onBroadcast?: (ctx: BroadcastContext) => {
+		version: number;
+		patch: unknown[] | null;
+		data: Record<string, unknown>;
+	} | boolean | void | Promise<{
+		version: number;
+		patch: unknown[] | null;
+		data: Record<string, unknown>;
+	} | boolean | void>;
+}
+/**
+* Plugin manager handles plugin lifecycle and hook execution.
+*/
+declare class PluginManager {
+	private plugins;
 	/**
-	* Apply an array operation and return new array.
+	* Register a plugin.
 	*/
-	private applyArrayOperation;
+	register(plugin: ServerPlugin): void;
 	/**
-	* Push array update to a specific client.
-	* Computes optimal diff strategy.
+	* Get all registered plugins.
 	*/
-	private pushArrayToClient;
+	getPlugins(): readonly ServerPlugin[];
 	/**
-	* Get current canonical array state
+	* Run onConnect hooks.
+	* Returns false if any plugin rejects the connection.
 	*/
-	getArrayState(entity: string, id: string): unknown[] | undefined;
+	runOnConnect(ctx: ConnectContext): Promise<boolean>;
 	/**
-	* Get current canonical state for an entity
+	* Run onDisconnect hooks.
 	*/
-	getState(entity: string, id: string): Record<string, unknown> | undefined;
+	runOnDisconnect(ctx: DisconnectContext): Promise<void>;
 	/**
-	* Check if entity has any subscribers
+	* Run onSubscribe hooks.
+	* Returns false if any plugin rejects the subscription.
 	*/
-	hasSubscribers(entity: string, id: string): boolean;
+	runOnSubscribe(ctx: SubscribeContext2): Promise<boolean>;
 	/**
-	* Push update to a specific client
+	* Run onUnsubscribe hooks.
 	*/
-	private pushToClient;
+	runOnUnsubscribe(ctx: UnsubscribeContext2): Promise<void>;
 	/**
-	* Push a single field update to a client.
-	* Computes optimal transfer strategy.
+	* Run beforeSend hooks.
+	* Each plugin can modify the data.
 	*/
-	private pushFieldToClient;
+	runBeforeSend(ctx: BeforeSendContext): Promise<Record<string, unknown>>;
 	/**
-	* Push multiple field updates to a client.
-	* Computes optimal transfer strategy for each field.
+	* Run afterSend hooks.
 	*/
-	private pushFieldsToClient;
+	runAfterSend(ctx: AfterSendContext): Promise<void>;
 	/**
-	* Send initial data to a newly subscribed client
+	* Run beforeMutation hooks.
+	* Returns false if any plugin rejects the mutation.
 	*/
-	private sendInitialData;
+	runBeforeMutation(ctx: BeforeMutationContext): Promise<boolean>;
 	/**
-	* Cleanup entity when no subscribers remain
+	* Run afterMutation hooks.
 	*/
-	private cleanupEntity;
-	private makeKey;
+	runAfterMutation(ctx: AfterMutationContext): Promise<void>;
 	/**
-	* Get statistics
+	* Run onReconnect hooks.
+	* Returns the first non-null result from a plugin.
 	*/
-	getStats(): {
-		clients: number;
-		entities: number;
-		totalSubscriptions: number;
-	};
+	runOnReconnect(ctx: ReconnectContext2): Promise<ReconnectHookResult2[] | null>;
 	/**
-	* Clear all state (for testing)
+	* Run onUpdateFields hooks.
 	*/
-	clear(): void;
+	runOnUpdateFields(ctx: UpdateFieldsContext2): Promise<void>;
+	/**
+	* Run enhanceOperationMeta hooks.
+	* Each plugin can add fields to the operation metadata.
+	*/
+	runEnhanceOperationMeta(ctx: EnhanceOperationMetaContext): void;
+	/**
+	* Run onBroadcast hooks.
+	* Returns BroadcastResult if a plugin handled it, null otherwise.
+	*/
+	runOnBroadcast(ctx: BroadcastContext): Promise<{
+		version: number;
+		patch: unknown[] | null;
+		data: Record<string, unknown>;
+	} | null>;
 }
 /**
-* Create a GraphStateManager instance
+* Create a new plugin manager.
 */
-declare function createGraphStateManager(config?: GraphStateManagerConfig): GraphStateManager;
+declare function createPluginManager(): PluginManager;
+import { FieldType } from "@sylphx/lens-core";
 /** Selection object type for nested field selection */
 interface SelectionObject {
 	[key: string]: boolean | SelectionObject | {
@@ -220,13 +451,13 @@ type MutationsMap = Record<string, MutationDef<unknown, unknown>>;
 /** Operation metadata for handshake */
 interface OperationMeta {
 	type: "query" | "mutation" | "subscription";
-	optimistic?: unknown;
+	optimistic?: OptimisticDSL;
 }
 /** Nested operations structure for handshake */
 type OperationsMap = {
 	[key: string]: OperationMeta | OperationsMap;
 };
-/** Logger interface for server */
+/** Logger interface */
 interface LensLogger {
 	info?: (message: string, ...args: unknown[]) => void;
 	warn?: (message: string, ...args: unknown[]) => void;
@@ -234,75 +465,51 @@ interface LensLogger {
 }
 /** Server configuration */
 interface LensServerConfig<
-	TContext extends ContextValue = ContextValue,
+	TContext extends ContextValue2 = ContextValue2,
 	TRouter extends RouterDef = RouterDef
 > {
 	/** Entity definitions */
 	entities?: EntitiesMap | undefined;
-	/** Router definition (namespaced operations) - context type is inferred */
+	/** Router definition (namespaced operations) */
 	router?: TRouter | undefined;
-	/** Query definitions (flat, legacy) */
+	/** Query definitions (flat) */
 	queries?: QueriesMap | undefined;
-	/** Mutation definitions (flat, legacy) */
+	/** Mutation definitions (flat) */
 	mutations?: MutationsMap | undefined;
-	/** Field resolvers array (use lens() factory to create) */
+	/** Field resolvers array */
 	resolvers?: Resolvers | undefined;
 	/** Logger for server messages (default: silent) */
 	logger?: LensLogger | undefined;
-	/** Context factory - must return the context type expected by the router */
+	/** Context factory */
 	context?: ((req?: unknown) => TContext | Promise<TContext>) | undefined;
 	/** Server version */
 	version?: string | undefined;
+	/**
+	* Server-level plugins for subscription lifecycle and state management.
+	* Plugins are processed at the server level, not adapter level.
+	*/
+	plugins?: ServerPlugin[] | undefined;
 }
 /** Server metadata for transport handshake */
 interface ServerMetadata {
-	/** Server version */
 	version: string;
-	/** Operations metadata map */
 	operations: OperationsMap;
 }
-/** Operation for in-process transport */
+/** Operation for execution */
 interface LensOperation {
-	/** Operation path (e.g., 'user.get', 'session.create') */
 	path: string;
-	/** Operation input */
 	input?: unknown;
 }
 /** Result from operation execution */
 interface LensResult<T = unknown> {
-	/** Success data */
 	data?: T;
-	/** Error if operation failed */
 	error?: Error;
 }
-/** Lens server interface */
-interface LensServer {
-	/** Get server metadata for transport handshake */
-	getMetadata(): ServerMetadata;
-	/** Execute operation - auto-detects query vs mutation from registered operations */
-	execute(op: LensOperation): Promise<LensResult>;
-	/** Execute a query (one-time) */
-	executeQuery<
-		TInput,
-		TOutput
-	>(name: string, input?: TInput): Promise<TOutput>;
-	/** Execute a mutation */
-	executeMutation<
-		TInput,
-		TOutput
-	>(name: string, input: TInput): Promise<TOutput>;
-	/** Handle WebSocket connection */
-	handleWebSocket(ws: WebSocketLike): void;
-	/** Handle HTTP request */
-	handleRequest(req: Request): Promise<Response>;
-	/** Get GraphStateManager for external access */
-	getStateManager(): GraphStateManager;
-	/** Start server */
-	listen(port: number): Promise<void>;
-	/** Close server */
-	close(): Promise<void>;
-}
-/** WebSocket interface */
+/**
+* Client send function type for subscription updates.
+*/
+type ClientSendFn = (message: unknown) => void;
+/** WebSocket interface for adapters */
 interface WebSocketLike {
 	send(data: string): void;
 	close(): void;
@@ -313,86 +520,128 @@ interface WebSocketLike {
 	onerror?: ((error: unknown) => void) | null;
 }
 /**
-* Infer input type from a query/mutation definition
-*/
-type InferInput<T> = T extends QueryDef<infer I, unknown> ? I extends void ? void : I : T extends MutationDef<infer I, unknown> ? I : never;
-/**
-* Infer output type from a query/mutation definition
-*/
-type InferOutput<T> = T extends QueryDef<unknown, infer O> ? O : T extends MutationDef<unknown, infer O> ? O : never;
-/**
-* API type for client inference
-* Export this type for client-side type safety
+* Lens server interface
 *
-* @example
-* ```typescript
-* // Server
-* const server = createLensServer({ queries, mutations });
-* type Api = InferApi<typeof server>;
+* Core methods:
+* - getMetadata() - Server metadata for transport handshake
+* - execute() - Execute any operation
 *
-* // Client (only imports TYPE)
-* import type { Api } from './server';
-* const client = createClient<Api>({ links: [...] });
-* ```
+* Subscription support (used by adapters):
+* - addClient() / removeClient() - Client connection management
+* - subscribe() / unsubscribe() - Subscription lifecycle
+* - send() - Send data to client (runs through plugin hooks)
+* - broadcast() - Broadcast to all entity subscribers
+* - handleReconnect() - Handle client reconnection
+*
+* The server handles all business logic including state management (via plugins).
+* Handlers are pure protocol translators that call these methods.
 */
+interface LensServer {
+	/** Get server metadata for transport handshake */
+	getMetadata(): ServerMetadata;
+	/** Execute operation - auto-detects query vs mutation */
+	execute(op: LensOperation): Promise<LensResult>;
+	/**
+	* Register a client connection.
+	* Call when a client connects via WebSocket/SSE.
+	*/
+	addClient(clientId: string, send: ClientSendFn): Promise<boolean>;
+	/**
+	* Remove a client connection.
+	* Call when a client disconnects.
+	*/
+	removeClient(clientId: string, subscriptionCount: number): void;
+	/**
+	* Subscribe a client to an entity.
+	* Runs plugin hooks and sets up state tracking (if clientState is enabled).
+	*/
+	subscribe(ctx: import("../plugin/types.js").SubscribeContext): Promise<boolean>;
+	/**
+	* Unsubscribe a client from an entity.
+	* Runs plugin hooks and cleans up state tracking.
+	*/
+	unsubscribe(ctx: import("../plugin/types.js").UnsubscribeContext): void;
+	/**
+	* Send data to a client for a specific subscription.
+	* Runs through plugin hooks (beforeSend/afterSend) for optimization.
+	*/
+	send(clientId: string, subscriptionId: string, entity: string, entityId: string, data: Record<string, unknown>, isInitial: boolean): Promise<void>;
+	/**
+	* Broadcast data to all subscribers of an entity.
+	* Runs through plugin hooks for each subscriber.
+	*/
+	broadcast(entity: string, entityId: string, data: Record<string, unknown>): Promise<void>;
+	/**
+	* Handle a reconnection request from a client.
+	* Uses plugin hooks (onReconnect) for reconnection logic.
+	*/
+	handleReconnect(ctx: import("../plugin/types.js").ReconnectContext): Promise<import("../plugin/types.js").ReconnectHookResult[] | null>;
+	/**
+	* Update subscribed fields for a client's subscription.
+	* Runs plugin hooks (onUpdateFields) to sync state.
+	*/
+	updateFields(ctx: import("../plugin/types.js").UpdateFieldsContext): Promise<void>;
+	/**
+	* Get the plugin manager for direct hook access.
+	*/
+	getPluginManager(): PluginManager;
+}
+type InferInput<T> = T extends QueryDef<infer I, any> ? I : T extends MutationDef<infer I, any> ? I : never;
+type InferOutput<T> = T extends QueryDef<any, infer O> ? O : T extends MutationDef<any, infer O> ? O : T extends FieldType<infer F> ? F : never;
 type InferApi<T> = T extends {
 	_types: infer Types;
 } ? Types : never;
-/**
-* Config helper type that infers context from router
-*/
 type ServerConfigWithInferredContext<
 	TRouter extends RouterDef,
 	Q extends QueriesMap = QueriesMap,
 	M extends MutationsMap = MutationsMap
 > = {
-	entities?: EntitiesMap;
 	router: TRouter;
+	entities?: EntitiesMap;
 	queries?: Q;
 	mutations?: M;
-	/** Field resolvers array */
 	resolvers?: Resolvers;
-	/** Context factory - type is inferred from router's procedures */
-	context?: (req?: unknown) => InferRouterContext<TRouter> | Promise<InferRouterContext<TRouter>>;
+	logger?: LensLogger;
+	context?: () => InferRouterContext<TRouter> | Promise<InferRouterContext<TRouter>>;
 	version?: string;
+	/** Server-level plugins (clientState, etc.) */
+	plugins?: ServerPlugin[];
 };
-/**
-* Config without router (legacy flat queries/mutations)
-*/
 type ServerConfigLegacy<
-	TContext extends ContextValue = ContextValue,
+	TContext extends ContextValue2,
 	Q extends QueriesMap = QueriesMap,
 	M extends MutationsMap = MutationsMap
 > = {
+	router?: RouterDef | undefined;
 	entities?: EntitiesMap;
-	router?: undefined;
 	queries?: Q;
 	mutations?: M;
-	/** Field resolvers array */
 	resolvers?: Resolvers;
-	context?: (req?: unknown) => TContext | Promise<TContext>;
+	logger?: LensLogger;
+	context?: () => TContext | Promise<TContext>;
 	version?: string;
+	/** Server-level plugins (clientState, etc.) */
+	plugins?: ServerPlugin[];
 };
 /**
-* Create Lens server with Operations API + Optimization Layer
-*
-* When using a router with typed context (from initLens), the context
-* function's return type is automatically enforced to match.
+* Create Lens server with optional plugin support.
 *
 * @example
 * ```typescript
-* // Context type is inferred from router's procedures
-* const server = createServer({
-*   router: appRouter,  // RouterDef with MyContext
-*   context: () => ({
-*     db: prisma,
-*     user: null,
-*   }),  // Must match MyContext!
-* })
+* // Stateless mode (default)
+* const app = createApp({ router });
+* createWSHandler(app); // Sends full data on each update
+*
+* // Stateful mode (with clientState)
+* const app = createApp({
+*   router,
+*   plugins: [clientState()], // Enables per-client state tracking
+* });
+* createWSHandler(app); // Sends minimal diffs
 * ```
 */
-declare function createServer<
-	TRouter extends RouterDef,
+declare function createApp<
+	TRouter extends RouterDef2,
 	Q extends QueriesMap = QueriesMap,
 	M extends MutationsMap = MutationsMap
 >(config: ServerConfigWithInferredContext<TRouter, Q, M>): LensServer & {
@@ -400,11 +649,11 @@ declare function createServer<
 		router: TRouter;
 		queries: Q;
 		mutations: M;
-		context: InferRouterContext<TRouter>;
+		context: InferRouterContext2<TRouter>;
 	};
 };
-declare function createServer<
-	TContext extends ContextValue = ContextValue,
+declare function createApp<
+	TContext extends ContextValue3 = ContextValue3,
 	Q extends QueriesMap = QueriesMap,
 	M extends MutationsMap = MutationsMap
 >(config: ServerConfigLegacy<TContext, Q, M>): LensServer & {
@@ -414,74 +663,809 @@ declare function createServer<
 		context: TContext;
 	};
 };
+/**
+* @sylphx/lens-server - SSE Handler
+*
+* Pure transport handler for Server-Sent Events.
+* No state management - just handles SSE connection lifecycle and message sending.
+*/
 /** SSE handler configuration */
 interface SSEHandlerConfig {
-	/** GraphStateManager instance (required) */
-	stateManager: GraphStateManager;
 	/** Heartbeat interval in ms (default: 30000) */
 	heartbeatInterval?: number;
+	/** Called when a client connects */
+	onConnect?: (client: SSEClient) => void;
+	/** Called when a client disconnects */
+	onDisconnect?: (clientId: string) => void;
 }
-/** SSE client info */
-interface SSEClientInfo {
+/** SSE client handle for sending messages */
+interface SSEClient {
+	/** Unique client ID */
 	id: string;
-	connectedAt: number;
+	/** Send a message to this client */
+	send: (message: unknown) => void;
+	/** Send a named event to this client */
+	sendEvent: (event: string, data: unknown) => void;
+	/** Close this client's connection */
+	close: () => void;
 }
 /**
-* SSE transport adapter for GraphStateManager.
+* Pure SSE transport handler.
 *
-* This is a thin adapter that:
-* - Creates SSE connections
-* - Registers clients with GraphStateManager
-* - Forwards updates to SSE streams
+* This handler ONLY manages:
+* - SSE connection lifecycle
+* - Message sending to clients
+* - Heartbeat keepalive
 *
-* All state/subscription logic is handled by GraphStateManager.
+* It does NOT know about:
+* - State management
+* - Subscriptions
+* - Plugins
 *
 * @example
 * ```typescript
-* const stateManager = new GraphStateManager();
-* const sse = new SSEHandler({ stateManager });
+* const sse = new SSEHandler({
+*   onConnect: (client) => {
+*     console.log('Client connected:', client.id);
+*     // Register with your state management here
+*   },
+*   onDisconnect: (clientId) => {
+*     console.log('Client disconnected:', clientId);
+*     // Cleanup your state management here
+*   },
+* });
 *
 * // Handle SSE connection
 * app.get('/events', (req) => sse.handleConnection(req));
 *
-* // Subscribe via separate endpoint or message
-* stateManager.subscribe(clientId, "Post", "123", "*");
+* // Send message to specific client
+* sse.send(clientId, { type: 'update', data: {...} });
 * ```
 */
 declare class SSEHandler {
-	private stateManager;
 	private heartbeatInterval;
+	private onConnectCallback;
+	private onDisconnectCallback;
 	private clients;
 	private clientCounter;
-	constructor(config: SSEHandlerConfig);
+	constructor(config?: SSEHandlerConfig);
 	/**
-	* Handle new SSE connection
-	* Returns a Response with SSE stream
+	* Handle new SSE connection.
+	* Returns a Response with SSE stream.
 	*/
 	handleConnection(_req?: Request): Response;
 	/**
-	* Remove client and cleanup
+	* Send a message to a specific client.
+	*/
+	send(clientId: string, message: unknown): boolean;
+	/**
+	* Send a named event to a specific client.
+	*/
+	sendEvent(clientId: string, event: string, data: unknown): boolean;
+	/**
+	* Broadcast a message to all connected clients.
+	*/
+	broadcast(message: unknown): void;
+	/**
+	* Remove client and cleanup.
 	*/
 	private removeClient;
 	/**
-	* Close specific client connection
+	* Close specific client connection.
 	*/
 	closeClient(clientId: string): void;
 	/**
-	* Get connected client count
+	* Get connected client count.
 	*/
 	getClientCount(): number;
 	/**
-	* Get connected client IDs
+	* Get connected client IDs.
 	*/
 	getClientIds(): string[];
 	/**
-	* Close all connections
+	* Check if a client is connected.
+	*/
+	hasClient(clientId: string): boolean;
+	/**
+	* Close all connections.
 	*/
 	closeAll(): void;
 }
 /**
-* Create SSE handler (transport adapter)
+* Create SSE handler (pure transport).
+*/
+declare function createSSEHandler(config?: SSEHandlerConfig): SSEHandler;
+interface HTTPHandlerOptions {
+	/**
+	* Path prefix for Lens endpoints.
+	* Default: "" (no prefix)
+	*
+	* @example
+	* ```typescript
+	* // All endpoints under /api
+	* createHTTPHandler(app, { pathPrefix: '/api' })
+	* // Metadata: GET /api/__lens/metadata
+	* // Operations: POST /api
+	* ```
+	*/
+	pathPrefix?: string;
+	/**
+	* Custom CORS headers.
+	* Default: Allow all origins
+	*/
+	cors?: {
+		origin?: string | string[];
+		methods?: string[];
+		headers?: string[];
+	};
+}
+interface HTTPHandler {
+	/**
+	* Handle HTTP request.
+	* Compatible with fetch API (Bun, Cloudflare Workers, Vercel).
+	*/
+	(request: Request): Promise<Response>;
+	/**
+	* Alternative method-style call.
+	*/
+	handle(request: Request): Promise<Response>;
+}
+/**
+* Create an HTTP handler from a Lens app.
+*
+* @example
+* ```typescript
+* import { createApp, createHTTPHandler } from '@sylphx/lens-server'
+*
+* const app = createApp({ router })
+* const handler = createHTTPHandler(app)
+*
+* // Bun
+* Bun.serve({ port: 3000, fetch: handler })
+*
+* // Vercel
+* handler
+*
+* // Cloudflare Workers
+* { fetch: handler }
+* ```
+*/
+declare function createHTTPHandler(server: LensServer, options?: HTTPHandlerOptions): HTTPHandler;
+interface HandlerOptions extends HTTPHandlerOptions {
+	/**
+	* SSE endpoint path.
+	* Default: "/__lens/sse"
+	*/
+	ssePath?: string;
+	/**
+	* Heartbeat interval for SSE connections in ms.
+	* Default: 30000
+	*/
+	heartbeatInterval?: number;
+}
+interface Handler {
+	/**
+	* Handle HTTP/SSE request.
+	* Compatible with fetch API (Bun, Cloudflare Workers, Vercel).
+	*/
+	(request: Request): Promise<Response>;
+	/**
+	* Alternative method-style call.
+	*/
+	handle(request: Request): Promise<Response>;
+	/**
+	* Access the SSE handler for manual operations.
+	*/
+	sse: SSEHandler;
+}
+/**
+* Create a unified HTTP + SSE handler from a Lens app.
+*
+* Automatically routes:
+* - GET {ssePath} → SSE connection
+* - Other requests → HTTP handler
+*
+* @example
+* ```typescript
+* import { createApp, createHandler } from '@sylphx/lens-server'
+*
+* const app = createApp({ router })
+* const handler = createHandler(app)
+*
+* // Bun
+* Bun.serve({ port: 3000, fetch: handler })
+*
+* // SSE endpoint: GET /__lens/sse
+* // HTTP endpoints: POST /, GET /__lens/metadata
+* ```
+*/
+declare function createHandler(server: LensServer, options?: HandlerOptions): Handler;
+/**
+* Create a proxy object that provides typed access to server procedures.
+*
+* This proxy allows calling server procedures directly without going through
+* HTTP. Useful for:
+* - Server-side rendering (SSR)
+* - Server Components
+* - Testing
+* - Same-process communication
+*
+* @example
+* ```typescript
+* const serverClient = createServerClientProxy(server);
+*
+* // Call procedures directly (typed!)
+* const users = await serverClient.user.list();
+* const user = await serverClient.user.get({ id: '123' });
+* ```
+*/
+declare function createServerClientProxy(server: LensServer): unknown;
+/**
+* Handle a query request using standard Web Request/Response API.
+*
+* Expects input in URL search params as JSON string.
+*
+* @example
+* ```typescript
+* // GET /api/lens/user.get?input={"id":"123"}
+* const response = await handleWebQuery(server, 'user.get', url);
+* ```
+*/
+declare function handleWebQuery(server: LensServer, path: string, url: URL): Promise<Response>;
+/**
+* Handle a mutation request using standard Web Request/Response API.
+*
+* Expects input in request body as JSON.
+*
+* @example
+* ```typescript
+* // POST /api/lens/user.create with body { "input": { "name": "John" } }
+* const response = await handleWebMutation(server, 'user.create', request);
+* ```
+*/
+declare function handleWebMutation(server: LensServer, path: string, request: Request): Promise<Response>;
+/**
+* Handle an SSE subscription request using standard Web Request/Response API.
+*
+* Creates a ReadableStream that emits SSE events from the subscription.
+*
+* @example
+* ```typescript
+* // GET /api/lens/events.stream with Accept: text/event-stream
+* const response = handleWebSSE(server, 'events.stream', url, request.signal);
+* ```
+*/
+declare function handleWebSSE(server: LensServer, path: string, url: URL, signal?: AbortSignal): Response;
+/**
+* Options for creating a framework handler.
+*/
+interface FrameworkHandlerOptions {
+	/** Base path to strip from request URLs */
+	basePath?: string;
+}
+/**
+* Create a complete request handler for Web standard Request/Response.
+*
+* Handles:
+* - GET requests → Query execution
+* - POST requests → Mutation execution
+* - SSE requests (Accept: text/event-stream) → Subscriptions
+*
+* @example
+* ```typescript
+* const handler = createFrameworkHandler(server, { basePath: '/api/lens' });
+*
+* // In Next.js App Router:
+* const GET = handler;
+* const POST = handler;
+*
+* // In Fresh:
+* const handler = { GET: lensHandler, POST: lensHandler };
+* ```
+*/
+declare function createFrameworkHandler(server: LensServer, options?: FrameworkHandlerOptions): (request: Request) => Promise<Response>;
+interface WSHandlerOptions {
+	/**
+	* Logger for debugging.
+	*/
+	logger?: {
+		info?: (message: string, ...args: unknown[]) => void;
+		warn?: (message: string, ...args: unknown[]) => void;
+		error?: (message: string, ...args: unknown[]) => void;
+	};
+}
+/**
+* WebSocket adapter for Bun's websocket handler.
+*/
+interface WSHandler {
+	/**
+	* Handle a new WebSocket connection.
+	* Call this when a WebSocket connection is established.
+	*/
+	handleConnection(ws: WebSocketLike): void;
+	/**
+	* Bun-compatible websocket handler object.
+	* Use directly with Bun.serve({ websocket: wsHandler.handler })
+	*/
+	handler: {
+		message(ws: unknown, message: string | Buffer): void;
+		close(ws: unknown): void;
+		open?(ws: unknown): void;
+	};
+	/**
+	* Close all connections and cleanup.
+	*/
+	close(): Promise<void>;
+}
+/**
+* Create a WebSocket handler from a Lens app.
+*
+* The handler is a pure protocol translator - all business logic is in the server.
+* State management is controlled by server plugins (e.g., clientState).
+*
+* @example
+* ```typescript
+* import { createApp, createWSHandler, clientState } from '@sylphx/lens-server'
+*
+* // Stateless mode (default) - sends full data
+* const app = createApp({ router });
+* const wsHandler = createWSHandler(app);
+*
+* // Stateful mode - sends minimal diffs
+* const appWithState = createApp({
+*   router,
+*   plugins: [clientState()],
+* });
+* const wsHandlerWithState = createWSHandler(appWithState);
+*
+* // Bun
+* Bun.serve({
+*   port: 3000,
+*   fetch: httpHandler,
+*   websocket: wsHandler.handler,
+* })
+* ```
+*/
+declare function createWSHandler(server: LensServer, options?: WSHandlerOptions): WSHandler;
+import { PatchOperation as PatchOperation2 } from "@sylphx/lens-core";
+import { PatchOperation } from "@sylphx/lens-core";
+/**
+* Entity state stored in the operation log.
+*/
+interface StoredEntityState {
+	/** Canonical state data */
+	data: Record<string, unknown>;
+	/** Current version */
+	version: number;
+	/** Timestamp of last update */
+	updatedAt: number;
+}
+/**
+* Operation log entry stored in storage.
+*/
+interface StoredPatchEntry {
+	/** Version this patch creates */
+	version: number;
+	/** Patch operations */
+	patch: PatchOperation[];
+	/** Timestamp when patch was created */
+	timestamp: number;
+}
+/**
+* Result from emit operation.
+*/
+interface EmitResult {
+	/** New version after emit */
+	version: number;
+	/** Computed patch (null if first emit) */
+	patch: PatchOperation[] | null;
+	/** Whether state actually changed */
+	changed: boolean;
+}
+/**
+* Storage adapter interface for opLog.
+*
+* Implementations:
+* - `memoryStorage()` - In-memory (default, for long-running servers)
+* - `redisStorage()` - Redis/Upstash (for serverless)
+* - `kvStorage()` - Cloudflare KV, Vercel KV
+*
+* All methods are async to support external storage.
+*
+* @example
+* ```typescript
+* // Default (in-memory)
+* const app = createApp({
+*   router,
+*   plugins: [opLog()],
+* });
+*
+* // With Redis for serverless
+* const app = createApp({
+*   router,
+*   plugins: [opLog({
+*     storage: redisStorage({ url: process.env.REDIS_URL }),
+*   })],
+* });
+* ```
+*/
+interface OpLogStorage {
+	/**
+	* Emit new state for an entity.
+	* This is an atomic operation that:
+	* 1. Computes patch from previous state (if exists)
+	* 2. Stores new state with incremented version
+	* 3. Appends patch to operation log
+	*
+	* @param entity - Entity type name
+	* @param entityId - Entity ID
+	* @param data - New state data
+	* @returns Emit result with version, patch, and changed flag
+	*/
+	emit(entity: string, entityId: string, data: Record<string, unknown>): Promise<EmitResult>;
+	/**
+	* Get current canonical state for an entity.
+	*
+	* @param entity - Entity type name
+	* @param entityId - Entity ID
+	* @returns State data or null if not found
+	*/
+	getState(entity: string, entityId: string): Promise<Record<string, unknown> | null>;
+	/**
+	* Get current version for an entity.
+	* Returns 0 if entity doesn't exist.
+	*
+	* @param entity - Entity type name
+	* @param entityId - Entity ID
+	* @returns Current version (0 if not found)
+	*/
+	getVersion(entity: string, entityId: string): Promise<number>;
+	/**
+	* Get the latest patch for an entity.
+	* Returns null if no patches available.
+	*
+	* @param entity - Entity type name
+	* @param entityId - Entity ID
+	* @returns Latest patch or null
+	*/
+	getLatestPatch(entity: string, entityId: string): Promise<PatchOperation[] | null>;
+	/**
+	* Get all patches since a given version.
+	* Used for reconnection to bring client up to date.
+	*
+	* @param entity - Entity type name
+	* @param entityId - Entity ID
+	* @param sinceVersion - Client's current version
+	* @returns Array of patches (one per version), or null if too old
+	*/
+	getPatchesSince(entity: string, entityId: string, sinceVersion: number): Promise<PatchOperation[][] | null>;
+	/**
+	* Check if entity exists in storage.
+	*
+	* @param entity - Entity type name
+	* @param entityId - Entity ID
+	* @returns True if entity exists
+	*/
+	has(entity: string, entityId: string): Promise<boolean>;
+	/**
+	* Delete an entity from storage.
+	* Removes state, version, and all patches.
+	*
+	* @param entity - Entity type name
+	* @param entityId - Entity ID
+	*/
+	delete(entity: string, entityId: string): Promise<void>;
+	/**
+	* Clear all data from storage.
+	* Used for testing.
+	*/
+	clear(): Promise<void>;
+	/**
+	* Dispose storage resources.
+	* Called when shutting down.
+	*/
+	dispose?(): Promise<void>;
+}
+/**
+* Configuration for operation log storage.
+*/
+interface OpLogStorageConfig {
+	/**
+	* Maximum number of patches to keep per entity.
+	* Older patches are evicted when limit is reached.
+	* @default 1000
+	*/
+	maxPatchesPerEntity?: number;
+	/**
+	* Maximum age of patches in milliseconds.
+	* Patches older than this are evicted.
+	* @default 300000 (5 minutes)
+	*/
+	maxPatchAge?: number;
+	/**
+	* Cleanup interval in milliseconds.
+	* Set to 0 to disable automatic cleanup.
+	* @default 60000 (1 minute)
+	*/
+	cleanupInterval?: number;
+	/**
+	* Maximum retries for emit operations on version conflict.
+	* Only applies to external storage (Redis, Upstash, Vercel KV).
+	* Set to 0 to disable retries (fail immediately on conflict).
+	* @default 3
+	*/
+	maxRetries?: number;
+}
+/**
+* Default storage configuration.
+*/
+declare const DEFAULT_STORAGE_CONFIG: Required<OpLogStorageConfig>;
+/**
+* Create an in-memory storage adapter.
+*
+* @example
+* ```typescript
+* const storage = memoryStorage();
+*
+* // Or with custom config
+* const storage = memoryStorage({
+*   maxPatchesPerEntity: 500,
+*   maxPatchAge: 60000,
+* });
+* ```
+*/
+declare function memoryStorage(config?: OpLogStorageConfig): OpLogStorage;
+/**
+* Operation log plugin configuration.
+*/
+interface OpLogOptions extends OpLogStorageConfig {
+	/**
+	* Storage adapter for state/version/patches.
+	* Defaults to in-memory storage.
+	*
+	* @example
+	* ```typescript
+	* // In-memory (default)
+	* opLog()
+	*
+	* // Redis for serverless
+	* opLog({ storage: redisStorage({ url: REDIS_URL }) })
+	* ```
+	*/
+	storage?: OpLogStorage;
+	/**
+	* Whether to enable debug logging.
+	* @default false
+	*/
+	debug?: boolean;
+}
+/**
+* Broadcast result returned by the plugin.
+* Handler uses this to send updates to subscribers.
+*/
+interface BroadcastResult {
+	/** Current version after update */
+	version: number;
+	/** Patch operations (null if first emit or log evicted) */
+	patch: PatchOperation2[] | null;
+	/** Full data (for initial sends or when patch unavailable) */
+	data: Record<string, unknown>;
+}
+/**
+* OpLog plugin instance type.
+*/
+interface OpLogPlugin extends ServerPlugin {
+	/** Get the storage adapter */
+	getStorage(): OpLogStorage;
+	/** Get version for an entity (async) */
+	getVersion(entity: string, entityId: string): Promise<number>;
+	/** Get current canonical state for an entity (async) */
+	getState(entity: string, entityId: string): Promise<Record<string, unknown> | null>;
+	/** Get latest patch for an entity (async) */
+	getLatestPatch(entity: string, entityId: string): Promise<PatchOperation2[] | null>;
+}
+/**
+* Create an operation log plugin.
+*
+* This plugin provides cursor-based state synchronization:
+* - Canonical state per entity (server truth)
+* - Version tracking for cursor-based sync
+* - Operation log for efficient reconnection (patches or snapshot)
+*
+* This plugin does NOT handle subscription routing - that's the handler's job.
+* Memory: O(entities × history) - does not scale with client count.
+*
+* @example
+* ```typescript
+* // Default (in-memory)
+* const server = createApp({
+*   router: appRouter,
+*   plugins: [opLog()],
+* });
+*
+* // With Redis for serverless
+* const server = createApp({
+*   router: appRouter,
+*   plugins: [opLog({
+*     storage: redisStorage({ url: process.env.REDIS_URL }),
+*   })],
+* });
+* ```
+*/
+declare function opLog(options?: OpLogOptions): OpLogPlugin;
+/**
+* Check if a plugin is an opLog plugin.
+*/
+declare function isOpLogPlugin(plugin: ServerPlugin): plugin is OpLogPlugin;
+import { OptimisticPluginMarker } from "@sylphx/lens-core";
+import { isOptimisticPlugin } from "@sylphx/lens-core";
+/**
+* Optimistic plugin configuration.
+*/
+interface OptimisticPluginOptions {
+	/**
+	* Whether to auto-derive optimistic config from mutation naming.
+	* - `updateX` → "merge"
+	* - `createX` / `addX` → "create"
+	* - `deleteX` / `removeX` → "delete"
+	* @default true
+	*/
+	autoDerive?: boolean;
+	/**
+	* Enable debug logging.
+	* @default false
+	*/
+	debug?: boolean;
+}
+/**
+* Combined plugin type that works with both lens() and createApp().
+*
+* This type satisfies:
+* - OptimisticPluginMarker (RuntimePlugin<OptimisticPluginExtension>) for lens() type extensions
+* - ServerPlugin for server-side metadata processing
+*/
+type OptimisticPlugin = OptimisticPluginMarker & ServerPlugin;
+/**
+* Create an optimistic plugin.
+*
+* This plugin enables type-safe .optimistic() on mutation builders when used
+* with lens(), and processes mutation definitions for server metadata.
+*
+* @example With lens() for type-safe builders
+* ```typescript
+* const { mutation, plugins } = lens<AppContext>({ plugins: [optimisticPlugin()] });
+*
+* // .optimistic() is type-safe (compile error without plugin)
+* const updateUser = mutation()
+*   .input(z.object({ id: z.string(), name: z.string() }))
+*   .returns(User)
+*   .optimistic('merge')
+*   .resolve(({ input }) => db.user.update(input));
+*
+* const server = createApp({ router, plugins });
+* ```
+*
+* @example Direct server usage
+* ```typescript
+* const server = createApp({
+*   router: appRouter,
+*   plugins: [optimisticPlugin()],
+* });
+* ```
+*/
+declare function optimisticPlugin(options?: OptimisticPluginOptions): OptimisticPlugin;
+import { OperationLogConfig, OperationLogEntry, OperationLogStats, PatchOperation as PatchOperation3, Version } from "@sylphx/lens-core";
+/**
+* Operation log with efficient lookup and bounded memory.
+*
+* Features:
+* - O(1) lookup by entity key (via index)
+* - Automatic eviction based on count, age, and memory
+* - Version tracking for efficient reconnect
+*
+* @example
+* ```typescript
+* const log = new OperationLog({ maxEntries: 10000, maxAge: 300000 });
+*
+* // Append operation
+* log.append({
+*   entityKey: "user:123",
+*   version: 5,
+*   timestamp: Date.now(),
+*   patch: [{ op: "replace", path: "/name", value: "Alice" }],
+*   patchSize: 50,
+* });
+*
+* // Get patches since version
+* const patches = log.getSince("user:123", 3);
+* // Returns patches for versions 4 and 5, or null if too old
+* ```
+*/
+declare class OperationLog {
+	private entries;
+	private config;
+	private totalMemory;
+	private entityIndex;
+	private oldestVersionIndex;
+	private newestVersionIndex;
+	private cleanupTimer;
+	constructor(config?: Partial<OperationLogConfig>);
+	/**
+	* Append new operation to log.
+	* Automatically evicts old entries if limits exceeded.
+	*/
+	append(entry: OperationLogEntry): void;
+	/**
+	* Append batch of operations efficiently.
+	*/
+	appendBatch(entries: OperationLogEntry[]): void;
+	/**
+	* Get all operations for entity since given version.
+	* Returns null if version is too old (not in log).
+	* Returns empty array if client is already at latest version.
+	*/
+	getSince(entityKey: string, fromVersion: Version): OperationLogEntry[] | null;
+	/**
+	* Check if version is within log range for entity.
+	*/
+	hasVersion(entityKey: string, version: Version): boolean;
+	/**
+	* Get oldest version available for entity.
+	*/
+	getOldestVersion(entityKey: string): Version | null;
+	/**
+	* Get newest version for entity.
+	*/
+	getNewestVersion(entityKey: string): Version | null;
+	/**
+	* Get all patches for entity (for debugging/testing).
+	*/
+	getAll(entityKey: string): OperationLogEntry[];
+	/**
+	* Cleanup expired entries.
+	* Called automatically on interval or manually.
+	*/
+	cleanup(): void;
+	/**
+	* Remove oldest entry and update tracking.
+	*/
+	private removeOldest;
+	/**
+	* Rebuild indices after cleanup.
+	* O(n) operation, should be called sparingly.
+	*/
+	private rebuildIndices;
+	/**
+	* Check limits and trigger cleanup if needed.
+	*/
+	private checkLimits;
+	/**
+	* Get statistics about the operation log.
+	*/
+	getStats(): OperationLogStats;
+	/**
+	* Clear all entries.
+	*/
+	clear(): void;
+	/**
+	* Stop cleanup timer and release resources.
+	*/
+	dispose(): void;
+	/**
+	* Update configuration.
+	*/
+	updateConfig(config: Partial<OperationLogConfig>): void;
+}
+/**
+* Coalesce multiple patches into single optimized patch.
+* Removes redundant operations and combines sequential changes.
+*
+* @param patches - Array of patch arrays (one per version)
+* @returns Single coalesced patch array
+*/
+declare function coalescePatches(patches: PatchOperation3[][]): PatchOperation3[];
+/**
+* Estimate memory size of patch operations.
 */
-declare function createSSEHandler(config: SSEHandlerConfig): SSEHandler;
-export { router, query, mutation, createServer, createSSEHandler, createGraphStateManager, WebSocketLike, Subscription, StateUpdateMessage, StateFullMessage, StateClient, ServerMetadata, LensServerConfig as ServerConfig, SelectionObject, SSEHandlerConfig, SSEHandler, SSEClientInfo, RouterRoutes, RouterDef2 as RouterDef, ResolverFn, ResolverContext, QueryDef2 as QueryDef, QueriesMap, OperationsMap, OperationMeta, MutationsMap, MutationDef2 as MutationDef, LensServer, LensResult, LensOperation, InferRouterContext2 as InferRouterContext, InferOutput, InferInput, InferApi, GraphStateManagerConfig, GraphStateManager, EntityKey, EntitiesMap };
+declare function estimatePatchSize(patch: PatchOperation3[]): number;
+export { useContext, tryUseContext, runWithContextAsync, runWithContext, router, query, optimisticPlugin, opLog, mutation, memoryStorage, isOptimisticPlugin, isOpLogPlugin, hasContext, handleWebSSE, handleWebQuery, handleWebMutation, extendContext, estimatePatchSize, createWSHandler, createServerClientProxy, createSSEHandler, createPluginManager, createHandler, createHTTPHandler, createFrameworkHandler, createContext, createApp, coalescePatches, WebSocketLike, WSHandlerOptions, WSHandler, UnsubscribeContext2 as UnsubscribeContext, SubscribeContext2 as SubscribeContext, StoredPatchEntry, StoredEntityState, ServerPlugin, ServerMetadata, LensServerConfig as ServerConfig, SelectionObject, SSEHandlerConfig as SSEHandlerOptions, SSEHandlerConfig, SSEHandler, SSEClient, RouterRoutes, RouterDef3 as RouterDef, ResolverFn, ResolverContext, QueryDef2 as QueryDef, QueriesMap, PluginManager, OptimisticPluginOptions, OperationsMap, OperationMeta, OperationLog, OpLogStorageConfig, OpLogStorage, OpLogPlugin, OpLogOptions, MutationsMap, MutationDef2 as MutationDef, LensServer, LensResult, LensOperation, InferRouterContext3 as InferRouterContext, InferOutput, InferInput, InferApi, HandlerOptions, Handler, HTTPHandlerOptions, HTTPHandler, FrameworkHandlerOptions, EntitiesMap, EnhanceOperationMetaContext, EmitResult, DisconnectContext, DEFAULT_STORAGE_CONFIG, ConnectContext, ClientSendFn, BroadcastResult, BeforeSendContext, BeforeMutationContext, AfterSendContext, AfterMutationContext };