From 3b2e2d9e5553755115d6e802c830658c380998af Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Fri, 20 Feb 2026 12:46:52 +0100
Subject: [PATCH 1/6] feat: add snapshot diff command and snapshot efficiency
 guidance

---
 README.md                                     |  24 +-
 skills/agent-device/SKILL.md                  |  11 +
 .../agent-device/references/snapshot-refs.md  |  16 ++
 src/__tests__/cli-diff.test.ts                |  96 +++++++
 src/cli.ts                                    |   7 +-
 src/core/__tests__/capabilities.test.ts       |   1 +
 src/core/capabilities.ts                      |   1 +
 src/daemon/__tests__/snapshot-diff.test.ts    |  77 ++++++
 .../__tests__/snapshot-handler.test.ts        | 109 ++++++++
 src/daemon/handlers/snapshot.ts               | 261 ++++++++++++++----
 src/daemon/snapshot-diff.ts                   | 129 +++++++++
 src/utils/__tests__/args.test.ts              |  11 +
 src/utils/__tests__/output.test.ts            |  34 +++
 src/utils/command-schema.ts                   |   6 +
 src/utils/output.ts                           | 177 ++----------
 src/utils/snapshot-lines.ts                   | 165 +++++++++++
 website/docs/docs/commands.md                 |   2 +
 website/docs/docs/introduction.md             |   3 +-
 website/docs/docs/quick-start.md              |   4 +
 website/docs/docs/snapshots.md                |  14 +
 20 files changed, 931 insertions(+), 217 deletions(-)
 create mode 100644 src/__tests__/cli-diff.test.ts
 create mode 100644 src/daemon/__tests__/snapshot-diff.test.ts
 create mode 100644 src/daemon/snapshot-diff.ts
 create mode 100644 src/utils/__tests__/output.test.ts
 create mode 100644 src/utils/snapshot-lines.ts

diff --git a/README.md b/README.md
index 8aa8e1f3a..174bc59b0 100644
--- a/README.md
+++ b/README.md
@@ -14,8 +14,8 @@ The project is in early development and considered experimental. Pull requests a
 
 ## Features
 - Platforms: iOS (simulator + physical device core automation) and Android (emulator + device).
-- Core commands: `open`, `back`, `home`, `app-switcher`, `press`, `longpress`, `focus`, `type`, `fill`, `scroll`, `scrollintoview`, `wait`, `alert`, `screenshot`, `close`, `reinstall`.
-- Inspection commands: `snapshot` (accessibility tree), `appstate`, `apps`, `devices`.
+- Core commands: `open`, `back`, `home`, `app-switcher`, `press`, `long-press`, `focus`, `type`, `fill`, `scroll`, `scrollintoview`, `wait`, `alert`, `screenshot`, `close`, `reinstall`.
+- Inspection commands: `snapshot` (accessibility tree), `diff snapshot` (structural baseline diff), `appstate`, `apps`, `devices`.
 - Device tooling: `adb` (Android), `simctl`/`devicectl` (iOS via Xcode).
 - Minimal dependencies; TypeScript executed directly on Node 22+ (no build step).
 
@@ -39,9 +39,11 @@ Use `press` as the canonical tap command; `click` is an equivalent alias.
 ```bash
 agent-device open Contacts --platform ios # creates session on iOS Simulator
 agent-device snapshot
+agent-device diff snapshot # first run initializes baseline
 agent-device press @e5
 agent-device fill @e6 "John"
 agent-device fill @e7 "Doe"
+agent-device diff snapshot # subsequent runs compare against previous baseline
 agent-device press @e3
 agent-device close
 ```
@@ -135,8 +137,8 @@ agent-device swipe 540 1500 540 500 120 --count 8 --pause-ms 30 --pattern ping-p
 ## Command Index
 - `boot`, `open`, `close`, `reinstall`, `home`, `back`, `app-switcher`
 - `batch`
-- `snapshot`, `find`, `get`
-- `press` (alias: `click`), `focus`, `type`, `fill`, `longpress`, `swipe`, `scroll`, `scrollintoview`, `pinch`, `is`
+- `snapshot`, `diff snapshot`, `find`, `get`
+- `press` (alias: `click`), `focus`, `type`, `fill`, `long-press`, `swipe`, `scroll`, `scrollintoview`, `pinch`, `is`
 - `alert`, `wait`, `screenshot`
 - `trace start`, `trace stop`
 - `settings wifi|airplane|location on|off`
@@ -149,6 +151,20 @@ Notes:
 - iOS snapshots use XCTest on simulators and physical devices.
 - Scope snapshots with `-s "<label>"` or `-s @ref`.
 - If XCTest returns 0 nodes (e.g., foreground app changed), agent-device fails explicitly.
+- `diff snapshot` uses the same snapshot flags and compares the current capture with the previous session baseline, then updates baseline.
+
+Diff snapshots:
+- Run `diff snapshot` once to initialize baseline for the current session.
+- Run `diff snapshot` again after UI changes to get unified-style output (`-` removed, `+` added, unchanged context).
+- Use `--json` to get `{ mode, baselineInitialized, summary, lines }`.
+
+Efficient snapshot usage:
+- Default to `snapshot -i` for iterative agent loops.
+- Add `-s "<label>"` (or `-s @ref`) for screen-local work to reduce payload size.
+- Add `-d <depth>` when lower tree levels are not needed.
+- Re-snapshot after UI mutations before reusing refs.
+- Use `diff snapshot` for low-noise structural change verification between adjacent states.
+- Reserve `--raw` for troubleshooting and parser/debug investigations.
 
 Flags:
 - `--version, -V` print version and exit
diff --git a/skills/agent-device/SKILL.md b/skills/agent-device/SKILL.md
index 83e00a79f..5fe0f1d6d 100644
--- a/skills/agent-device/SKILL.md
+++ b/skills/agent-device/SKILL.md
@@ -64,10 +64,16 @@ agent-device snapshot -c               # Compact output
 agent-device snapshot -d 3             # Limit depth
 agent-device snapshot -s "Camera"      # Scope to label/identifier
 agent-device snapshot --raw            # Raw node output
+agent-device diff snapshot             # Structural diff against previous session baseline
 ```
 
 XCTest is the iOS snapshot engine: fast, complete, and no Accessibility permission required.
 
+Snapshot diff notes:
+- First `diff snapshot` call initializes baseline for the current session.
+- Subsequent `diff snapshot` calls compare current UI to prior baseline and then update baseline.
+- Use this for compact change tracking between adjacent UI states.
+
 ### Find (semantic)
 
 ```bash
@@ -241,6 +247,11 @@ agent-device apps --platform android --user-installed
 - Snapshot refs are the core mechanism for interactive agent flows.
 - Use selectors for deterministic replay artifacts and assertions (e.g. in e2e test workflows).
 - Prefer `snapshot -i` to reduce output size.
+- Prefer scoped snapshots (`-s "<label>"` or `-s @ref`) for screen-local tasks.
+- Add `-d <depth>` when only upper tree levels matter; avoid full-tree snapshots by default.
+- Use `diff snapshot` after mutations to detect structural changes with less output than full re-read.
+- Refresh refs immediately after navigation/modal/list mutations before issuing next ref-targeted action.
+- Use `--raw` only for debugging parser/tree edge-cases; avoid it for normal agent loops due to size.
 - On iOS, snapshots use XCTest and do not require Accessibility permission.
 - If XCTest returns 0 nodes (foreground app changed), treat it as an explicit failure and retry the flow/app state.
 - `open <app|url> [url]` can be used within an existing session to switch apps or open deep links.
