fix: default showDiffSinceLastCall to false when search is provided

Instead of hard-blocking diff when search is present, change the
default: showDiffSinceLastCall defaults to !search. This way agents
don't get implicit diffs that swallow their search results, but can
still explicitly pass showDiffSinceLastCall: true to combine both.

Applied to snapshot(), getPageMarkdown(), and getCleanHTML().
Updated skill.md docs to document the new default behavior.

playwriter/src/clean-html.ts

@@ -36,7 +36,7 @@ export async function getCleanHTML(options: GetCleanHTMLOptions): Promise<string
   const {
     locator,
     search,
-    showDiffSinceLastCall = true,
+    showDiffSinceLastCall = !search,
     includeStyles = false,
     maxAttrLen = 200,
     maxContentLen = 500,
@@ -76,8 +76,8 @@ export async function getCleanHTML(options: GetCleanHTMLOptions): Promise<string
   const previousSnapshot = pageSnapshots.get(snapshotKey)
   pageSnapshots.set(snapshotKey, htmlStr)
 
-  // Never diff when agent is searching — search should always filter the full content
-  if (showDiffSinceLastCall && previousSnapshot && !search) {
+  // Diff defaults off when search is provided, but agent can explicitly enable both
+  if (showDiffSinceLastCall && previousSnapshot) {
     const diffResult = createSmartDiff({
       oldContent: previousSnapshot,
       newContent: htmlStr,

playwriter/src/executor.ts

@@ -736,7 +736,7 @@ export class PlaywrightExecutor {
           frame,
           locator,
           search,
-          showDiffSinceLastCall = true,
+          showDiffSinceLastCall = !search,
           interactiveOnly = false,
         } = options
         const resolvedPage = targetPage || page
@@ -772,8 +772,8 @@ export class PlaywrightExecutor {
           this.lastSnapshots.set(resolvedPage, snapshotStr)
         }
 
-        // Never diff when agent is searching — search should always filter the full snapshot
-        if (showDiffSinceLastCall && previousSnapshot && shouldCacheSnapshot && !search) {
+        // Diff defaults off when search is provided, but agent can explicitly enable both
+        if (showDiffSinceLastCall && previousSnapshot && shouldCacheSnapshot) {
           const diffResult = createSmartDiff({
             oldContent: previousSnapshot,
             newContent: snapshotStr,

playwriter/src/page-markdown.ts

@@ -70,7 +70,7 @@ function isRegExp(value: unknown): value is RegExp {
  * the main content. Returns plain text content (no HTML).
  */
 export async function getPageMarkdown(options: GetPageMarkdownOptions): Promise<string> {
-  const { page, search, showDiffSinceLastCall = true } = options
+  const { page, search, showDiffSinceLastCall = !search } = options
 
   // Check if readability is already injected
   const hasReadability = await page.evaluate(() => !!(globalThis as any).__readability)
@@ -172,8 +172,8 @@ export async function getPageMarkdown(options: GetPageMarkdownOptions): Promise<
   const previousSnapshot = lastMarkdownSnapshots.get(page)
   lastMarkdownSnapshots.set(page, markdown)
 
-  // Never diff when agent is searching — search should always filter the full content
-  if (showDiffSinceLastCall && previousSnapshot && !search) {
+  // Diff defaults off when search is provided, but agent can explicitly enable both
+  if (showDiffSinceLastCall && previousSnapshot) {
     const diffResult = createSmartDiff({
       oldContent: previousSnapshot,
       newContent: markdown,

playwriter/src/skill.md

@@ -453,9 +453,9 @@ await snapshot({ page: state.page, search?, showDiffSinceLastCall? })
 `accessibilitySnapshot` is still available as an alias for backward compatibility.
 
 - `search` - string/regex to filter results (returns first 10 matching lines)
-- `showDiffSinceLastCall` - returns diff since last snapshot (default: `true`). Pass `false` to get full snapshot.
+- `showDiffSinceLastCall` - returns diff since last snapshot (default: `true`, but `false` when `search` is provided). Pass `false` to get full snapshot.
 
-Snapshots return full content on first call, then diffs on subsequent calls. Diff is only returned when shorter than full content. If nothing changed, returns "No changes since last snapshot" message. Use `showDiffSinceLastCall: false` to always get full content. This diffing behavior also applies to `getCleanHTML` and `getPageMarkdown`.
+Snapshots return full content on first call, then diffs on subsequent calls. Diff is only returned when shorter than full content. If nothing changed, returns "No changes since last snapshot" message. Use `showDiffSinceLastCall: false` to always get full content. When `search` is provided, diffing is disabled by default so the search filters the full content — pass `showDiffSinceLastCall: true` explicitly to combine both. This diffing behavior also applies to `getCleanHTML` and `getPageMarkdown`.
 
 Example output:
 
@@ -764,7 +764,7 @@ const fullHtml = await getCleanHTML({ locator: state.page, showDiffSinceLastCall
 
 - `locator` - Playwright Locator or Page to get HTML from
 - `search` - string/regex to filter results (returns first 10 matching lines with 5 lines context)
-- `showDiffSinceLastCall` - returns diff since last call (default: `true`). Pass `false` to get full HTML.
+- `showDiffSinceLastCall` - returns diff since last call (default: `true`, but `false` when `search` is provided). Pass `false` to get full HTML.
 - `includeStyles` - keep style and class attributes (default: false)
 
 **HTML processing:**
@@ -806,7 +806,7 @@ The main article content as plain text, with paragraphs preserved...
 
 - `page` - Playwright Page to extract content from
 - `search` - string/regex to filter content (returns first 10 matching lines with 5 lines context)
-- `showDiffSinceLastCall` - returns diff since last call (default: `true`). Pass `false` to get full content.
+- `showDiffSinceLastCall` - returns diff since last call (default: `true`, but `false` when `search` is provided). Pass `false` to get full content.
 
 **Use cases:**