Skip to content

Architecture — who owns what?

flowchart TD
  APP[Your Python or PowerShell program] --> SDK[Language SDK<br/>nativehtmlkit / NativeHTMLKit]
  SDK -->|wire protocol v1<br/>local authenticated IPC| HOST[Core native host<br/>nativehtmlkit-host, Rust]
  HOST --> OS[Linux KDE Wayland / Windows desktop]

NativeHTMLKit is not a website in a hidden browser tab. A Rust native host parses HTML and CSS, lays out and draws the page, owns the native windows, handles keyboard, pointer, IME, accessibility and native dialogs, and reports events to your program. Your program — the backend — contains the application logic and sends commands such as “set this element's text” back to the host.

Components

Component Owns Does not own
Core (nativehtmlkit-host) Native windows, HTML/CSS engine, input, rendering, native dialogs, clipboard, live bitmaps, the wire protocol Application logic, language APIs
Python SDK (nativehtmlkit) Python API for applications, windows, documents, nodes, bitmaps; launching the bundled host; diagnostics Rendering, widgets
PowerShell SDK (NativeHTMLKit) The same host-level features as exported functions; the event pump and background tasks for PowerShell Rendering, widgets

Each SDK wheel and module ships the native host it was released with, so a normal install needs no separate Core download.

The boundary rule

  • The SDKs use only the public wire protocol of Core. They never link Core internals.
  • A feature that Core does not expose cannot be added in an SDK or an application through private calls; it belongs in Core first.

The wire protocol

The SDKs talk to the host over a private local channel (a Unix-domain socket on Linux, a named pipe on Windows), authenticated with a per-launch token. Messages are length-prefixed JSON-RPC 2.0. Protocol v1 is the public, stable contract since Core 1.0.3: within v1, framing, method and operation names, parameter names and types, error codes and lifecycle ordering never change; new methods, operations, optional parameters and result members may be added, and clients must ignore what they do not know. The authoritative description is the Core protocol README.

Most applications never see the protocol: they use the SDK. Low-level escape hatches exist (Document.command(op, ...) in Python, Invoke-NativeHTMLKitDocumentCommand in PowerShell) for documented document operations that have no convenience wrapper.

Where to read more