diff --git a/skills/agent-device/references/snapshot-refs.md b/skills/agent-device/references/snapshot-refs.md
index e9c448c55..1bbac1298 100644
--- a/skills/agent-device/references/snapshot-refs.md
+++ b/skills/agent-device/references/snapshot-refs.md
@@ -51,6 +51,22 @@ agent-device snapshot -i -s "Camera"
 agent-device snapshot -i -s @e3
 ```
 
+## Diff snapshots (structural)
+
+Use `diff snapshot` when you need compact state-change visibility between nearby UI states:
+
+```bash
+agent-device diff snapshot           # First run initializes baseline
+agent-device press @e5
+agent-device diff snapshot           # Shows +/− structural lines vs prior baseline
+```
+
+Efficient pattern:
+- Initialize once at a stable point.
+- Mutate UI (`press`, `fill`, `swipe`).
+- Run `diff snapshot` to confirm expected change shape.
+- Re-run full/scoped `snapshot` only when you need fresh refs for next step selection.
+
 ## Troubleshooting
 
 - Ref not found: re-snapshot.
diff --git a/src/__tests__/cli-diff.test.ts b/src/__tests__/cli-diff.test.ts
new file mode 100644
index 000000000..ea3d62720
--- /dev/null
+++ b/src/__tests__/cli-diff.test.ts
@@ -0,0 +1,96 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { runCli } from '../cli.ts';
+import type { DaemonRequest, DaemonResponse } from '../daemon-client.ts';
+
+class ExitSignal extends Error {
+  public readonly code: number;
+
+  constructor(code: number) {
+    super(`EXIT_${code}`);
+    this.code = code;
+  }
+}
+
+type RunResult = {
+  code: number | null;
+  stdout: string;
+  stderr: string;
+  calls: Omit<DaemonRequest, 'token'>[];
+};
+
+async function runCliCapture(argv: string[]): Promise<RunResult> {
+  let stdout = '';
+  let stderr = '';
+  let code: number | null = null;
+  const calls: Array<Omit<DaemonRequest, 'token'>> = [];
+
+  const originalExit = process.exit;
+  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+  const originalStderrWrite = process.stderr.write.bind(process.stderr);
+
+  (process as any).exit = ((nextCode?: number) => {
+    throw new ExitSignal(nextCode ?? 0);
+  }) as typeof process.exit;
+  (process.stdout as any).write = ((chunk: unknown) => {
+    stdout += String(chunk);
+    return true;
+  }) as typeof process.stdout.write;
+  (process.stderr as any).write = ((chunk: unknown) => {
+    stderr += String(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+
+  const sendToDaemon = async (req: Omit<DaemonRequest, 'token'>): Promise<DaemonResponse> => {
+    calls.push(req);
+    return {
+      ok: true,
+      data: {
+        mode: 'snapshot',
+        baselineInitialized: false,
+        summary: { additions: 1, removals: 1, unchanged: 1 },
+        lines: [
+          { kind: 'unchanged', text: '@e2 [window]' },
+          { kind: 'removed', text: '  @e3 [text] "67"' },
+          { kind: 'added', text: '  @e3 [text] "134"' },
+        ],
+      },
+    };
+  };
+
+  try {
+    await runCli(argv, { sendToDaemon });
+  } catch (error) {
+    if (error instanceof ExitSignal) code = error.code;
+    else throw error;
+  } finally {
+    process.exit = originalExit;
+    process.stdout.write = originalStdoutWrite;
+    process.stderr.write = originalStderrWrite;
+  }
+
+  return { code, stdout, stderr, calls };
+}
+
+test('diff snapshot renders human-readable unified diff text', async () => {
+  const result = await runCliCapture(['diff', 'snapshot']);
+  assert.equal(result.code, null);
+  assert.equal(result.calls.length, 1);
+  assert.match(result.stdout, /^@e2 \[window\]/m);
+  assert.match(result.stdout, /^-  @e3 \[text\] "67"$/m);
+  assert.match(result.stdout, /^\+  @e3 \[text\] "134"$/m);
+  assert.match(result.stdout, /1 additions, 1 removals, 1 unchanged/);
+  assert.equal(result.stderr, '');
+});
+
+test('diff snapshot --json passes daemon payload through unchanged', async () => {
+  const result = await runCliCapture(['diff', 'snapshot', '--json']);
+  assert.equal(result.code, null);
+  assert.equal(result.calls.length, 1);
+  const payload = JSON.parse(result.stdout);
+  assert.equal(payload.success, true);
+  assert.equal(payload.data.mode, 'snapshot');
+  assert.equal(payload.data.baselineInitialized, false);
+  assert.equal(Array.isArray(payload.data.lines), true);
+  assert.equal(result.stderr, '');
+});
diff --git a/src/cli.ts b/src/cli.ts
index a74ad7679..26112cee7 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -1,6 +1,6 @@
 import { parseArgs, toDaemonFlags, usage, usageForCommand } from './utils/args.ts';
 import { asAppError, AppError, normalizeError } from './utils/errors.ts';
-import { formatSnapshotText, printHumanError, printJson } from './utils/output.ts';
+import { formatSnapshotDiffText, formatSnapshotText, printHumanError, printJson } from './utils/output.ts';
 import { readVersion } from './utils/version.ts';
 import { pathToFileURL } from 'node:url';
 import { sendToDaemon } from './daemon-client.ts';
@@ -189,6 +189,11 @@ export async function runCli(argv: string[], deps: CliDeps = DEFAULT_CLI_DEPS):
         if (logTailStopper) logTailStopper();
         return;
       }
+      if (command === 'diff' && positionals[0] === 'snapshot') {
+        process.stdout.write(formatSnapshotDiffText((response.data ?? {}) as Record<string, unknown>));
+        if (logTailStopper) logTailStopper();
+        return;
+      }
       if (command === 'get') {
         const sub = positionals[0];
         if (sub === 'text') {
diff --git a/src/core/__tests__/capabilities.test.ts b/src/core/__tests__/capabilities.test.ts
index e5145f769..f13efef01 100644
--- a/src/core/__tests__/capabilities.test.ts
+++ b/src/core/__tests__/capabilities.test.ts
@@ -54,6 +54,7 @@ test('core commands support iOS simulator, iOS device, and Android', () => {
     'boot',
     'click',
     'close',
+    'diff',
     'fill',
     'find',
     'focus',
diff --git a/src/core/capabilities.ts b/src/core/capabilities.ts
index 615975d62..185d267ed 100644
--- a/src/core/capabilities.ts
+++ b/src/core/capabilities.ts
@@ -23,6 +23,7 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
   click: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   close: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   fill: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  diff: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   find: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   focus: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   get: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
diff --git a/src/daemon/__tests__/snapshot-diff.test.ts b/src/daemon/__tests__/snapshot-diff.test.ts
new file mode 100644
index 000000000..234a8e26c
--- /dev/null
+++ b/src/daemon/__tests__/snapshot-diff.test.ts
@@ -0,0 +1,77 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { attachRefs, type RawSnapshotNode } from '../../utils/snapshot.ts';
+import { buildSnapshotDiff } from '../snapshot-diff.ts';
+
+function nodes(raw: RawSnapshotNode[]) {
+  return attachRefs(raw);
+}
+
+test('buildSnapshotDiff reports unchanged lines when snapshots are equal', () => {
+  const previous = nodes([
+    { index: 0, depth: 0, type: 'XCUIElementTypeWindow' },
+    { index: 1, depth: 1, type: 'XCUIElementTypeButton', label: 'Increment' },
+  ]);
+  const current = nodes([
+    { index: 0, depth: 0, type: 'XCUIElementTypeWindow' },
+    { index: 1, depth: 1, type: 'XCUIElementTypeButton', label: 'Increment' },
+  ]);
+
+  const diff = buildSnapshotDiff(previous, current);
+  assert.equal(diff.summary.additions, 0);
+  assert.equal(diff.summary.removals, 0);
+  assert.equal(diff.summary.unchanged, 2);
+  assert.deepEqual(diff.lines.map((line) => line.kind), ['unchanged', 'unchanged']);
+});
+
+test('buildSnapshotDiff reports added and removed lines', () => {
+  const previous = nodes([
+    { index: 0, depth: 0, type: 'XCUIElementTypeWindow' },
+    { index: 1, depth: 1, type: 'XCUIElementTypeStaticText', label: '67' },
+    { index: 2, depth: 1, type: 'XCUIElementTypeButton', label: 'Increment' },
+  ]);
+  const current = nodes([
+    { index: 0, depth: 0, type: 'XCUIElementTypeWindow' },
+    { index: 1, depth: 1, type: 'XCUIElementTypeStaticText', label: '134' },
+    { index: 2, depth: 1, type: 'XCUIElementTypeButton', label: 'Increment' },
+  ]);
+
+  const diff = buildSnapshotDiff(previous, current);
+  assert.equal(diff.summary.additions, 1);
+  assert.equal(diff.summary.removals, 1);
+  assert.equal(diff.summary.unchanged, 2);
+  assert.deepEqual(diff.lines.map((line) => line.kind), ['unchanged', 'removed', 'added', 'unchanged']);
+});
+
+test('buildSnapshotDiff treats value changes as remove plus add', () => {
+  const previous = nodes([{ index: 0, depth: 0, type: 'XCUIElementTypeTextField', label: 'Amount', value: '67' }]);
+  const current = nodes([{ index: 0, depth: 0, type: 'XCUIElementTypeTextField', label: 'Amount', value: '134' }]);
+
+  const diff = buildSnapshotDiff(previous, current);
+  assert.equal(diff.summary.additions, 1);
+  assert.equal(diff.summary.removals, 1);
+  assert.equal(diff.summary.unchanged, 0);
+  assert.deepEqual(diff.lines.map((line) => line.kind), ['removed', 'added']);
+});
+
+test('buildSnapshotDiff preserves surrounding context ordering', () => {
+  const previous = nodes([
+    { index: 0, depth: 0, type: 'XCUIElementTypeWindow' },
+    { index: 1, depth: 1, type: 'XCUIElementTypeStaticText', label: 'Count' },
+    { index: 2, depth: 1, type: 'XCUIElementTypeStaticText', label: '67' },
+    { index: 3, depth: 1, type: 'XCUIElementTypeButton', label: 'Increment' },
+  ]);
+  const current = nodes([
+    { index: 0, depth: 0, type: 'XCUIElementTypeWindow' },
+    { index: 1, depth: 1, type: 'XCUIElementTypeStaticText', label: 'Count' },
+    { index: 2, depth: 1, type: 'XCUIElementTypeStaticText', label: '134' },
+    { index: 3, depth: 1, type: 'XCUIElementTypeButton', label: 'Increment' },
+  ]);
+
+  const diff = buildSnapshotDiff(previous, current);
+  assert.equal(diff.lines[0]?.kind, 'unchanged');
+  assert.equal(diff.lines[1]?.kind, 'unchanged');
+  assert.equal(diff.lines[2]?.kind, 'removed');
+  assert.equal(diff.lines[3]?.kind, 'added');
+  assert.equal(diff.lines[4]?.kind, 'unchanged');
+});
diff --git a/src/daemon/handlers/__tests__/snapshot-handler.test.ts b/src/daemon/handlers/__tests__/snapshot-handler.test.ts
index 6c8a6b742..0a24704f4 100644
--- a/src/daemon/handlers/__tests__/snapshot-handler.test.ts
+++ b/src/daemon/handlers/__tests__/snapshot-handler.test.ts
@@ -114,3 +114,112 @@ test('settings usage hint documents canonical faceid states', async () => {
     assert.doesNotMatch(response.error.message, /validate\|unvalidate/);
   }
 });
+
+test('diff rejects unsupported kind', async () => {
+  const sessionStore = makeSessionStore();
+  const response = await handleSnapshotCommands({
+    req: {
+      token: 't',
+      session: 'default',
+      command: 'diff',
+      positionals: ['screenshot'],
+      flags: {},
+    },
+    sessionName: 'default',
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+  });
+
+  assert.ok(response);
+  assert.equal(response?.ok, false);
+  if (response && !response.ok) {
+    assert.equal(response.error.code, 'INVALID_ARGS');
+    assert.match(response.error.message, /diff snapshot/i);
+  }
+});
+
+test('diff initializes baseline on first run and updates it for subsequent runs', async () => {
+  const sessionStore = makeSessionStore();
+  const sessionName = 'ios-sim';
+  sessionStore.set(
+    sessionName,
+    makeSession(sessionName, {
+      platform: 'ios',
+      id: 'sim-1',
+      name: 'My iPhone Simulator',
+      kind: 'simulator',
+      booted: true,
+    }),
+  );
+
+  let snapshotCall = 0;
+  const dispatchSnapshotCommand = async () => {
+    snapshotCall += 1;
+    if (snapshotCall === 1) {
+      return {
+        nodes: [
+          { index: 0, depth: 0, type: 'XCUIElementTypeWindow' },
+          { index: 1, depth: 1, type: 'XCUIElementTypeStaticText', label: '67' },
+        ],
+        truncated: false,
+        backend: 'xctest' as const,
+      };
+    }
+    return {
+      nodes: [
+        { index: 0, depth: 0, type: 'XCUIElementTypeWindow' },
+        { index: 1, depth: 1, type: 'XCUIElementTypeStaticText', label: '134' },
+      ],
+      truncated: false,
+      backend: 'xctest' as const,
+    };
+  };
+
+  const first = await handleSnapshotCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'diff',
+      positionals: ['snapshot'],
+      flags: {},
+    },
+    sessionName,
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+    dispatchSnapshotCommand: dispatchSnapshotCommand as any,
+  });
+
+  assert.ok(first);
+  assert.equal(first?.ok, true);
+  if (first && first.ok) {
+    assert.equal((first.data as any).baselineInitialized, true);
+    assert.deepEqual((first.data as any).lines, []);
+  }
+  const baselineSession = sessionStore.get(sessionName);
+  assert.ok(baselineSession?.snapshot);
+  assert.equal(baselineSession?.snapshot?.nodes[1]?.label, '67');
+
+  const second = await handleSnapshotCommands({
+    req: {
+      token: 't',
+      session: sessionName,
+      command: 'diff',
+      positionals: ['snapshot'],
+      flags: {},
+    },
+    sessionName,
+    logPath: '/tmp/daemon.log',
+    sessionStore,
+    dispatchSnapshotCommand: dispatchSnapshotCommand as any,
+  });
+
+  assert.ok(second);
+  assert.equal(second?.ok, true);
+  if (second && second.ok) {
+    assert.equal((second.data as any).baselineInitialized, false);
+    assert.equal((second.data as any).summary.additions, 1);
+    assert.equal((second.data as any).summary.removals, 1);
+  }
+  const updatedSession = sessionStore.get(sessionName);
+  assert.equal(updatedSession?.snapshot?.nodes[1]?.label, '134');
+});
diff --git a/src/daemon/handlers/snapshot.ts b/src/daemon/handlers/snapshot.ts
index d1db000c1..bbb026efb 100644
--- a/src/daemon/handlers/snapshot.ts
+++ b/src/daemon/handlers/snapshot.ts
@@ -16,14 +16,17 @@ import { ensureDeviceReady } from '../device-ready.ts';
 import { findNodeByLabel, pruneGroupNodes, resolveRefLabel } from '../snapshot-processing.ts';
 import { findSelectorChainMatch, splitSelectorFromArgs, tryParseSelectorChain, type SelectorChain } from '../selectors.ts';
 import { parseTimeout, POLL_INTERVAL_MS, DEFAULT_TIMEOUT_MS } from './parse-utils.ts';
+import { buildSnapshotDiff, countSnapshotComparableLines } from '../snapshot-diff.ts';
 
 export async function handleSnapshotCommands(params: {
   req: DaemonRequest;
   sessionName: string;
   logPath: string;
   sessionStore: SessionStore;
+  dispatchSnapshotCommand?: typeof dispatchCommand;
 }): Promise<DaemonResponse | null> {
   const { req, sessionName, logPath, sessionStore } = params;
+  const dispatchSnapshotCommand = params.dispatchSnapshotCommand ?? dispatchCommand;
   const command = req.command;
 
   if (command === 'snapshot') {
@@ -37,72 +40,39 @@ export async function handleSnapshotCommands(params: {
         },
       };
     }
-    const appBundleId = session?.appBundleId;
-    let snapshotScope = req.flags?.snapshotScope;
-    if (snapshotScope && snapshotScope.trim().startsWith('@')) {
-      if (!session?.snapshot) {
-        return {
-          ok: false,
-          error: {
-            code: 'INVALID_ARGS',
-            message: 'Ref scope requires an existing snapshot in session.',
-          },
-        };
-      }
-      const ref = normalizeRef(snapshotScope.trim());
-      if (!ref) {
-        return {
-          ok: false,
-          error: { code: 'INVALID_ARGS', message: `Invalid ref scope: ${snapshotScope}` },
-        };
-      }
-      const node = findNodeByRef(session.snapshot.nodes, ref);
-      const resolved = node ? resolveRefLabel(node, session.snapshot.nodes) : undefined;
-      if (!resolved) {
-        return {
-          ok: false,
-          error: {
-            code: 'COMMAND_FAILED',
-            message: `Ref ${snapshotScope} not found or has no label`,
-          },
-        };
-      }
-      snapshotScope = resolved;
-    }
+    const resolvedScope = resolveSnapshotScope(req.flags?.snapshotScope, session);
+    if (!resolvedScope.ok) return resolvedScope.response;
+
     return await withSessionlessRunnerCleanup(session, device, async () => {
-      const data = (await dispatchCommand(device, 'snapshot', [], req.flags?.out, {
-        ...contextFromFlags(
-          logPath,
-          { ...req.flags, snapshotScope },
-          appBundleId,
-          session?.trace?.outPath,
-        ),
-      })) as {
-        nodes?: RawSnapshotNode[];
-        truncated?: boolean;
-        backend?: 'xctest' | 'android';
-      };
-      const rawNodes = data?.nodes ?? [];
-      const nodes = attachRefs(req.flags?.snapshotRaw ? rawNodes : pruneGroupNodes(rawNodes));
-      const snapshot: SnapshotState = {
-        nodes,
-        truncated: data?.truncated,
-        createdAt: Date.now(),
-        backend: data?.backend,
-      };
+      const appBundleId = session?.appBundleId;
+      const capture = await captureSnapshot({
+        dispatchSnapshotCommand,
+        device,
+        session,
+        req,
+        logPath,
+        snapshotScope: resolvedScope.scope,
+      });
       const nextSession: SessionState = session
-        ? { ...session, snapshot }
-        : { name: sessionName, device, createdAt: Date.now(), appBundleId, snapshot, actions: [] };
+        ? { ...session, snapshot: capture.snapshot }
+        : {
+          name: sessionName,
+          device,
+          createdAt: Date.now(),
+          appBundleId,
+          snapshot: capture.snapshot,
+          actions: [],
+        };
       recordIfSession(sessionStore, nextSession, req, {
-        nodes: nodes.length,
-        truncated: data?.truncated ?? false,
+        nodes: capture.snapshot.nodes.length,
+        truncated: capture.snapshot.truncated ?? false,
       });
       sessionStore.set(sessionName, nextSession);
       return {
         ok: true,
         data: {
-          nodes,
-          truncated: data?.truncated ?? false,
+          nodes: capture.snapshot.nodes,
+          truncated: capture.snapshot.truncated ?? false,
           appName: nextSession.appBundleId
             ? (nextSession.appName ?? nextSession.appBundleId)
             : undefined,
@@ -112,6 +82,98 @@ export async function handleSnapshotCommands(params: {
     });
   }
 
+  if (command === 'diff') {
+    if (req.positionals?.[0] !== 'snapshot') {
+      return {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message: 'diff currently supports only: diff snapshot',
+        },
+      };
+    }
+    const { session, device } = await resolveSessionDevice(sessionStore, sessionName, req.flags);
+    if (!isCommandSupportedOnDevice('diff', device)) {
+      return {
+        ok: false,
+        error: {
+          code: 'UNSUPPORTED_OPERATION',
+          message: 'diff is not supported on this device',
+        },
+      };
+    }
+    const resolvedScope = resolveSnapshotScope(req.flags?.snapshotScope, session);
+    if (!resolvedScope.ok) return resolvedScope.response;
+
+    return await withSessionlessRunnerCleanup(session, device, async () => {
+      const appBundleId = session?.appBundleId;
+      const capture = await captureSnapshot({
+        dispatchSnapshotCommand,
+        device,
+        session,
+        req,
+        logPath,
+        snapshotScope: resolvedScope.scope,
+      });
+      const currentSnapshot = capture.snapshot;
+
+      if (!session?.snapshot) {
+        const unchanged = countSnapshotComparableLines(currentSnapshot.nodes);
+        const nextSession: SessionState = session
+          ? { ...session, snapshot: currentSnapshot }
+          : {
+            name: sessionName,
+            device,
+            createdAt: Date.now(),
+            appBundleId,
+            snapshot: currentSnapshot,
+            actions: [],
+          };
+        recordIfSession(sessionStore, nextSession, req, {
+          mode: 'snapshot',
+          baselineInitialized: true,
+          summary: {
+            additions: 0,
+            removals: 0,
+            unchanged,
+          },
+        });
+        sessionStore.set(sessionName, nextSession);
+        return {
+          ok: true,
+          data: {
+            mode: 'snapshot',
+            baselineInitialized: true,
+            summary: {
+              additions: 0,
+              removals: 0,
+              unchanged,
+            },
+            lines: [],
+          },
+        };
+      }
+
+      const diff = buildSnapshotDiff(session.snapshot.nodes, currentSnapshot.nodes);
+      const nextSession: SessionState = { ...session, snapshot: currentSnapshot };
+      recordIfSession(sessionStore, nextSession, req, {
+        mode: 'snapshot',
+        baselineInitialized: false,
+        summary: diff.summary,
+      });
+      sessionStore.set(sessionName, nextSession);
+      return {
+        ok: true,
+        data: {
+          mode: 'snapshot',
+          baselineInitialized: false,
+          summary: diff.summary,
+          lines: diff.lines,
+        },
+      };
+    });
+  }
+
   if (command === 'wait') {
     const { session, device } = await resolveSessionDevice(sessionStore, sessionName, req.flags);
     const args = req.positionals ?? [];
@@ -140,7 +202,7 @@ export async function handleSnapshotCommands(params: {
         const timeout = parsed.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         const start = Date.now();
         while (Date.now() - start < timeout) {
-          const data = (await dispatchCommand(device, 'snapshot', [], req.flags?.out, {
+          const data = (await dispatchSnapshotCommand(device, 'snapshot', [], req.flags?.out, {
             ...contextFromFlags(
               logPath,
               {
@@ -345,6 +407,87 @@ export async function handleSnapshotCommands(params: {
   return null;
 }
 
+type CaptureSnapshotParams = {
+  dispatchSnapshotCommand: typeof dispatchCommand;
+  device: SessionState['device'];
+  session: SessionState | undefined;
+  req: DaemonRequest;
+  logPath: string;
+  snapshotScope?: string;
+};
+
+async function captureSnapshot(params: CaptureSnapshotParams): Promise<{ snapshot: SnapshotState }> {
+  const { dispatchSnapshotCommand, device, session, req, logPath, snapshotScope } = params;
+  const data = (await dispatchSnapshotCommand(device, 'snapshot', [], req.flags?.out, {
+    ...contextFromFlags(
+      logPath,
+      { ...req.flags, snapshotScope },
+      session?.appBundleId,
+      session?.trace?.outPath,
+    ),
+  })) as {
+    nodes?: RawSnapshotNode[];
+    truncated?: boolean;
+    backend?: 'xctest' | 'android';
+  };
+  const rawNodes = data?.nodes ?? [];
+  const nodes = attachRefs(req.flags?.snapshotRaw ? rawNodes : pruneGroupNodes(rawNodes));
+  return {
+    snapshot: {
+      nodes,
+      truncated: data?.truncated,
+      createdAt: Date.now(),
+      backend: data?.backend,
+    },
+  };
+}
+
+function resolveSnapshotScope(
+  snapshotScope: string | undefined,
+  session: SessionState | undefined,
+): { ok: true; scope?: string } | { ok: false; response: DaemonResponse } {
+  if (!snapshotScope || !snapshotScope.trim().startsWith('@')) {
+    return { ok: true, scope: snapshotScope };
+  }
+  if (!session?.snapshot) {
+    return {
+      ok: false,
+      response: {
+        ok: false,
+        error: {
+          code: 'INVALID_ARGS',
+          message: 'Ref scope requires an existing snapshot in session.',
+        },
+      },
+    };
+  }
+  const ref = normalizeRef(snapshotScope.trim());
+  if (!ref) {
+    return {
+      ok: false,
+      response: {
+        ok: false,
+        error: { code: 'INVALID_ARGS', message: `Invalid ref scope: ${snapshotScope}` },
+      },
+    };
+  }
+  const node = findNodeByRef(session.snapshot.nodes, ref);
+  const resolved = node ? resolveRefLabel(node, session.snapshot.nodes) : undefined;
+  if (!resolved) {
+    return {
+      ok: false,
+      response: {
+        ok: false,
+        error: {
+          code: 'COMMAND_FAILED',
+          message: `Ref ${snapshotScope} not found or has no label`,
+        },
+      },
+    };
+  }
+  return { ok: true, scope: resolved };
+}
+
 type WaitParsed =
   | { kind: 'sleep'; durationMs: number }
   | { kind: 'ref'; rawRef: string; timeoutMs: number | null }
diff --git a/src/daemon/snapshot-diff.ts b/src/daemon/snapshot-diff.ts
new file mode 100644
index 000000000..659df88f8
--- /dev/null
+++ b/src/daemon/snapshot-diff.ts
@@ -0,0 +1,129 @@
+import type { SnapshotNode } from '../utils/snapshot.ts';
+import { buildSnapshotDisplayLines, displayLabel, formatRole } from '../utils/snapshot-lines.ts';
+
+export type SnapshotDiffLine = {
+  kind: 'added' | 'removed' | 'unchanged';
+  text: string;
+};
+
+export type SnapshotDiffSummary = {
+  additions: number;
+  removals: number;
+  unchanged: number;
+};
+
+export type SnapshotDiffResult = {
+  summary: SnapshotDiffSummary;
+  lines: SnapshotDiffLine[];
+};
+
+type SnapshotComparableLine = {
+  text: string;
+  comparable: string;
+};
+
+export function snapshotNodeToComparableLine(node: SnapshotNode, depthOverride?: number): string {
+  const role = formatRole(node.type ?? 'Element');
+  const textPart = displayLabel(node, role);
+  const enabledPart = node.enabled === false ? 'disabled' : 'enabled';
+  const selectedPart = node.selected === true ? 'selected' : 'unselected';
+  const hittablePart = node.hittable === true ? 'hittable' : 'not-hittable';
+  const depthPart = String(depthOverride ?? node.depth ?? 0);
+  return [depthPart, role, textPart, enabledPart, selectedPart, hittablePart].join('|');
+}
+
+export function buildSnapshotDiff(previousNodes: SnapshotNode[], currentNodes: SnapshotNode[]): SnapshotDiffResult {
+  const previous = snapshotNodesToLines(previousNodes);
+  const current = snapshotNodesToLines(currentNodes);
+  const lines = diffComparableLinesMyers(previous, current);
+  const summary: SnapshotDiffSummary = { additions: 0, removals: 0, unchanged: 0 };
+  for (const line of lines) {
+    if (line.kind === 'added') summary.additions += 1;
+    if (line.kind === 'removed') summary.removals += 1;
+    if (line.kind === 'unchanged') summary.unchanged += 1;
+  }
+  return { summary, lines };
+}
+
+export function countSnapshotComparableLines(nodes: SnapshotNode[]): number {
+  return snapshotNodesToLines(nodes).length;
+}
+
+function snapshotNodesToLines(nodes: SnapshotNode[]): SnapshotComparableLine[] {
+  return buildSnapshotDisplayLines(nodes).map((line) => ({
+    text: line.text,
+    comparable: snapshotNodeToComparableLine(line.node, line.depth),
+  }));
+}
+
+function diffComparableLinesMyers(previous: SnapshotComparableLine[], current: SnapshotComparableLine[]): SnapshotDiffLine[] {
+  const n = previous.length;
+  const m = current.length;
+  const max = n + m;
+  const v = new Map<number, number>();
+  const trace: Array<Map<number, number>> = [];
+  v.set(1, 0);
+
+  for (let d = 0; d <= max; d += 1) {
+    trace.push(new Map(v));
+    for (let k = -d; k <= d; k += 2) {
+      const goDown = k === -d || (k !== d && getV(v, k - 1) < getV(v, k + 1));
+      let x = goDown ? getV(v, k + 1) : getV(v, k - 1) + 1;
+      let y = x - k;
+      while (x < n && y < m && previous[x].comparable === current[y].comparable) {
+        x += 1;
+        y += 1;
+      }
+      v.set(k, x);
+      if (x >= n && y >= m) {
+        return backtrackMyers(trace, previous, current, n, m);
+      }
+    }
+  }
+
+  return [];
+}
+
+function backtrackMyers(
+  trace: Array<Map<number, number>>,
+  previous: SnapshotComparableLine[],
+  current: SnapshotComparableLine[],
+  n: number,
+  m: number,
+): SnapshotDiffLine[] {
+  const lines: SnapshotDiffLine[] = [];
+  let x = n;
+  let y = m;
+
+  for (let d = trace.length - 1; d >= 0; d -= 1) {
+    const v = trace[d];
+    const k = x - y;
+    const goDown = k === -d || (k !== d && getV(v, k - 1) < getV(v, k + 1));
+    const prevK = goDown ? k + 1 : k - 1;
+    const prevX = getV(v, prevK);
+    const prevY = prevX - prevK;
+
+    while (x > prevX && y > prevY) {
+      lines.push({ kind: 'unchanged', text: current[y - 1].text });
+      x -= 1;
+      y -= 1;
+    }
+
+    if (d === 0) break;
+
+    if (x === prevX) {
+      lines.push({ kind: 'added', text: current[prevY].text });
+      y = prevY;
+    } else {
+      lines.push({ kind: 'removed', text: previous[prevX].text });
+      x = prevX;
+    }
+  }
+
+  lines.reverse();
+  return lines;
+}
+
+function getV(v: Map<number, number>, k: number): number {
+  return v.get(k) ?? 0;
+}
diff --git a/src/utils/__tests__/args.test.ts b/src/utils/__tests__/args.test.ts
index 580cbb1e7..8efe08769 100644
--- a/src/utils/__tests__/args.test.ts
+++ b/src/utils/__tests__/args.test.ts
@@ -227,6 +227,16 @@ test('snapshot command accepts command-specific flags', () => {
   assert.equal(parsed.flags.snapshotScope, 'Login');
 });
 
+test('diff snapshot command accepts snapshot flags', () => {
+  const parsed = parseArgs(['diff', 'snapshot', '-i', '--depth', '4', '--scope', 'Counter', '--raw'], { strictFlags: true });
+  assert.equal(parsed.command, 'diff');
+  assert.deepEqual(parsed.positionals, ['snapshot']);
+  assert.equal(parsed.flags.snapshotInteractiveOnly, true);
+  assert.equal(parsed.flags.snapshotDepth, 4);
+  assert.equal(parsed.flags.snapshotScope, 'Counter');
+  assert.equal(parsed.flags.snapshotRaw, true);
+});
+
 test('unknown short flags are rejected', () => {
   assert.throws(
     () => parseArgs(['press', '10', '20', '-x'], { strictFlags: true }),
@@ -290,6 +300,7 @@ test('invalid range errors are deterministic', () => {
 
 test('usage includes swipe and press series options', () => {
   const help = usage();
+  assert.match(help, /diff snapshot/);
   assert.match(help, /swipe <x1> <y1> <x2> <y2>/);
   assert.match(help, /--pattern one-way\|ping-pong/);
   assert.match(help, /--interval-ms/);
diff --git a/src/utils/__tests__/output.test.ts b/src/utils/__tests__/output.test.ts
new file mode 100644
index 000000000..cad389834
--- /dev/null
+++ b/src/utils/__tests__/output.test.ts
@@ -0,0 +1,34 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { formatSnapshotDiffText } from '../output.ts';
+
+test('formatSnapshotDiffText renders unified diff lines with summary', () => {
+  const text = formatSnapshotDiffText({
+    baselineInitialized: false,
+    summary: { additions: 2, removals: 2, unchanged: 2 },
+    lines: [
+      { kind: 'unchanged', text: '@e2 [window]' },
+      { kind: 'removed', text: '  @e3 [other] "67"' },
+      { kind: 'removed', text: '  @e4 [text] "67"' },
+      { kind: 'added', text: '  @e3 [other] "134"' },
+      { kind: 'added', text: '  @e4 [text] "134"' },
+      { kind: 'unchanged', text: '  @e5 [button] "Increment"' },
+    ],
+  });
+
+  assert.match(text, /^@e2 \[window\]/m);
+  assert.match(text, /^-  @e3 \[other\] "67"$/m);
+  assert.match(text, /^\+  @e3 \[other\] "134"$/m);
+  assert.match(text, /2 additions, 2 removals, 2 unchanged/);
+});
+
+test('formatSnapshotDiffText renders baseline initialization text', () => {
+  const text = formatSnapshotDiffText({
+    baselineInitialized: true,
+    summary: { additions: 0, removals: 0, unchanged: 5 },
+    lines: [],
+  });
+
+  assert.match(text, /Baseline initialized \(5 lines\)\./);
+  assert.match(text, /0 additions, 0 removals, 5 unchanged/);
+});
diff --git a/src/utils/command-schema.ts b/src/utils/command-schema.ts
index a1ffde486..a6b40ed60 100644
--- a/src/utils/command-schema.ts
+++ b/src/utils/command-schema.ts
@@ -370,6 +370,12 @@ export const COMMAND_SCHEMAS: Record<string, CommandSchema> = {
     positionalArgs: [],
     allowedFlags: [...SNAPSHOT_FLAGS],
   },
+  diff: {
+    usageOverride: 'diff snapshot',
+    description: 'Diff current accessibility snapshot against previous baseline',
+    positionalArgs: ['kind'],
+    allowedFlags: [...SNAPSHOT_FLAGS],
+  },
   devices: {
     description: 'List available devices',
     positionalArgs: [],
diff --git a/src/utils/output.ts b/src/utils/output.ts
index e7b5ac89f..8de5b1e42 100644
--- a/src/utils/output.ts
+++ b/src/utils/output.ts
@@ -1,4 +1,6 @@
 import { AppError, normalizeError, type NormalizedError } from './errors.ts';
+import { buildSnapshotDisplayLines, formatSnapshotLine } from './snapshot-lines.ts';
+import type { SnapshotNode } from './snapshot.ts';
 
 export type JsonResult =
   | { success: true; data?: Record<string, unknown> }
@@ -38,17 +40,9 @@ export function printHumanError(
   }
 }
 
-type SnapshotRect = { x: number; y: number; width: number; height: number };
-type SnapshotNode = {
-  ref?: string;
-  depth?: number;
-  type?: string;
-  label?: string;
-  value?: string;
-  identifier?: string;
-  rect?: SnapshotRect;
-  hittable?: boolean;
-  enabled?: boolean;
+type SnapshotDiffLine = {
+  kind?: 'added' | 'removed' | 'unchanged';
+  text?: string;
 };
 
 export function formatSnapshotText(
@@ -76,151 +70,30 @@ export function formatSnapshotText(
     const flatLines = nodes.map((node) => formatSnapshotLine(node, 0, false));
     return `${prefix}${header}\n${flatLines.join('\n')}\n`;
   }
-  const hiddenGroupDepths: number[] = [];
-  const lines: string[] = [];
-  for (const node of nodes) {
-    const depth = node.depth ?? 0;
-    while (hiddenGroupDepths.length > 0 && depth <= hiddenGroupDepths[hiddenGroupDepths.length - 1]) {
-      hiddenGroupDepths.pop();
-    }
-    const label = node.label?.trim() || node.value?.trim() || node.identifier?.trim() || '';
-    const type = formatRole(node.type ?? 'Element');
-    const isHiddenGroup = type === 'group' && !label;
-    if (isHiddenGroup) {
-      hiddenGroupDepths.push(depth);
-    }
-    const adjustedDepth = isHiddenGroup
-      ? depth
-      : Math.max(0, depth - hiddenGroupDepths.length);
-    lines.push(formatSnapshotLine(node, adjustedDepth, isHiddenGroup));
-  }
+  const lines = buildSnapshotDisplayLines(nodes).map((line) => line.text);
   return `${prefix}${header}\n${lines.join('\n')}\n`;
 }
 
-function formatSnapshotLine(node: SnapshotNode, depth: number, hiddenGroup: boolean): string {
-  const type = formatRole(node.type ?? 'Element');
-  const label = displayLabel(node, type);
-  const indent = '  '.repeat(depth);
-  const ref = node.ref ? `@${node.ref}` : '';
-  const flags = [node.enabled === false ? 'disabled' : null].filter(Boolean).join(', ');
-  const flagText = flags ? ` [${flags}]` : '';
-  const textPart = label ? ` "${label}"` : '';
-  if (hiddenGroup) {
-    return `${indent}${ref} [${type}]${flagText}`.trimEnd();
-  }
-  return `${indent}${ref} [${type}]${textPart}${flagText}`.trimEnd();
-}
-
-function displayLabel(node: SnapshotNode, type: string): string {
-  const label = node.label?.trim();
-  const value = node.value?.trim();
-  if (isEditableRole(type)) {
-    // For inputs, prefer current value over placeholder/accessibility label.
-    if (value) return value;
-    if (label) return label;
-  } else if (label) {
-    return label;
-  }
-  if (value) return value;
-  const identifier = node.identifier?.trim();
-  if (!identifier) return '';
-  if (isGenericResourceId(identifier) && (type === 'group' || type === 'image' || type === 'list' || type === 'collection')) {
-    return '';
+export function formatSnapshotDiffText(data: Record<string, unknown>): string {
+  const baselineInitialized = data.baselineInitialized === true;
+  const summaryRaw = (data.summary ?? {}) as Record<string, unknown>;
+  const additions = toNumber(summaryRaw.additions);
+  const removals = toNumber(summaryRaw.removals);
+  const unchanged = toNumber(summaryRaw.unchanged);
+  if (baselineInitialized) {
+    return `Baseline initialized (${unchanged} lines).\n${additions} additions, ${removals} removals, ${unchanged} unchanged\n`;
   }
-  return identifier;
+  const rawLines = Array.isArray(data.lines) ? (data.lines as SnapshotDiffLine[]) : [];
+  const lines = rawLines.map((line) => {
+    const text = typeof line.text === 'string' ? line.text : '';
+    if (line.kind === 'added') return `+${text}`;
+    if (line.kind === 'removed') return `-${text}`;
+    return text;
+  });
+  const body = lines.length > 0 ? `${lines.join('\n')}\n` : '';
+  return `${body}${additions} additions, ${removals} removals, ${unchanged} unchanged\n`;
 }
 
-function isEditableRole(type: string): boolean {
-  return type === 'text-field' || type === 'text-view' || type === 'search';
-}
-
-function isGenericResourceId(value: string): boolean {
-  return /^[\w.]+:id\/[\w.-]+$/i.test(value);
-}
-
-function formatRole(type: string): string {
-  const raw = type;
-  let normalized = type.replace(/XCUIElementType/gi, '').toLowerCase();
-  const isAndroidClass =
-    raw.includes('.') &&
-    (raw.startsWith('android.') || raw.startsWith('androidx.') || raw.startsWith('com.'));
-  if (normalized.includes('.')) {
-    normalized = normalized
-      .replace(/^android\.widget\./, '')
-      .replace(/^android\.view\./, '')
-      .replace(/^android\.webkit\./, '')
-      .replace(/^androidx\./, '')
-      .replace(/^com\.google\.android\./, '')
-      .replace(/^com\.android\./, '');
-  }
-  switch (normalized) {
-    case 'application':
-      return 'application';
-    case 'navigationbar':
-      return 'navigation-bar';
-    case 'tabbar':
-      return 'tab-bar';
-    case 'button':
-    case 'imagebutton':
-      return 'button';
-    case 'link':
-      return 'link';
-    case 'cell':
-      return 'cell';
-    case 'statictext':
-    case 'checkedtextview':
-      return 'text';
-    case 'textfield':
-    case 'edittext':
-      return 'text-field';
-    case 'textview':
-      return isAndroidClass ? 'text' : 'text-view';
-    case 'textarea':
-      return 'text-view';
-    case 'switch':
-      return 'switch';
-    case 'slider':
-      return 'slider';
-    case 'image':
-    case 'imageview':
-      return 'image';
-    case 'webview':
-      return 'webview';
-    case 'framelayout':
-    case 'linearlayout':
-    case 'relativelayout':
-    case 'constraintlayout':
-    case 'viewgroup':
-    case 'view':
-      return 'group';
-    case 'listview':
-    case 'recyclerview':
-      return 'list';
-    case 'collectionview':
-      return 'collection';
-    case 'searchfield':
-      return 'search';
-    case 'segmentedcontrol':
-      return 'segmented-control';
-    case 'group':
-      return 'group';
-    case 'window':
-      return 'window';
-    case 'checkbox':
-      return 'checkbox';
-    case 'radio':
-      return 'radio';
-    case 'menuitem':
-      return 'menu-item';
-    case 'toolbar':
-      return 'toolbar';
-    case 'scrollarea':
-    case 'scrollview':
-    case 'nestedscrollview':
-      return 'scroll-area';
-    case 'table':
-      return 'table';
-    default:
-      return normalized || 'element';
-  }
+function toNumber(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
 }
diff --git a/src/utils/snapshot-lines.ts b/src/utils/snapshot-lines.ts
new file mode 100644
index 000000000..6d0f08d55
--- /dev/null
+++ b/src/utils/snapshot-lines.ts
@@ -0,0 +1,165 @@
+import type { SnapshotNode } from './snapshot.ts';
+
+export type SnapshotDisplayLine = {
+  node: SnapshotNode;
+  depth: number;
+  type: string;
+  text: string;
+};
+
+export function buildSnapshotDisplayLines(nodes: SnapshotNode[]): SnapshotDisplayLine[] {
+  const hiddenGroupDepths: number[] = [];
+  const lines: SnapshotDisplayLine[] = [];
+  for (const node of nodes) {
+    const depth = node.depth ?? 0;
+    while (hiddenGroupDepths.length > 0 && depth <= hiddenGroupDepths[hiddenGroupDepths.length - 1]) {
+      hiddenGroupDepths.pop();
+    }
+    const label = node.label?.trim() || node.value?.trim() || node.identifier?.trim() || '';
+    const type = formatRole(node.type ?? 'Element');
+    const isHiddenGroup = type === 'group' && !label;
+    if (isHiddenGroup) {
+      hiddenGroupDepths.push(depth);
+    }
+    const adjustedDepth = isHiddenGroup ? depth : Math.max(0, depth - hiddenGroupDepths.length);
+    lines.push({
+      node,
+      depth: adjustedDepth,
+      type,
+      text: formatSnapshotLine(node, adjustedDepth, isHiddenGroup, type),
+    });
+  }
+  return lines;
+}
+
+export function formatSnapshotLine(
+  node: SnapshotNode,
+  depth: number,
+  hiddenGroup: boolean,
+  normalizedType?: string,
+): string {
+  const type = normalizedType ?? formatRole(node.type ?? 'Element');
+  const label = displayLabel(node, type);
+  const indent = '  '.repeat(depth);
+  const ref = node.ref ? `@${node.ref}` : '';
+  const flags = [node.enabled === false ? 'disabled' : null].filter(Boolean).join(', ');
+  const flagText = flags ? ` [${flags}]` : '';
+  const textPart = label ? ` "${label}"` : '';
+  if (hiddenGroup) {
+    return `${indent}${ref} [${type}]${flagText}`.trimEnd();
+  }
+  return `${indent}${ref} [${type}]${textPart}${flagText}`.trimEnd();
+}
+
+export function displayLabel(node: SnapshotNode, type: string): string {
+  const label = node.label?.trim();
+  const value = node.value?.trim();
+  if (isEditableRole(type)) {
+    if (value) return value;
+    if (label) return label;
+  } else if (label) {
+    return label;
+  }
+  if (value) return value;
+  const identifier = node.identifier?.trim();
+  if (!identifier) return '';
+  if (isGenericResourceId(identifier) && (type === 'group' || type === 'image' || type === 'list' || type === 'collection')) {
+    return '';
+  }
+  return identifier;
+}
+
+export function formatRole(type: string): string {
+  const raw = type;
+  let normalized = type.replace(/XCUIElementType/gi, '').toLowerCase();
+  const isAndroidClass =
+    raw.includes('.') &&
+    (raw.startsWith('android.') || raw.startsWith('androidx.') || raw.startsWith('com.'));
+  if (normalized.includes('.')) {
+    normalized = normalized
+      .replace(/^android\.widget\./, '')
+      .replace(/^android\.view\./, '')
+      .replace(/^android\.webkit\./, '')
+      .replace(/^androidx\./, '')
+      .replace(/^com\.google\.android\./, '')
+      .replace(/^com\.android\./, '');
+  }
+  switch (normalized) {
+    case 'application':
+      return 'application';
+    case 'navigationbar':
+      return 'navigation-bar';
+    case 'tabbar':
+      return 'tab-bar';
+    case 'button':
+    case 'imagebutton':
+      return 'button';
+    case 'link':
+      return 'link';
+    case 'cell':
+      return 'cell';
+    case 'statictext':
+    case 'checkedtextview':
+      return 'text';
+    case 'textfield':
+    case 'edittext':
+      return 'text-field';
+    case 'textview':
+      return isAndroidClass ? 'text' : 'text-view';
+    case 'textarea':
+      return 'text-view';
+    case 'switch':
+      return 'switch';
+    case 'slider':
+      return 'slider';
+    case 'image':
+    case 'imageview':
+      return 'image';
+    case 'webview':
+      return 'webview';
+    case 'framelayout':
+    case 'linearlayout':
+    case 'relativelayout':
+    case 'constraintlayout':
+    case 'viewgroup':
+    case 'view':
+      return 'group';
+    case 'listview':
+    case 'recyclerview':
+      return 'list';
+    case 'collectionview':
+      return 'collection';
+    case 'searchfield':
+      return 'search';
+    case 'segmentedcontrol':
+      return 'segmented-control';
+    case 'group':
+      return 'group';
+    case 'window':
+      return 'window';
+    case 'checkbox':
+      return 'checkbox';
+    case 'radio':
+      return 'radio';
+    case 'menuitem':
+      return 'menu-item';
+    case 'toolbar':
+      return 'toolbar';
+    case 'scrollarea':
+    case 'scrollview':
+    case 'nestedscrollview':
+      return 'scroll-area';
+    case 'table':
+      return 'table';
+    default:
+      return normalized || 'element';
+  }
+}
+
+function isEditableRole(type: string): boolean {
+  return type === 'text-field' || type === 'text-view' || type === 'search';
+}
+
+function isGenericResourceId(value: string): boolean {
+  return /^[\w.]+:id\/[\w.-]+$/i.test(value);
+}
diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md
index b5374e49c..e60754341 100644
--- a/website/docs/docs/commands.md
+++ b/website/docs/docs/commands.md
@@ -36,11 +36,13 @@ agent-device open MyApp "myapp://screen/to" --platform ios       # open deep lin
 
 ```bash
 agent-device snapshot [-i] [-c] [-d <depth>] [-s <scope>] [--raw]
