maxjay · maxjay · Jun 15, 2026 · Jun 15, 2026
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@maxjay/patchwork",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "A JSON editing engine with base/draft, diff, undo, and scoped lenses.",
   "type": "module",
   "main": "dist/index.js",

diff --git a/src/engine.test.ts b/src/engine.test.ts
@@ -1410,4 +1410,20 @@ describe('Engine — $self set diff', () => {
 		e.replace('$.tags[0]', ['c']);
 		expect(() => e.diff()).toThrow(/\$self.*requires primitive items/);
 	});
+
+	it('includeUnchanged emits unchanged ops for items present in both sets', () => {
+		const e = new Engine<any>({ tags: ['urgent', 'review', 'blocked'] }, { schema });
+		e.delete('$.tags[0]');
+		const ops = e.diff('$.tags', { includeUnchanged: true });
+		expect(ops.some(o => o.op === 'remove'    && (o as any).identity === 'urgent')).toBe(true);
+		expect(ops.some(o => o.op === 'unchanged' && (o as any).identity === 'review')).toBe(true);
+		expect(ops.some(o => o.op === 'unchanged' && (o as any).identity === 'blocked')).toBe(true);
+	});
+
+	it('includeUnchanged with no changes emits all items as unchanged', () => {
+		const e = new Engine<any>({ tags: ['a', 'b', 'c'] }, { schema });
+		const ops = e.diff('$.tags', { includeUnchanged: true });
+		expect(ops).toHaveLength(3);
+		expect(ops.every(o => o.op === 'unchanged')).toBe(true);
+	});
 });
diff --git a/src/engine.ts b/src/engine.ts
@@ -671,7 +671,7 @@ export class Engine<T extends JsonValue = JsonValue> {
 	// is the cleaner answer when items have a natural ID. Tracked in #18.
 	private diffArrayBySelf(
 		a: JsonValue[], b: JsonValue[],
-		path: string, ops: DiffOp[]
+		path: string, ops: DiffOp[], includeUnchanged: boolean
 	): void {
 		for (const arr of [a, b]) {
 			for (const item of arr) {
@@ -692,16 +692,18 @@ export class Engine<T extends JsonValue = JsonValue> {
 		for (const [item, i] of aMap)
 			if (!bMap.has(item)) ops.push({ op: OpType.Remove, path: `${path}[${i}]`, value: item, identity: item });
 
-		for (const [item, i] of bMap)
+		for (const [item, i] of bMap) {
 			if (!aMap.has(item)) ops.push({ op: OpType.Add, path: `${path}[${i}]`, value: item, identity: item });
+			else if (includeUnchanged) ops.push({ op: OpType.Unchanged, path: `${path}[${i}]`, value: item, identity: item, displacement: 0 });
+		}
 	}
 
 	private diffNode(a: JsonValue, b: JsonValue, path: string, ops: DiffOp[], includeUnchanged: boolean, cascade: boolean, insideElement: boolean, identity?: JsonValue): void {
 		if (Array.isArray(a) && Array.isArray(b)) {
 			const meta = this.keyMap.get(path) ?? this.keyMap.get(toPathPattern(path));
 			if (meta) {
 				if (insideElement && !cascade) return;
-				if (meta.key === '$self') { this.diffArrayBySelf(a, b, path, ops); return; }
+				if (meta.key === '$self') { this.diffArrayBySelf(a, b, path, ops, includeUnchanged); return; }
 				this.diffArrayByKey(a, b, path, meta.key, meta.ordered, ops, includeUnchanged, cascade);
 				return;
 			}