@sylphx/lens-server 1.0.4 → 1.2.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ContextValue, EntityDef, EntityDefinition, EntityResolvers, EntityResolversDefinition, MutationDef, QueryDef, RelationDef, RelationTypeWithForeignKey, RouterDef } from "@sylphx/lens-core";
-import { EntityKey, Update } from "@sylphx/lens-core";
+import { EntityKey, Update, EmitCommand, InternalFieldUpdate, ArrayOperation } from "@sylphx/lens-core";
 /** Client connection interface */
 interface StateClient {
 	id: string;
@@ -56,8 +56,12 @@ declare class GraphStateManager {
 	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 */
@@ -96,6 +100,63 @@ declare class GraphStateManager {
 		replace?: boolean;
 	}): 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)
+	*/
+	emitField(entity: string, id: string, field: string, update: Update): void;
+	/**
+	* 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
+	*/
+	emitBatch(entity: string, id: string, updates: InternalFieldUpdate[]): void;
+	/**
+	* Process an EmitCommand from the Emit API.
+	* Routes to appropriate emit method.
+	*
+	* @param entity - Entity name
+	* @param id - Entity ID
+	* @param command - Emit command from resolver
+	*/
+	processCommand(entity: string, id: string, command: EmitCommand): void;
+	/**
+	* Emit array data (replace entire array).
+	*
+	* @param entity - Entity name
+	* @param id - Entity ID
+	* @param items - Array items
+	*/
+	emitArray(entity: string, id: string, items: unknown[]): void;
+	/**
+	* Apply an array operation to the canonical state.
+	*
+	* @param entity - Entity name
+	* @param id - Entity ID
+	* @param operation - Array operation to apply
+	*/
+	emitArrayOperation(entity: string, id: string, operation: ArrayOperation): void;
+	/**
+	* Apply an array operation and return new array.
+	*/
+	private applyArrayOperation;
+	/**
+	* Push array update to a specific client.
+	* Computes optimal diff strategy.
+	*/
+	private pushArrayToClient;
+	/**
+	* Get current canonical array state
+	*/
+	getArrayState(entity: string, id: string): unknown[] | undefined;
+	/**
 	* Get current canonical state for an entity
 	*/
 	getState(entity: string, id: string): Record<string, unknown> | undefined;