+agent-device diff snapshot [-i] [-c] [-d <depth>] [-s <scope>] [--raw]
 agent-device get text @e1
 agent-device get attrs @e1
 ```
 
 - iOS snapshots use XCTest on simulators and physical devices.
+- `diff snapshot` compares the current snapshot with the previous session baseline and then updates baseline.
 
 ## Interactions
 
diff --git a/website/docs/docs/introduction.md b/website/docs/docs/introduction.md
index c3e1fb918..663580d64 100644
--- a/website/docs/docs/introduction.md
+++ b/website/docs/docs/introduction.md
@@ -20,7 +20,7 @@ If you know `agent-browser`, this is the mobile-native counterpart for iOS/Andro
 
 ## Platform support highlights
 
-- iOS core runner commands: `snapshot`, `wait`, `click`, `fill`, `get`, `is`, `find`, `press`, `longpress`, `focus`, `type`, `scroll`, `scrollintoview`, `back`, `home`, `app-switcher`, `open` (app), `close`, `screenshot`, `apps`, `appstate`.
+- iOS core runner commands: `snapshot`, `diff snapshot`, `wait`, `click`, `fill`, `get`, `is`, `find`, `press`, `long-press`, `focus`, `type`, `scroll`, `scrollintoview`, `back`, `home`, `app-switcher`, `open` (app), `close`, `screenshot`, `apps`, `appstate`.
 - iOS `appstate` is session-scoped on the selected target device.
 - iOS simulator-only: `alert`, `pinch`, `record`, `reinstall`, `settings`.
 - Android support remains unchanged.
@@ -54,6 +54,7 @@ agent-device snapshot -i
 # Click and fill
 agent-device click @e8
 agent-device snapshot -i
+agent-device diff snapshot
 agent-device fill @e5 "Doe 2"
 agent-device close
 ```
