Add comprehensive AI-friendly EventHandlers documentation

[Copilot]

EventHandlers lacked structured reference documentation. AI assistants and developers needed clear guidance on the 28 event handlers across Load/Browse/Crawl phases, their execution order, signatures, and practical usage patterns.

Changes

Documentation Files

• docs/event-handlers-ai.md (1,527 lines): Complete API reference
  • Event lifecycle flow diagram (26 steps)
  • All 28 handlers with signatures, parameters, return values, use cases
  • 8 usage patterns: logging, automation, extraction, login, errors, performance, modals, chaining
  • Full e-commerce scraper example
  • Best practices and troubleshooting
  • Quick reference tables
• docs/event-handlers-ai-summary.md: Overview and key highlights
• Updated README.md and docs/get-started/9event-handling.md with links

Source Code KDoc Enhancements

• EventHandlers.kt: Comprehensive documentation for all handler types and event chains
• PageEvents.kt: Detailed documentation for all interfaces (CrawlEventHandlers, LoadEventHandlers, BrowseEventHandlers, PageEventHandlers)
  • Each event includes purpose, signature, common uses, examples

Key Event Handlers

onDocumentSteady - Primary for browser automation:

browseEventHandlers.onDocumentSteady.addLast { page, driver ->
    // Page is stable - ideal for custom actions
    if (driver.exists("#cookie-consent")) {
        driver.click("#cookie-consent .accept")
    }
    while (driver.exists(".load-more")) {
        driver.click(".load-more")
        delay(2000)
    }
}

onHTMLDocumentParsed - Primary for data extraction:

loadEventHandlers.onHTMLDocumentParsed.addLast { page, document ->
    val products = document.select(".product").map {
        Product(
            name = it.selectFirst(".name")?.text(),
            price = it.selectFirst(".price")?.text()
        )
    }
}

Event Execution Order

1. crawl.onWillLoad → 2. load.onNormalize → 3. load.onWillLoad → 4. load.onWillFetch → 5-19. Browse phase (if using browser) → 20-25. Load phase parsing → 26. crawl.onLoaded

Coverage

• 28 event handlers (complete coverage)
• All handler types documented with signatures
• 25+ code examples
• Optimized for AI assistant consumption

Original prompt

Add comprehensive AI-friendly documentation for EventHandlers, see ai/platon/pulsar/manual/_6_EventHandler.kt for usage.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.