@@ -108,6 +169,16 @@ declare class GraphStateManager {
 	*/
 	private pushToClient;
 	/**
+	* Push a single field update to a client.
+	* Computes optimal transfer strategy.
+	*/
+	private pushFieldToClient;
+	/**
+	* Push multiple field updates to a client.
+	* Computes optimal transfer strategy for each field.
+	*/
+	private pushFieldsToClient;
+	/**
 	* Send initial data to a newly subscribed client
 	*/
 	private sendInitialData;

package/dist/index.js

@@ -1,6 +1,7 @@
 // src/server/create.ts
 import {
   createContext,
+  createEmit,
   createUpdate as createUpdate2,
   flattenRouter,
   isBatchResolver,
@@ -10,12 +11,18 @@ import {
 } from "@sylphx/lens-core";
 
 // src/state/graph-state-manager.ts
-import { createUpdate, makeEntityKey } from "@sylphx/lens-core";
+import {
+  createUpdate,
+  applyUpdate,
+  makeEntityKey
+} from "@sylphx/lens-core";
 
 class GraphStateManager {
   clients = new Map;
   canonical = new Map;
+  canonicalArrays = new Map;
   clientStates = new Map;
+  clientArrayStates = new Map;
   entitySubscribers = new Map;
   config;
   constructor(config = {}) {
@@ -24,6 +31,7 @@ class GraphStateManager {
   addClient(client) {
     this.clients.set(client.id, client);
     this.clientStates.set(client.id, new Map);
+    this.clientArrayStates.set(client.id, new Map);
   }
   removeClient(clientId) {
     for (const [key, subscribers] of this.entitySubscribers) {
@@ -34,6 +42,7 @@ class GraphStateManager {
     }
     this.clients.delete(clientId);
     this.clientStates.delete(clientId);
+    this.clientArrayStates.delete(clientId);
   }
   subscribe(clientId, entity, id, fields = "*") {
     const key = this.makeKey(entity, id);
@@ -96,6 +105,148 @@ class GraphStateManager {
       this.pushToClient(clientId, entity, id, key, currentCanonical);
     }
   }
+  emitField(entity, id, field, update) {
+    const key = this.makeKey(entity, id);
+    let currentCanonical = this.canonical.get(key);
+    if (!currentCanonical) {
+      currentCanonical = {};
+    }
+    const oldValue = currentCanonical[field];
+    const newValue = applyUpdate(oldValue, update);
+    currentCanonical = { ...currentCanonical, [field]: newValue };
+    this.canonical.set(key, currentCanonical);
+    const subscribers = this.entitySubscribers.get(key);
+    if (!subscribers)
+      return;
+    for (const clientId of subscribers) {
+      this.pushFieldToClient(clientId, entity, id, key, field, newValue);
+    }
+  }
+  emitBatch(entity, id, updates) {
+    const key = this.makeKey(entity, id);
+    let currentCanonical = this.canonical.get(key);
+    if (!currentCanonical) {
+      currentCanonical = {};
+    }
+    const changedFields = [];
+    for (const { field, update } of updates) {
+      const oldValue = currentCanonical[field];
+      const newValue = applyUpdate(oldValue, update);
+      currentCanonical[field] = newValue;
+      changedFields.push(field);
+    }
+    this.canonical.set(key, currentCanonical);
+    const subscribers = this.entitySubscribers.get(key);
+    if (!subscribers)
+      return;
+    for (const clientId of subscribers) {
+      this.pushFieldsToClient(clientId, entity, id, key, changedFields, currentCanonical);
+    }
+  }
+  processCommand(entity, id, command) {
+    switch (command.type) {
+      case "full":
+        this.emit(entity, id, command.data, {
+          replace: command.replace
+        });
+        break;
+      case "field":
+        this.emitField(entity, id, command.field, command.update);
+        break;
+      case "batch":
+        this.emitBatch(entity, id, command.updates);
+        break;
+      case "array":
+        this.emitArrayOperation(entity, id, command.operation);
+        break;
+    }
+  }
+  emitArray(entity, id, items) {
+    const key = this.makeKey(entity, id);
+    this.canonicalArrays.set(key, [...items]);
+    const subscribers = this.entitySubscribers.get(key);
+    if (!subscribers)
+      return;
+    for (const clientId of subscribers) {
+      this.pushArrayToClient(clientId, entity, id, key, items);
+    }
+  }
+  emitArrayOperation(entity, id, operation) {
+    const key = this.makeKey(entity, id);
+    let currentArray = this.canonicalArrays.get(key);
+    if (!currentArray) {
+      currentArray = [];
+    }
+    const newArray = this.applyArrayOperation([...currentArray], operation);
+    this.canonicalArrays.set(key, newArray);
+    const subscribers = this.entitySubscribers.get(key);
+    if (!subscribers)
+      return;
+    for (const clientId of subscribers) {
+      this.pushArrayToClient(clientId, entity, id, key, newArray);
+    }
+  }
+  applyArrayOperation(array, operation) {
+    switch (operation.op) {
+      case "push":
+        return [...array, operation.item];
+      case "unshift":
+        return [operation.item, ...array];
+      case "insert":
+        return [
+          ...array.slice(0, operation.index),
+          operation.item,
+          ...array.slice(operation.index)
+        ];
+      case "remove":
+        return [...array.slice(0, operation.index), ...array.slice(operation.index + 1)];
+      case "removeById": {
+        const idx = array.findIndex((item) => typeof item === "object" && item !== null && ("id" in item) && item.id === operation.id);
+        if (idx === -1)
+          return array;
+        return [...array.slice(0, idx), ...array.slice(idx + 1)];
+      }
+      case "update":
+        return array.map((item, i) => i === operation.index ? operation.item : item);
+      case "updateById":
+        return array.map((item) => typeof item === "object" && item !== null && ("id" in item) && item.id === operation.id ? operation.item : item);
+      case "merge":
+        return array.map((item, i) => i === operation.index && typeof item === "object" && item !== null ? { ...item, ...operation.partial } : item);
+      case "mergeById":
+        return array.map((item) => typeof item === "object" && item !== null && ("id" in item) && item.id === operation.id ? { ...item, ...operation.partial } : item);
+      default:
+        return array;
+    }
+  }
+  pushArrayToClient(clientId, entity, id, key, newArray) {
+    const client = this.clients.get(clientId);
+    if (!client)
+      return;
+    const clientArrayStateMap = this.clientArrayStates.get(clientId);
+    if (!clientArrayStateMap)
+      return;
+    let clientArrayState = clientArrayStateMap.get(key);
+    if (!clientArrayState) {
+      clientArrayState = { lastState: [] };
+      clientArrayStateMap.set(key, clientArrayState);
+    }
+    const { lastState } = clientArrayState;
+    if (JSON.stringify(lastState) === JSON.stringify(newArray)) {
+      return;
+    }
+    client.send({
+      type: "update",
+      entity,
+      id,
+      updates: {
+        _items: { strategy: "value", data: newArray }
+      }
+    });
+    clientArrayState.lastState = [...newArray];
+  }
+  getArrayState(entity, id) {
+    return this.canonicalArrays.get(this.makeKey(entity, id));
+  }
   getState(entity, id) {
     return this.canonical.get(this.makeKey(entity, id));
   }
@@ -143,6 +294,77 @@ class GraphStateManager {
       }
     }
   }
+  pushFieldToClient(clientId, entity, id, key, field, newValue) {
+    const client = this.clients.get(clientId);
+    if (!client)
+      return;
+    const clientStateMap = this.clientStates.get(clientId);
+    if (!clientStateMap)
+      return;
+    const clientEntityState = clientStateMap.get(key);
+    if (!clientEntityState)
+      return;
+    const { lastState, fields } = clientEntityState;
+    if (fields !== "*" && !fields.has(field)) {
+      return;
+    }
+    const oldValue = lastState[field];
+    if (oldValue === newValue)
+      return;
+    if (typeof oldValue === "object" && typeof newValue === "object" && JSON.stringify(oldValue) === JSON.stringify(newValue)) {
+      return;
+    }
+    const update = createUpdate(oldValue, newValue);
+    client.send({
+      type: "update",
+      entity,
+      id,
+      updates: { [field]: update }
+    });
+    clientEntityState.lastState[field] = newValue;
+  }
+  pushFieldsToClient(clientId, entity, id, key, changedFields, newState) {
+    const client = this.clients.get(clientId);
+    if (!client)
+      return;
+    const clientStateMap = this.clientStates.get(clientId);
+    if (!clientStateMap)
+      return;
+    const clientEntityState = clientStateMap.get(key);
+    if (!clientEntityState)
+      return;
+    const { lastState, fields } = clientEntityState;
+    const updates = {};
+    let hasChanges = false;
+    for (const field of changedFields) {
+      if (fields !== "*" && !fields.has(field)) {
+        continue;
+      }
+      const oldValue = lastState[field];
+      const newValue = newState[field];
+      if (oldValue === newValue)
+        continue;
+      if (typeof oldValue === "object" && typeof newValue === "object" && JSON.stringify(oldValue) === JSON.stringify(newValue)) {
+        continue;
+      }
+      const update = createUpdate(oldValue, newValue);
+      updates[field] = update;
+      hasChanges = true;
+    }
+    if (!hasChanges)
+      return;
+    client.send({
+      type: "update",
+      entity,
+      id,
+      updates
+    });
+    for (const field of changedFields) {
+      if (newState[field] !== undefined) {
+        clientEntityState.lastState[field] = newState[field];
+      }
+    }
+  }
   sendInitialData(clientId, entity, id, state, fields) {
     const client = this.clients.get(clientId);
     if (!client)
@@ -195,7 +417,9 @@ class GraphStateManager {
   clear() {
     this.clients.clear();
     this.canonical.clear();
+    this.canonicalArrays.clear();
     this.clientStates.clear();
+    this.clientArrayStates.clear();
     this.entitySubscribers.clear();
   }
 }
@@ -505,21 +729,31 @@ class LensServerImpl {
       if (!resolver) {
         throw new Error(`Query ${sub.operation} has no resolver`);
       }
-      const contextWithHelpers = {
-        ...context,
-        emit: emitData,
-        onCleanup: (fn) => {
-          sub.cleanups.push(fn);
-          return () => {
-            const idx = sub.cleanups.indexOf(fn);
-            if (idx >= 0)
-              sub.cleanups.splice(idx, 1);
-          };
+      const emit = createEmit((command) => {
+        const entityName = this.getEntityNameFromOutput(queryDef._output);
+        if (entityName) {
+          const entities = this.extractEntities(entityName, command.type === "full" ? command.data : {});
+          for (const { entity, id } of entities) {
+            this.stateManager.processCommand(entity, id, command);
+          }
+        }
+        if (command.type === "full") {
+          emitData(command.data);
         }
+      });
+      const onCleanup = (fn) => {
+        sub.cleanups.push(fn);
+        return () => {
+          const idx = sub.cleanups.indexOf(fn);
+          if (idx >= 0)
+            sub.cleanups.splice(idx, 1);
+        };
       };
       const result = resolver({
         input: sub.input,
-        ctx: contextWithHelpers
+        ctx: context,
+        emit,
+        onCleanup
       });
       if (isAsyncIterable(result)) {
         for await (const value of result) {
@@ -668,13 +902,14 @@ class LensServerImpl {
         if (!resolver) {
           throw new Error(`Query ${name} has no resolver`);
         }
-        const resolverCtx = {
+        const emit = createEmit(() => {});
+        const onCleanup = () => () => {};
+        const result = resolver({
           input: cleanInput,
           ctx: context,
-          emit: () => {},
-          onCleanup: () => () => {}
-        };
-        const result = resolver(resolverCtx);
+          emit,
+          onCleanup
+        });
         let data;
         if (isAsyncIterable(result)) {
           for await (const value of result) {
@@ -711,9 +946,13 @@ class LensServerImpl {
         if (!resolver) {
           throw new Error(`Mutation ${name} has no resolver`);
         }
+        const emit = createEmit(() => {});
+        const onCleanup = () => () => {};
         const result = await resolver({
           input,
-          ctx: context
+          ctx: context,
+          emit,
+          onCleanup
         });
         const entityName = this.getEntityNameFromMutation(name);
         const entities = this.extractEntities(entityName, result);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sylphx/lens-server",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "description": "Server runtime for Lens API framework",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,7 @@
   "author": "SylphxAI",
   "license": "MIT",
   "dependencies": {
-    "@sylphx/lens-core": "^1.0.4"
+    "@sylphx/lens-core": "^1.2.0"
   },
   "devDependencies": {
     "typescript": "^5.9.3",

package/src/e2e/server.test.ts

@@ -306,14 +306,14 @@ describe("E2E - Subscriptions", () => {
 		expect(received[0]).toMatchObject({ name: "Alice" });
 	});
 
-	it("subscribe receives updates via ctx.emit", async () => {
+	it("subscribe receives updates via emit", async () => {
 		let emitFn: ((data: unknown) => void) | null = null;
 
 		const watchUser = query()
 			.input(z.object({ id: z.string() }))
 			.returns(User)
-			.resolve(({ input, ctx }) => {
-				emitFn = ctx.emit;
+			.resolve(({ input, emit }) => {
+				emitFn = emit;
 				return mockUsers.find((u) => u.id === input.id) ?? null;
 			});
 
@@ -355,8 +355,8 @@ describe("E2E - Subscriptions", () => {
 		const watchUser = query()
 			.input(z.object({ id: z.string() }))
 			.returns(User)
-			.resolve(({ input, ctx }) => {
-				emitFn = ctx.emit;
+			.resolve(({ input, emit }) => {
+				emitFn = emit;
 				return mockUsers.find((u) => u.id === input.id) ?? null;
 			});
 
@@ -447,7 +447,7 @@ describe("E2E - Server API", () => {
 });
 
 // =============================================================================
-// Test: Cleanup (ctx.onCleanup)
+// Test: Cleanup (onCleanup)
 // =============================================================================
 
 describe("E2E - Cleanup", () => {
@@ -457,8 +457,8 @@ describe("E2E - Cleanup", () => {
 		const watchUser = query()
 			.input(z.object({ id: z.string() }))
 			.returns(User)
-			.resolve(({ input, ctx }) => {
-				ctx.onCleanup(() => {
+			.resolve(({ input, onCleanup }) => {
+				onCleanup(() => {
 					cleanedUp = true;
 				});
 				return mockUsers.find((u) => u.id === input.id) ?? null;
@@ -497,8 +497,8 @@ describe("E2E - GraphStateManager", () => {
 		const getUser = query()
 			.input(z.object({ id: z.string() }))
 			.returns(User)
-			.resolve(({ input, ctx }) => {
-				emitFn = ctx.emit;
+			.resolve(({ input, emit }) => {
+				emitFn = emit;
 				return mockUsers.find((u) => u.id === input.id) ?? null;
 			});
 

package/src/server/create.test.ts

@@ -644,8 +644,8 @@ describe("Minimum Transfer", () => {
 
 		const liveQuery = query()
 			.returns(User)
-			.resolve(({ ctx }) => {
-				emitFn = ctx.emit;
+			.resolve(({ emit }) => {
+				emitFn = emit;
 				return { id: "1", name: "Alice", email: "alice@example.com" };
 			});
 
@@ -681,13 +681,13 @@ describe("Minimum Transfer", () => {
 		}
 	});
 
-	it("sends updates via ctx.emit", async () => {
+	it("sends updates via emit", async () => {
 		let emitFn: ((data: unknown) => void) | null = null;
 
 		const liveQuery = query()
 			.returns(User)
-			.resolve(({ ctx }) => {
-				emitFn = ctx.emit;
+			.resolve(({ emit }) => {
+				emitFn = emit;
 				return { id: "1", name: "Alice", email: "alice@example.com" };
 			});
 
@@ -723,17 +723,17 @@ describe("Minimum Transfer", () => {
 });
 
 // =============================================================================
-// Test: ctx.onCleanup
+// Test: onCleanup
 // =============================================================================
 
-describe("ctx.onCleanup", () => {
+describe("onCleanup", () => {
 	it("calls cleanup function on unsubscribe", async () => {
 		let cleanedUp = false;
 
 		const liveQuery = query()
 			.returns(User)
-			.resolve(({ ctx }) => {
-				ctx.onCleanup(() => {
+			.resolve(({ onCleanup }) => {
+				onCleanup(() => {
 					cleanedUp = true;
 				});
 				return mockUsers[0];
@@ -772,8 +772,8 @@ describe("ctx.onCleanup", () => {
 
 		const liveQuery = query()
 			.returns(User)
-			.resolve(({ ctx }) => {
-				ctx.onCleanup(() => {
+			.resolve(({ onCleanup }) => {
+				onCleanup(() => {
 					cleanedUp = true;
 				});
 				return mockUsers[0];

package/src/server/create.ts

@@ -10,6 +10,8 @@
 
 import {
 	type ContextValue,
+	type Emit,
+	type EmitCommand,
 	type EntityDef,
 	type EntityDefinition,
 	type EntityResolvers,
@@ -22,6 +24,7 @@ import {
 	type RouterDef,
 	type Update,
 	createContext,
+	createEmit,
 	createUpdate,
 	flattenRouter,
 	isBatchResolver,
@@ -666,22 +669,37 @@ class LensServerImpl<
 				throw new Error(`Query ${sub.operation} has no resolver`);
 			}
 
-			// Add emit and onCleanup to context for subscriptions
-			const contextWithHelpers = {
-				...context,
-				emit: emitData,
-				onCleanup: (fn: () => void) => {
-					sub.cleanups.push(fn);
-					return () => {
-						const idx = sub.cleanups.indexOf(fn);
-						if (idx >= 0) sub.cleanups.splice(idx, 1);
-					};
-				},
+			// Create emit API for this subscription
+			const emit = createEmit((command: EmitCommand) => {
+				// Route emit commands to appropriate handler
+				const entityName = this.getEntityNameFromOutput(queryDef._output);
+				if (entityName) {
+					// For entity-typed outputs, use GraphStateManager
+					const entities = this.extractEntities(entityName, command.type === "full" ? command.data : {});
+					for (const { entity, id } of entities) {
+						this.stateManager.processCommand(entity, id, command);
+					}
+				}
+				// Also emit the raw data for operation-level updates
+				if (command.type === "full") {
+					emitData(command.data);
+				}
+			});
+
+			// Create onCleanup function
+			const onCleanup = (fn: () => void) => {
+				sub.cleanups.push(fn);
+				return () => {
+					const idx = sub.cleanups.indexOf(fn);
+					if (idx >= 0) sub.cleanups.splice(idx, 1);
+				};
 			};
 
 			const result = resolver({
 				input: sub.input,
-				ctx: contextWithHelpers,
+				ctx: context,
+				emit,
+				onCleanup,
 			});
 
 			if (isAsyncIterable(result)) {
@@ -892,14 +910,16 @@ class LensServerImpl<
 					throw new Error(`Query ${name} has no resolver`);
 				}
 
-				const resolverCtx = {
-					input: cleanInput as TInput,
-					ctx: context, // Pass context directly to resolver (tRPC style)
-					emit: () => {},
-					onCleanup: () => () => {},
-				};
+				// Create no-op emit for one-shot queries (emit is only meaningful in subscriptions)
+				const emit = createEmit(() => {});
+				const onCleanup = () => () => {};
 
-				const result = resolver(resolverCtx);
+				const result = resolver({
+					input: cleanInput as TInput,
+					ctx: context,
+					emit,
+					onCleanup,
+				});
 
 				let data: TOutput;
 				if (isAsyncIterable(result)) {
@@ -944,9 +964,15 @@ class LensServerImpl<
 					throw new Error(`Mutation ${name} has no resolver`);
 				}
 
+				// Create no-op emit for mutations (emit is primarily for subscriptions)
+				const emit = createEmit(() => {});
+				const onCleanup = () => () => {};
+
 				const result = await resolver({
 					input: input as TInput,
-					ctx: context, // Pass context directly to resolver (tRPC style)
+					ctx: context,
+					emit,
+					onCleanup,
 				});
 
 				// Emit to GraphStateManager

package/src/state/graph-state-manager.test.ts

@@ -331,4 +331,219 @@ describe("GraphStateManager", () => {
 			expect(stats.totalSubscriptions).toBe(3);
 		});
 	});
+
+	describe("array operations", () => {
+		interface User {
+			id: string;
+			name: string;
+		}
+
+		it("emits array data", () => {
+			manager.subscribe("client-1", "Users", "list", "*");
+			mockClient.messages = [];
+
+			manager.emitArray("Users", "list", [
+				{ id: "1", name: "Alice" },
+				{ id: "2", name: "Bob" },
+			]);
+
+			expect(mockClient.messages.length).toBe(1);
+			expect(mockClient.messages[0]).toMatchObject({
+				type: "update",
+				entity: "Users",
+				id: "list",
+			});
+			expect(mockClient.messages[0].updates._items.data).toEqual([
+				{ id: "1", name: "Alice" },
+				{ id: "2", name: "Bob" },
+			]);
+		});
+
+		it("gets array state", () => {
+			manager.emitArray("Users", "list", [{ id: "1", name: "Alice" }]);
+
+			expect(manager.getArrayState("Users", "list")).toEqual([{ id: "1", name: "Alice" }]);
+		});
+
+		it("applies push operation", () => {
+			manager.emitArray("Users", "list", [{ id: "1", name: "Alice" }]);
+			manager.emitArrayOperation("Users", "list", {
+				op: "push",
+				item: { id: "2", name: "Bob" },
+			});
+
+			expect(manager.getArrayState("Users", "list")).toEqual([
+				{ id: "1", name: "Alice" },
+				{ id: "2", name: "Bob" },
+			]);
+		});
+
+		it("applies unshift operation", () => {
+			manager.emitArray("Users", "list", [{ id: "1", name: "Alice" }]);
+			manager.emitArrayOperation("Users", "list", {
+				op: "unshift",
+				item: { id: "0", name: "Zero" },
+			});
+
+			expect(manager.getArrayState("Users", "list")).toEqual([
+				{ id: "0", name: "Zero" },
+				{ id: "1", name: "Alice" },
+			]);
+		});
+
+		it("applies insert operation", () => {
+			manager.emitArray("Users", "list", [
+				{ id: "1", name: "Alice" },
+				{ id: "3", name: "Charlie" },
+			]);
+			manager.emitArrayOperation("Users", "list", {
+				op: "insert",
+				index: 1,
+				item: { id: "2", name: "Bob" },
+			});
+
+			expect(manager.getArrayState("Users", "list")).toEqual([
+				{ id: "1", name: "Alice" },
+				{ id: "2", name: "Bob" },
+				{ id: "3", name: "Charlie" },
+			]);
+		});
+
+		it("applies remove operation", () => {
+			manager.emitArray("Users", "list", [
+				{ id: "1", name: "Alice" },
+				{ id: "2", name: "Bob" },
+			]);
+			manager.emitArrayOperation("Users", "list", { op: "remove", index: 0 });
+
+			expect(manager.getArrayState("Users", "list")).toEqual([{ id: "2", name: "Bob" }]);
+		});
+
+		it("applies removeById operation", () => {
+			manager.emitArray("Users", "list", [
+				{ id: "1", name: "Alice" },
+				{ id: "2", name: "Bob" },
+			]);
+			manager.emitArrayOperation("Users", "list", { op: "removeById", id: "1" });
+
+			expect(manager.getArrayState("Users", "list")).toEqual([{ id: "2", name: "Bob" }]);
+		});
+
+		it("handles removeById for non-existent id", () => {
+			manager.emitArray("Users", "list", [{ id: "1", name: "Alice" }]);
+			manager.emitArrayOperation("Users", "list", { op: "removeById", id: "999" });
+
+			expect(manager.getArrayState("Users", "list")).toEqual([{ id: "1", name: "Alice" }]);
+		});
+
+		it("applies update operation", () => {
+			manager.emitArray("Users", "list", [
+				{ id: "1", name: "Alice" },
+				{ id: "2", name: "Bob" },
+			]);
+			manager.emitArrayOperation("Users", "list", {
+				op: "update",
+				index: 1,
+				item: { id: "2", name: "Robert" },
+			});
+
+			expect(manager.getArrayState("Users", "list")).toEqual([
+				{ id: "1", name: "Alice" },
+				{ id: "2", name: "Robert" },
+			]);
+		});
+
+		it("applies updateById operation", () => {
+			manager.emitArray("Users", "list", [
+				{ id: "1", name: "Alice" },
+				{ id: "2", name: "Bob" },
+			]);
+			manager.emitArrayOperation("Users", "list", {
+				op: "updateById",
+				id: "2",
+				item: { id: "2", name: "Robert" },
+			});
+
+			expect(manager.getArrayState("Users", "list")).toEqual([
+				{ id: "1", name: "Alice" },
+				{ id: "2", name: "Robert" },
+			]);
+		});
+
+		it("applies merge operation", () => {
+			manager.emitArray("Users", "list", [
+				{ id: "1", name: "Alice" },
+				{ id: "2", name: "Bob" },
+			]);
+			manager.emitArrayOperation("Users", "list", {
+				op: "merge",
+				index: 0,
+				partial: { name: "Alicia" },
+			});
+
+			expect(manager.getArrayState("Users", "list")).toEqual([
+				{ id: "1", name: "Alicia" },
+				{ id: "2", name: "Bob" },
+			]);
+		});
+
+		it("applies mergeById operation", () => {
+			manager.emitArray("Users", "list", [
+				{ id: "1", name: "Alice" },
+				{ id: "2", name: "Bob" },
+			]);
+			manager.emitArrayOperation("Users", "list", {
+				op: "mergeById",
+				id: "2",
+				partial: { name: "Bobby" },
+			});
+
+			expect(manager.getArrayState("Users", "list")).toEqual([
+				{ id: "1", name: "Alice" },
+				{ id: "2", name: "Bobby" },
+			]);
+		});
+
+		it("processCommand handles array operations", () => {
+			manager.emitArray("Users", "list", [{ id: "1", name: "Alice" }]);
+
+			manager.processCommand("Users", "list", {
+				type: "array",
+				operation: { op: "push", item: { id: "2", name: "Bob" } },
+			});
+
+			expect(manager.getArrayState("Users", "list")).toEqual([
+				{ id: "1", name: "Alice" },
+				{ id: "2", name: "Bob" },
+			]);
+		});
+
+		it("sends array updates to subscribed clients", () => {
+			manager.subscribe("client-1", "Users", "list", "*");
+			mockClient.messages = [];
+
+			manager.emitArray("Users", "list", [{ id: "1", name: "Alice" }]);
+			manager.emitArrayOperation("Users", "list", {
+				op: "push",
+				item: { id: "2", name: "Bob" },
+			});
+
+			expect(mockClient.messages.length).toBe(2);
+			expect(mockClient.messages[1].updates._items.data).toEqual([
+				{ id: "1", name: "Alice" },
+				{ id: "2", name: "Bob" },
+			]);
+		});
+
+		it("does not send update if array unchanged", () => {
+			manager.subscribe("client-1", "Users", "list", "*");
+			manager.emitArray("Users", "list", [{ id: "1", name: "Alice" }]);
+			mockClient.messages = [];
+
+			// Remove by non-existent id (no change)
+			manager.emitArrayOperation("Users", "list", { op: "removeById", id: "999" });
+
+			expect(mockClient.messages.length).toBe(0);
+		});
+	});
 });

package/src/state/graph-state-manager.ts

@@ -9,7 +9,16 @@
  * - Pushes updates to subscribed clients
  */
 
-import { type EntityKey, type Update, createUpdate, makeEntityKey } from "@sylphx/lens-core";
+import {
+	type EntityKey,
+	type Update,
+	type EmitCommand,
+	type InternalFieldUpdate,
+	type ArrayOperation,
+	createUpdate,
+	applyUpdate,
+	makeEntityKey,
+} from "@sylphx/lens-core";
 
 // Re-export for convenience
 export type { EntityKey };
@@ -51,6 +60,12 @@ interface ClientEntityState {
 	fields: Set<string> | "*";
 }
 
+/** Per-client state for an array */
+interface ClientArrayState {
+	/** Last array state sent to this client */
+	lastState: unknown[];
+}
+
 /** Configuration */
 export interface GraphStateManagerConfig {
 	/** Called when an entity has no more subscribers */
@@ -89,9 +104,15 @@ export class GraphStateManager {
 	/** Canonical state per entity (server truth) */
 	private canonical = new Map<EntityKey, Record<string, unknown>>();
 
+	/** Canonical array state per entity (server truth for array outputs) */
+	private canonicalArrays = new Map<EntityKey, unknown[]>();
+
 	/** Per-client state tracking */
 	private clientStates = new Map<string, Map<EntityKey, ClientEntityState>>();
 
+	/** Per-client array state tracking */
+	private clientArrayStates = new Map<string, Map<EntityKey, ClientArrayState>>();
+
 	/** Entity → subscribed client IDs */
 	private entitySubscribers = new Map<EntityKey, Set<string>>();
 
@@ -112,6 +133,7 @@ export class GraphStateManager {
 	addClient(client: StateClient): void {
 		this.clients.set(client.id, client);
 		this.clientStates.set(client.id, new Map());
+		this.clientArrayStates.set(client.id, new Map());
 	}
 
 	/**
@@ -128,6 +150,7 @@ export class GraphStateManager {
 
 		this.clients.delete(clientId);
 		this.clientStates.delete(clientId);
+		this.clientArrayStates.delete(clientId);
 	}
 
 	// ===========================================================================
@@ -245,6 +268,278 @@ export class GraphStateManager {
 		}
 	}
 
+	/**
+	 * 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)
+	 */
+	emitField(entity: string, id: string, field: string, update: Update): void {
+		const key = this.makeKey(entity, id);
+
+		// Get or create canonical state
+		let currentCanonical = this.canonical.get(key);
+		if (!currentCanonical) {
+			currentCanonical = {};
+		}
+
+		// Apply update to canonical state based on strategy
+		const oldValue = currentCanonical[field];
+		const newValue = applyUpdate(oldValue, update);
+		currentCanonical = { ...currentCanonical, [field]: newValue };
+
+		this.canonical.set(key, currentCanonical);
+
+		// Push updates to all subscribed clients
+		const subscribers = this.entitySubscribers.get(key);
+		if (!subscribers) return;
+
+		for (const clientId of subscribers) {
+			this.pushFieldToClient(clientId, entity, id, key, field, newValue);
+		}
+	}
+
+	/**
+	 * 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
+	 */
+	emitBatch(entity: string, id: string, updates: InternalFieldUpdate[]): void {
+		const key = this.makeKey(entity, id);
+
+		// Get or create canonical state
+		let currentCanonical = this.canonical.get(key);
+		if (!currentCanonical) {
+			currentCanonical = {};
+		}
+
+		// Apply all updates to canonical state
+		const changedFields: string[] = [];
+		for (const { field, update } of updates) {
+			const oldValue = currentCanonical[field];
+			const newValue = applyUpdate(oldValue, update);
+			currentCanonical[field] = newValue;
+			changedFields.push(field);
+		}
+
+		this.canonical.set(key, currentCanonical);
+
+		// Push updates to all subscribed clients
+		const subscribers = this.entitySubscribers.get(key);
+		if (!subscribers) return;
+
+		for (const clientId of subscribers) {
+			this.pushFieldsToClient(clientId, entity, id, key, changedFields, currentCanonical);
+		}
+	}
+
+	/**
+	 * Process an EmitCommand from the Emit API.
+	 * Routes to appropriate emit method.
+	 *
+	 * @param entity - Entity name
+	 * @param id - Entity ID
+	 * @param command - Emit command from resolver
+	 */
+	processCommand(entity: string, id: string, command: EmitCommand): void {
+		switch (command.type) {
+			case "full":
+				this.emit(entity, id, command.data as Record<string, unknown>, {
+					replace: command.replace,
+				});
+				break;
+			case "field":
+				this.emitField(entity, id, command.field, command.update);
+				break;
+			case "batch":
+				this.emitBatch(entity, id, command.updates);
+				break;
+			case "array":
+				this.emitArrayOperation(entity, id, command.operation);
+				break;
+		}
+	}
+
+	// ===========================================================================
+	// Array State Emission
+	// ===========================================================================
+
+	/**
+	 * Emit array data (replace entire array).
+	 *
+	 * @param entity - Entity name
+	 * @param id - Entity ID
+	 * @param items - Array items
+	 */
+	emitArray(entity: string, id: string, items: unknown[]): void {
+		const key = this.makeKey(entity, id);
+		this.canonicalArrays.set(key, [...items]);
+
+		// Push updates to all subscribed clients
+		const subscribers = this.entitySubscribers.get(key);
+		if (!subscribers) return;
+
+		for (const clientId of subscribers) {
+			this.pushArrayToClient(clientId, entity, id, key, items);
+		}
+	}
+
+	/**
+	 * Apply an array operation to the canonical state.
+	 *
+	 * @param entity - Entity name
+	 * @param id - Entity ID
+	 * @param operation - Array operation to apply
+	 */
+	emitArrayOperation(entity: string, id: string, operation: ArrayOperation): void {
+		const key = this.makeKey(entity, id);
+
+		// Get or create canonical array state
+		let currentArray = this.canonicalArrays.get(key);
+		if (!currentArray) {
+			currentArray = [];
+		}
+
+		// Apply operation
+		const newArray = this.applyArrayOperation([...currentArray], operation);
+		this.canonicalArrays.set(key, newArray);
+
+		// Push updates to all subscribed clients
+		const subscribers = this.entitySubscribers.get(key);
+		if (!subscribers) return;
+
+		for (const clientId of subscribers) {
+			this.pushArrayToClient(clientId, entity, id, key, newArray);
+		}
+	}
+
+	/**
+	 * Apply an array operation and return new array.
+	 */
+	private applyArrayOperation(array: unknown[], operation: ArrayOperation): unknown[] {
+		switch (operation.op) {
+			case "push":
+				return [...array, operation.item];
+
+			case "unshift":
+				return [operation.item, ...array];
+
+			case "insert":
+				return [
+					...array.slice(0, operation.index),
+					operation.item,
+					...array.slice(operation.index),
+				];
+
+			case "remove":
+				return [...array.slice(0, operation.index), ...array.slice(operation.index + 1)];
+
+			case "removeById": {
+				const idx = array.findIndex(
+					(item) =>
+						typeof item === "object" &&
+						item !== null &&
+						"id" in item &&
+						(item as { id: string }).id === operation.id,
+				);
+				if (idx === -1) return array;
+				return [...array.slice(0, idx), ...array.slice(idx + 1)];
+			}
+
+			case "update":
+				return array.map((item, i) => (i === operation.index ? operation.item : item));
+
+			case "updateById":
+				return array.map((item) =>
+					typeof item === "object" &&
+					item !== null &&
+					"id" in item &&
+					(item as { id: string }).id === operation.id
+						? operation.item
+						: item,
+				);
+
+			case "merge":
+				return array.map((item, i) =>
+					i === operation.index && typeof item === "object" && item !== null
+						? { ...item, ...(operation.partial as object) }
+						: item,
+				);
+
+			case "mergeById":
+				return array.map((item) =>
+					typeof item === "object" &&
+					item !== null &&
+					"id" in item &&
+					(item as { id: string }).id === operation.id
+						? { ...item, ...(operation.partial as object) }
+						: item,
+				);
+
+			default:
+				return array;
+		}
+	}
+
+	/**
+	 * Push array update to a specific client.
+	 * Computes optimal diff strategy.
+	 */
+	private pushArrayToClient(
+		clientId: string,
+		entity: string,
+		id: string,
+		key: EntityKey,
+		newArray: unknown[],
+	): void {
+		const client = this.clients.get(clientId);
+		if (!client) return;
+
+		const clientArrayStateMap = this.clientArrayStates.get(clientId);
+		if (!clientArrayStateMap) return;
+
+		let clientArrayState = clientArrayStateMap.get(key);
+		if (!clientArrayState) {
+			// Initialize client array state
+			clientArrayState = { lastState: [] };
+			clientArrayStateMap.set(key, clientArrayState);
+		}
+
+		const { lastState } = clientArrayState;
+
+		// Skip if unchanged
+		if (JSON.stringify(lastState) === JSON.stringify(newArray)) {
+			return;
+		}
+
+		// For now, send full array replacement
+		// TODO: Compute array diff for optimal transfer
+		client.send({
+			type: "update",
+			entity,
+			id,
+			updates: {
+				_items: { strategy: "value", data: newArray },
+			},
+		});
+
+		// Update client's last known state
+		clientArrayState.lastState = [...newArray];
+	}
+
+	/**
+	 * Get current canonical array state
+	 */
+	getArrayState(entity: string, id: string): unknown[] | undefined {
+		return this.canonicalArrays.get(this.makeKey(entity, id));
+	}
+
 	/**
 	 * Get current canonical state for an entity
 	 */
@@ -330,6 +625,131 @@ export class GraphStateManager {
 		}
 	}
 
+	/**
+	 * Push a single field update to a client.
+	 * Computes optimal transfer strategy.
+	 */
+	private pushFieldToClient(
+		clientId: string,
+		entity: string,
+		id: string,
+		key: EntityKey,
+		field: string,
+		newValue: unknown,
+	): void {
+		const client = this.clients.get(clientId);
+		if (!client) return;
+
+		const clientStateMap = this.clientStates.get(clientId);
+		if (!clientStateMap) return;
+
+		const clientEntityState = clientStateMap.get(key);
+		if (!clientEntityState) return;
+
+		const { lastState, fields } = clientEntityState;
+
+		// Check if client is subscribed to this field
+		if (fields !== "*" && !fields.has(field)) {
+			return;
+		}
+
+		const oldValue = lastState[field];
+
+		// Skip if unchanged
+		if (oldValue === newValue) return;
+		if (
+			typeof oldValue === "object" &&
+			typeof newValue === "object" &&
+			JSON.stringify(oldValue) === JSON.stringify(newValue)
+		) {
+			return;
+		}
+
+		// Compute optimal update for transfer
+		const update = createUpdate(oldValue, newValue);
+
+		// Send update
+		client.send({
+			type: "update",
+			entity,
+			id,
+			updates: { [field]: update },
+		});
+
+		// Update client's last known state
+		clientEntityState.lastState[field] = newValue;
+	}
+
+	/**
+	 * Push multiple field updates to a client.
+	 * Computes optimal transfer strategy for each field.
+	 */
+	private pushFieldsToClient(
+		clientId: string,
+		entity: string,
+		id: string,
+		key: EntityKey,
+		changedFields: string[],
+		newState: Record<string, unknown>,
+	): void {
+		const client = this.clients.get(clientId);
+		if (!client) return;
+
+		const clientStateMap = this.clientStates.get(clientId);
+		if (!clientStateMap) return;
+
+		const clientEntityState = clientStateMap.get(key);
+		if (!clientEntityState) return;
+
+		const { lastState, fields } = clientEntityState;
+
+		// Compute updates for changed fields
+		const updates: Record<string, Update> = {};
+		let hasChanges = false;
+
+		for (const field of changedFields) {
+			// Check if client is subscribed to this field
+			if (fields !== "*" && !fields.has(field)) {
+				continue;
+			}
+
+			const oldValue = lastState[field];
+			const newValue = newState[field];
+
+			// Skip if unchanged
+			if (oldValue === newValue) continue;
+			if (
+				typeof oldValue === "object" &&
+				typeof newValue === "object" &&
+				JSON.stringify(oldValue) === JSON.stringify(newValue)
+			) {
+				continue;
+			}
+
+			// Compute optimal update for transfer
+			const update = createUpdate(oldValue, newValue);
+			updates[field] = update;
+			hasChanges = true;
+		}
+
+		if (!hasChanges) return;
+
+		// Send update
+		client.send({
+			type: "update",
+			entity,
+			id,
+			updates,
+		});
+
+		// Update client's last known state
+		for (const field of changedFields) {
+			if (newState[field] !== undefined) {
+				clientEntityState.lastState[field] = newState[field];
+			}
+		}
+	}
+
 	/**
 	 * Send initial data to a newly subscribed client
 	 */
@@ -426,7 +846,9 @@ export class GraphStateManager {
 	clear(): void {
 		this.clients.clear();
 		this.canonical.clear();
+		this.canonicalArrays.clear();
 		this.clientStates.clear();
+		this.clientArrayStates.clear();
 		this.entitySubscribers.clear();
 	}
 }