Files
waoziandClaude Opus 5.5 15c3a22e43 Bring pictures, text input and scroll devices only with the widgets that use them
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]>
2026-11-15 23:10:23 -03:00

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 under build/ 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 its ziran.lock (or, for an app that still vendors Kryon, its clean vendor/kryon pointer).
  • 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.txt lists the core modules compiled into libkryon.a. *_laws.zi files throughout src/ui/ are proved by make laws, and optional modules such as Window, Media, Video, Clock, and Service are package exports in ziran.toml. A checker pass alone does not establish native or portable readiness.
  • Run make push-check before pushing: it takes minutes and links the hosts a shared backend change can break. CI runs it before its long jobs.
  • make test is 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-level build/ directories. make clean-scratch removes scratch output that has been idle for a day; BUILD_OUTPUTS in the Makefile lists the directories that targets and tests own.
  • Use direct domain names for APIs. Do not restore the removed KIR compiler, .kry runtime, or .krb loader 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.