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.
Website and widget gallery
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.