Native browser windows for Matrix and the NIL Framework. The public API is written in Matrix; small providers use GTK4/WebKitGTK on Linux, WebView2 on Windows, and WKWebView on macOS.
API · Platform support · Migration · Contributing · Security
This is the initial implementation. Shared ownership, JSON transport and checked framework integration have local automated coverage. The Matrix wrapper has been exercised with a synthetic provider through textual NIL, binary NIL, native compilation and JIT. Actual browser qualification on Linux, Windows, Intel macOS and Apple Silicon macOS is pending. A synthetic provider pass does not establish browser behavior or qualify a published SDK.
The current profile provides hidden-window creation, explicit showing, navigation, loading HTML, synchronous JavaScript function evaluation, copied events, page messages and closing. It does not provide every feature of the archived Ny WebView library; the migration table records each legacy function.
Import nilwebview and configure an explicit absolute path to a trusted native
provider library. Create a window, poll for Ready, and then show it or start
an operation. Polling drives the browser on the process UI thread. Navigation
and script calls return operation identities; their completion events carry
the same identities. The application decides when to close a window.
Pages send JSON-serializable values through:
window.nilwebview.post({ kind: "message", text: "Hello from the page" });Matrix receives a PageMessage event containing serialized JSON text. This
bridge does not interpret messages as commands, launch processes, or grant
pages filesystem access. Applications decide what each message means.
Sender metadata has explicit capabilities and quality. GTK currently provides no authenticated sender URL, origin or frame metadata. A native sender URL alone is not proof of origin. Applications that require origin or frame checks must reject messages when the required native metadata is unavailable.
Navigation accepts HTTP, HTTPS and about:blank. Each explicit call authorizes
one initial request. Redirects and uninitiated navigation are cancelled and
reported as NavigationRequested; the application may validate the requested
destination and explicitly navigate after the previous operation completes.
Use a compatible NIL Framework build containing the checked webview.v1
intrinsics. A previous SDK without that bridge cannot run this revision.
See platform support for provider dependencies.
The exact source revision used by CI is pinned in
framework-revision.txt. The four platform jobs build
that compiler and standard library from source, verify the shared ABI headers,
and run both synthetic and actual-browser Matrix consumers through interpreted
and native execution. The same jobs also check the pinned framework's formatted
text and markup contracts with LLVM enabled on all four hosts. Provider binaries and SDKs are not published by these
source checks.
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release --parallel 2
ctest --test-dir build -C Release --output-on-failureOn Windows, first fetch the pinned WebView2 SDK with the repository's fetch
script and pass its extracted directory as NILWEBVIEW_WEBVIEW2_SDK to CMake.
WebView2 also requires an installed compatible browser runtime.
The message-console example loads
its bundled HTML, prints page messages and a JavaScript result in the terminal,
and closes when its native window is closed. It needs no HTTP server. Its
program arguments are --provider ABSOLUTE_LIBRARY --html ABSOLUTE_HTML_FILE.
The runner compiles the example and supplies its bundled HTML path:
python3 scripts/run-example.py --compiler "$NIL_COMPILER" \
--interpreter "$NIL_INTERPRETER" --nilstd "$NIL_STD" \
--provider "$NILWEBVIEW_PROVIDER"Set those variables to the compatible tools, standard-library source directory
and absolute provider library path. To compile directly, put the repository's
src directory on the Matrix import path and pass the program arguments after
the interpreter's -- separator. Use the example project's
nil.project.nildata when working through nilbuild or the editor.
The provider output is normally build/native/libnilwebview.so on Linux,
build/native/libnilwebview.dylib on macOS, or
build/native/Release/nilwebview.dll with a Visual Studio generator on Windows.
Resolve the actual output to an absolute path; loading code from an arbitrary
download or untrusted writable directory is not a supported trust boundary.
Text is valid UTF-8 without embedded NUL, with a 1 MiB limit per field. JSON can represent NUL as an escape. Contexts allow at most 16 windows; provider queues hold at most 256 events and 8 MiB including retained provider snapshots and metadata. Framework snapshot copies are also bounded. Initialization and operations have a 30-second deadline checked while polling.
A timeout makes the affected window unusable for new operations; close it and create another. Queue overflow is an explicit failure. The event pump has a bounded dispatch batch with a soft time budget; it is not a hard real-time deadline. See the API contract for ownership and failure details.
src/nilwebview/ Matrix API, types and copied event handling
native/include/ versioned provider C ABI and JSON grammar
native/src/ shared controls and platform providers
tests/ shared, transport, framework and desktop controls
examples/message-console/ local HTML and Matrix application
docs/ API, migration and platform evidence
scripts/ build/test support and source audit
You can support Execute Software through Ko-fi. Donations are optional and do not change the project's features or license. Original project materials use the MIT License. Platform browser engines, loaders and SDKs retain their own licenses and distribution terms.