explorbot 0.4.5 → 0.4.7

package/src/ai/researcher.ts

@@ -24,6 +24,7 @@ import { type CoordinateMethods, WithCoordinates } from './researcher/coordinate
 import { type DeepAnalysisMethods, WithDeepAnalysis } from './researcher/deep-analysis.ts';
 import { detectFocusedSection, hasFocusedSection, markSectionAsFocused, pickDefaultFocusedSection } from './researcher/focus.ts';
 import { type LocatorMethods, WithLocators } from './researcher/locators.ts';
+import { type PaginationMethods, WithPagination } from './researcher/pagination.ts';
 import { extractValidContainers, formatResearchSummary, parseResearchSections } from './researcher/parser.ts';
 import { ResearchResult } from './researcher/research-result.ts';
 import { type SectionMethods, WithSections } from './researcher/sections.ts';
@@ -44,9 +45,9 @@ export const POSSIBLE_SECTIONS = {
   navigation: 'main navigation (top bar, sidebar, breadcrumbs)',
 };
 
-const ResearcherBase = WithSections(WithDeepAnalysis(WithCoordinates(WithLocators(TaskAgent as unknown as new (...args: any[]) => TaskAgent))));
+const ResearcherBase = WithSections(WithPagination(WithDeepAnalysis(WithCoordinates(WithLocators(TaskAgent as unknown as new (...args: any[]) => TaskAgent)))));
 