diff --git a/website/docs/docs/quick-start.md b/website/docs/docs/quick-start.md
index f8b710059..ea0dcf7ce 100644
--- a/website/docs/docs/quick-start.md
+++ b/website/docs/docs/quick-start.md
@@ -21,6 +21,9 @@ agent-device click @e2
 
 # 4. Re-snapshot before next interactions
 agent-device snapshot -i
+
+# 5. Optional: see structural changes since last baseline
+agent-device diff snapshot
 ```
 
 Boot target if there is no ready device/simulator:
@@ -34,6 +37,7 @@ agent-device boot --platform ios # or android
 ```bash
 agent-device open SampleApp
 agent-device snapshot -i                 # Get interactive elements with refs
+agent-device diff snapshot               # First run initializes baseline; next runs show structural deltas
 agent-device click @e2                   # Click by ref
 agent-device fill @e3 "test@example.com" # Clear then type (Android verifies and retries once if needed)
 agent-device get text @e1                # Get text content
diff --git a/website/docs/docs/snapshots.md b/website/docs/docs/snapshots.md
index def1b06b3..3561b25a1 100644
--- a/website/docs/docs/snapshots.md
+++ b/website/docs/docs/snapshots.md
@@ -13,6 +13,7 @@ agent-device snapshot -c                 # Compact (remove empty elements)
 agent-device snapshot -d 3               # Limit depth to 3 levels
 agent-device snapshot -s "Contacts"      # Scope to label/identifier
 agent-device snapshot -i -c -d 5         # Combine options
