0039: libWolkit and Wolkit

Context

0036 said wolkit is a declarative view tree that maps one to one onto shared::view, drawn by the Kit host, with "a small 2D canvas over Vulkan" for acceleration and a wol_surface family in wol.h. Three limits make that too small for the lead's goal of a fast, reactive, GPU-first UI kit. The view wire carries at most 200 parts, 12 levels and ten kinds, with no custom styling, no long lists and no canvas. The whole tree crosses as one JSON line on every change. And everything the kit can do is whatever the GPL Kit host already draws, so an app cannot be faster than the host. The lead's two rulings are a Rust library with a stable C ABI that holds the engine, and a thin Crystal binding that owns the DSL, the runtime abstractions and the developer experience.

Decision

• libWolkit is the engine. A new crate crates/wolkit (package wolkit, libwolkit.so.1, header crates/wolkit/include/wolkit.h), BSD-2-Clause, depending only on shared and core. It holds the retained scene, style, layout, text, paint, a CPU reference rasteriser and a Vulkan renderer, input routing, the accessibility tree and the animation clock. Its C ABI has 53 verbs, opaque handles, UTF-8 with lengths, a status code and an optional error sentence, one thread at a time per engine, and no callbacks.
• Everything else crosses as data. An app changes a window with one binary patch stream per frame (wolkit_window_apply, format WKP1, interface I10) and learns what happened by draining binary event records (wolkit_engine_read_events, interface I12). Ids of node kinds, properties, ops, events, roles and state bits are append-only, listed in the header and snapshot-tested (abi/wolkit-1.0.props, abi/wolkit-1.0.h). A newer app can send an optional op to an older engine because every op is length-prefixed with a must-understand flag. New widget behaviour adds ids, not symbols.
• One scene ABI, two backends per window. The kit backend lowers the scene to shared::view and talks to the Kit host over its existing socket, so it needs no change to the GPL side and ships first. The native backend is the engine's own window and becomes the default after a parity gate (screen reader, input method, clipboard and drag and drop, budgets, look parity, fuzzing, audit). The kit backend stays supported for at least two releases after that. A headless backend has no display and backs the conformance suite, the golden harness and the shard's test harness. One conformance suite (crates/wolkit/tests/conformance.rs) runs on every backend with a per-backend list of expected differences.
• The shard owns the DSL and the user-level reactive layer. Signal, computed, effect, Resource, components, navigation and the developer tools stay in Crystal because the values and closures live in the Crystal heap. The engine owns a render-level dirty graph (per-node dirty bits for style, layout, paint and accessibility) and the animation clock, so springs and tweens run in Rust. Cost, stated plainly: a binding for another language must write its own user-level reactive layer. 0036 already says WolOS writes no high layer for other languages.
• 0036 amended in two places. wolkit is no longer "a view-tree builder mapping one to one onto shared::view": shared::view is the kit backend's wire only, and the shard's golden is a decoded scene dump, not view JSON. The GPU paragraph's "small 2D canvas over Vulkan" becomes the engine's own canvas and surface nodes (wolkit_window_canvas_submit, wolkit_surface_*); the wol_surface family is not added to wol.h (it stays 1.14), because native windows are not Kit-host windows. If the lead keeps wol_surface in wol.h for Kit-host windows, it is added as 1.15 independent of this engine.
• Boundaries. crates/wolkit may depend on shared and core and on permissive third-party crates allowed by deny.toml; no GPL crate depends on it (crates/shared/tests/architecture.rs). unsafe is confined to src/ffi/ (the C boundary), src/loop_/ (one poll call), src/gpu/ and src/window/native/, each block with a // SAFETY: comment, listed in RR-068 (docs/RULES.md, crates/shared/tests/rules_rust.rs) and counted by crates/shared/tests/unsafe_ratchet.rs (a wolkit row, provisional at creation and lowered by the closing worker). Raw slices from C pointers are built only in src/ffi/mod.rs (bytes_in, bytes_out, behind clippy.toml's disallowed methods). Every list is bounded (docs/modules/libwolkit.md, Limits). Untrusted input is validated before it is applied and applied atomically; every decoder has a fuzz target (wolkit_patch, wolkit_wsb, wolkit_wolcss). A panic stops at the boundary as WOLKIT_ERR_INTERNAL.
• Crystal rules this adds (next free RCR ids, checked by crates/controller/tests/rules_crystal.rs): FFI_ALLOW gains the wolkit FFI files, and ALLOWED_SHARDS and the shard census gain cryswol and wolkit, so an app that requires wolkit passes RCR-043.

Consequences

the engine is a second large Rust component beside the Kit host, about 45 to 60 thousand lines by the plan's estimate (not measured), with its own text, layout and rendering to keep correct and fast. In return an app is no longer limited by the Kit's 200 parts, can scroll a hundred thousand rows, can draw, and can share a GPU device with the AI framework (wolkit_engine_get_gpu_uuid). The look of native windows must track the Kit's: both read the same token sources (design/tokens/colors.json, crates/shared/src/theme.rs, crates/shell/src/kit/contrast.css) and a drift test compares them. Two open items sit outside the engine: a compositor rule so a toplevel can ask for glass, and a hook so native windows reach the global menu bar (crates/shell/src/appmenu.rs); until they land, backdrop: glass draws the normal translucent token colour and a native window carries its own menu. The version of the ABI is 1.0 until the first release that ships it; after that a shipped symbol never changes.