Skip to content

NativeHTMLKit PowerShell SDK v0.1.1

Choose a tag to compare

@nativehtmlkit nativehtmlkit released this 16 Nov 01:53
· 19 commits to main since this release

NativeHTMLKit PowerShell SDK 0.1.1

NativeHTMLKit is a PowerShell module that turns ordinary PowerShell scripts into native desktop apps built from local HTML
and CSS. Windows, input, layout, rendering and accessibility come from the bundled NativeHTMLKit Core host (Rust); the module
speaks the Core wire protocol v1 to it. No browser, JavaScript runtime, web server, Python or Rust toolchain is needed.
Canonical commands are Verb-NativeHTMLKitNoun (88 functions), each with a Verb-NHKNoun alias.

This is a full release. It bundles NativeHTMLKit Core 1.0.3, with which Core wire protocol v1 became the public-stable wire
contract (1.0), and it requires Core 1.0.3 behaviour. It is the first version on the PowerShell Gallery.

Install

Install-PSResource NativeHTMLKit -Version 0.1.1     # PowerShell 7.4+ (PSResourceGet)
Install-Module NativeHTMLKit -RequiredVersion 0.1.1 # Windows PowerShell 5.1 / PowerShellGet

Or from the ZIP below:

  1. Check the download: sha256sum NativeHTMLKit-0.1.1-linux-x64+win-x64.zip (Linux) or
    Get-FileHash NativeHTMLKit-0.1.1-linux-x64+win-x64.zip (Windows) must print the SHA-256 below.
  2. Extract it into a folder on your PSModulePath, so that NativeHTMLKit/NativeHTMLKit.psd1 sits directly in it
    (current user: Linux PS 7 ~/.local/share/powershell/Modules/, Windows PS 7 Documents\PowerShell\Modules\,
    Windows PowerShell 5.1 Documents\WindowsPowerShell\Modules\). On Windows, Unblock-File a browser download first.
  3. Import-Module NativeHTMLKit (or just use a command; the module auto-loads), then try
    New-NativeHTMLKitProject -Path ./MyApp and pwsh -File ./MyApp/app.ps1 (or powershell.exe -File .\MyApp\app.ps1).

Either way the bundled host is checked against HOST-MANIFEST.json before each launch. A package manager may drop the Linux
host's executable bit; the module restores it.

Artifact

File SHA-256
NativeHTMLKit-0.1.1-linux-x64+win-x64.zip e7fac0d0ef230b32eb0ea544fbbc17fcbe32e424a49682a08374f33219fb40ce

