Writing an independent NativeHTMLKit client (SDK authoring guide)¶
A client is a backend process launched by the host; the host owns windows, rendering, input and
accessibility. Use only the published contract — this directory, README.md and
v1/ — never Core's private Rust crates.
New to the protocol? Work through the tutorial first; its
dependency-free client examples/wire-v1/wire_client.py is a
compact, verified implementation of the steps below.
1. Launcher¶
- Locate a pinned host binary and verify it (the Python SDK checks the SHA-256 recorded next to its
bundled host).
nativehtmlkit-host --version --verboseprints the embedded source identity (version,source_commit,source_tree,source_dirty) as JSON. - Write an
app.toml(reference §1) into a private temporary directory. Quote every string safely (a JSON string is a valid TOML basic string, except that DEL must be escaped);{app_dir}is substituted everywhere and has no escape, so reject arguments that contain it. - Run
nativehtmlkit-host run --app <manifest>; add--headlessonly when the user asked for test mode (the SDKs useNATIVEHTMLKIT_TEST_MODE=1). Never select headless silently because no desktop was found. - Bind the host's lifetime to the launcher: Linux
PR_SET_PDEATHSIGin the child, Windows a Job Object withJOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE(plusSILENT_BREAKAWAY_OKso applications the host opens for the user survive). Otherwise a killed launcher leaves an orphaned window. - Read the host's stderr continuously: it is JSON lines. Relay
fields.source == "backend"records as the app's stdout/stderr (fields.stream), showWARN/ERRORrecords, and hide the rest unless the user asked for verbose output. Return the host's exit status. - Delete the manifest directory afterwards; keep any result/session files in
0700directories.
2. Backend connection¶
- Read and remove
UI4ME_ENDPOINT,UI4ME_TOKEN,UI4ME_APP_ID,UI4ME_PROTOCOL_VERSION. Validate the token (64 hex characters) and the version (1). Never log the token or pass it to child processes. - Connect: Linux
AF_UNIXSOCK_STREAMto the path. Windows: open the named pipe for read and write, retrying briefly while it is busy. If one thread reads while another writes, open the pipe for overlapped I/O (FILE_FLAG_OVERLAPPED, oneOVERLAPPED/event per operation): on a synchronous handle a pendingReadFileblocks everyWriteFile. A single-threaded client (read only while waiting for something, as inwire_client.py) can use a plain synchronous handle. - Framing: write a
u32big-endian length followed by the UTF-8 JSON; read the same. Reject length 0 or more than 2,097,152 before allocating. Never interleave two writers on one stream. - Send
host.hello {token, protocol_version: 1}first; requireresult.protocol_version == 1. Keepresult.capabilities.
3. Requests and the reader loop¶
- Use unique, non-empty string ids (≤128 bytes, no control characters); keep at most 128 requests pending, and refuse locally beyond that.
- Dispatch every incoming frame:
methodandid→ host request. Answerwindow.before_close/app.before_quitwith{"allow": bool}(missing or non-boolean is a veto); answer any other method with error-32601. Answer promptly — the host has no deadline and waits.methodwithoutid→ notification. Deliver it; ignore unknown methods and members.- otherwise → response; correlate by
id, never by order. An error response withid: nullbelongs to no request: treat it as a defect in your client (log it, fail loudly in tests). - Keep reading at all times. Run the reader on its own thread or task (or read whenever you wait,
as the example does). A backend that stops reading loses
document.event/window.eventnotifications (counted inhost.diagnostics.dropped_notifications) and, if it leaves responses unread, fails the session. Hand slow application work to another thread; never run user callbacks on the reader thread if they may block on a request. - Give long-running requests (dialogs, clipboard reads, path loads) a cancellation path:
request.cancel {id}; the original request is then answered-32006. - Map error codes to typed exceptions and never parse
message; treat unknown codes as failure. Distinguish-32004(stale window/document/node: retire the handle) and-32008(lifecycle phase).
4. Application model¶
window.create→document.load {window_id, html|path}→app.ready(withinstartup_timeout_ms).- Expose handles that carry both
window_idanddocument_id. Retire the old document handle only after a successfuldocument.load(a refused load keeps the old document). Afterwindow.event closedretire the window; afterapp.shutdownretire everything (noclosedarrives for the last window). - Wrap
document.commandgenerically (command(op, **fields)) so new additive ops work without an SDK release, then add typed helpers. Generate them fromv1/schemas/document-command.schema.jsonif your language allows. - Events: deliver
document.eventwith the documented members (events guide). Let users match a target onevent.elementorevent.path. Ignore members beginning with_. - Default actions cannot be cancelled from a callback; expose
set_default_actionas a declarative API ("prevent Enter in #search", "prevent submit on #form"). - Validate what
document.commandreturns before trusting it (form entries are{name, kind, value}, file entries carrypath/filename). - Make HTML insertion APIs obviously "trusted HTML" and offer text APIs (
set_text,set_value) for user data. Provide an escaping helper. - Live bitmaps: map the returned
pathbefore the firstbitmap.present, write straight-alpha RGBA8 rows ofstridebytes into a slot, present it with an increasingsequence, and reuse the slot only after the acknowledgement. On Windows open the file with delete sharing so the host can unlink it after the first present. - On
app.shutdown {deadline_ms}release resources (close bitmaps' mappings, flush files) and exit before the deadline; otherwise the backend is killed and the host exits with status 1.
5. Verifying a new client¶
- Run it against the pinned host in headless mode and compare every method and op you wrap with
v1/conformance/golden.json(error codes, result member kinds); the wire tables show the same data per method. - Exercise the edge cases the golden locks: stale documents (
-32004),app.readytwice (-32008), unknown members (-32602), oversize HTML (-32005), a host request arriving while you wait for a response, quit vetoed and then allowed. - Check for orphans: after a normal exit, a crash of your backend and a killed launcher, no host or backend process may remain.
- Then qualify real windows on Linux KDE Plasma Wayland and an interactive Windows desktop (input, focus, resize, close decisions, file dialogs, clipboard). Headless mode proves the protocol and document state, not native behaviour.
The Python SDK and the PowerShell SDK are independent v1 clients qualified against the same host and are useful references.
Source: nativehtmlkit-core/protocol/SDK-AUTHORING.md · edit the page there.