Reference: application lifecycle¶
Module NativeHTMLKit 0.1.2 (Core 1.0.3, wire protocol v1). Starting the host, connecting,
signalling readiness, pumping events, quitting and closing. Task-oriented explanation:
Script lifecycle guide.
All commands in this module are advanced functions: parameters bind by name or by position in
the order shown in the syntax blocks, and common parameters (-Verbose, -ErrorAction, ...) are
accepted. The module sets $ErrorActionPreference = 'Stop' internally, so every failure
described below is a terminating error that try/catch can handle.
Typical order¶
Import-Module NativeHTMLKit
$app = Start-NativeHTMLKitScript -Name 'My tool' # 1. host + backend connection
try {
$window = New-NativeHTMLKitWindow -Application $app # 2. at least one window
$doc = Open-NativeHTMLKitHtml -Window $window -Html '<p id="s">Ready</p>'
# 3. register events, policies, notifications
Set-NativeHTMLKitReady -Application $app # 4. startup finished
Wait-NativeHTMLKit -Application $app -UntilShutdown # 5. run callbacks until quit
} finally {
Close-NativeHTMLKit -Application $app # 6. retire every handle
}
Start-NativeHTMLKitScript¶
Alias: Start-NHKScript
Runs an ordinary .ps1 file as a NativeHTMLKit app and returns the connected
NativeHTMLKit.Application. It has two roles, chosen from the process environment:
- Launcher role (you ran the script with
pwsh -File app.ps1orpowershell.exe -File app.ps1): writes a private temporaryapp.toml, starts the native host (run --app, plus--headlesswhenNATIVEHTMLKIT_TEST_MODE=1), and waits. The host runs the same script again with the same PowerShell edition (-NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File) and the same arguments, as its supervised backend. When the host exits, the launcher callsexit <host exit code>: code below this call never runs in the launcher process. - Backend role (
UI4ME_ENDPOINTandUI4ME_TOKENare set by the host): connects likeConnect-NativeHTMLKit, removes the launch variables from the process environment so child processes cannot see them, and returns the application.
Everything above the call runs twice. Keep side effects (files, prompts, network calls) below it.
On Linux the launcher starts the host through setpriv --pdeathsig TERM when available, so the
host stops even if the launcher is killed. The temporary manifest folder is created with mode
0700 (Linux) or in the per-user %TEMP% (Windows) and removed afterwards; folders left by a
killed launcher are removed after one day.
Start-NativeHTMLKitScript [[-Name] <string>] [[-AppId] <string>] [[-Version] <string>] [[-Icon] <string>] [[-Instance] <string>] [[-StartupTimeoutMilliseconds] <int>] [[-ShutdownTimeoutMilliseconds] <int>] [[-MaxWindows] <int>] [[-ArgumentList] <string[]>] [[-ScriptPath] <string>] [[-Diagnostics] <string>] [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Name |
string |
no | - | Application name shown by the desktop (1-128 characters, no control characters). Default: the script file name without extension. |
-AppId |
string |
no | - | Reverse-DNS identity such as org.example.MyTool (letters, digits, _, -, dot-separated, at most 128). Default: local.nativehtmlkit.<name-slug>.h<12 hex digits of the script path hash>, stable per script path. |
-Version |
string |
no | - | Application version string (1-128 characters). |
-Icon |
string |
no | - | Path of an application icon file; must exist. |
-Instance |
string |
no | 'single' |
single forwards a second launch of the same AppId to the running app; multiple allows several instances. One of: single, multiple. |
-StartupTimeoutMilliseconds |
int |
no | 30000 |
Host limit for the backend to connect and call Set-NativeHTMLKitReady. Range 1000 to 300000. |
-ShutdownTimeoutMilliseconds |
int |
no | 5000 |
Host limit for the backend to exit after shutdown. Range 100 to 120000. |
-MaxWindows |
int |
no | 16 |
Maximum number of windows the host allows for this app. Range 1 to 64. |
-ArgumentList |
string[] |
no | - | Arguments for the backend run. Default: the arguments that followed the script on the pwsh/powershell.exe command line. |
-ScriptPath |
string |
no | - | Script to run as the backend. Default: the calling script ($MyInvocation.PSCommandPath). Required when called outside a script file. |
-Diagnostics |
string |
no | 'Normal' |
Sets NATIVEHTMLKIT_DIAGNOSTICS for the host and backend when not Normal (Off, Debug, Trace). See diagnostics. One of: Off, Normal, Debug, Trace. |
Returns NativeHTMLKit.Application (backend role only).
Errors
- Invalid
-Name,-Versionor-AppId:Name must be 1-128 characters...,AppId must be a dot-separated ASCII identity.... - Called from the console instead of a file:
Start-NativeHTMLKitScript must be called from a .ps1 script file. - Only one of
UI4ME_ENDPOINT/UI4ME_TOKENset, or a backend started by a launcher without a connection: refuses to start a second host. - Host binary missing or failing its integrity check: see Get-NativeHTMLKitHostPath.
- Connection failure in the backend role: as for
Connect-NativeHTMLKit.
param([string]$Folder) # parameters are forwarded to the backend run
Import-Module NativeHTMLKit
$app = Start-NativeHTMLKitScript -Name 'Folder report' -AppId 'org.example.FolderReport' -Instance multiple
Connect-NativeHTMLKit¶
Alias: Connect-NHK
Connects a backend that a manifest-based launch started (Start-NativeHTMLKitHost, or
nativehtmlkit-host run --app app.toml). It reads the endpoint and token, clears the four
UI4ME_* launch variables from the process environment before anything can fail, opens the Unix
socket or Windows named pipe and authenticates with host.hello (protocol version 1). Most
scripts use Start-NativeHTMLKitScript, which calls this in its backend role.
Connect-NativeHTMLKit [[-Endpoint] <string>] [[-Token] <string>] [[-ConnectTimeoutMilliseconds] <int>] [-SkipTokenValidation] [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Endpoint |
string |
no | $env:UI4ME_ENDPOINT |
Socket path or pipe name. Default: $env:UI4ME_ENDPOINT. |
-Token |
string |
no | $env:UI4ME_TOKEN |
Launch token (64 hexadecimal digits). Default: $env:UI4ME_TOKEN. |
-ConnectTimeoutMilliseconds |
int |
no | 15000 |
How long to wait for the endpoint. Range 1 to 120000. |
-SkipTokenValidation |
switch |
no | off | For test peers only: accept a token that is not 64 hexadecimal digits. |
Returns NativeHTMLKit.Application. Its Hello property holds the host's host.hello result.
Errors missing endpoint/token (message explains to use Start-NativeHTMLKitScript);
System.ArgumentException for a malformed token; NativeHTMLKit.DisconnectedException
(Cannot connect to the native host endpoint (...)) when the endpoint does not answer;
NativeHTMLKit.RpcException when authentication fails; Unsupported NativeHTMLKit Core protocol version.
Set-NativeHTMLKitReady¶
Alias: Set-NHKReady
Tells the host that startup finished (app.ready). Call it once, after creating at least one
window and registering the event handlers the first frame needs. Repeated calls do nothing.
Until ready, the host treats closing the last window as cancelling startup, and closes extra
windows without asking their close policy.
Set-NativeHTMLKitReady [-Application] <Object> [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Application |
NativeHTMLKit.Application |
yes | - | The application. |
Returns nothing. Errors NativeHTMLKit.RpcException from the host (for example when no window exists).
Wait-NativeHTMLKit¶
Alias: Wait-NHK
Pumps host messages on the calling runspace: every document event, notification, close/quit decision and background-task completion callback runs inside this call (or inside any other command that waits for a host reply). Two parameter sets:
- Run (
-UntilShutdown): pumps until the host requests shutdown orClose-NativeHTMLKitis called (for example from a callback). Returns no output. ThrowsNativeHTMLKit.DisconnectedExceptionif the host disappears first. - Pump (default): waits up to
-TimeoutMillisecondsfor the first message, then handles up to 64 queued messages without waiting, and returns how many it handled (0on timeout or after close).-Oncehandles at most one message. Use this for your own loop with periodic work.
Wait-NativeHTMLKit -Application <Object> [-TimeoutMilliseconds <int>] [-Once] [<CommonParameters>]
Wait-NativeHTMLKit -Application <Object> [-UntilShutdown] [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Application |
NativeHTMLKit.Application |
yes | - | The application. |
-TimeoutMilliseconds |
int |
no | 100 |
How long to wait for the first message; -1 waits indefinitely. Range -1 to 2147483647. Parameter set: Pump. |
-Once |
switch |
no | off | Handle at most one message. Parameter set: Pump. |
-UntilShutdown |
switch |
no | off | Pump until shutdown or close. Parameter set: Run. |
Returns [int] (Pump set) or nothing (Run set).
# A custom loop: do periodic work between pumps (prefer a background task for real work).
while (-not $done) {
$handled = Wait-NativeHTMLKit -Application $app -TimeoutMilliseconds 250
if ($handled -eq 0) { Update-Clock }
}
Request-NativeHTMLKitQuit¶
Alias: Request-NHKQuit
Asks the host for an orderly quit (app.request_quit). The host asks the
Set-NativeHTMLKitBeforeQuit policy (if any); when allowed it sends app.shutdown, which makes
Wait-NativeHTMLKit -UntilShutdown return. Use it for a Quit button or menu item.
Request-NativeHTMLKitQuit [-Application] <Object> [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Application |
NativeHTMLKit.Application |
yes | - | The application. |
Returns the host result, @{ requested = $true } when the request was accepted. The quit
itself happens later, while events are pumped.
Set-NativeHTMLKitBeforeQuit¶
Alias: Set-NHKBeforeQuit
Sets the application's quit policy. The host asks it (request app.before_quit) when a quit is
requested, for example by Request-NativeHTMLKitQuit (reason = 'backend_request'). The
scriptblock receives the host parameters (with a reason property); its last output value
decides: truthy allows the quit, $false or no output vetoes it. A throwing policy is reported as a
callback failure and the host receives an error reply. Pass $null to remove the policy.
Set-NativeHTMLKitBeforeQuit [-Application] <Object> [-Callback] <scriptblock> [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Application |
NativeHTMLKit.Application |
yes | - | The application. |
-Callback |
scriptblock |
yes | - | Policy scriptblock, or $null to remove it. Accepts $null. |
Set-NativeHTMLKitBeforeQuit -Application $app -Callback {
param($request)
if ($script:unsaved) { Set-NativeHTMLKitDocumentText -Document $doc -Element status -Text 'Save first.'; $false; return }
$true
}
Register-NativeHTMLKitNotification¶
Alias: Register-NHKNotification
Runs a scriptblock for every host notification with the given method, for example
window.event (window state changes, including type = 'closed') or
desktop.preferences_changed. One callback per method; registering again replaces it; $null
removes it. The SDK's own bookkeeping (closing window handles, retiring documents, dispatching
document events) always runs before your callback. The callback receives the notification's
params object.
Register-NativeHTMLKitNotification [-Application] <Object> [-Method] <string> [-Callback] <scriptblock> [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Application |
NativeHTMLKit.Application |
yes | - | The application. |
-Method |
string |
yes | - | Notification method name, for example window.event. |
-Callback |
scriptblock |
yes | - | Scriptblock receiving the notification parameters, or $null to remove it. Accepts $null. |
window.event parameters observed with Core 1.0.3: window_id, type (for example closed,
close_requested, focused, resized, moved, dropped_files, theme_changed) and data.
Register-NativeHTMLKitNotification -Application $app -Method 'window.event' -Callback {
param($params)
if ($params.type -eq 'closed') { Write-Verbose "window $($params.window_id) closed" }
}
Close-NativeHTMLKit¶
Alias: Close-NHK
Closes the application connection and retires every window, document, node and bitmap handle
(later use throws NativeHTMLKit.StaleObjectException). It removes all callbacks, requests
cancellation of unfinished background tasks without waiting for them, and is idempotent; $null
is accepted, so it is safe in a finally block even when startup failed. In a backend started by
Start-NativeHTMLKitScript before shutdown, the connection is left for process exit to close, so
an error that is unwinding through finally is still reported by PowerShell before the host stops
the process. Calling it inside a callback ends Wait-NativeHTMLKit -UntilShutdown normally.
Close-NativeHTMLKit [-Application] <Object> [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Application |
NativeHTMLKit.Application |
yes | - | The application, or $null. Accepts $null. |
Start-NativeHTMLKitHost¶
Alias: Start-NHKHost
Runs an app manifest (app.toml) through the native host and waits for it to exit (throws
NativeHTMLKit host exited with code N on a nonzero exit). With -NoWait it starts the host and
returns its System.Diagnostics.Process. The manifest's backend must call Connect-NativeHTMLKit
or Start-NativeHTMLKitScript (which only connects in that case). New-NativeHTMLKitProject
writes a suitable app.toml.
Start-NativeHTMLKitHost [-Manifest] <string> [-NoWait] [<CommonParameters>]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
-Manifest |
string |
yes | - | Path of the app.toml manifest; must exist. |
-NoWait |
switch |
no | off | Start the host and return its process object instead of waiting. |
Get-NativeHTMLKitHostPath¶
Alias: Get-NHKHostPath
Returns the full path of the native host this module will run: NATIVEHTMLKIT_HOST_BINARY (or the
legacy UI4ME_HOST_BINARY) when set, otherwise the bundled runtimes/linux-x64/nativehtmlkit-host
or runtimes/win-x64/nativehtmlkit-host.exe. A bundled host is checked against the SHA-256 in
HOST-MANIFEST.json on every call (fail closed), and on Linux made executable if a package
extraction dropped the execute bit.
Get-NativeHTMLKitHostPath [<CommonParameters>]
No parameters (common parameters only).
Errors NATIVEHTMLKIT_HOST_BINARY does not exist: <path>; NativeHTMLKit ships x64 hosts only;
NativeHTMLKit supports Linux and Windows only; The native NativeHTMLKit host is missing (a source
checkout without hosts: set NATIVEHTMLKIT_HOST_BINARY); a missing or mismatching HOST-MANIFEST.json.
Environment variables¶
| Variable | Used by | Effect |
|---|---|---|
NATIVEHTMLKIT_HOST_BINARY |
Get-NativeHTMLKitHostPath, launcher |
Use this host binary instead of the bundled one. |
NATIVEHTMLKIT_TEST_MODE=1 |
Start-NativeHTMLKitScript |
Start the host with --headless: the full protocol runs without windows on screen. No native input, clipboard, file dialogs, external open or attention requests. |
NATIVEHTMLKIT_DIAGNOSTICS |
SDK, host, backend | off, normal (default), debug or trace. |
NATIVEHTMLKIT_VERBOSE |
launcher | Any value other than empty, 0, false, no relays the host's informational records to stderr. |
NATIVEHTMLKIT_DIAGNOSTIC_SESSION_ID |
SDK, host | Correlation ID shared by launcher, host and backend; generated when absent. |
UI4ME_ENDPOINT, UI4ME_TOKEN, UI4ME_APP_ID, UI4ME_PROTOCOL_VERSION |
backend | Set by the host for its backend (wire v1 names). Removed from the environment on connect. |
Source: nativehtmlkit-powershell/docs/reference/lifecycle.md ยท edit the page there.