The ZIP is byte-reproducible from source commit 215f75a0b49d1e946b094e45e72596774255d19d (SDK source tree hash
a98ba47152089aea6a6a6059e6897be173fc1c2bc07b8ef24b6f813799487636) with scripts/package-local.py and the Core release
directories below. It contains the module, both Core hosts, the Core licences and notices, HOST-MANIFEST.json
(development_package: false, host hashes and each host's embedded source identity) and SHA256SUMS for every packaged file.

Bundled Core hosts: NativeHTMLKit Core 1.0.3, source commit d73dec36adbe1b1380f982388d13655750e607df, source tree
523c7a42e458e96e6943f8641df6cf3a32a85152, clean. Both hosts report that identity in nativehtmlkit-host --version --verbose,
and the packager checked it against the Core release manifests.

Runtime File SHA-256
linux-x64 runtimes/linux-x64/nativehtmlkit-host 1cd4e9de701f3ef8d8b870b678765243f2365d69d7352c0543f171ff249c999f
win-x64 runtimes/win-x64/nativehtmlkit-host.exe 15967208d2e20d208d69b97bba6f397056e28c57add126909a8734361ae8f8c8

Changes since 0.1.0 (prerelease)

  • Bundles Core 1.0.3 (was 1.0.2). Protocol v1 is now stable (1.0).
  • Diagnostics level off is passed to the host unchanged. Core 1.0.3 relays the script's own output and fatal error at every
    level (NHK-CROSS-0007), so the 0.1.0 interim off→normal mapping and NATIVEHTMLKIT_SDK_DIAGNOSTICS are gone.
  • Live bitmaps work on Linux with the Core 1.0.3 host's shared lock on transport files (NHK-CROSS-0008, found by this SDK).
    The transport path the host returns is exposed as $bitmap.Mapping.TransportPath. On Windows the files now live in
    %TEMP%\nativehtmlkit-bitmaps\.
  • Get-NativeHTMLKitDiagnosticReport includes the host's dropped_notifications counter.
  • Core 1.0.3 window behaviour applies: a new window is first shown when its first document has loaded, or after at most
    750 ms (on Windows observed.visible is false until then), and new windows are clamped to the work area. In the
    accessibility tree a drop-down <select> is now a combo box holding a list of list items (NHK-CROSS-0009).
  • Packaging records and cross-checks each host's source identity, and refuses hosts built from different Core sources.
  • PowerShell Gallery: manifest metadata meets the Gallery rules, and installing by module name is part of qualification.

Supported platforms and editions

  • PowerShell 7.2+ on Linux x64 (qualified on 7.7.0; installed-package smoke also on 7.4.2) and Windows x64 (qualified on 7.7.0).
  • Windows PowerShell 5.1 on Windows x64 (qualified on 5.1.20348, Windows Server 2022).
  • Desktops: KDE Plasma 6.6 (native Wayland) and the interactive Windows desktop. x64 only.

What was qualified

All runs used this ZIP and the pinned hosts, from the clean commit above, with one command per platform/edition
(scripts/qualify.ps1). There are 55 results, all with the same source tree hash. Evidence is in the Project workspace under
verification/2026-11-16-full-release/powershell/release/.

Runtime / session Gates Pester tests Real desktop GUI (real input) Installed package Gallery-style install
PowerShell 7.7.0, Debian 13 workstation (headless) 12 PASS, 1 BLOCKED (no desktop, by design) 158 passed, 0 failed, 0 skipped — PASS; Docker clean room (Ubuntu 22.04, PowerShell 7.4.2, no network, no Rust/Python) 12/12 PASS
PowerShell 7.7.0, KDE Plasma 6.6 Wayland (linuxDEV) 14/14 PASS 158/158 29/29 checks, clean teardown PASS headless and GUI PASS
PowerShell 7.7.0, Windows interactive desktop (winDEV) 14/14 PASS 158/158 29/29 checks, clean teardown PASS headless and GUI PASS
Windows PowerShell 5.1.20348, same desktop 14/14 PASS 158/158 29/29 checks, clean teardown PASS headless and GUI PASS (PowerShellGet Install-Module)

Pester skips the 2 tests that only apply to the other OS (Linux-only on Windows, Windows-only on Linux); a skipped
real-host test would count as a failure.

  • Gallery-style install: PowerShell 7 publishes the module from this ZIP to a local repository with
    Publish-PSResource and checks the .nupkg contents. It then installs the module by name with Save-PSResource and runs
    the installed-package smoke. Windows PowerShell 5.1 installs from that repository with PowerShellGet Install-Module, runs
    the same smoke, and uninstalls.
  • GUI checks: they use real OS input (uinput on Wayland, SendInput on Windows) and cover:
    • the window appears;
    • mouse (left/right/middle), keyboard into inputs, form submit, ordered callbacks under input;
    • native save/open dialogs and cancellation;
    • minimize/maximize, frameless drag and eight resize edges, HTML window-chrome buttons;
    • live bitmaps (geometry, 1000+ frames, bounded memory, transport cleanup);
    • the accessibility tree (AT-SPI / UI Automation);
    • clipboard exchange with another app;
    • close veto then allow, and a clean exit with no leftover processes.
  • Pester: it covers the transport, fault injection, background tasks, diagnostics privacy and launch-credential
    scrubbing. New in 0.1.1 are real-host tests for out-of-order reply correlation and for opening the bitmap transport from
    .NET while the host holds it.

Known limitations

  • Hang detection: a request that gets no reply raises NativeHTMLKit.RpcTimeoutException after its deadline (default
    15 s; native dialogs wait indefinitely). Its outcome is unknown. The SDK has no separate
    liveness watchdog for a host that stops answering.
  • Stopped host (Linux): if the launcher dies while the whole host process is stopped (SIGSTOP, a debugger halt), the
    host, its backend and its systemd unit stay until the host is continued or killed. Core's launcher watchdog covers a
    blocked event loop only (Core protocol §9, NHK-CROSS-0001 residual). The PowerShell SDK does not kill the host itself in
    that case.
  • Host integrity check: the bundled host is re-hashed against HOST-MANIFEST.json on every launch, but the file could
    still be replaced between the hash and the moment the OS executes it. This checks the installed copy; it doesn't prove
    who built it. NATIVEHTMLKIT_HOST_BINARY overrides the bundled host without verification (development use).
  • No cross-SDK parity suite: behaviour is qualified per SDK against the same Core host, not by one shared conformance
    suite run against the Python, PowerShell and CLI clients.
  • List commands return one array object (Get-NativeHTMLKitWindowList, Get-NativeHTMLKitStylesheets,
    Get-NativeHTMLKitSelectOptions): assign the result ($list = ...; $list.Count); wrapping the call in @() or piping it
    gives a single item.
  • Not qualified: mixed per-monitor DPI scaling on Windows, real system suspend/resume, input methods (IME), and the
    long-running idle and bitmap-kill harness modes.
  • x64 only (Linux x64, Windows x64).