PowerShell SDK architecture¶
This page explains how the NativeHTMLKit module turns a PowerShell script into a native desktop
app, so that the rules in the guides (side effects below Start-NativeHTMLKitScript, callbacks on
one runspace, plain data for background work) make sense. It describes module 0.1.2 with Core
1.0.3 and wire protocol v1.
Two processes¶
+---------------------------+ private local channel +---------------------------+
| nativehtmlkit-host (Rust) | <--- length-prefixed JSON-RPC ---> | PowerShell backend |
| windows, input, layout, | Unix socket / named pipe | your script + this module |
| rendering, accessibility, | | state, logic, callbacks |
| native dialogs, clipboard | | |
+---------------------------+ +---------------------------+
- The host is the native NativeHTMLKit Core executable bundled in the module
(
runtimes/linux-x64,runtimes/win-x64). It owns everything the user sees and touches: the windows, the HTML/CSS engine (no browser and no JavaScript), input methods, accessibility trees and operating-system services. - The backend is a PowerShell process running your script. It holds your data and logic and
tells the host what to show. The module is the backend half of the protocol: a C# transport
compiled at import (
Private/NativeHTMLKit.Transport.cs), the cmdlets (NativeHTMLKit.psm1), background tasks and diagnostics. - They talk over a private, authenticated local channel: a Unix-domain socket (Linux) or a
restricted named pipe (Windows), never TCP or HTTP. The host creates it, starts the backend with
UI4ME_ENDPOINTand a one-timeUI4ME_TOKEN, and the backend proves the token inhost.hello. Messages are 4-byte length prefixes plus UTF-8 JSON-RPC 2.0, at most 2 MiB each.
The host supervises the backend: it enforces startup and shutdown deadlines, stops it when the app quits, and reports a backend that disappears without an accepted quit as an application failure.
How a script becomes a backend¶
Start-NativeHTMLKitScript makes a normal .ps1 file both launcher and backend:
pwsh -File app.ps1 args (launcher run)
Start-NativeHTMLKitScript
writes private app.toml -> starts nativehtmlkit-host run --app app.toml
host starts: pwsh -NoProfile -NonInteractive -File app.ps1 args (backend run)
Start-NativeHTMLKitScript -> Connect -> returns $app
... your code: windows, documents, handlers, ready, wait ...
waits for the host; exit <host exit code>
The launcher role is chosen when the UI4ME_* variables are absent; it validates the options,
resolves and verifies the host binary (SHA-256 against HOST-MANIFEST.json), writes the manifest
into a folder only the current user can access, starts the host (on Linux through
setpriv --pdeathsig so the host stops if the launcher is killed), relays the host's records to
the console as plain text, and finally exits with the host's exit code. The backend role connects
and removes the launch secrets from its environment so programs it starts cannot inherit them.
Everything above the call therefore runs twice, which is why side effects belong below it.
Manifest-based deployments skip the launcher: the host is started with an explicit app.toml and
the backend only connects.
One owner runspace, one event pump¶
The transport's reader is a .NET thread that parses frames into a bounded queue; it never runs PowerShell code. PowerShell code runs only on the owner runspace, the one that created the application, when it pumps the queue:
Wait-NativeHTMLKitpumps explicitly;- every SDK command that needs a reply pumps while it waits, so events can be handled in the middle
of, for example,
Get-NativeHTMLKitValue.
Messages are handled in host order. Replies complete waiting requests; host requests
(window.before_close, app.before_quit) run your policy scriptblock and are answered at once,
even inside a nested wait, so the host is never left waiting on a decision; host
notifications (document.event, window.event, desktop.preferences_changed, ...) run your
callbacks one at a time. While a callback runs, further notifications are deferred until it
returns (bounded at 128; extra ones are dropped and counted). A failing callback is isolated:
logged, counted, and the app continues.
This single-threaded model is why SDK objects must not be shared with other runspaces, why long
work in a callback freezes the window, and why Start-NativeHTMLKitTask exists.
Handles and their lifetime¶
The SDK mirrors host objects as small handle objects: application, window, document, node, live
bitmap, request, subscription, task. Each handle knows its owner and whether it is still current.
The host's lifecycle events retire them: a closed window retires its document; loading a new
document retires the previous one together with its subscriptions, nodes and bitmaps;
app.shutdown retires every window (the host sends no separate closed event for the last
window); Close-NativeHTMLKit retires everything and removes all callbacks. A retired handle
throws NativeHTMLKit.StaleObjectException locally instead of sending a request the host would
reject.
Documents and commands¶
A document is HTML and CSS rendered by the host. The backend changes it with document commands
(document.command with an op such as set_text, insert_html, batch, get_form_data); the
typed cmdlets are thin wrappers that build these commands, and Invoke-NativeHTMLKitDocumentCommand
reaches the rest of the 81 operations. Elements are addressed by id, or by generation-bound node
references for elements without ids. Events travel the other way as document.event notifications
that carry the element id, the id path, the target node reference and event-specific fields;
the SDK matches them against subscriptions (type plus id on the path) after native dispatch.
Live bitmaps bypass the message channel for pixels: the host creates a file mapping with two or
three frame slots, the backend writes a frame into the next slot and sends a small bitmap.present
request.
Background work¶
Start-NativeHTMLKitTask runs a scriptblock in a fresh runspace (its text is re-parsed there, so no
variables, functions or modules carry over) and refuses SDK objects among its arguments. The pump
checks for finished tasks between messages and runs -OnCompleted/-OnFailed on the owner
runspace, never inside another callback. Limits (8 per application, 32 per process) count workers
until their thread really ends, because cancellation is only a request.
Diagnostics¶
The SDK records redacted, allow-listed events into an in-memory ring (2048 records) according to
NATIVEHTMLKIT_DIAGNOSTICS. A session ID shared through the environment correlates SDK records,
host records and the backend. Export-NativeHTMLKitSupportBundle writes these records and counters
to a ZIP only when called; nothing leaves the machine.
Boundaries¶
- The SDK depends only on the public Core wire protocol v1; it does not use Core internals.
- Declarative components and reactive state are not part of the SDK; a layer for them must use only the public cmdlets of this SDK.
- Platforms: PowerShell 7.2+ on Linux x64 and Windows x64; Windows PowerShell 5.1 on Windows (the C# transport compiles against .NET Framework there). Native behaviour is qualified per platform; see the capability matrix.
Source: nativehtmlkit-powershell/docs/ARCHITECTURE.md ยท edit the page there.