+agent-device diff snapshot               # Structural diff vs previous session baseline
 ```
 
 | Option       | Description               |
@@ -25,6 +26,19 @@ agent-device snapshot -i -c -d 5         # Combine options
 Note: If XCTest returns 0 nodes (foreground app changed), agent-device fails explicitly.
 It does not automatically switch to AX.
 
+## Efficient snapshot usage
+
+- Default to `snapshot -i` for agent loops.
+- Add `-s "<label>"` (or `-s @ref`) to keep results screen-local.
+- Add `-d <depth>` when you only need upper hierarchy layers.
+- Re-snapshot after any UI mutation before reusing refs.
+- Use `diff snapshot` between mutations to validate structural changes with lower output volume.
+- Keep `--raw` for troubleshooting only.
+
+`diff snapshot` behavior:
+- First run initializes baseline (`baselineInitialized: true` in JSON).
+- Later runs return unified-style lines (`+` added, `-` removed, unchanged context) and update baseline after each call.
+
 ## Example output:
 
 ```bash

From e3542e691b694e906b4f0d17a26787945b2ea373 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Fri, 20 Feb 2026 14:37:43 +0100
Subject: [PATCH 2/6] chore: polish snapshot diff baseline output

---
 src/daemon/snapshot-diff.ts        | 1 +
 src/utils/__tests__/output.test.ts | 2 +-
 src/utils/output.ts                | 2 +-
 3 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/daemon/snapshot-diff.ts b/src/daemon/snapshot-diff.ts
