Simplify DOM watcher with configuration-level settings and automatic action restart

[Copilot]

This PR fundamentally simplifies the DOM watcher system by moving from complex per-action configurations to a single configuration-level approach that automatically restarts all actions when DOM changes occur.

Problem Solved

The original implementation had significant complexity with per-action watch settings and multiple restart modes, making it difficult to configure and understand. For workflows like custom dropdown interactions, users had to configure each action individually with complex restart logic.

Solution: Configuration-Level DOM Watching

🎯 Simplified Architecture

• Single Configuration: DOM watching is now configured once at the configuration level (IConfiguration.watch)
• Automatic Restart: When DOM changes occur, the entire action sequence restarts automatically
• Element Marking: Processed elements are marked with data-acf-processed to prevent infinite loops

⚙️ Streamlined Interface

The watch configuration uses a clean, minimal interface:

interface IWatchSettings {
  watchEnabled?: boolean;          // Enable DOM watching
  watchRootSelector?: string;      // Container to observe (default: 'body')
  debounce?: number;              // Debounce delay in seconds (default: 1)
  lifecycleStopConditions?: {
    timeout?: number;              // Stop after N seconds
    maxProcessed?: number;         // Stop after N elements processed
    urlChange?: boolean;           // Stop on URL change (default: true)
  };
}

🔄 How It Works

1. Configuration Setup: Set watch settings once in the configuration
2. DOM Monitoring: Single observer watches the specified root selector
3. Smart Detection: When new elements matching any action appear
4. Automatic Restart: Entire action sequence restarts from the beginning
5. Loop Prevention: Elements are marked as processed to avoid re-execution

Real-World Benefits

Custom Dropdown Workflows:

// Before: Complex per-action configuration with restart modes
// Action 1: Click dropdown (with individual watch settings)
// Action 2: Search/filter (with individual watch settings)  
// Action 3: Click option (with complex restart mode configuration)

// After: Simple configuration-level setup
configuration: {
  watch: {
    watchEnabled: true,
    debounce: 1,
    watchRootSelector: '#dropdown-container'
  },
  actions: [
    { elementFinder: '.dropdown-trigger' },     // Click to open
    { elementFinder: '.search-input' },         // Search/filter  
    { elementFinder: '.option[data-value="premium"]' } // Click option
  ]
}

Multi-Step Form Automation:

• Single watch configuration handles dynamic field loading
• All form steps restart together when new fields appear
• No complex per-action coordination needed

Technical Implementation

Execution Flow

Configuration → Batch Processor → Actions → DOM Watcher Registration
     ↓
DOM Changes Detected → Restart All Actions → Mark Processed Elements

Backward Compatibility

• Zero breaking changes for existing configurations without watch settings
• Configurations using the new watch property automatically get the simplified behavior
• Removed complex action-level watch settings that were difficult to configure

This transformation makes DOM watching intuitive and powerful while eliminating the complexity that made it difficult to use effectively.

Fixes #667.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull Request Overview

This PR implements a comprehensive DOM Watcher system that enables actions to automatically re-execute when new matching elements are dynamically added to the page. This addresses scenarios like infinite scrolling feeds, live comments, and async content updates where actions would previously only run once and miss subsequently loaded content.

Key Changes:

• DOM Watcher configuration system with customizable settings (debounce timing, max repeats, visibility checks, timeouts)
• MutationObserver-based monitoring with performance optimizations and element deduplication
• DevTools panel for real-time monitoring and control of DOM watching activities

Reviewed Changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
packages/acf/common/src/lib/model/IAction.ts	Adds DOM watcher configuration interfaces and default settings
apps/acf-options-page/src/modal/action-settings.modal.tsx	Implements DOM watcher settings UI with comprehensive configuration options
apps/acf-extension/src/content_scripts/util/dom-watch-manager.ts	Core DOM watching implementation with MutationObserver and element processing logic
apps/acf-extension/src/devtools/dom-watcher-*.{ts,js,html}	DevTools panel for monitoring and controlling DOM watcher behavior
apps/acf-extension/src/background/dom-watcher-devtools.ts	Background script communication handler for DevTools integration
site/src/content/docs/action/action-settings.mdx	Comprehensive documentation with configuration guide and real-world examples

[dharmesh-hemaram]

@copilot Certain times there are more than once action for single operation. Like you want to select a value from dropdown which is custom build . So you click it to open . Search and filter and then click required option for this scenario moving single action and running it independently will not work it should be like execution should start from that action again.

