Application SDK#

cw_sdk::Application separates persistent state, input handling and presentation. An application has kind, version, initialize, event and page methods. event receives mutable JSON state, AppContext and an AppEvent, returning explicit AppEffect values. page receives immutable state and returns a native Page; observation should never change application state.

AppContext identifies the actor, machine, logical tick, seed and instance. AppEvent has a kind, optional target and JSON data. Effects are explicit HTTP requests, file reads/writes, application launch or named emitted data. The embedding environment mediates them; returning an effect is not a capability to access arbitrary host resources.

Use stable element IDs so semantic targeting, keyboard focus and pointer hit regions refer to the same control across updates. Buttons/forms describe actions, not JavaScript callbacks. A custom application should render state after actual operations complete, rather than echoing requested input as proof of success.

For an agent-driven application, register with World::register_application (or Environment::register_application). Registry::register_application is the lower-level code registry operation. Multiple instances can share the implementation while keeping separate state. Version changes participate in the runtime's module identity. See custom application and rendering.

Launch a registered application with family application.v1, op launch, and payload { "kind": "your.kind", "instance": "optional-id", "initial": {} }. Send op event with { "instance": "optional-id", "event": { "kind": "activate", "target": "control-id", "data": null } }. Effects return through an effect_result event whose data identifies the completed operation, such as HTTP or file access. Actor observations expose its page, not the private application state.

Web applications#

cw_sdk::WebApplication registers an application written as a web app instead (Registry::register_web_application, World::register_web_application): a kind, a version, window titles by platform and a WebSource: a script (typically compiled from TSX) with its stylesheet, optionally on React 18, or the IR cw-tsx compiles an app in its subset to, which cw-ui runs without a VM. It opens in a desktop window whose frame is the platform's and whose content is its document, laid out and painted by the web engine. Its effects are the same mediated requests — file reads and writes, HTTP to world services, launching, named data — made through the cw global, and its snapshot is the state it declares, keyed by kind and version like any module (module_versions lists it as web:<kind>). See custom application.