index 659df88f8..f67b57608 100644
--- a/src/daemon/snapshot-diff.ts
+++ b/src/daemon/snapshot-diff.ts
@@ -57,6 +57,7 @@ function snapshotNodesToLines(nodes: SnapshotNode[]): SnapshotComparableLine[] {
 }
 
 function diffComparableLinesMyers(previous: SnapshotComparableLine[], current: SnapshotComparableLine[]): SnapshotDiffLine[] {
+  // Myers diff is efficient for normal UI snapshots; very large trees may still be expensive.
   const n = previous.length;
   const m = current.length;
   const max = n + m;
diff --git a/src/utils/__tests__/output.test.ts b/src/utils/__tests__/output.test.ts
index cad389834..9000ee7f8 100644
--- a/src/utils/__tests__/output.test.ts
+++ b/src/utils/__tests__/output.test.ts
@@ -30,5 +30,5 @@ test('formatSnapshotDiffText renders baseline initialization text', () => {
   });
 
   assert.match(text, /Baseline initialized \(5 lines\)\./);
-  assert.match(text, /0 additions, 0 removals, 5 unchanged/);
+  assert.doesNotMatch(text, /additions|removals|unchanged/);
 });
diff --git a/src/utils/output.ts b/src/utils/output.ts
index 8de5b1e42..ebce7b14d 100644
--- a/src/utils/output.ts
+++ b/src/utils/output.ts
@@ -81,7 +81,7 @@ export function formatSnapshotDiffText(data: Record<string, unknown>): string {
   const removals = toNumber(summaryRaw.removals);
   const unchanged = toNumber(summaryRaw.unchanged);
   if (baselineInitialized) {
-    return `Baseline initialized (${unchanged} lines).\n${additions} additions, ${removals} removals, ${unchanged} unchanged\n`;
+    return `Baseline initialized (${unchanged} lines).\n`;
   }
   const rawLines = Array.isArray(data.lines) ? (data.lines as SnapshotDiffLine[]) : [];
   const lines = rawLines.map((line) => {

From b7406f0710c3b8631dc92bfcdacd107caa3dcaf6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Fri, 20 Feb 2026 18:18:40 +0100
Subject: [PATCH 3/6] fix: trim diff output context and normalize +/-
 indentation

---
 src/__tests__/cli-diff.test.ts     |  4 ++--
 src/utils/__tests__/output.test.ts | 13 +++++++++----
 src/utils/output.ts                | 26 +++++++++++++++++++++++---
 3 files changed, 34 insertions(+), 9 deletions(-)

diff --git a/src/__tests__/cli-diff.test.ts b/src/__tests__/cli-diff.test.ts
index ea3d62720..c1316480c 100644
--- a/src/__tests__/cli-diff.test.ts
+++ b/src/__tests__/cli-diff.test.ts
@@ -77,8 +77,8 @@ test('diff snapshot renders human-readable unified diff text', async () => {
   assert.equal(result.code, null);
   assert.equal(result.calls.length, 1);
   assert.match(result.stdout, /^@e2 \[window\]/m);
-  assert.match(result.stdout, /^-  @e3 \[text\] "67"$/m);
-  assert.match(result.stdout, /^\+  @e3 \[text\] "134"$/m);
+  assert.match(result.stdout, /^- @e3 \[text\] "67"$/m);
+  assert.match(result.stdout, /^\+ @e3 \[text\] "134"$/m);
   assert.match(result.stdout, /1 additions, 1 removals, 1 unchanged/);
   assert.equal(result.stderr, '');
 });
diff --git a/src/utils/__tests__/output.test.ts b/src/utils/__tests__/output.test.ts
index 9000ee7f8..ac3004970 100644
--- a/src/utils/__tests__/output.test.ts
+++ b/src/utils/__tests__/output.test.ts
@@ -5,21 +5,26 @@ import { formatSnapshotDiffText } from '../output.ts';
 test('formatSnapshotDiffText renders unified diff lines with summary', () => {
   const text = formatSnapshotDiffText({
     baselineInitialized: false,
-    summary: { additions: 2, removals: 2, unchanged: 2 },
+    summary: { additions: 2, removals: 2, unchanged: 4 },
     lines: [
+      { kind: 'unchanged', text: '@e0 [application]' },
       { kind: 'unchanged', text: '@e2 [window]' },
       { kind: 'removed', text: '  @e3 [other] "67"' },
       { kind: 'removed', text: '  @e4 [text] "67"' },
       { kind: 'added', text: '  @e3 [other] "134"' },
       { kind: 'added', text: '  @e4 [text] "134"' },
       { kind: 'unchanged', text: '  @e5 [button] "Increment"' },
+      { kind: 'unchanged', text: '  @e6 [text] "Footer"' },
     ],
   });
 
+  assert.doesNotMatch(text, /^@e0 \[application\]$/m);
   assert.match(text, /^@e2 \[window\]/m);
-  assert.match(text, /^-  @e3 \[other\] "67"$/m);
-  assert.match(text, /^\+  @e3 \[other\] "134"$/m);
-  assert.match(text, /2 additions, 2 removals, 2 unchanged/);
+  assert.match(text, /^- @e3 \[other\] "67"$/m);
+  assert.match(text, /^\+ @e3 \[other\] "134"$/m);
+  assert.match(text, /^  @e5 \[button\] "Increment"$/m);
+  assert.doesNotMatch(text, /^  @e6 \[text\] "Footer"$/m);
+  assert.match(text, /2 additions, 2 removals, 4 unchanged/);
 });
 
 test('formatSnapshotDiffText renders baseline initialization text', () => {
diff --git a/src/utils/output.ts b/src/utils/output.ts
index ebce7b14d..0aa851f23 100644
--- a/src/utils/output.ts
+++ b/src/utils/output.ts
@@ -84,10 +84,11 @@ export function formatSnapshotDiffText(data: Record<string, unknown>): string {
     return `Baseline initialized (${unchanged} lines).\n`;
   }
   const rawLines = Array.isArray(data.lines) ? (data.lines as SnapshotDiffLine[]) : [];
-  const lines = rawLines.map((line) => {
+  const contextLines = applyContextWindow(rawLines, 1);
+  const lines = contextLines.map((line) => {
     const text = typeof line.text === 'string' ? line.text : '';
-    if (line.kind === 'added') return `+${text}`;
-    if (line.kind === 'removed') return `-${text}`;
+    if (line.kind === 'added') return `+ ${text.trimStart()}`;
+    if (line.kind === 'removed') return `- ${text.trimStart()}`;
     return text;
   });
   const body = lines.length > 0 ? `${lines.join('\n')}\n` : '';
@@ -97,3 +98,22 @@ export function formatSnapshotDiffText(data: Record<string, unknown>): string {
 function toNumber(value: unknown): number {
   return typeof value === 'number' && Number.isFinite(value) ? value : 0;
 }
+
+function applyContextWindow(lines: SnapshotDiffLine[], contextWindow: number): SnapshotDiffLine[] {
+  if (lines.length === 0) return lines;
+  const changedIndices = lines
+    .map((line, index) => ({ index, kind: line.kind }))
+    .filter((entry) => entry.kind === 'added' || entry.kind === 'removed')
+    .map((entry) => entry.index);
+  if (changedIndices.length === 0) return lines;
+
+  const keep = new Array<boolean>(lines.length).fill(false);
+  for (const index of changedIndices) {
+    const start = Math.max(0, index - contextWindow);
+    const end = Math.min(lines.length - 1, index + contextWindow);
+    for (let i = start; i <= end; i += 1) {
+      keep[i] = true;
+    }
+  }
+  return lines.filter((_, index) => keep[index]);
+}

From 725f46055e604059cceb14d5adcd82333e5bfd0b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Fri, 20 Feb 2026 18:21:05 +0100
Subject: [PATCH 4/6] fix: normalize unchanged context indentation in diff
 output

---
 src/__tests__/cli-diff.test.ts     | 2 +-
 src/utils/__tests__/output.test.ts | 2 +-
 src/utils/output.ts                | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/__tests__/cli-diff.test.ts b/src/__tests__/cli-diff.test.ts
index c1316480c..99a78f58e 100644
--- a/src/__tests__/cli-diff.test.ts
+++ b/src/__tests__/cli-diff.test.ts
@@ -76,7 +76,7 @@ test('diff snapshot renders human-readable unified diff text', async () => {
   const result = await runCliCapture(['diff', 'snapshot']);
   assert.equal(result.code, null);
   assert.equal(result.calls.length, 1);
-  assert.match(result.stdout, /^@e2 \[window\]/m);
+  assert.match(result.stdout, /^  @e2 \[window\]/m);
   assert.match(result.stdout, /^- @e3 \[text\] "67"$/m);
   assert.match(result.stdout, /^\+ @e3 \[text\] "134"$/m);
   assert.match(result.stdout, /1 additions, 1 removals, 1 unchanged/);
diff --git a/src/utils/__tests__/output.test.ts b/src/utils/__tests__/output.test.ts
index ac3004970..461c6ba44 100644
--- a/src/utils/__tests__/output.test.ts
+++ b/src/utils/__tests__/output.test.ts
@@ -19,7 +19,7 @@ test('formatSnapshotDiffText renders unified diff lines with summary', () => {
   });
 
   assert.doesNotMatch(text, /^@e0 \[application\]$/m);
-  assert.match(text, /^@e2 \[window\]/m);
+  assert.match(text, /^  @e2 \[window\]/m);
   assert.match(text, /^- @e3 \[other\] "67"$/m);
   assert.match(text, /^\+ @e3 \[other\] "134"$/m);
   assert.match(text, /^  @e5 \[button\] "Increment"$/m);
diff --git a/src/utils/output.ts b/src/utils/output.ts
index 0aa851f23..abdd7f2d7 100644
--- a/src/utils/output.ts
+++ b/src/utils/output.ts
@@ -89,7 +89,7 @@ export function formatSnapshotDiffText(data: Record<string, unknown>): string {
     const text = typeof line.text === 'string' ? line.text : '';
     if (line.kind === 'added') return `+ ${text.trimStart()}`;
     if (line.kind === 'removed') return `- ${text.trimStart()}`;
-    return text;
+    return `  ${text.trimStart()}`;
   });
   const body = lines.length > 0 ? `${lines.join('\n')}\n` : '';
   return `${body}${additions} additions, ${removals} removals, ${unchanged} unchanged\n`;

From bb9fd126154354703fcccaf0bc06091caddffeb7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Fri, 20 Feb 2026 18:26:03 +0100
Subject: [PATCH 5/6] fix: preserve snapshot indentation in diff formatter

---
 src/__tests__/cli-diff.test.ts     | 6 +++---
 src/utils/__tests__/output.test.ts | 6 +++---
 src/utils/output.ts                | 6 +++---
 3 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/src/__tests__/cli-diff.test.ts b/src/__tests__/cli-diff.test.ts
index 99a78f58e..ea3d62720 100644
--- a/src/__tests__/cli-diff.test.ts
+++ b/src/__tests__/cli-diff.test.ts
@@ -76,9 +76,9 @@ test('diff snapshot renders human-readable unified diff text', async () => {
   const result = await runCliCapture(['diff', 'snapshot']);
   assert.equal(result.code, null);
   assert.equal(result.calls.length, 1);
-  assert.match(result.stdout, /^  @e2 \[window\]/m);
-  assert.match(result.stdout, /^- @e3 \[text\] "67"$/m);
-  assert.match(result.stdout, /^\+ @e3 \[text\] "134"$/m);
+  assert.match(result.stdout, /^@e2 \[window\]/m);
+  assert.match(result.stdout, /^-  @e3 \[text\] "67"$/m);
+  assert.match(result.stdout, /^\+  @e3 \[text\] "134"$/m);
   assert.match(result.stdout, /1 additions, 1 removals, 1 unchanged/);
   assert.equal(result.stderr, '');
 });
diff --git a/src/utils/__tests__/output.test.ts b/src/utils/__tests__/output.test.ts
index 461c6ba44..1380c4c71 100644
--- a/src/utils/__tests__/output.test.ts
+++ b/src/utils/__tests__/output.test.ts
@@ -19,9 +19,9 @@ test('formatSnapshotDiffText renders unified diff lines with summary', () => {
   });
 
   assert.doesNotMatch(text, /^@e0 \[application\]$/m);
-  assert.match(text, /^  @e2 \[window\]/m);
-  assert.match(text, /^- @e3 \[other\] "67"$/m);
-  assert.match(text, /^\+ @e3 \[other\] "134"$/m);
+  assert.match(text, /^@e2 \[window\]/m);
+  assert.match(text, /^-  @e3 \[other\] "67"$/m);
+  assert.match(text, /^\+  @e3 \[other\] "134"$/m);
   assert.match(text, /^  @e5 \[button\] "Increment"$/m);
   assert.doesNotMatch(text, /^  @e6 \[text\] "Footer"$/m);
   assert.match(text, /2 additions, 2 removals, 4 unchanged/);
diff --git a/src/utils/output.ts b/src/utils/output.ts
index abdd7f2d7..2b84bcca1 100644
--- a/src/utils/output.ts
+++ b/src/utils/output.ts
@@ -87,9 +87,9 @@ export function formatSnapshotDiffText(data: Record<string, unknown>): string {
   const contextLines = applyContextWindow(rawLines, 1);
   const lines = contextLines.map((line) => {
     const text = typeof line.text === 'string' ? line.text : '';
-    if (line.kind === 'added') return `+ ${text.trimStart()}`;
-    if (line.kind === 'removed') return `- ${text.trimStart()}`;
-    return `  ${text.trimStart()}`;
+    if (line.kind === 'added') return text.startsWith(' ') ? `+${text}` : `+ ${text}`;
+    if (line.kind === 'removed') return text.startsWith(' ') ? `-${text}` : `- ${text}`;
+    return text;
   });
   const body = lines.length > 0 ? `${lines.join('\n')}\n` : '';
   return `${body}${additions} additions, ${removals} removals, ${unchanged} unchanged\n`;

From 4e6c73d0708b6b3c6cadd87d6b4f38fbe5259167 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= <thymikee@gmail.com>
Date: Fri, 20 Feb 2026 18:32:45 +0100
Subject: [PATCH 6/6] fix: honor diff snapshot -i flatten mode

---
 src/daemon/__tests__/snapshot-diff.test.ts | 22 +++++++++++++++
 src/daemon/handlers/snapshot.ts            |  5 ++--
 src/daemon/snapshot-diff.ts                | 31 +++++++++++++++++-----
 3 files changed, 49 insertions(+), 9 deletions(-)

diff --git a/src/daemon/__tests__/snapshot-diff.test.ts b/src/daemon/__tests__/snapshot-diff.test.ts
index 234a8e26c..70ee832f6 100644
--- a/src/daemon/__tests__/snapshot-diff.test.ts
+++ b/src/daemon/__tests__/snapshot-diff.test.ts
@@ -75,3 +75,25 @@ test('buildSnapshotDiff preserves surrounding context ordering', () => {
   assert.equal(diff.lines[3]?.kind, 'added');
   assert.equal(diff.lines[4]?.kind, 'unchanged');
 });
+
+test('buildSnapshotDiff flatten option uses flat snapshot line shape', () => {
+  const previous = nodes([
+    { index: 0, depth: 0, type: 'XCUIElementTypeWindow' },
+    { index: 1, depth: 1, type: 'XCUIElementTypeOther', label: '335' },
+    { index: 2, depth: 2, type: 'XCUIElementTypeStaticText', label: '335' },
+  ]);
+  const current = nodes([
+    { index: 0, depth: 0, type: 'XCUIElementTypeWindow' },
+    { index: 1, depth: 1, type: 'XCUIElementTypeOther', label: '402' },
+    { index: 2, depth: 2, type: 'XCUIElementTypeStaticText', label: '402' },
+  ]);
+
+  const diff = buildSnapshotDiff(previous, current, { flatten: true });
+  assert.equal(diff.summary.additions, 2);
+  assert.equal(diff.summary.removals, 2);
+  const changed = diff.lines.filter((line) => line.kind !== 'unchanged');
+  assert.equal(changed.length, 4);
+  for (const line of changed) {
+    assert.equal(line.text.startsWith('  '), false);
+  }
+});
diff --git a/src/daemon/handlers/snapshot.ts b/src/daemon/handlers/snapshot.ts
index bbb026efb..96891776b 100644
--- a/src/daemon/handlers/snapshot.ts
+++ b/src/daemon/handlers/snapshot.ts
@@ -104,6 +104,7 @@ export async function handleSnapshotCommands(params: {
     }
     const resolvedScope = resolveSnapshotScope(req.flags?.snapshotScope, session);
     if (!resolvedScope.ok) return resolvedScope.response;
+    const flattenForDiff = req.flags?.snapshotInteractiveOnly === true;
 
     return await withSessionlessRunnerCleanup(session, device, async () => {
       const appBundleId = session?.appBundleId;
@@ -118,7 +119,7 @@ export async function handleSnapshotCommands(params: {
       const currentSnapshot = capture.snapshot;
 
       if (!session?.snapshot) {
-        const unchanged = countSnapshotComparableLines(currentSnapshot.nodes);
+        const unchanged = countSnapshotComparableLines(currentSnapshot.nodes, { flatten: flattenForDiff });
         const nextSession: SessionState = session
           ? { ...session, snapshot: currentSnapshot }
           : {
@@ -154,7 +155,7 @@ export async function handleSnapshotCommands(params: {
         };
       }
 
-      const diff = buildSnapshotDiff(session.snapshot.nodes, currentSnapshot.nodes);
+      const diff = buildSnapshotDiff(session.snapshot.nodes, currentSnapshot.nodes, { flatten: flattenForDiff });
       const nextSession: SessionState = { ...session, snapshot: currentSnapshot };
       recordIfSession(sessionStore, nextSession, req, {
         mode: 'snapshot',
diff --git a/src/daemon/snapshot-diff.ts b/src/daemon/snapshot-diff.ts
index f67b57608..ba0eb42c4 100644
--- a/src/daemon/snapshot-diff.ts
+++ b/src/daemon/snapshot-diff.ts
@@ -1,5 +1,5 @@
 import type { SnapshotNode } from '../utils/snapshot.ts';
-import { buildSnapshotDisplayLines, displayLabel, formatRole } from '../utils/snapshot-lines.ts';
+import { buildSnapshotDisplayLines, displayLabel, formatRole, formatSnapshotLine } from '../utils/snapshot-lines.ts';
 
 export type SnapshotDiffLine = {
   kind: 'added' | 'removed' | 'unchanged';
@@ -17,6 +17,10 @@ export type SnapshotDiffResult = {
   lines: SnapshotDiffLine[];
 };
 
+export type SnapshotDiffOptions = {
+  flatten?: boolean;
+};
+
 type SnapshotComparableLine = {
   text: string;
   comparable: string;
@@ -32,9 +36,13 @@ export function snapshotNodeToComparableLine(node: SnapshotNode, depthOverride?:
   return [depthPart, role, textPart, enabledPart, selectedPart, hittablePart].join('|');
 }
 
-export function buildSnapshotDiff(previousNodes: SnapshotNode[], currentNodes: SnapshotNode[]): SnapshotDiffResult {
-  const previous = snapshotNodesToLines(previousNodes);
-  const current = snapshotNodesToLines(currentNodes);
+export function buildSnapshotDiff(
+  previousNodes: SnapshotNode[],
+  currentNodes: SnapshotNode[],
+  options: SnapshotDiffOptions = {},
+): SnapshotDiffResult {
+  const previous = snapshotNodesToLines(previousNodes, options);
+  const current = snapshotNodesToLines(currentNodes, options);
   const lines = diffComparableLinesMyers(previous, current);
   const summary: SnapshotDiffSummary = { additions: 0, removals: 0, unchanged: 0 };
   for (const line of lines) {
@@ -45,11 +53,20 @@ export function buildSnapshotDiff(previousNodes: SnapshotNode[], currentNodes: S
   return { summary, lines };
 }
 
-export function countSnapshotComparableLines(nodes: SnapshotNode[]): number {
-  return snapshotNodesToLines(nodes).length;
+export function countSnapshotComparableLines(
+  nodes: SnapshotNode[],
+  options: SnapshotDiffOptions = {},
+): number {
+  return snapshotNodesToLines(nodes, options).length;
 }
 
-function snapshotNodesToLines(nodes: SnapshotNode[]): SnapshotComparableLine[] {
+function snapshotNodesToLines(nodes: SnapshotNode[], options: SnapshotDiffOptions): SnapshotComparableLine[] {
+  if (options.flatten) {
+    return nodes.map((node) => ({
+      text: formatSnapshotLine(node, 0, false),
+      comparable: snapshotNodeToComparableLine(node, 0),
+    }));
+  }
   return buildSnapshotDisplayLines(nodes).map((line) => ({
     text: line.text,
     comparable: snapshotNodeToComparableLine(line.node, line.depth),