The desktop rasterizer loads, decodes and smooth-copies file pictures once a program first asks a picture's size, which every widget that draws one does first, so vector icons and managed pixels draw without decoders, threads or asset paths. LanczosSnap is geometry's RectangleSnap, so a texture draw no longer reaches the Lanczos cache. A button reaches file pictures and atlas icons through the new image_lookup. kryon/image is now image_files, which re-exports the Image widget (image) and fills the pictures; kryon/icon fills the atlas. Library code imports image itself, so importing a picture-capable widget registers nothing. Navigation, copy and confirm buttons and the widget host fill the lookup where they draw, as they reached pictures before. Props modules that only name Image.Props import image_props, now also exported; unused image imports are gone. The frame and the accessibility host reach text requests and editor focus through text_editing, which text_request and text_input_platform fill, and the frame samples scrolls through scroll_sampling, which scroll_device fills. Desktop examples (C files, C bytes, executable), before -> after: button 96, 1 411 582, 448 264 -> 70, 980 794, 342 016 text 95, 1 445 077, 462 504 -> 71, 1 020 207, 356 472 textfield 107, 1 580 157, 514 496 -> 84, 1 166 840, 409 840 make pay-per-import-test checks button and textfield; tests whose programs no longer reach pictures lose their picture bindings and stubs. Co-Authored-By: Claude Opus 5.5 <[email protected]>
4.9 KiB
Kryon repository rules
Kryon is a reusable UI library authored in Ziran. The Ziran language,
compiler, .zir representation, .zx format, and portable runtime live in
the separate Ziran repository (~/Projects/ziranlang/ziran). Kryon's reusable widgets
live in src/ui/<component>/, shared UI infrastructure stays in src/ui/,
its hosts live in src/backend/*.zi, and the
kryon project tool in src/project/*.zi.
100% Ziran rule
- Kryon's handwritten implementation, platform integration, and maintained
examples must be written in current Ziran (
.zi). Do not add or expand handwritten C, C++, Go, or other language implementations inside Kryon. Generated native output underbuild/is an output of Ziran, not source. - Use the latest Ziran syntax and APIs directly. Do not add compatibility wrappers, aliases, fallback runtimes, or old-syntax paths for Ziran in Kryon. When Ziran lacks a general capability, implement it in Ziran first and import it as an ordinary language capability. Do not add UI special cases to Ziran.
- The library, hosts, project tool, and examples are all Ziran. Python and
shell scripts are build and test tooling, and
templates/droid/is the Android project scaffold an app build copies; keep widget and host behavior out of them.
Source and build
- Make changes in this upstream repository on
master. Commit and push here before a downstream application updates itsziran.lock(or, for an app that still vendors Kryon, its cleanvendor/kryonpointer). - Never create or work in temporary Kryon or Ziran checkouts, clones, or
worktrees. Edit the root repositories on
master; reserve temporary directories for disposable test outputs only. src/ui/modules.txtlists the core modules compiled intolibkryon.a.*_laws.zifiles throughoutsrc/ui/are proved bymake laws, and optional modules such asWindow,Media,Video,Clock, andServiceare package exports inziran.toml. A checker pass alone does not establish native or portable readiness.- Run
make push-checkbefore pushing: it takes minutes and links the hosts a shared backend change can break. CI runs it before its long jobs. make testis the current Kryon gate. It builds the checked Ziran library and runs Ziran source, saved-IR, and bundle behavior tests without a display.- Put one-off experiment builds in
build/scratch/<name>/, never in new top-levelbuild/directories.make clean-scratchremoves scratch output that has been idle for a day;BUILD_OUTPUTSin the Makefile lists the directories that targets and tests own. - Use direct domain names for APIs. Do not restore the removed KIR compiler,
.kryruntime, or.krbloader as compatibility paths.
UI ownership
Author reusable widget behavior, composition, layout, interaction, styling,
accessibility, and UI tree decisions in .zi. Platform hosts may gather OS
input, manage windows, load fonts and images, rasterize, and store data. Host
code must not independently choose widget behavior.
An application imports Kryon as an ordinary Ziran library. The Ziran compiler and portable loader must never recognize Kryon widget names specially. An application that does not import Kryon needs no Kryon code or graphical host. Keep app-specific screens, assets, copy, workflows, and state in the app repo.
Nothing is imported by default. A program carries only the code for what it
imports and uses. A bare window carries the window, its events and
presenting; import a frame and you get a frame, import a rectangle and you get
a rectangle. Optional features arrive through their import or first use, never
through runtime flags. Shared code reaches an optional part through a small
slot module (such as frame_driver, image_lookup, text_editing and
scroll_sampling) that the part's own module fills from its initializer or
first use; shared code never imports the part itself. Make generated code
smaller by cutting what isn't
needed, never by merging files (owner, 2026-11-15).
One widget concept has one public implementation. Text.Draw(Text.Props) and
Image.Draw(Image.Props) are the intended text and image widget surfaces. Do not
add parallel wrappers or expose raw texture draw calls as app widget APIs.
Testing and desktop safety
Test changed modules through all relevant generated targets and portable bundles. Use focused behavior tests for decisions that could diverge across targets. Do not treat code generation alone as proof that a host or app works.
Never run tests or binaries that can send X/Wayland requests against the
developer's live desktop. Use a private Xvfb/Xephyr display for any visual or
window-management test, and scope window effects to processes Kryon owns.
Never touch the inherited display or /tmp/.X11-unix/X0 during cleanup.
Bend
When using Bend, run bend guide, keep important rules in LAWS.bend, run
bend PROOF.bend before committing, and parallelize the code where possible.