-export interface Researcher extends LocatorMethods, CoordinateMethods, DeepAnalysisMethods, SectionMethods {}
+export interface Researcher extends LocatorMethods, CoordinateMethods, DeepAnalysisMethods, SectionMethods, PaginationMethods {}
 
 export class Researcher extends ResearcherBase implements Agent {
   protected readonly ACTION_TOOLS = ['click'];
@@ -277,6 +278,10 @@ export class Researcher extends ResearcherBase implements Agent {
         await this.backfillBrokenLocators(result);
       }
 
+      if (!interrupted()) {
+        await this.detectPagination(result);
+      }
+
       // Focused section: final fallback (vision-only — without a screenshot we don't infer focus)
       if (this.hasScreenshotToAnalyze && !hasFocusedSection(result.text)) {
         const sections = parseResearchSections(result.text);
@@ -426,7 +431,7 @@ export class Researcher extends ResearcherBase implements Agent {
 
       ${generalLocatorRuleText}
 
-      ${RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element', 'container-rules'], currentUrl)}
+      ${RulesLoader.loadRules('researcher', ['ui-map-table', 'list-element', 'container-rules', 'pagination'], currentUrl)}
 
       <section_identification>
       Identify page sections in this priority order:
@@ -502,6 +507,7 @@ export class Researcher extends ResearcherBase implements Agent {
       - When a section contains a list of similar data items (records, entities, rows — content that varies by data, not by app UI), output it as a Data section with NO table.
       - Data section heading MUST be a level-2 heading (##) that starts exactly with "Data:" — for example: "## Data: Suites List". Do NOT use ### or add section numbers.
       - Data sections must NOT include a UI map table. Only include the container and a brief summary line.
+      - When the data list has controls that move between pages of the collection, add "> Pagination: controls" under its container.
       - Example data section:
 
       ## Data: Suites List

package/src/ai/rules.ts

@@ -349,6 +349,22 @@ export const actionRule = dedent`
   For checkboxes, prefer I.checkOption/I.uncheckOption over I.click.
 
 
+  ### I.scrollTo
+
+  scrolls until the element is in view
+
+  I.scrollTo(<locator>)
+
+  Scrolls every scrollable ancestor of the target, so it reaches an element inside a container
+  that has its own scrollbar. I.scrollPageToBottom() moves only the page itself.
+
+  <example>
+    I.scrollTo('.rows > *:last-child');
+    I.scrollTo({ role: 'listitem', text: 'Last entry' });
+    I.scrollPageToBottom();
+  </example>
+
+
   ### I.fillField
 
   fills the field with the given value

package/src/ai/scout.ts

@@ -56,13 +56,20 @@ export class Scout implements Agent {
           agentName: 'scout',
         });
 
+        const responseText = invokeResult?.response?.text;
+        if (responseText?.trim()) {
+          finishFromText(responseText);
+          stop();
+          return;
+        }
+
         if (!invokeResult?.toolExecutions?.length) {
-          finishFromText(invokeResult?.response?.text);
           stop();
           return;
         }
 
-        if (iteration >= MAX_ITERATIONS) {
+        if (iteration >= MAX_ITERATIONS - 1) {
+          conversation.addUserText('Exploration time is over. Report your findings now as your final message.');
           const final = await this.provider.invokeConversation(conversation, undefined, { agentName: 'scout' });
           finishFromText(final?.response?.text);
           stop();

package/src/ai/tools.ts

@@ -1,18 +1,18 @@
 import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
-import type { ExecutedStep } from '../action.ts';
 import { ActionResult, type PageDiff, type ToolResultMetadata } from '../action-result.ts';
+import type { ExecutedStep } from '../action.ts';
 import { type ExperienceTracker, renderExperienceRecipes } from '../experience-tracker.ts';
 import { Stats } from '../stats.ts';
 import { type Task, TestResult } from '../test-plan.js';
+import { ariaRefSelector, describeRef, refIsGone } from '../utils/aria-ref.ts';
 import { LARGE_ARIA_CHANGE_THRESHOLD } from '../utils/aria.ts';
 import { isFatalBrowserError } from '../utils/browser-errors.ts';
 import { cleanHtmlSnippet } from '../utils/html.ts';
 import { createDebug, tag } from '../utils/logger.js';
-import { compactErrorMessage, normalizeInlineText, truncate } from '../utils/strings.ts';
 import { pause } from '../utils/loop.js';
-import { ariaRefSelector, describeRef, refIsGone } from '../utils/aria-ref.ts';
+import { compactErrorMessage, normalizeInlineText, truncate } from '../utils/strings.ts';
 import { WebElement } from '../utils/web-element.ts';
 import type { ToolDeps } from './agent.ts';
 import { Navigator } from './navigator.ts';
@@ -133,7 +133,13 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
             }
 
             await commitNote(activeNote, TestResult.PASSED, toolResult, action);
-            return successToolResult('click', { ...toolResult, attempts, code: command }, action);
+            const data: Record<string, any> = { ...toolResult, attempts, code: command };
+            const notExecuted = commands.slice(i + 1);
+            if (notExecuted.length) {
+              data.notExecuted = notExecuted;
+              data.suggestion = `SKIPPED: ${notExecuted.join('; ')}`;
+            }
+            return successToolResult('click', data, action);
           }
         }
 
@@ -368,6 +374,7 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
         - Working with iframes (switch context with I.switchTo)
         - Performing multiple form actions in a single batch
         - Complex interactions requiring sequential commands
+        - Reaching items further down a list (I.scrollTo)
 
         Example - filling a form with context (PREFERRED):
         I.fillField('Username', 'John', '.login-form')
@@ -435,10 +442,10 @@ export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task
 
           if (!hasObservablePageChange(toolResult)) {
             activeNote.commit(TestResult.FAILED);
-            return failedToolResult('form', 'Form command executed, but no observable page or form-state change was captured.', {
+            return failedToolResult('form', 'Command executed, but nothing on the page changed: no navigation, no ARIA change, no HTML change and no request.', {
               ...toolResult,
               code: codeBlock,
-              suggestion: 'Treat the field/form action as not completed. Re-locate the editable control, check whether another UI layer is active, then retry and verify the field value before submitting.',
+              suggestion: 'The command ran without reaching anything. Re-locate the target, check whether another UI layer is active, then retry. If the goal was to load more of a list, no change means the collection has ended.',
             });
           }
           await commitNote(activeNote, TestResult.PASSED, toolResult, action);
@@ -1232,7 +1239,10 @@ export function successToolResult(action: string, data?: Record<string, any>, so
 }
 
 export function isMajorPageChange(pageDiff: PageDiff): boolean {
-  return pageDiff.urlChanged !== true && (pageDiff.ariaChangeCount ?? 0) >= LARGE_ARIA_CHANGE_THRESHOLD;
+  if (pageDiff.urlChanged === true) return false;
+  if ((pageDiff.ariaChangeCount ?? 0) < LARGE_ARIA_CHANGE_THRESHOLD) return false;
+  if (pageDiff.ariaRemoved === 0 && (pageDiff.ariaAdded ?? 0) > 0) return false;
+  return true;
 }
 
 export function hasFailedRequest(pageDiff: PageDiff): boolean {
@@ -1265,7 +1275,7 @@ export async function failedToolResult(action: string, message: string, data?: R
   const errorTexts = [message, ...(data?.attempts?.map((a: any) => a.error || '') || [])];
   if (errorTexts.some((t: string) => t.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))) {
     const matched = await extractWebElements(error);
-    result.suggestion = getMultipleElementsSuggestion(matched);
+    result.suggestion = getMultipleElementsSuggestion();
     result.multipleElementsDetected = true;
     result.elements = formatElementList(matched);
     return result;
@@ -1280,16 +1290,12 @@ export async function failedToolResult(action: string, message: string, data?: R
   return result;
 }
 
-function getMultipleElementsSuggestion(matched: MatchedElement[] | null): string {
-  const visible = (matched || []).filter((element) => element.visible !== false);
-  let onlyVisible = '';
-  if (matched && visible.length === 1) onlyVisible = `\nOnly element ${matched.indexOf(visible[0]) + 1} is on screen, so that is the one to act on.`;
-
+function getMultipleElementsSuggestion(): string {
   return dedent`
     Multiple elements matched your locator, so that command did nothing — it selected no element and acted on none.
     Read the numbered elements list and act on the one you meant by its number:
     reuse the same locator with step.opts({ elementIndex: N }) as the last argument.
-    A match reported as not visible can never be acted on — pick one that is.${onlyVisible}
+    A match reported as not visible can never be acted on — pick one that is.
     If none of them is the element you want, narrow the locator with a container or its full unique text.
     If the list is missing, call xpathCheck() to see what the locator matches.
   `;
@@ -1365,6 +1371,8 @@ function formatElementList(matched: MatchedElement[] | null): string {
     .map((el, i) => {
       const lines = [`Element ${i + 1}:`, `Text: "${el.text}"`];
       if (el.visible !== undefined) lines.push(`Visible: ${el.visible}`);
+      const wrapped = matched.map((_, j) => j).filter((j) => j !== i && matched[j].xpath.startsWith(`${el.xpath}/`));
+      if (wrapped.length) lines.push(`Wraps: element ${wrapped.map((j) => j + 1).join(', ')}`);
       lines.push(`XPath: ${el.xpath}`, `HTML: ${el.html}`);
       return lines.join('\n');
     })

package/src/api/spec-reader.ts

@@ -51,7 +51,7 @@ export function extractEndpointDefinition(schema: any, endpoint: string, baseEnd
   }
 
   const basePath = toBasePath(baseEndpoint);
-  const matched = collectMatchingPaths(schema, basePath, (normalized) => matchesEndpoint(normalized, endpoint));
+  const matched = collectEndpointPaths(schema, basePath, endpoint);
 
   if (!Object.keys(matched).length) {
     const available = listNormalizedPaths(schema, basePath);
@@ -61,6 +61,35 @@ export function extractEndpointDefinition(schema: any, endpoint: string, baseEnd
   return safeStringify(matched);
 }
 
+export function resolveEndpoints(schema: any, pattern: string, baseEndpoint?: string): string[] {
+  if (!schema?.paths) {
+    throw new Error('OpenAPI spec has no paths defined');
+  }
+
+  const basePath = toBasePath(baseEndpoint);
+  const normalized = Object.keys(schema.paths).map((specPath) => stripBasePath(specPath, basePath));
+  const matched = normalized.filter((specPath) => matchesPattern(specPath, pattern));
+
+  if (!matched.length) {
+    throw new Error(`Endpoint "${pattern}" not found in spec. Available: ${listNormalizedPaths(schema, basePath)}`);
+  }
+
+  const roots = matched.map((specPath) => toCollection(specPath, normalized, pattern));
+  const resolved = [...new Set(roots.map((root) => fillParameters(root, pattern)))];
+  const endpoints = resolved.filter((specPath) => !specPath.includes('{'));
+
+  if (!endpoints.length) {
+    throw new Error(`Endpoint "${pattern}" leaves ${listParameters(resolved)} unresolved. Give the value in the endpoint or in the base endpoint.`);
+  }
+
+  const skipped = resolved.filter((specPath) => specPath.includes('{'));
+  if (skipped.length) {
+    tag('warning').log(`Skipped, no value for their parameters: ${skipped.join(', ')}`);
+  }
+
+  return endpoints;
+}
+
 export function searchEndpoints(schema: any, query: string, baseEndpoint?: string): string {
   if (!schema?.paths) return 'No endpoints available';
 
@@ -166,6 +195,82 @@ function stripBasePath(specPath: string, basePath: string): string {
   return `/${specSegments.slice(i).join('/')}`;
 }
 
+function collectEndpointPaths(schema: any, basePath: string, endpoint: string): Record<string, any> {
+  const normalized = Object.keys(schema.paths).map((specPath) => stripBasePath(specPath, basePath));
+  const roots = resolveEndpoint(normalized, endpoint);
+
+  if (!roots.length) return collectMatchingPaths(schema, basePath, (path) => matchesEndpoint(path, endpoint));
+
+  return collectMatchingPaths(schema, basePath, (path) => roots.some((root) => path === root || path.startsWith(`${root}/`)));
+}
+
+function resolveEndpoint(specPaths: string[], endpoint: string): string[] {
+  const wanted = toSegments(endpoint);
+  if (!wanted.length) return [];
+
+  const matched = specPaths.filter((specPath) => {
+    const segments = toSegments(specPath);
+    if (segments.length !== wanted.length) return false;
+    return segmentsMatch(segments, wanted);
+  });
+
+  const literals = matched.map((specPath) => toSegments(specPath).filter((segment, i) => segment === wanted[i]).length);
+  const best = Math.max(0, ...literals);
+  return matched.filter((_, i) => literals[i] === best);
+}
+
+function matchesPattern(specPath: string, pattern: string): boolean {
+  const wanted = toSegments(pattern);
+  const segments = toSegments(specPath);
+  if (segments.length < wanted.length) return false;
+  return segmentsMatch(segments, wanted);
+}
+
+function segmentsMatch(segments: string[], wanted: string[]): boolean {
+  return wanted.every((want, i) => want === '*' || segments[i] === want || segments[i].startsWith('{'));
+}
+
+function toCollection(specPath: string, specPaths: string[], pattern: string): string {
+  const segments = toSegments(specPath);
+  const filled = toSegments(fillParameters(specPath, pattern));
+
+  let deepest = segments.length;
+  const unfilled = filled.findIndex((segment) => segment.startsWith('{'));
+  if (unfilled >= 0) deepest = unfilled;
+
+  for (let i = Math.max(1, Math.min(toSegments(pattern).length, deepest)); i <= deepest; i++) {
+    const prefix = `/${segments.slice(0, i).join('/')}`;
+    if (specPaths.includes(prefix)) return prefix;
+  }
+
+  return specPath;
+}
+
+function fillParameters(specPath: string, pattern: string): string {
+  const wanted = toSegments(pattern);
+  const segments = toSegments(specPath);
+  for (let i = 0; i < wanted.length && i < segments.length; i++) {
+    if (wanted[i] === '*') continue;
+    if (!segments[i].startsWith('{')) continue;
+    segments[i] = wanted[i];
+  }
+  return `/${segments.join('/')}`;
+}
+
+function listParameters(specPaths: string[]): string {
+  const found = new Set<string>();
+  for (const specPath of specPaths) {
+    for (const segment of toSegments(specPath)) {
+      if (segment.startsWith('{')) found.add(segment);
+    }
+  }
+  return [...found].join(', ');
+}
+
+function toSegments(path: string): string[] {
+  return path.split('/').filter(Boolean);
+}
+
 function matchesEndpoint(specPath: string, endpoint: string): boolean {
   if (specPath === endpoint) return true;
   if (specPath.startsWith(`${endpoint}/`)) return true;

package/src/commands/base-command.ts

@@ -15,7 +15,7 @@ export interface Suggestion {
   hint: string;
 }
 
-export abstract class BaseCommand {
+export abstract class BaseCommand<T = ExplorBot> {
   abstract name: string;
   abstract description: string;
   aliases: string[] = [];
@@ -23,9 +23,9 @@ export abstract class BaseCommand {
   tuiEnabled = true;
   suggestions: Suggestion[] = [];
 
-  protected explorBot: ExplorBot;
+  protected explorBot: T;
 
-  constructor(explorBot: ExplorBot) {
+  constructor(explorBot: T) {
     this.explorBot = explorBot;
   }
 

package/src/commands/init-command.ts

@@ -39,7 +39,7 @@ ${moduleExport}
 `;
 }
 
-function envTemplate(provider: string): string {
+export function envTemplate(provider: string): string {
   const keyLines = Object.entries(PROVIDERS).map(([name, { envKey }]) => {
     if (name === provider) return `${envKey}=`;
     return `# ${envKey}=`;
@@ -253,7 +253,7 @@ async function renderLocalProviderWizard(): Promise<string | null> {
   });
 }
 
-function modelLines(provider: string): string {
+export function modelLines(provider: string, only?: ModelRole[]): string {
   const recommended = ConfigParser.recommendedModels()[provider] || {};
   const roles: Array<[ModelRole, string]> = [
     ['model', 'fast model with tool calling capabilities'],
@@ -261,7 +261,10 @@ function modelLines(provider: string): string {
     ['agenticModel', 'agentic model for decision making'],
   ];
 
-  return roles.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
+  let selected = roles;
+  if (only) selected = roles.filter(([role]) => only.includes(role));
+
+  return selected.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
 }
 
 function globalConfigTemplate(provider: string): string {

package/src/commands/options/ws-option.ts

@@ -6,6 +6,20 @@ export class WsOption extends BaseOption {
   flags = '--ws <url>';
   description = 'Stream this run to a remote UI over WebSocket';
 
+  /**
+   * An open socket holds the event loop, and `WebSocket` has no `unref` on
+   * either runtime — so a command that ends by returning rather than through
+   * `showStatsAndExit` would never exit once it is attached. The option that
+   * opened the connection is what closes it.
+   */
+  override register(command: Command): void {
+    super.register(command);
+    command.hook('postAction', async () => {
+      if (!remote.isAttached()) return;
+      await remote.close(0);
+    });
+  }
+
   protected apply(options: Record<string, any>, command: Command): void {
     const url = options.ws || process.env.EXPLORBOT_WS_URL;
     if (!url) return;

package/src/config.ts

@@ -677,17 +677,7 @@ export class ConfigParser {
       config.playwright.url = options.baseUrl;
     }
 
-    if (config.ai) {
-      const langfuse = config.ai.langfuse;
-      const publicKey = langfuse?.publicKey || process.env.LANGFUSE_PUBLIC_KEY;
-      const secretKey = langfuse?.secretKey || process.env.LANGFUSE_SECRET_KEY;
-      config.ai.langfuse = {
-        enabled: langfuse?.enabled ?? Boolean(publicKey && secretKey),
-        publicKey,
-        secretKey,
-        baseUrl: langfuse?.baseUrl || process.env.LANGFUSE_BASE_URL || process.env.LANGFUSE_HOST,
-      };
-    }
+    resolveLangfuse(config.ai);
 
     return config;
   }
@@ -857,6 +847,20 @@ export async function resolveConfigModels(ai?: AIConfig): Promise<void> {
   }
 }
 
+export function resolveLangfuse(ai?: AIConfig): void {
+  if (!ai) return;
+
+  const langfuse = ai.langfuse;
+  const publicKey = langfuse?.publicKey || process.env.LANGFUSE_PUBLIC_KEY;
+  const secretKey = langfuse?.secretKey || process.env.LANGFUSE_SECRET_KEY;
+  ai.langfuse = {
+    enabled: langfuse?.enabled ?? Boolean(publicKey && secretKey),
+    publicKey,
+    secretKey,
+    baseUrl: langfuse?.baseUrl || process.env.LANGFUSE_BASE_URL || process.env.LANGFUSE_HOST,
+  };
+}
+
 export function resolveOutputRoot(baseUrl?: string): string {
   if (cachedOutputRoot) return cachedOutputRoot;
 

package/src/explorer.ts

@@ -263,7 +263,7 @@ class Explorer {
   }
 
   private convertToCodeceptConfig(config: ExplorbotConfig): any {
-    const playwrightConfig = { ...config.playwright };
+    const playwrightConfig = { visibleLocator: true, ...config.playwright };
 
     if (this.options?.show !== undefined) {
       playwrightConfig.show = this.options.show;

package/src/remote.ts

@@ -28,6 +28,7 @@ export class Remote implements LogDestination {
   private asks = new Map<string, (value: string | null) => void>();
   private askCounter = 0;
   private lastActivity: string | null = null;
+  private closing: Promise<void> | null = null;
 
   attach(url: string, command: string): void {
     if (this.url) return;
@@ -73,21 +74,10 @@ export class Remote implements LogDestination {
     });
   }
 
-  async close(exitCode: number): Promise<void> {
-    if (!this.url) return;
-    this.send('result', { ok: exitCode === 0, exitCode });
-    await this.flush();
-
-    this.url = null;
-    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
-    // Whoever asks next has nobody to ask — leaving the callback installed would
-    // route them into a closed socket and park them until the ask times out.
-    executionController.clearInputCallback();
-    for (const resolve of this.asks.values()) resolve(null);
-    this.asks.clear();
-    this.queue = [];
-    this.socket?.close();
-    this.socket = null;
+  close(exitCode: number): Promise<void> {
+    if (!this.url) return Promise.resolve();
+    if (!this.closing) this.closing = this.shutdown(exitCode);
+    return this.closing;
   }
 
   isEnabled(): boolean {
@@ -116,6 +106,23 @@ export class Remote implements LogDestination {
     });
   }
 
+  private async shutdown(exitCode: number): Promise<void> {
+    this.send('result', { ok: exitCode === 0, exitCode });
+    await this.flush();
+
+    this.url = null;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    // Whoever asks next has nobody to ask — leaving the callback installed would
+    // route them into a closed socket and park them until the ask times out.
+    executionController.clearInputCallback();
+    for (const resolve of this.asks.values()) resolve(null);
+    this.asks.clear();
+    this.queue = [];
+    this.socket?.close();
+    this.socket = null;
+    this.closing = null;
+  }
+
   private connect(): void {
     if (!this.url) return;
 

package/src/utils/aria.ts

@@ -521,7 +521,12 @@ export const diffAriaSnapshots = (previous: string | null, current: string | nul
   const renames = detectRenames(prev, curr, prevTotals, currTotals);
   const added = [...byCount.added, ...renames.added];
   const removed = [...byCount.removed, ...renames.removed];
-  return { text: formatDiff(added, removed, toggled, typed), count: added.length + removed.length + toggled.length + typed.length };
+  return {
+    text: formatDiff(added, removed, toggled, typed),
+    count: added.length + removed.length + toggled.length + typed.length,
+    added: added.length,
+    removed: removed.length,
+  };
 };
 
 export const detectFocusArea = (snapshot: string | null): FocusAreaResult => {
@@ -587,6 +592,8 @@ export const LARGE_ARIA_CHANGE_THRESHOLD = 50;
 export interface AriaDiff {
   text: string | null;
   count: number;
+  added: number;
+  removed: number;
 }
 
 type AriaNode = {

package/src/utils/html-diff.ts

@@ -37,7 +37,7 @@ const IGNORED_PATHS = new Set(['html[1]', 'html[1]/head[1]', 'html[1]/body[1]'])
 const SHELL_RATIO = 0.8;
 const ROOT_CONTENT_RATIO = 0.8;
 
-const LIVE_REGION_ROLES = new Set(['alert', 'alertdialog', 'status', 'log']);
+const LIVE_REGION_ROLES = new Set(['alert', 'alertdialog', 'status', 'log', 'tooltip']);
 const TEXT_LINE_PREFIX = 'TEXT:';
 const MESSAGE_MAX_LENGTH = 200;
 const MESSAGE_LIMIT = 8;
@@ -549,6 +549,8 @@ function semanticSelectorFor(element: ElementNode, allElements: NodeMap): string
   while (current) {
     const selector = buildContainerSelector(current, allElements);
     if (selector) return selector;
+    const classAttr = (current.attrs ?? []).find((a) => a.name === 'class')?.value;
+    if (classAttr && filterContainerClasses(classAttr.split(/\s+/).filter(Boolean)).length > 0) return undefined;
     current = dominantChild(current);
   }
   return undefined;

package/src/utils/markdown-query.ts

@@ -162,6 +162,12 @@ function matchText(text: string, matcher: TextMatcher): boolean {
   return matcher.negated ? !result : result;
 }
 
+function entryKey(line: string): string | null {
+  const separator = line.indexOf(':');
+  if (separator < 1) return null;
+  return line.slice(0, separator).trim().toLowerCase();
+}
+
 function getTokenText(token: Token): string {
   const t = token as any;
   switch (token.type) {
@@ -407,6 +413,39 @@ export class MarkdownQuery {
     return results;
   }
 
+  keyValue(): Record<string, string> {
+    const entries: Record<string, string> = {};
+
+    for (const range of this.matches) {
+      for (const line of getTokenText(range.token).split('\n')) {
+        const key = entryKey(line);
+        if (!key) continue;
+        const value = line.slice(line.indexOf(':') + 1).trim();
+        if (value) entries[key] = value;
+      }
+    }
+
+    return entries;
+  }
+
+  setKeyValue(key: string, value: string | null): string {
+    return this.replaceEach((match) => {
+      const token = match.matches[0].token;
+      const lines = getTokenText(token)
+        .split('\n')
+        .map((line) => line.trim())
+        .filter(Boolean);
+
+      const index = lines.findIndex((line) => entryKey(line) === key.toLowerCase());
+      if (index < 0 && value) lines.push(`${key}: ${value}`);
+      if (index >= 0 && value) lines[index] = `${key}: ${value}`;
+      if (index >= 0 && !value) lines.splice(index, 1);
+
+      if (token.type !== 'blockquote') return lines.join('\n');
+      return lines.map((line) => `> ${line}`).join('\n');
+    });
+  }
+
   replace(content: string): string {
     return this.replaceEach(() => content);
   }

package/src/utils/pagination.ts

@@ -0,0 +1,36 @@
+export function inspectList(css: string): ListMeasure | null {
+  const element = document.querySelector(css);
+  if (!element) return null;
+  const rect = element.getBoundingClientRect();
+  return {
+    hasPagingControls: !!element.querySelector('a[rel="next"], a[rel="prev"]'),
+    isFeed: element.matches('[role="feed"]') || !!element.querySelector('[role="feed"]'),
+    scrolls: element.scrollHeight > element.clientHeight + 1 || rect.bottom > window.innerHeight,
+    items: element.querySelectorAll(':scope > *').length,
+    scrollTop: element.scrollTop,
+    pageScrollY: window.scrollY,
+  };
+}
+
+export function restoreScroll({ css, scrollTop, pageScrollY }: ScrollPosition): void {
+  const element = document.querySelector(css);
+  if (element) element.scrollTop = scrollTop;
+  window.scrollTo(0, pageScrollY);
+}
+
+export type PaginationStrategy = 'controls' | 'infinite';
+
+export interface ListMeasure {
+  hasPagingControls: boolean;
+  isFeed: boolean;
+  scrolls: boolean;
+  items: number;
+  scrollTop: number;
+  pageScrollY: number;
+}
+
+export interface ScrollPosition {
+  css: string;
+  scrollTop: number;
+  pageScrollY: number;
+}