@rosepetal/node-red-contrib-utils 1.1.1

package/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Publish Package
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: 'Publish to npm'
+        required: false
+        default: 'false'
+        type: boolean
+
+env:
+  NODE_VERSION: '20'
+
+jobs:
+  publish:
+    runs-on: ubuntu-22.04
+    if: ${{ startsWith(github.ref, 'refs/tags/v') || github.event.inputs.publish == 'true' }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Determine npm dist-tag
+        id: dist-tag
+        run: |
+          ref_name="${GITHUB_REF_NAME}"
+          dist_tag="latest"
+          if [[ "${GITHUB_REF}" == refs/tags/v* ]]; then
+            version="${ref_name#v}"
+            if [[ "$version" == *-* ]]; then
+              pre="${version#*-}"
+              preid="${pre%%[.+]*}"
+              if [[ -n "$preid" ]]; then
+                dist_tag="$preid"
+              fi
+            fi
+          fi
+          echo "tag=$dist_tag" >> "$GITHUB_OUTPUT"
+          echo "Using dist-tag: $dist_tag"
+
+      - name: Publish package
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          PUBLISH_TAG: ${{ steps.dist-tag.outputs.tag }}
+        run: |
+          npm publish --access public --tag "$PUBLISH_TAG" || echo "Package may already exist"

package/docs/nodes/io/array-in.md

@@ -0,0 +1,119 @@
+# Array-In Node
+
+## Purpose & Use Cases
+
+The `array-in` node collects data from various sources and tags it with position information for ordered array assembly. It works in partnership with the `array-out` node to create structured arrays from multiple parallel data streams.
+
+**Real-World Applications:**
+- **Batch Image Processing**: Collect multiple images for simultaneous processing
+- **Data Aggregation**: Combine results from parallel processing pipelines
+- **Multi-Source Analysis**: Merge data from different sensors or inputs
+- **Synchronized Processing**: Ensure data maintains order through parallel workflows
+- **Multi-Camera Systems**: Collect images from multiple cameras in correct sequence
+
+![Array-In Demo](../../../assets/nodes/io/array-in-demo.gif)
+
+## Input/Output Specification
+
+### Inputs
+- **Input Message**: Message containing data at the configured input path
+- **Dynamic Position**: Array position can be resolved from message properties
+
+### Outputs
+The node adds metadata to the message and mirrors the extracted data into the payload only when reading from `msg.payload`. For other input paths, the existing payload remains untouched while the metadata provides access to the collected value:
+
+```javascript
+{
+  ...originalMessage,
+  payload: any,           // Unchanged unless input is msg.payload; when mirrored matches meta.arrayData
+  meta: {
+    arrayPosition: number,  // Index where this data belongs in array
+    arrayData: any         // The extracted data from input path
+  }
+}
+```
+
+## Configuration Options
+
+### Input From
+- **Default**: `msg.payload`
+- **Options**: 
+  - `msg.*` - Read from message property
+  - `flow.*` - Read from flow context
+  - `global.*` - Read from global context
+- **Purpose**: Specifies where to extract the data to be included in the array
+
+### Array Position
+- **Type**: Number or dynamic reference
+- **Options**:
+  - **Fixed Number**: Static position (0, 1, 2, ...)
+  - **msg.***: Dynamic position from message property
+  - **flow.***: Position from flow context
+  - **global.***: Position from global context
+- **Range**: Non-negative integers (0-based indexing)
+- **Purpose**: Determines where this data appears in the final array
+
+## Performance Notes
+
+### Array Assembly Strategy
+- **Position Tagging**: Lightweight metadata addition with minimal processing overhead
+- **Memory Efficient**: Only stores references and position information
+- **Parallel Collection**: Multiple array-in nodes can operate simultaneously
+- **Order Preservation**: Maintains correct data sequence regardless of processing timing
+
+### Status Display
+- **Processing Info**: Shows array position and data type
+- **Validation**: Indicates successful data extraction
+- **Error Handling**: Displays warnings for missing data or invalid positions
+
+## Real-World Examples
+
+### Basic Multi-Image Collection
+```
+[Image-In: photo1.jpg] → [Array-In: pos=0] ┐
+[Image-In: photo2.jpg] → [Array-In: pos=1] ├→ [Array-Out] → [Resize All]
+[Image-In: photo3.jpg] → [Array-In: pos=2] ┘
+```
+Collect three images into an ordered array for batch processing.
+
+### Dynamic Position Assignment
+```
+[Process Data] → [Set msg.index] → [Array-In: pos=msg.index] → [Array-Out]
+```
+Use dynamic positioning based on processing results.
+
+### Mixed Data Sources
+```
+[msg.image1] → [Array-In: pos=0] ┐
+[flow.image2] → [Array-In: pos=1] ├→ [Array-Out] → [Concat Images]
+[global.image3] → [Array-In: pos=2] ┘
+```
+Combine data from different context levels.
+
+### Conditional Assembly
+```
+[Switch] → [Array-In: pos=flow.nextIndex] → [Array-Out]
+```
+Dynamic array building based on conditions.
+
+## Common Issues & Troubleshooting
+
+### Position Conflicts
+- **Issue**: Multiple nodes using same position
+- **Solution**: Ensure each array-in node has unique position when feeding same array-out
+- **Best Practice**: Use sequential positions starting from 0
+
+### Missing Data
+- **Issue**: Input path contains no data
+- **Result**: `meta.arrayData` set to `null`
+- **Solution**: Verify data exists at specified input path before processing
+
+### Dynamic Position Errors
+- **Issue**: Position resolves to non-integer or negative value
+- **Solution**: Validate dynamic position sources return valid array indices
+- **Check**: Use debug node to verify position values
+
+### Array Gaps
+- **Issue**: Non-sequential positions create sparse arrays
+- **Result**: Array contains undefined elements at missing positions
+- **Solution**: Use sequential positions or handle sparse arrays in downstream nodes

package/docs/nodes/io/array-out.md

@@ -0,0 +1,150 @@
+# Array-Out Node
+
+## Purpose & Use Cases
+
+The `array-out` node serves as the collection point for multiple `array-in` nodes, assembling ordered arrays from parallel data streams. It provides timeout protection and ensures data integrity during the assembly process.
+
+**Real-World Applications:**
+- **Batch Image Processing**: Assemble multiple images for simultaneous operations
+- **Multi-Camera Synchronization**: Collect frames from multiple cameras in sequence
+- **Parallel Pipeline Merging**: Combine results from parallel processing workflows  
+- **Data Aggregation**: Merge processed data from multiple sources
+- **Quality Control**: Collect inspection results from multiple checkpoints
+
+![Array-Out Demo](../../../assets/nodes/io/array-out-demo.gif)
+
+## Input/Output Specification
+
+### Inputs
+Messages from `array-in` nodes containing:
+```javascript
+{
+  ...originalMessage,
+  payload: any,           // Fallback data source
+  meta: {
+    arrayPosition: number,  // Position index (0, 1, 2, ...)
+    arrayData: any         // Preferred data source (takes priority over payload)
+  }
+}
+```
+
+**Data Extraction Priority**: The node prefers `msg.meta.arrayData` but falls back to `msg.payload` if arrayData is undefined.
+
+### Outputs
+
+#### Output 1 - Complete Array (Success)
+```javascript
+[data0, data1, data2, ...]  // Ordered array of collected data
+```
+
+#### Output 2 - Timeout Data (Error)
+```javascript
+{
+  [outputPath]: [data0, null, data2, ...],  // Partial array in configured location
+  meta: {
+    timeout: true,                     // Timeout flag
+    missingPositions: [1, 4],         // Positions that didn't arrive  
+    collectedPositions: [0, 2, 3],    // Positions that were collected
+    expectedCount: 5,                 // Number expected
+    collectedCount: 3,                // Number actually collected
+    elapsed: 5000                     // Time elapsed in milliseconds
+  }
+}
+```
+
+## Configuration Options
+
+### Expected Count
+- **Type**: Number (required)
+- **Range**: Minimum 1
+- **Purpose**: Number of array elements required before output
+- **Validation**: Must match the number of connected array-in nodes
+- **Impact**: Array assembly completes when this many elements are collected
+
+### Timeout
+- **Type**: Number (milliseconds)
+- **Default**: 5000ms (5 seconds)
+- **Range**: Minimum 100ms
+- **Purpose**: Maximum wait time for all elements after first message
+- **Behavior**: Sends partial data to output 2 on timeout
+
+### Output Location
+- **Default**: `msg.payload`
+- **Options**:
+  - `msg.*` - Store in message property
+  - `flow.*` - Store in flow context
+  - `global.*` - Store in global context
+- **Purpose**: Where to store the assembled array
+
+## Performance Notes
+
+### Assembly Strategy
+- **Efficient Collection**: Uses position-based indexing for O(1) insertion
+- **Memory Management**: Minimal overhead during collection
+- **Timeout Protection**: Prevents indefinite waiting for missing data
+- **State Reset**: Automatic cleanup between collection cycles
+
+### Status Display
+- **Collection Progress**: Shows number of items collected vs expected
+- **Success Timing**: Displays total assembly time on completion
+- **Timeout Warning**: Indicates when timeout occurs with diagnostic info
+
+## Real-World Examples
+
+### Basic Image Array Assembly
+```
+[Image-In: img1.jpg] → [Array-In: pos=0] ┐
+[Image-In: img2.jpg] → [Array-In: pos=1] ├→ [Array-Out: count=3, timeout=500] → [Resize: All Images]
+[Image-In: img3.jpg] → [Array-In: pos=2] ┘
+```
+Collect three images for batch resizing.
+
+### Multi-Camera Frame Collection
+```
+[Camera 1] → [Array-In: pos=0] ┐
+[Camera 2] → [Array-In: pos=1] ├→ [Array-Out: count=4, timeout=100] → [Sync Analysis]
+[Camera 3] → [Array-In: pos=2] │
+[Camera 4] → [Array-In: pos=3] ┘
+```
+Synchronize frames from multiple cameras with tight timing.
+
+### Parallel Processing Merge
+```
+→ [Process A] → [Array-In: pos=0] ┐
+→ [Process B] → [Array-In: pos=1] ├→ [Array-Out: count=3, timeout=500] → [Combine Results]
+→ [Process C] → [Array-In: pos=2] ┘
+```
+Merge results from parallel processing pipelines.
+
+### Quality Control Assembly
+```
+[Inspection A] → [Array-In: pos=0] ┐
+[Inspection B] → [Array-In: pos=1] ├→ [Array-Out: timeout=10000] → [Final Report]
+[Inspection C] → [Array-In: pos=2] ┘
+```
+Collect quality control results with extended timeout.
+
+## Common Issues & Troubleshooting
+
+### Timeout Issues
+- **Issue**: Frequent timeouts preventing array completion
+- **Causes**: Slow upstream processing, network delays, missing data
+- **Solutions**: 
+  - Increase timeout value for slow processes
+  - Add debug nodes to identify bottlenecks
+  - Implement fallback logic using output 2
+
+### Count Mismatch
+- **Issue**: Expected count doesn't match number of array-in nodes
+- **Result**: Perpetual waiting or premature completion
+- **Solution**: Verify expected count equals number of connected array-in nodes
+
+### Position Conflicts
+- **Issue**: Multiple array-in nodes using same position
+- **Result**: Data overwrites, array count confusion
+- **Solution**: Ensure each array-in node has unique position
+
+### Missing Metadata
+- **Issue**: Messages arriving without proper meta.arrayPosition
+- **Result**: Messages ignored, incomplete arrays
+- **Solution**: Verify all input messages come from array-in nodes

package/docs/nodes/io/array-select.md

@@ -0,0 +1,157 @@
+# Array-Select Node
+
+## Purpose & Use Cases
+
+The `array-select` node provides powerful array element selection with Python-like slicing syntax. It extracts specific elements, ranges, or patterns from arrays, making it essential for filtering and selecting processed results.
+
+**Real-World Applications:**
+- **Result Filtering**: Select best results from batch processing operations
+- **Data Sampling**: Extract samples from large datasets for analysis
+- **Quality Control**: Pick specific items that passed validation
+- **A/B Testing**: Select specific variants for comparison
+- **Image Gallery Creation**: Choose specific images from collections
+
+![Array-Select Demo](../../../assets/nodes/io/array-select-demo.gif)
+
+## Input/Output Specification
+
+### Inputs
+- **Array Data**: Input array from the configured path
+- **Selection String**: Pattern specifying which elements to extract
+
+### Outputs
+- **Single Element**: Direct element output (unless Force Array enabled)
+- **Multiple Elements**: Always output as array
+- **Invalid Selection**: No message sent, warning logged
+
+## Configuration Options
+
+### Input From
+- **Default**: `msg.payload`
+- **Options**:
+  - `msg.*` - Read from message property
+  - `flow.*` - Read from flow context
+  - `global.*` - Read from global context
+- **Validation**: Input must be an array
+
+### Selection Pattern
+- **Type**: String with flexible syntax
+- **Formats**:
+  - **Single Index**: `0`, `2`, `-1`
+  - **Multiple Indices**: `1,3,5` (comma-separated)
+  - **Range**: `1:4` (slice from index 1 to 3)
+  - **Step Pattern**: `0::2` (every 2nd element)
+  - **Negative Indexing**: `-1` (last), `-2:` (last two)
+
+### Force Array
+- **Type**: Boolean checkbox
+- **Default**: false
+- **Behavior**: When enabled, single elements output as arrays
+- **Use Case**: Ensure consistent array output format
+
+## Performance Notes
+
+### Selection Efficiency
+- **Minimal Memory Copy**: Efficient element extraction without full array duplication
+- **Index Validation**: Fast bounds checking with graceful error handling
+- **Pattern Parsing**: Optimized pattern recognition and processing
+- **Status Display**: Real-time selection information and processing state
+
+### Error Handling
+- **Input Validation**: Comprehensive array and pattern validation
+- **Graceful Degradation**: Invalid indices skipped with warnings
+- **Bounds Checking**: Out-of-range indices handled safely
+
+## Selection Syntax Guide
+
+### Basic Selection
+```
+Array: ["A", "B", "C", "D", "E"]
+
+0      → "A"         // First element
+-1     → "E"         // Last element
+1,3    → ["B", "D"]  // Multiple specific indices
+```
+
+### Range Selection
+```
+Array: ["A", "B", "C", "D", "E"]
+
+1:4    → ["B", "C", "D"]  // Range from 1 to 3
+0:3    → ["A", "B", "C"]  // First three elements
+-2:    → ["D", "E"]       // Last two elements
+```
+
+### Step Patterns
+```
+Array: ["A", "B", "C", "D", "E", "F"]
+
+0::2   → ["A", "C", "E"]     // Every 2nd starting at 0
+1::2   → ["B", "D", "F"]     // Every 2nd starting at 1
+1:5:2  → ["B", "D"]          // Range 1-4, every 2nd
+```
+
+### Advanced Patterns
+```
+Array: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+
+::3     → [0, 3, 6, 9]       // Every 3rd element
+2:8:2   → [2, 4, 6]          // Range 2-7, step 2
+-3:     → [7, 8, 9]          // Last 3 elements
+:-3     → [0, 1, 2, 3, 4, 5, 6]  // All but last 3
+```
+
+## Real-World Examples
+
+### Best Result Selection
+```
+[Batch Process] → [Array-Out] → [Array-Select: "0,2,4"] → [Top Results]
+```
+Select 1st, 3rd, and 5th results from batch processing.
+
+### Quality Control Sampling
+```
+[Production Line] → [Array-Out] → [Array-Select: "::10"] → [Quality Check]
+```
+Sample every 10th item for quality inspection.
+
+### Image Gallery Creation
+```
+[Image Array] → [Array-Select: "1:6"] → [Display Gallery]
+```
+Select images 2-6 for gallery display.
+
+### A/B Test Splitting
+```
+[User Array] → [Array-Select: "0::2"] → [Group A]
+            → [Array-Select: "1::2"] → [Group B]
+```
+Split users into alternating test groups.
+
+### Last N Results
+```
+[Processing Queue] → [Array-Out] → [Array-Select: "-5:"] → [Recent Results]
+```
+Get the last 5 processed items.
+
+## Common Issues & Troubleshooting
+
+### Invalid Input Type
+- **Issue**: Input is not an array
+- **Result**: Warning logged, message not sent
+- **Solution**: Verify input is array type, use array-out to create arrays
+
+### Out of Bounds Indices
+- **Issue**: Selection indices exceed array length
+- **Result**: Invalid indices ignored, partial results returned
+- **Example**: Array length 5, selection "1,3,7" returns elements at indices 1,3 only
+
+### Empty Selection Results
+- **Issue**: Selection pattern matches no elements
+- **Result**: Empty array `[]` output
+- **Common Cause**: Range beyond array bounds
+
+### Syntax Errors
+- **Issue**: Invalid selection pattern syntax
+- **Result**: Warning logged, message not sent
+- **Solution**: Verify pattern follows documented syntax

package/docs/nodes/io/queue.md

@@ -0,0 +1,57 @@
+# Queue Node
+
+## Purpose & Use Cases
+
+The `queue` node buffers incoming messages, enforces a minimum interval between outputs, and discards stale entries. It helps coordinate bursty producers with slower consumers by smoothing throughput and avoiding overload.
+
+**Common Scenarios:**
+- Throttle high-frequency image sources before storage or slow analysis stages
+- Prevent downstream rate limits from being exceeded when batch processing arrays
+- Provide simple back-pressure where only a fixed number of messages can be buffered
+- Drop stale detections or frames that are no longer relevant after a timeout
+
+## Input/Output Specification
+
+### Inputs
+- **Incoming Message**: Any Node-RED message to be enqueued.
+
+### Outputs
+- **Queued Message**: Messages are forwarded in FIFO order while respecting the configured interval.
+
+When timeout mode is selected, messages that exceed the configured timeout are silently discarded with a warning in the node's log.
+
+## Configuration Options
+
+### Mode
+- **Type**: Dropdown (`Queue Size Limit` / `Timeout`)
+- **Default**: `Queue Size Limit`
+- **Purpose**: Select whether the node enforces a hard buffer capacity or lets messages expire after a timeout; the controls shown below change depending on the selected mode.
+
+### Queue Size Limit
+- **Type**: Number (integer)
+- **Default**: `0` (no limit)
+- **Purpose**: Available only in queue-size mode. Controls how many messages may be enqueued before excess messages are ignored.
+
+### Timeout (ms)
+- **Type**: Number (integer)
+- **Default**: `0` (no timeout)
+- **Purpose**: Available only in timeout mode. Messages that stay longer than this duration are removed before they reach the output.
+
+### Interval (ms)
+- **Type**: Number (integer)
+- **Default**: `0` (no enforced delay)
+- **Purpose**: Minimum time that must elapse between forwarded messages. When set to 0, messages flow out as soon as they are available.
+
+## Behavior & Status
+
+- Messages are processed in first-in-first-out order.
+- The node emits messages immediately when the interval requirement has already been satisfied.
+- If necessary, the node waits the remaining interval before releasing the next message.
+- When messages expire due to timeout (and timeout mode is active) they are removed from the queue and a warning is logged.
+- Node status indicates whether the queue is idle, holding messages, or actively sending.
+
+## Best Practices
+
+- Pair with Array nodes to control the rate of batch processing pipelines.
+- Use timeouts to keep sensor readings or camera frames current.
+- Combine with Catch or Status nodes to monitor when the queue reaches capacity or drops messages.

package/docs/nodes/io/save-file.md

@@ -0,0 +1,30 @@
+# save-file
+
+Write incoming data to disk as an image, JSON, text, or binary file. The node can auto-detect the best mode from the payload or a provided filename/extension.
+
+## Inputs
+- **payload** (default): Data to write. Supports raw image objects (`{data,width,height,channels,colorSpace}`), encoded image buffers, plain objects/arrays, strings, or buffers.
+- **Alternative path**: Use the *Input* field to read from any `msg`/`flow`/`global` property.
+
+## Properties
+- **Folder** (*str | env | msg | flow | global*) – Destination directory. Created if missing.
+- **Filename** (*str | msg | flow | global*) – Optional name without path separators. If left blank, a timestamped name is generated. If you include an extension here, it is respected.
+- **File Type** (*auto | image | json | text | binary*) – Force the save mode or let the node decide. Auto uses the extension, raw image structure, or Sharp metadata for buffers.
+- **Image Format** (*jpg | png | webp*) – Encoding for image saves. Quality and PNG optimization are available.
+- **JSON Indent** – Spacing for pretty-printed JSON output.
+- **Overwrite protection** – Enabled by default; adds a numeric suffix when the file already exists.
+- **Result to** – Where to store summary metadata `{ path, filename, type, extension, sizeBytes, format? }` (default `msg.savedFile`).
+
+## Behavior
+- Raw image inputs are validated and encoded with Sharp; BGR/BGRA channels are auto-swapped.
+- JSON inputs are pretty-printed; valid JSON strings are kept as-is.
+- Text mode writes stringified content; binary mode writes buffers directly (or stringified when not a buffer).
+- When overwrite protection is enabled, the node keeps adding `_<n>` until a free filename is found.
+
+## Status
+- Shows the final filename, duration, and whether an overwrite was avoided.
+
+## Example flows
+- Save final inference results as `results.json` in `/data/out`.
+- Persist camera frames as WebP by setting *File Type = image* and *Image Format = webp*.
+- Archive arbitrary payloads by pointing *Input* to `msg.myBuffer` and enabling overwrite protection.

package/docs/nodes/promise-reader/promise-reader.md

@@ -0,0 +1,60 @@
+# Promise Reader Node
+
+## Purpose & Use Cases
+
+The `promise-reader` node resolves an array of promises stored on the message, merges their results into the message, and records simple performance timing. It is useful when upstream nodes perform parallel async work (for example, multiple inference calls) and return promises instead of immediate results.
+
+**Typical scenarios:**
+- Collect results from multiple asynchronous HTTP or inference requests
+- Merge parallel processing outputs into one message
+- Aggregate timing data across async tasks
+
+## Input/Output Specification
+
+### Inputs
+- **Promise Array**: An array of promises at the configured message path (default `msg.promises`).
+
+### Outputs
+On success, the node merges resolved values into the original message and removes the promise array:
+
+```javascript
+{
+  ...originalMessage,
+  // resolved values merged into the message
+  resultA: {...},
+  resultB: {...},
+  performance: {
+    "promise-reader": {
+      startTime: 1680000000000,
+      endTime: 1680000000500,
+      milliseconds: 500
+    }
+  }
+}
+```
+
+If the configured field is missing or not an array, the node warns and passes the message through unchanged.
+
+## Configuration Options
+
+### Field to read
+- **Default**: `promises`
+- **Type**: Message path (dot notation supported)
+- **Purpose**: Location of the promise array (e.g. `inference.promises`).
+
+## Behavior
+
+- Validates that the field is an array.
+- Ensures every entry is a promise/thenable; otherwise logs an error and stops.
+- Resolves all promises in parallel using `Promise.all()`.
+- Merges resolved objects into the message. If both sides are plain objects, it deep-merges; otherwise later values overwrite earlier ones.
+- Aggregates timing from any resolved value that contains a `performance` object with `startTime` and `endTime` fields.
+- Deletes the original promise array from the message before sending.
+
+If any promise rejects, the node logs a warning and does not send an output message.
+
+## Common Issues & Troubleshooting
+
+- **Non-array field**: Ensure `msg.promises` (or your configured path) is an array.
+- **Non-promise entries**: Verify each element is a promise or thenable object.
+- **Rejected promise**: Handle errors upstream or add retries so Promise.all can resolve.

package/docs/nodes/util/block-detect.md

@@ -0,0 +1,46 @@
+# Block Detect Node
+
+## Purpose & Use Cases
+
+The `block-detect` node gives you a lightweight watchdog that keeps an eye on Node-RED's event loop. When long running synchronous work or runaway CPU usage blocks the event loop, flows become sluggish, timers fire late, and HTTP endpoints stall. Dropping this node anywhere in your workspace makes it easy to detect those situations without wiring any messages.
+
+**Typical scenarios**
+
+- **Production health checks** — raise a warning in the runtime log when flows or custom code keep the event loop busy for too long.
+- **Profiling new nodes** — temporarily add the node next to experimental flows to confirm they remain non-blocking.
+- **Shared environments** — monitor collaborative / multi-tenant Node-RED instances for noisy neighbours that block everyone else.
+
+## How It Works
+
+- The node samples the Node.js [`monitorEventLoopDelay`](https://nodejs.org/api/perf_hooks.html#perf_hooks_monitor_event_loop_delay_options) histogram every *N* milliseconds (default one second).
+- When the measured delay exceeds the configured threshold for a number of consecutive samples, the node writes an alert to the runtime log (`warn`, `error`, or plain `log`) and changes its editor status to red.
+- If `monitorEventLoopDelay` is unavailable (very old Node.js builds), it falls back to measuring timer drift, which still provides a useful signal with minimal CPU overhead.
+- A cooldown timer prevents log flooding when the system stays blocked for longer periods.
+
+## Configuration
+
+| Option | Description |
+|--------|-------------|
+| **Threshold (ms)** | Maximum acceptable event loop delay. Samples above this value count as "blocking". Default: `120 ms`. |
+| **Sample interval (ms)** | How often to collect a measurement. Smaller values react faster but use slightly more CPU. Default: `1000 ms`. |
+| **Consecutive hits** | Number of back-to-back samples that must exceed the threshold before an alert fires. Helps filter out one-off spikes. Default: `1`. |
+| **Cooldown (ms)** | Minimum time between alerts so your logs do not get spammed while a problem persists. Default: `30,000 ms`. |
+| **Show live delay metrics** | When enabled (default) the node's status displays the latest average and max delay so you can watch it in real time. |
+
+The node has no inputs or outputs and can sit anywhere in your flow.
+
+> The watchdog internally samples `monitorEventLoopDelay` with a medium (20 ms) resolution, which provides enough fidelity for alerts while keeping CPU overhead negligible.
+
+Alerts are always emitted with `node.warn(...)` so they appear in the standard Node-RED log without additional configuration.
+
+## Interpreting the Status
+
+- **Green dot** — Event loop delay is within the safe range.
+- **Yellow ring** — Recent samples exceeded the threshold but not enough to trigger an alert yet.
+- **Red dot** — Blocking detected. Check the runtime log for details about the max/avg delay.
+
+## Tips
+
+- Run multiple watchdogs with different thresholds (for example *warn at 120 ms*, *error at 500 ms*) if you want layered alerting.
+- Pair the node with system level monitoring (CPU, memory) to quickly confirm whether the blocking originated from Node-RED or external processes.
+- Because the watchdog is passive and does not emit messages, it is safe to leave it deployed permanently even in large workspaces.