From ee676f6106a807f12e753eb49126b53a485ef2d8 Mon Sep 17 00:00:00 2001
From: Avi Fenesh <aviarchi1994@gmail.com>
Date: Wed, 25 Feb 2026 00:59:32 +0200
Subject: [PATCH 1/3] fix: include complementary ARIA landmarks in auto-scoped
 snapshots (#26)

detectMainContent now captures adjacent aside and [role="complementary"]
siblings when a main landmark is found, returning a virtual locator that
concatenates all region snapshots. This surfaces sidebar content like
repository stats without requiring manual scoping. Complementary regions
are capped at 3 and failures are silently skipped.
---
 CHANGELOG.md                  |   1 +
 scripts/web-ctl.js            |  35 +++-
 skills/web-browse/SKILL.md    |   2 +-
 tests/get-snapshot.test.js    | 357 +++++++++++++++++++++++++++++++++-
 tests/web-ctl-actions.test.js |   4 +
 5 files changed, 391 insertions(+), 8 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 02ac84d..b72732c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,6 +27,7 @@
 - `--max-field-length <N>` flag for `extract` macro to configure maximum characters per extracted field (default: 500, max: 2000)
 
 ### Fixed
+- Smart default snapshot scoping now includes complementary ARIA landmarks (`<aside>`, `[role="complementary"]`) alongside `<main>`, capturing sidebar content like repository stats (#26)
 - `extract` auto-detect `buildSelector` no longer produces double ` > > ` combinators in CSS selectors (#52)
 - `extract` auto-detect `buildSelector` skips auto-generated IDs (numeric, hex strings, framework prefixes like `ext-`, `ember`, `ng-`, patterns with `:` or `.`) and anchors on stable human-readable IDs instead, making detected selectors reusable across page reloads (#52)
 - Auth success detection no longer triggers false positives when the login page URL matches the successUrl pattern (e.g. Instagram, Reddit, Facebook whose login pages are sub-paths of the site root) (#40)
diff --git a/scripts/web-ctl.js b/scripts/web-ctl.js
index 3dfb912..a60d366 100755
--- a/scripts/web-ctl.js
+++ b/scripts/web-ctl.js
@@ -90,17 +90,46 @@ function resolveSelector(page, selector) {
 /**
  * Detect the main content area of the page.
  * Tries <main>, then [role="main"], then falls back to <body>.
+ * When a main landmark is found, also captures adjacent complementary
+ * landmarks (aside, [role="complementary"]) and returns a virtual locator
+ * whose ariaSnapshot() concatenates all regions.
  *
  * @param {object} page - Playwright page object
- * @returns {object} Playwright locator for the main content area
+ * @returns {object} Playwright locator (or virtual locator) for the main content area
  */
 async function detectMainContent(page) {
   try {
     const mainTag = page.locator('main').first();
     const mainRole = page.locator('[role="main"]').first();
     const [mainCount, roleCount] = await Promise.all([mainTag.count(), mainRole.count()]);
-    if (mainCount > 0) return mainTag;
-    if (roleCount > 0) return mainRole;
+
+    let mainLocator = null;
+    let compSelector = null;
+    if (mainCount > 0) {
+      mainLocator = mainTag;
+      compSelector = 'main ~ aside, main ~ [role="complementary"]';
+    } else if (roleCount > 0) {
+      mainLocator = mainRole;
+      compSelector = '[role="main"] ~ aside, [role="main"] ~ [role="complementary"]';
+    }
+
+    if (mainLocator) {
+      const compLocator = page.locator(compSelector);
+      const compCount = await compLocator.count();
+      if (compCount > 0) {
+        const cap = Math.min(compCount, 3);
+        return {
+          ariaSnapshot: async () => {
+            const parts = [await mainLocator.ariaSnapshot()];
+            for (let i = 0; i < cap; i++) {
+              try { parts.push(await compLocator.nth(i).ariaSnapshot()); } catch { /* skip */ }
+            }
+            return parts.join('\n');
+          }
+        };
+      }
+      return mainLocator;
+    }
   } catch {
     // fall through to body
   }
diff --git a/skills/web-browse/SKILL.md b/skills/web-browse/SKILL.md
index 4890faa..215e7c8 100644
--- a/skills/web-browse/SKILL.md
+++ b/skills/web-browse/SKILL.md
@@ -357,7 +357,7 @@ Auto-detect mode also returns the detected CSS selector, which can be reused wit
 
 All actions that return a snapshot support these flags to control output size.
 
-By default, snapshots are auto-scoped to the main content area of the page. The tool looks for a `<main>` element, then `[role="main"]`, and falls back to `<body>` if neither exists. This automatically excludes navigation, headers, and footers from snapshots, reducing noise and token usage. Use `--snapshot-full` to capture the full page body when needed, or `--snapshot-selector` to scope to a specific element.
+By default, snapshots are auto-scoped to the main content area of the page. The tool looks for a `<main>` element, then `[role="main"]`, and falls back to `<body>` if neither exists. When a main landmark is found, adjacent complementary landmarks (`<aside>`, `[role="complementary"]`) are also included - this captures sidebar content like repository stats without requiring manual scoping. This automatically excludes navigation, headers, and footers from snapshots, reducing noise and token usage. Use `--snapshot-full` to capture the full page body when needed, or `--snapshot-selector` to scope to a specific element.
 
 ### --snapshot-depth N - Limit Tree Depth
 
diff --git a/tests/get-snapshot.test.js b/tests/get-snapshot.test.js
index 1f44619..57a25de 100644
--- a/tests/get-snapshot.test.js
+++ b/tests/get-snapshot.test.js
@@ -29,8 +29,34 @@ async function detectMainContent(page) {
     const mainTag = page.locator('main').first();
     const mainRole = page.locator('[role="main"]').first();
     const [mainCount, roleCount] = await Promise.all([mainTag.count(), mainRole.count()]);
-    if (mainCount > 0) return mainTag;
-    if (roleCount > 0) return mainRole;
+
+    let mainLocator = null;
+    let compSelector = null;
+    if (mainCount > 0) {
+      mainLocator = mainTag;
+      compSelector = 'main ~ aside, main ~ [role="complementary"]';
+    } else if (roleCount > 0) {
+      mainLocator = mainRole;
+      compSelector = '[role="main"] ~ aside, [role="main"] ~ [role="complementary"]';
+    }
+
+    if (mainLocator) {
+      const compLocator = page.locator(compSelector);
+      const compCount = await compLocator.count();
+      if (compCount > 0) {
+        const cap = Math.min(compCount, 3);
+        return {
+          ariaSnapshot: async () => {
+            const parts = [await mainLocator.ariaSnapshot()];
+            for (let i = 0; i < cap; i++) {
+              try { parts.push(await compLocator.nth(i).ariaSnapshot()); } catch { /* skip */ }
+            }
+            return parts.join('\n');
+          }
+        };
+      }
+      return mainLocator;
+    }
   } catch {
     // fall through to body
   }
@@ -1351,7 +1377,7 @@ describe('getSnapshot pipeline', () => {
 // ============ detectMainContent tests ============
 
 describe('detectMainContent', () => {
-  it('returns main locator when <main> element exists', async () => {
+  it('returns main locator when <main> element exists and no complementary siblings', async () => {
     const mainLocator = { ariaSnapshot: async () => 'main content' };
     const mockPage = {
       locator(selector) {
@@ -1372,6 +1398,9 @@ describe('detectMainContent', () => {
             }
           };
         }
+        if (selector.includes('~ aside') || selector.includes('complementary')) {
+          return { count: async () => 0 };
+        }
         return { ariaSnapshot: async () => 'body content' };
       }
     };
@@ -1380,7 +1409,7 @@ describe('detectMainContent', () => {
     assert.equal(snapshot, 'main content');
   });
 
-  it('returns role=main locator when no <main> but role exists', async () => {
+  it('returns role=main locator when no <main> but role exists and no complementary siblings', async () => {
     const roleLocator = { ariaSnapshot: async () => 'role content' };
     const mockPage = {
       locator(selector) {
@@ -1401,6 +1430,9 @@ describe('detectMainContent', () => {
             }
           };
         }
+        if (selector.includes('~ aside') || selector.includes('complementary')) {
+          return { count: async () => 0 };
+        }
         return { ariaSnapshot: async () => 'body content' };
       }
     };
@@ -1453,6 +1485,9 @@ describe('detectMainContent', () => {
             }
           };
         }
+        if (selector.includes('~ aside') || selector.includes('complementary')) {
+          return { count: async () => 0 };
+        }
         return { ariaSnapshot: async () => 'body content' };
       }
     };
@@ -1481,6 +1516,197 @@ describe('detectMainContent', () => {
     const snapshot = await result.ariaSnapshot();
     assert.equal(snapshot, 'body fallback');
   });
+
+  it('includes aside sibling content when main exists', async () => {
+    const mockPage = {
+      locator(selector) {
+        if (selector === 'main') {
+          return {
+            first() {
+              return {
+                count: async () => 1,
+                ariaSnapshot: async () => '- heading "Repo Code"'
+              };
+            }
+          };
+        }
+        if (selector === '[role="main"]') {
+          return { first() { return { count: async () => 0 }; } };
+        }
+        if (selector.includes('~ aside') || selector.includes('complementary')) {
+          return {
+            count: async () => 1,
+            nth(i) {
+              return { ariaSnapshot: async () => '- text "Stars: 42"' };
+            }
+          };
+        }
+        return { ariaSnapshot: async () => 'body' };
+      }
+    };
+    const result = await detectMainContent(mockPage);
+    const snapshot = await result.ariaSnapshot();
+    assert.ok(snapshot.includes('- heading "Repo Code"'), 'should include main content');
+    assert.ok(snapshot.includes('- text "Stars: 42"'), 'should include aside content');
+  });
+
+  it('includes role=complementary sibling content', async () => {
+    const mockPage = {
+      locator(selector) {
+        if (selector === 'main') {
+          return { first() { return { count: async () => 0 }; } };
+        }
+        if (selector === '[role="main"]') {
+          return {
+            first() {
+              return {
+                count: async () => 1,
+                ariaSnapshot: async () => '- heading "Main Area"'
+              };
+            }
+          };
+        }
+        if (selector.includes('~ aside') || selector.includes('complementary')) {
+          return {
+            count: async () => 1,
+            nth(i) {
+              return { ariaSnapshot: async () => '- text "Sidebar Info"' };
+            }
+          };
+        }
+        return { ariaSnapshot: async () => 'body' };
+      }
+    };
+    const result = await detectMainContent(mockPage);
+    const snapshot = await result.ariaSnapshot();
+    assert.ok(snapshot.includes('- heading "Main Area"'), 'should include role=main content');
+    assert.ok(snapshot.includes('- text "Sidebar Info"'), 'should include complementary content');
+  });
+
+  it('returns only main when no complementary siblings', async () => {
+    const mockPage = {
+      locator(selector) {
+        if (selector === 'main') {
+          return {
+            first() {
+              return {
+                count: async () => 1,
+                ariaSnapshot: async () => '- heading "Only Main"'
+              };
+            }
+          };
+        }
+        if (selector === '[role="main"]') {
+          return { first() { return { count: async () => 0 }; } };
+        }
+        if (selector.includes('~ aside') || selector.includes('complementary')) {
+          return { count: async () => 0 };
+        }
+        return { ariaSnapshot: async () => 'body' };
+      }
+    };
+    const result = await detectMainContent(mockPage);
+    const snapshot = await result.ariaSnapshot();
+    assert.equal(snapshot, '- heading "Only Main"');
+  });
+
+  it('caps complementary regions at 3', async () => {
+    let requestedIndices = [];
+    const mockPage = {
+      locator(selector) {
+        if (selector === 'main') {
+          return {
+            first() {
+              return {
+                count: async () => 1,
+                ariaSnapshot: async () => 'main'
+              };
+            }
+          };
+        }
+        if (selector === '[role="main"]') {
+          return { first() { return { count: async () => 0 }; } };
+        }
+        if (selector.includes('~ aside') || selector.includes('complementary')) {
+          return {
+            count: async () => 5,
+            nth(i) {
+              requestedIndices.push(i);
+              return { ariaSnapshot: async () => `aside-${i}` };
+            }
+          };
+        }
+        return { ariaSnapshot: async () => 'body' };
+      }
+    };
+    const result = await detectMainContent(mockPage);
+    const snapshot = await result.ariaSnapshot();
+    assert.deepEqual(requestedIndices, [0, 1, 2], 'should only request indices 0-2');
+    assert.ok(snapshot.includes('aside-0'), 'should include first aside');
+    assert.ok(snapshot.includes('aside-1'), 'should include second aside');
+    assert.ok(snapshot.includes('aside-2'), 'should include third aside');
+    assert.ok(!snapshot.includes('aside-3'), 'should NOT include fourth aside');
+    assert.ok(!snapshot.includes('aside-4'), 'should NOT include fifth aside');
+  });
+
+  it('gracefully handles complementary ariaSnapshot failure', async () => {
+    const mockPage = {
+      locator(selector) {
+        if (selector === 'main') {
+          return {
+            first() {
+              return {
+                count: async () => 1,
+                ariaSnapshot: async () => '- heading "Main OK"'
+              };
+            }
+          };
+        }
+        if (selector === '[role="main"]') {
+          return { first() { return { count: async () => 0 }; } };
+        }
+        if (selector.includes('~ aside') || selector.includes('complementary')) {
+          return {
+            count: async () => 2,
+            nth(i) {
+              if (i === 0) return { ariaSnapshot: async () => { throw new Error('detached'); } };
+              return { ariaSnapshot: async () => '- text "Second Aside"' };
+            }
+          };
+        }
+        return { ariaSnapshot: async () => 'body' };
+      }
+    };
+    const result = await detectMainContent(mockPage);
+    const snapshot = await result.ariaSnapshot();
+    assert.ok(snapshot.includes('- heading "Main OK"'), 'main content should be present');
+    assert.ok(snapshot.includes('- text "Second Aside"'), 'second aside should still be included');
+  });
+
+  it('complementary detection does not affect body fallback', async () => {
+    const mockPage = {
+      locator(selector) {
+        if (selector === 'main' || selector === '[role="main"]') {
+          return {
+            first() {
+              return { count: async () => 0 };
+            }
+          };
+        }
+        if (selector === 'body') {
+          return { ariaSnapshot: async () => '- heading "Body Fallback"' };
+        }
+        // Even if aside exists elsewhere, body fallback should not include it
+        if (selector.includes('~ aside') || selector.includes('complementary')) {
+          return { count: async () => 2 };
+        }
+        return { ariaSnapshot: async () => '' };
+      }
+    };
+    const result = await detectMainContent(mockPage);
+    const snapshot = await result.ariaSnapshot();
+    assert.equal(snapshot, '- heading "Body Fallback"', 'should fall back to body, not check for aside');
+  });
 });
 
 // ============ getSnapshot auto-scoping tests ============
@@ -1509,6 +1735,9 @@ describe('getSnapshot auto-scoping', () => {
             }
           };
         }
+        if (selector.includes('~ aside') || selector.includes('complementary')) {
+          return { count: async () => 0 };
+        }
         return { ariaSnapshot: async () => '- heading "Full Body"' };
       }
     };
@@ -1613,4 +1842,124 @@ describe('getSnapshot auto-scoping', () => {
     assert.ok(result.includes('- ...'), 'Should truncate deeper nodes');
     assert.ok(!result.includes('link "Home"'), 'Should not include depth-2 nodes');
   });
+
+  it('auto-scoped snapshot includes complementary regions', async () => {
+    const mockPage = {
+      locator(selector) {
+        if (selector === 'main') {
+          return {
+            first() {
+              return {
+                count: async () => 1,
+                ariaSnapshot: async () => '- heading "Repo Code"'
+              };
+            }
+          };
+        }
+        if (selector === '[role="main"]') {
+          return { first() { return { count: async () => 0 }; } };
+        }
+        if (selector.includes('~ aside') || selector.includes('complementary')) {
+          return {
+            count: async () => 1,
+            nth(i) {
+              return { ariaSnapshot: async () => '- text "Stars: 42"' };
+            }
+          };
+        }
+        return { ariaSnapshot: async () => 'body' };
+      }
+    };
+    const result = await getSnapshot(mockPage);
+    assert.ok(result.includes('- heading "Repo Code"'), 'should include main content');
+    assert.ok(result.includes('- text "Stars: 42"'), 'should include complementary content');
+  });
+
+  it('snapshotFull bypasses complementary detection', async () => {
+    const mockPage = {
+      locator(selector) {
+        if (selector === 'main') {
+          return {
+            first() {
+              return {
+                count: async () => 1,
+                ariaSnapshot: async () => '- heading "Main Only"'
+              };
+            }
+          };
+        }
+        if (selector === 'body') {
+          return { ariaSnapshot: async () => '- heading "Full Body"' };
+        }
+        return {
+          first() { return { count: async () => 0 }; },
+          ariaSnapshot: async () => ''
+        };
+      }
+    };
+    const result = await getSnapshot(mockPage, { snapshotFull: true });
+    assert.equal(result, '- heading "Full Body"', 'snapshotFull should use body, not main+complementary');
+  });
+
+  it('snapshotSelector bypasses complementary detection', async () => {
+    const mockPage = {
+      locator(selector) {
+        if (selector === '#custom') {
+          return { ariaSnapshot: async () => '- heading "Custom Area"' };
+        }
+        if (selector === 'main') {
+          return {
+            first() {
+              return {
+                count: async () => 1,
+                ariaSnapshot: async () => '- heading "Main"'
+              };
+            }
+          };
+        }
+        return {
+          first() { return { count: async () => 0 }; },
+          count: async () => 0,
+          ariaSnapshot: async () => ''
+        };
+      }
+    };
+    const result = await getSnapshot(mockPage, { snapshotSelector: '#custom' });
+    assert.equal(result, '- heading "Custom Area"', 'snapshotSelector should bypass complementary detection');
+  });
+
+  it('combined snapshot works with pipeline transforms', async () => {
+    const mockPage = {
+      locator(selector) {
+        if (selector === 'main') {
+          return {
+            first() {
+              return {
+                count: async () => 1,
+                ariaSnapshot: async () => '- heading "Code"\n  - link "file.js"'
+              };
+            }
+          };
+        }
+        if (selector === '[role="main"]') {
+          return { first() { return { count: async () => 0 }; } };
+        }
+        if (selector.includes('~ aside') || selector.includes('complementary')) {
+          return {
+            count: async () => 1,
+            nth(i) {
+              return { ariaSnapshot: async () => '- heading "Stats"\n  - text "Stars: 42"' };
+            }
+          };
+        }
+        return { ariaSnapshot: async () => 'body' };
+      }
+    };
+    const result = await getSnapshot(mockPage, { snapshotDepth: 1 });
+    assert.ok(result.includes('- heading "Code"'), 'main heading should survive depth trim');
+    assert.ok(result.includes('- heading "Stats"'), 'aside heading should survive depth trim');
+    assert.ok(result.includes('- ...'), 'deeper nodes should be truncated');
+    assert.ok(!result.includes('link "file.js"'), 'deep main child should be trimmed');
+    assert.ok(!result.includes('text "Stars: 42"'), 'deep aside child should be trimmed');
+  });
 });
diff --git a/tests/web-ctl-actions.test.js b/tests/web-ctl-actions.test.js
index 08e2daa..a781e55 100644
--- a/tests/web-ctl-actions.test.js
+++ b/tests/web-ctl-actions.test.js
@@ -523,6 +523,10 @@ describe('snapshot options in web-ctl source', () => {
   it('detectMainContent function exists', () => {
     assert.ok(webCtlSource.includes('async function detectMainContent(page)'), 'detectMainContent should be defined');
   });
+
+  it('detectMainContent handles complementary regions', () => {
+    assert.ok(webCtlSource.includes('complementary'), 'detectMainContent should handle complementary regions');
+  });
 });
 
 describe('web-ctl navigation state persistence', () => {

From fb21e03df10c7bca18b3d96bbeba269b13d1945c Mon Sep 17 00:00:00 2001
From: Avi Fenesh <aviarchi1994@gmail.com>
Date: Wed, 25 Feb 2026 01:05:14 +0200
Subject: [PATCH 2/3] fix: harden complementary detection error handling

Wrap complementary landmark detection in its own try-catch so failures
return mainLocator instead of falling back to body. Parallelize
ariaSnapshot calls using Promise.all. Add tests for compLocator.count()
throwing and all-complementary-fail scenarios.
---
 scripts/web-ctl.js         | 28 +++++++------
 tests/get-snapshot.test.js | 85 ++++++++++++++++++++++++++++++++------
 2 files changed, 87 insertions(+), 26 deletions(-)

diff --git a/scripts/web-ctl.js b/scripts/web-ctl.js
index a60d366..9417d9d 100755
--- a/scripts/web-ctl.js
+++ b/scripts/web-ctl.js
@@ -114,20 +114,22 @@ async function detectMainContent(page) {
     }
 
     if (mainLocator) {
-      const compLocator = page.locator(compSelector);
-      const compCount = await compLocator.count();
-      if (compCount > 0) {
-        const cap = Math.min(compCount, 3);
-        return {
-          ariaSnapshot: async () => {
-            const parts = [await mainLocator.ariaSnapshot()];
-            for (let i = 0; i < cap; i++) {
-              try { parts.push(await compLocator.nth(i).ariaSnapshot()); } catch { /* skip */ }
+      try {
+        const compLocator = page.locator(compSelector);
+        const compCount = await compLocator.count();
+        if (compCount > 0) {
+          const cap = Math.min(compCount, 3);
+          return {
+            ariaSnapshot: async () => {
+              const parts = [await mainLocator.ariaSnapshot()];
+              await Promise.all(Array.from({ length: cap }, (_, i) =>
+                compLocator.nth(i).ariaSnapshot().then(s => { parts[i + 1] = s; }).catch(() => {})
+              ));
+              return parts.filter(Boolean).join('\n');
             }
-            return parts.join('\n');
-          }
-        };
-      }
+          };
+        }
+      } catch { /* complementary detection failed, return main only */ }
       return mainLocator;
     }
   } catch {
diff --git a/tests/get-snapshot.test.js b/tests/get-snapshot.test.js
index 57a25de..b761de7 100644
--- a/tests/get-snapshot.test.js
+++ b/tests/get-snapshot.test.js
@@ -41,20 +41,22 @@ async function detectMainContent(page) {
     }
 
     if (mainLocator) {
-      const compLocator = page.locator(compSelector);
-      const compCount = await compLocator.count();
-      if (compCount > 0) {
-        const cap = Math.min(compCount, 3);
-        return {
-          ariaSnapshot: async () => {
-            const parts = [await mainLocator.ariaSnapshot()];
-            for (let i = 0; i < cap; i++) {
-              try { parts.push(await compLocator.nth(i).ariaSnapshot()); } catch { /* skip */ }
+      try {
+        const compLocator = page.locator(compSelector);
+        const compCount = await compLocator.count();
+        if (compCount > 0) {
+          const cap = Math.min(compCount, 3);
+          return {
+            ariaSnapshot: async () => {
+              const parts = [await mainLocator.ariaSnapshot()];
+              await Promise.all(Array.from({ length: cap }, (_, i) =>
+                compLocator.nth(i).ariaSnapshot().then(s => { parts[i + 1] = s; }).catch(() => {})
+              ));
+              return parts.filter(Boolean).join('\n');
             }
-            return parts.join('\n');
-          }
-        };
-      }
+          };
+        }
+      } catch { /* complementary detection failed, return main only */ }
       return mainLocator;
     }
   } catch {
@@ -1707,6 +1709,63 @@ describe('detectMainContent', () => {
     const snapshot = await result.ariaSnapshot();
     assert.equal(snapshot, '- heading "Body Fallback"', 'should fall back to body, not check for aside');
   });
+
+  it('returns main when complementary count() throws', async () => {
+    const mockPage = {
+      locator(selector) {
+        if (selector === 'main') {
+          return {
+            first() {
+              return {
+                count: async () => 1,
+                ariaSnapshot: async () => '- heading "Main Survives"'
+              };
+            }
+          };
+        }
+        if (selector === '[role="main"]') {
+          return { first() { return { count: async () => 0 }; } };
+        }
+        if (selector.includes('~ aside') || selector.includes('complementary')) {
+          return { count: async () => { throw new Error('detached frame'); } };
+        }
+        return { ariaSnapshot: async () => 'body' };
+      }
+    };
+    const result = await detectMainContent(mockPage);
+    const snapshot = await result.ariaSnapshot();
+    assert.equal(snapshot, '- heading "Main Survives"', 'should return main, not fall to body');
+  });
+
+  it('returns main content when all complementary ariaSnapshot calls fail', async () => {
+    const mockPage = {
+      locator(selector) {
+        if (selector === 'main') {
+          return {
+            first() {
+              return {
+                count: async () => 1,
+                ariaSnapshot: async () => '- heading "Main Only"'
+              };
+            }
+          };
+        }
+        if (selector === '[role="main"]') {
+          return { first() { return { count: async () => 0 }; } };
+        }
+        if (selector.includes('~ aside') || selector.includes('complementary')) {
+          return {
+            count: async () => 2,
+            nth() { return { ariaSnapshot: async () => { throw new Error('gone'); } }; }
+          };
+        }
+        return { ariaSnapshot: async () => 'body' };
+      }
+    };
+    const result = await detectMainContent(mockPage);
+    const snapshot = await result.ariaSnapshot();
+    assert.equal(snapshot, '- heading "Main Only"', 'should return just main when all complementary fail');
+  });
 });
 
 // ============ getSnapshot auto-scoping tests ============

From f004f9852d4bb0d3dd7f0403aef92fc6d33439cd Mon Sep 17 00:00:00 2001
From: Avi Fenesh <aviarchi1994@gmail.com>
Date: Wed, 25 Feb 2026 01:10:02 +0200
Subject: [PATCH 3/3] docs: update README snapshot-full flag description

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 2e9005b..63b9d8b 100644
--- a/README.md
+++ b/README.md
@@ -180,7 +180,7 @@ This eliminates the common click-snapshot-check loop that wastes agent turns on
 | `--snapshot-collapse` | Any action with snapshot | Collapse repeated siblings (keep first 2, summarize rest) |
 | `--snapshot-text-only` | Any action with snapshot | Strip structural nodes, keep content only |
 | `--max-field-length <N>` | `extract` | Max characters per field (default: 500, max: 2000) |
-| `--snapshot-full` | Any action with snapshot | Use full page body (default: auto-scope to `<main>` content area) |
+| `--snapshot-full` | Any action with snapshot | Use full page body (default: auto-scope to `<main>` and complementary landmarks) |
 | `--no-snapshot` | Any action with snapshot | Omit snapshot from output entirely |
 
 ## Error Handling