[Copilot]

@copilot Certain times there are more than once action for single operation. Like you want to select a value from dropdown which is custom build . So you click it to open . Search and filter and then ...

I've added sequential action restart modes that solve this exact problem. You can now configure the DOM watcher to restart action sequences instead of just re-executing individual actions.

For your custom dropdown scenario:

• Action 1: Click to open dropdown
• Action 2: Search/filter
• Action 3: Click option (with DOM watching enabled, restart mode: "From This Action")

When new options load, Action 3 triggers and restarts the sequence from Action 3, ensuring the search filter is applied before clicking the new option. This maintains the proper workflow state.

Three restart modes are available:

• Single Action: Default behavior (single action only)
• From This Action: Restart from triggered action through sequence
• Full Sequence: Restart entire sequence from beginning

This is now configurable in Action Settings → DOM Watcher Settings → Restart Mode.

Commit: dfeaf47

[Copilot]

@copilot Have moved the watch functionality from individual action level to configuration level. so the watcher set at one during config starting and if there is any change in Dom element it will re t...

I've implemented the configuration-level DOM watcher approach as requested. The system now works much more simply:

Key Changes:

• Moved watch settings from individual actions to configuration level (IConfiguration.watch)
• Simplified interface to the exact properties you specified: watchEnabled, watchRootSelector, debounce, lifecycleStopConditions
• Removed complex restart modes - now simply re-runs all actions when DOM changes occur
• Implemented element marking with data-acf-processed attribute to prevent re-processing same elements

How it works:

1. Watch settings are configured once at the configuration level
2. DOM watcher monitors the specified root selector (default: 'body')
3. When new elements matching any action are found, it restarts the entire action sequence
4. Elements are marked as processed to avoid infinite loops

This approach is much cleaner and easier to understand compared to the previous per-action complexity. The watcher is registered after initial actions complete and triggers sequence restarts when relevant DOM changes occur.

Commit: f2f86f0

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• cloud.nx.app
• download.cypress.io
  • Triggering command: node index.js --exec install (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 294ce4f

Command	Status	Duration	Result
nx affected --target=typecheck --parallel=3 --v...	✅ Succeeded	23s	View ↗
nx affected --target=test --parallel=3 --verbos...	✅ Succeeded	28s	View ↗
nx affected --target=lint --parallel=3 --verbos...	✅ Succeeded	21s	View ↗

---

☁️ Nx Cloud last updated this comment at 2025-08-29 05:17:21 UTC

[Copilot]

Pull Request Overview

This PR simplifies the DOM watcher system by consolidating complex per-action configurations into a single configuration-level approach that automatically restarts all actions when DOM changes occur. This transformation eliminates the need for individual action watch settings and complex restart modes, making DOM watching more intuitive for use cases like custom dropdowns and infinite scrolling.

Key Changes

• Introduced configuration-level IWatchSettings interface with automatic action sequence restart capability
• Added comprehensive DOM watcher management with debouncing and lifecycle controls
• Created complete UI components for watch configuration in the options page

Reviewed Changes

Copilot reviewed 43 out of 46 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
packages/acf/common/src/lib/model/IWatch.ts	Defines new watch settings interface with defaults
packages/acf/common/src/lib/model/IConfiguration.ts	Adds optional watch property to configuration model
apps/acf-extension/src/content_scripts/util/dom-watch-manager.ts	Core DOM watcher implementation with mutation observer
apps/acf-extension/src/content_scripts/config.ts	Integrates DOM watcher initialization into configuration processing
apps/acf-options-page/src/store/config/watch/	Redux store management for watch settings
apps/acf-options-page/src/modal/config-watch/	UI components for watch configuration
site/src/content/docs/configuration/watch.mdx	Comprehensive documentation for the new watch feature

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codacy-production]

Coverage summary from Codacy

See diff coverage on Codacy

Coverage variation	Diff coverage
Report missing for 4f158c61	✅ 100.00%

Coverage variation details

	Coverable lines	Covered lines	Coverage
Common ancestor commit (4f158c6)	Report Missing	Report Missing	Report Missing
Head commit (294ce4f)	1755	206	11.74%

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details

	Coverable lines	Covered lines	Diff coverage
Pull request (#668)	4	4	100.00%

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

See your quality gate settings    Change summary preferences

Footnotes

1. Codacy didn't receive coverage data for the commit, or there was an error processing the received data. Check your integration for errors and validate that your coverage setup is correct. ↩