The Resource Watchdog is an automated resilience and monitoring system built into the InkRider add-in. Because Python code executes locally within your browser's WebAssembly sandbox (Pyodide), intensive computations, large datasets, or accidental infinite loops can consume significant system memory or cause the browser tab to become unresponsive.

The Resource Watchdog operates continuously in the background, tracking kernel health, memory consumption, and execution duration. When thresholds are breached, it provides immediate visual warnings and safe intervention paths, ensuring you never lose unsaved work in Microsoft Word.

---

Key Monitoring Capabilities

1. WebAssembly Heap Memory Tracking

WebAssembly runtimes operate within a dedicated memory sandbox allocated by the browser. If a Python script loads massive DataFrames or generates large in-memory arrays without cleanup, the sandbox can approach the browser's hard memory limit (typically 2GB to 4GB depending on the browser and architecture).

• Proactive Polling: The Watchdog polls performance.memory every few seconds during active execution.
• Warning Threshold (85%): When memory usage exceeds 85% of the allocated ceiling, the Watchdog displays a warning banner with a Restart Kernel option.

2. Execution Stall & Infinite Loop Detection

A common hazard in interactive notebook authoring is an accidental infinite while loop or an unoptimized recursive calculation. In standard web applications, an infinite loop freezes the entire JavaScript main thread, locking up the UI and forcing the user to kill the browser process.

• Worker Decoupling: InkRider executes all Python kernels inside dedicated Web Workers, keeping the main Word add-in UI completely responsive even if Python locks up.
• Stall Timer: The Watchdog tracks the duration of every individual cell execution. If a cell runs continuously for more than 45 seconds without yielding or completing, the Watchdog flags the kernel as potentially unresponsive.
• Intervention Prompt: A banner appears alerting you that the kernel is unresponsive, offering a one-click Kill & Restart Kernel action.

---

Responding to Watchdog Alerts

When a Watchdog banner appears, you have several options to restore optimal performance:

Restarting the Kernel

Clicking the Restart Kernel button inside the warning banner immediately sends a termination signal to the underlying Web Worker, discards the bloated memory sandbox, and spins up a fresh, clean Python runtime in less than a second.

Note: Restarting the kernel clears all in-memory variables and imported modules. You will need to re-run your notebook cells to restore state.

Reclaiming Memory Manually

If you receive a memory warning but wish to finish your current calculation without restarting, you can manually free memory within your Python code:

import gc

# Delete large DataFrames or arrays that are no longer needed
del massive_dataframe
del temporary_matrix

# Force garbage collection to return memory to the WebAssembly heap
gc.collect()

---

Architectural Summary

Feature	Mechanism	Benefit
Worker Isolation	Pyodide runs in a background Web Worker	Main Word UI never freezes; add-in remains 100% responsive.
Memory Gauges	Polling performance.memory	Early warning system prevents sudden browser tab crashes.
Stall Watchdog	Active execution heartbeat timer	Detects infinite loops and provides a clean kill switch.
State Decoupling	Document VFS is managed on the main thread	Restarting a crashed kernel never corrupts or loses your Word document files.