Files
waozi 788f0151f7 Add hosted ZX software surfaces for Kryon apps
Reuse the Kryon frame, input and pixmap paths behind four typed surface bindings.
Verify the guest bundle in Ziran and the installed TaijiOS emulator.
2026-11-19 16:05:21 -03:00

7.4 KiB

Kryon

Documentation for Kryon 0.4.0 and Unreleased changes on master.

Linux desktop and portable hosts can decode local videos with synchronized audio using the optional GStreamer service exported as kryon/Video and kryon/VideoLinux. Display the returned frame with Image.Draw(Image.Props). Applications own playback controls and access checks; an optional expiring lease revokes both audio and decoded frames when authorization is no longer renewed. make test-focus TEST=ziran_video_linux_test checks synthetic moving frames, paused seeking, speed, volume, replay and lease revocation with a silent audio sink and no display access.

Kryon is a UI library written in Ziran. Its source lives under src/ui/ and imports Ziran modules normally. The Ziran compiler, .zir representation, and .zx bundle format belong to the separate Ziran repository.

Build

Install the ziran command first (make install-user in a Ziran checkout), then build Kryon:

make
make test

The Makefile builds against the Ziran revision locked in ziran.lock, found with ziran pkg path ziran. To build against a local Ziran checkout, name it in an ignored ziran.local.toml [overrides] table or set ZIRAN_ROOT.

make checks the modules listed in src/ui/modules.txt, writes checked .zir, generates C and Go, and compiles the native outputs from Ziran source. The current C archive is build/ziran/libkryon.a; C headers are generated from Ziran declarations into build/ziran/c/. Kryon has no handwritten source headers. Hosts provide declared effects such as raster lines, and CompositionQueue carries raw IME events to the checked text widgets.

Charts, tables, trees, and source coloring are separate Git packages that depend on Kryon: Plot, DataViews (TableView and TreeView), and Syntax. Add one with ziran add URL and import it as plot/Plot, data_views/TableView, or syntax/Syntax. Kryon exports the building blocks such packages draw with (session, tree, surface, paint_queue, style, and the others listed in ziran.toml); see writing a widget package.

Style sheets are the separate CSS package: it parses and formats a subset of CSS, installs the rules. Kryon keeps the rule table and style resolution, so an app that builds its rules in code needs no parser.

Kryon exports geometry and drawing_props for programs that need drawing values without importing widgets. Imports and use determine what a program carries. App.Show(window) carries only the window, events and presentation; App.Run(window, Draw) also brings the frame loop. Portable ZX windows run through the native desktop provider by default. See the API.

make test builds the test host and runs the Ziran source, saved-IR, and portable bundle tests with four concurrent jobs. Set TEST_JOBS=1 to run them serially or TEST_JOBS=8 on a larger machine. For a quick edit loop, use make test-focus TEST=link_widget; the filter matches test script names and skips the full library rebuild. Test subprocesses have no display access. make sanitize-test runs the behavior tests with AddressSanitizer and UndefinedBehaviorSanitizer. Keep one-off experiments in build/scratch/; make clean-scratch removes that and any other build/ entry that no target writes, once it has been idle for a day. See composition input for the checked IME event contract and host queue lifetime. See cursor input for the checked cursor decision and platform effect contract. See theming for palette and style customization. See zoom for Ctrl and mouse-wheel zoom of a whole application. See clipboard state for the portable clipboard value and host effect contract. See frame replay for committed UI and paint capture with scripted input on a headless host. The hello world example is one small Ziran program with an explicit main: it imports Kryon's app and text packages, opens a window, and draws the label Hello, world!. For Ziran app manifests, the terminal backend, and kryon run, see Ziran projects. Portable desktop profiles build a .zx with embedded assets; a downloaded file launches with ziran run app.zx after installing the desktop provider. See Zx applications.

make site packages the Canvas website, browser compiler, preview host and widget gallery into docs/site/. Emscripten is required; activate emsdk or set EMCC. make site-gallery builds only the gallery, and make site-gallery-test prepares editable examples and exercises the gallery in a private Chromium/Xvfb session.

The gallery at widgets.html uses the example package in examples/gallery/. Its core scenes are shared by the desktop, web and review hosts. Examples are grouped by installed module and category, including core UI and 2D drawing. Optional package integrations are registered only while their dependencies are declared. Each selected example includes editable Ziran source and a live preview, using the browser compiler and the gallery editor. Plot and DataViews supply charts, tree, Kanban and an interactive TableView. make site generates the scene metadata and editable snippets directly from these examples. The Pages workflow builds and tests the full website from fixed source revisions before publishing.

Current status

An app compiled to .zx can use Kryon's hosted software surface for a guest window with text, pointer and keyboard input, and resize events.

The feature matrix records package and host coverage. The Canvas2D browser host is covered by private headless Chromium, WebAudio, and Wasm tests. See accessibility for platform coverage.

Kryon commits land upstream first. Applications then update their ziran.lock with Ziran's package commands. This repository's tests verify Kryon itself, not every downstream application build.

See docs/ARCHITECTURE.md for the library boundary and Ziran's implementation status for language and portable runtime gaps.

kryon/breadcrumb serves Breadcrumb.Draw for keyed label navigation, with measured ancestors and an accessible, virtualized overflow menu. Applications own selection, focus and navigation; see the API.

Documentation