Fix Node.js crash when calling browser-only functions (imshow, VideoCapture)

[Copilot]

cv.imshow() and cv.VideoCapture() crash in Node.js/tsx with ReferenceError: document is not defined, causing infinite error loops. These functions access DOM APIs without environment checks.

Changes

opencv.js patches

• Add typeof document === "undefined" guards to Module["imshow"] and Module["VideoCapture"]
• Throw actionable errors with Node.js alternatives instead of crashing

Automation & maintenance

• scripts/apply-opencv-patch.js: Automated patch application with error message constants
• dist/opencv.js.patch: Patch documentation for rebuild scenarios

Testing & docs

• test/nodejs-compatibility.test.ts: Validates error handling in Node.js environment
• README: New "Browser vs Node.js Compatibility" section clarifying function availability

Error message improvement

Before: Infinite ReferenceError crashes

ReferenceError: document is not defined
  at Module["imshow"] ...
  (repeats infinitely, freezing editor)

After: Clear, actionable error

cv.imshow("canvas", mat);
// Error: cv.imshow() is only available in browser environments.
// It requires DOM API (canvas element) which is not available in Node.js.
// For Node.js, please use alternative methods like cv.imwrite() to save images to files.

All other OpenCV operations (Mat, image processing, computer vision algorithms) continue working in both environments. Backward compatible - browser usage unchanged.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>I'm using TSX to load OpenCV-JS in TypeScript, and it's outputting errors like crazy, causing the editor to freeze and the program to crash.</issue_title>
<issue_description>Node Version: v18.17.1
OS：windows 10 x64

• test.ts

import cvModule, { CV } from "@techstark/opencv-js";

async function getOpenCv():Promise<{ cv: CV }> {
  let cv;
  if (cvModule instanceof Promise) {
    cv = await cvModule;
  } else {
    await new Promise((resolve) => {
      cvModule.onRuntimeInitialized = () => resolve(1);
    });
    cv = cvModule;
  }
  return { cv };
}

async function main() {
  const { cv } = await getOpenCv();
  console.log("OpenCV.js is ready!");
  // You can now use OpenCV functions here
  console.log(cv.getBuildInformation());
  let mat=new cv.Mat(100,100,cv.CV_8UC3,new cv.Scalar(255,0,0))
  cv.imshow("mat:",mat)
}

main();

Run command：

tsx ./test.ts

But if you really need to explain, keep it under 200 words:

• What happened
  • The program frantically outputs commands to the command line, causing it to freeze and crash.
• What I expected
  • Normal operation
• Error stack trace
  • Unable to track, the program outputs incessantly, causing the editor to freeze.
• Documentation links
  • opencv-js：https://www.npmjs.com/package/@techstark/opencv-js
  • tsx：https://www.npmjs.com/package/tsx
    </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes I'm using TSX to load OpenCV-JS in TypeScript, and it's outputting errors like crazy, causing the editor to freeze and the program to crash. #108

---

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