Design and implement pluggable DOM stability detection strategies

[Copilot]

Analyzed existing DOM stability approaches (__pulsar_utils__.waitForReady, PageStateTracker.waitForDOMSettle) and implemented extensible framework with 3 new strategies.

Architecture

Strategy pattern with composition

interface DOMStabilityStrategy {
    suspend fun check(): Boolean
}

class HybridStabilityDetector(
    session: AgenticSession,
    pageStateTracker: PageStateTracker,
    config: StabilityConfig
) {
    suspend fun waitForStability(): StabilityResult
}

New Strategies

• NetworkIdleStrategy: Monitors inflight requests via Performance API, similar to Puppeteer's networkidle2
• ContentQualityStrategy: Validates minimum page content (height, elements, links, images)
• HybridStabilityDetector: Combines strategies with configurable modes (ALL, ANY_N, RACE)

Configuration Presets

StabilityConfig.FAST       // 10s, 1/3 strategies - AI agents
StabilityConfig.DEFAULT    // 30s, 2/3 strategies - balanced
StabilityConfig.THOROUGH   // 60s, all strategies - production
StabilityConfig.SPA        // 20s, network-focused - React/Vue

Existing Approach Analysis

Approach	Mechanism	Speed	Best For
waitForReady	JS polling, DOM metrics	Slow	Traditional sites, lazy-loading
waitForDOMSettle	MutationObserver + signature	Fast	SPAs, AI agents
Network-Idle	Performance API	Medium	AJAX-heavy
Hybrid	Multi-strategy	Configurable	Unknown/diverse sites

Usage

// AI agent: fast, tolerant
val detector = HybridStabilityDetector(session, tracker, StabilityConfig.FAST)

// Production: reliable, thorough
val detector = HybridStabilityDetector(session, tracker, StabilityConfig.THOROUGH)

val result = detector.waitForStability()
// => StabilityResult(success=true, strategy="any-2", elapsedMs=3421, passedStrategies=["dom-stable", "content-quality"])

Files

• docs/dom-stability-approaches.md: Technical analysis and design (488 lines)
• docs/dom-stability-quick-ref.md: Quick reference with decision tree (270 lines)
• pulsar-agentic/.../DOMStabilityStrategies.kt: Implementation (456 lines)
• pulsar-agentic/.../DOMStabilityStrategiesTest.kt: Unit tests (125 lines)
• dev-docs/.../DOM-STABILITY-SOLUTION.md: Bilingual summary (409 lines)

Non-intrusive - coexists with existing approaches.

Original prompt

设计几种等待 DOM 稳定的方案。比较已有方案 1. pulsar_utils.waitForReady 2. PageStateTracker.waitForDOMSettle

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.