Skip to content

fix(node): support Electron host on Windows#28

Open
JackCaow wants to merge 1 commit into
arcships:mainfrom
JackCaow:codex/fix-electron-win-delay-load
Open

fix(node): support Electron host on Windows#28
JackCaow wants to merge 1 commit into
arcships:mainfrom
JackCaow:codex/fix-electron-win-delay-load

Conversation

@JackCaow

@JackCaow JackCaow commented Jul 21, 2026

Copy link
Copy Markdown

Summary

  • delay-load node.exe and link a Windows host redirection hook into the final Node-API addon;
  • fail Windows builds when the generated PE imports node.exe normally instead of through the delay-import directory;
  • run an Electron 37.10 explicit-CPU OCR smoke on the compiled Windows runtime;
  • document the Windows renamed-host contract without claiming complete Electron lifecycle support.

Fixes #27.

Root cause

The published Windows addon links Node/N-API exports through a normal node.exe PE import. This works when the host executable is Node itself, but a renamed Node-API host such as Electron cannot redirect that normal import. On the reported machine Windows loaded an unrelated node.exe from PATH, and N-API calls entered an uninitialized Node image, causing a process-fatal execute access violation before ONNX Runtime session creation.

Linking node.lib is not itself the defect: that import library commonly records node.exe as the symbol provider. The missing piece is the established Windows delay-load hook that redirects the request to an already loaded libnode.dll or the current process executable.

Fix

  • add /DELAYLOAD:node.exe and link delayimp;
  • link win_delay_load_hook.cpp, resolving libnode.dll first and otherwise GetModuleHandleW(nullptr);
  • inspect the generated PE after linking and reject a normal node.exe import or a missing delayed import;
  • keep the addon host-name agnostic—there is no product-specific echoo.exe/electron.exe rewrite.

Validation

GitHub Actions run: https://github.com/JackCaow/light-ocr/actions/runs/29826497872

Both windows-x64 contract and linux-x64 contract passed for commit 8fe3dfedad3f402d9e769e2e5df8aa1f3db234fc.

Windows PE gate:

{
  "delayImports": ["node.exe"],
  "normalImports": ["onnxruntime.dll", "KERNEL32.dll", "MSVCP140.dll"]
}

Windows Electron smoke:

{
  "electron": "37.10.0",
  "node": "22.21.1",
  "platform": "win32-x64",
  "requestedProvider": "cpu",
  "actualProvider": "CPUExecutionProvider",
  "text": "HELLO 123"
}

Additional gates passed in the same run:

  • Windows MSVC configure, compile, link, CTest, and staged-runtime verification;
  • Node runtime loading from a sterile directory;
  • release metadata, descriptor, license, and SBOM generation;
  • Python PE parser tests rejecting the published direct-import shape;
  • Linux contract build and test matrix.

Compatibility and scope

The hook preserves normal Node support and supports differently named Electron executables without editing the compiled PE per consumer. This PR validates the Windows host-binding contract and an Electron 37 CPU smoke; it does not promote Electron to full Tier 1 support for ASAR, worker, or lifecycle behavior.

@JackCaow
JackCaow marked this pull request as ready for review July 21, 2026 15:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Windows addon crashes Electron because node.exe is not delay-loaded

1 participant