Picking the Wasm platform saves ziran.previewPlatform in the folder's .vscode/settings.json, so a run against a real checkout left Kryon's folder on Wasm. The test now restores the file it found, or removes the one it made.
Ziran Language for VS Code
Editor support for Ziran .zi source: syntax highlighting, brackets, comments,
import completion, and Go to Definition for extensionless #import "module"
statements. Modules are discovered from .zi and .zir files in the open
workspace. The extension also finds the standard modules in a sibling ziran/std
directory, so a Kryon workspace can import them without listing every module.
This is language support for any Ziran project; it does not bundle Kryon widgets.
A single .zi file works without a folder or kryon.toml: its own directory
and the Ziran checkout's std are searched for imports.
Inside a Ziran package (a folder with ziran.toml), files are checked with
ziran check --project, so dependencies added with ziran add URL are
checked too. Go to Definition and import completion then follow the
project's module map: #import "kryon/Widgets" opens that dependency's
exported module, #import "std/text" the pinned standard library, and a
short name resolves the way the compiler resolves it.
Running
Click ▶ in the editor title bar, or ▶ Run above main, to open the Run
pane beside a .zi file. Like the Kryon preview it shows, top to bottom:
- the program's output in a window, with the run time and any build or runtime errors below it (a run stops after 10 seconds);
- Targets: one tab per target (C, Go, WebAssembly and Native), with
syntax highlighting and a file picker; the checkboxes choose the targets and
save them to
ziran.previewTargets.
Every target shows one chain, in one order, from the same builds: Source,
ZIR (the checked program, listed by zi-inspect), LIR, Optimized
(the verified instructions read back from ZX and the optimization report) and
ZX. A target shows the stages it really uses, then its own output: C and Go
compile the checked ZIR directly, so they show Source and ZIR, then
C or Go with their Assembly and Binary; WebAssembly and Native
go through ZX, so they show every stage, then WAT and Binary, or
Assembly and Binary. TARGET_STAGES in targets.cjs is the one table
behind both the tabs and the commands each build runs. Source and ZIR list the
program's own modules first, then its dependencies, read only when picked from
the file dropdown above the code. Ziran source is colored with this
extension's own grammar, and the other tabs with light highlighting, in the
editor's light or dark theme.
Saving a .zi file in the same directory reruns everything; Run again does
it on demand. A file without main :: () still shows its source and generated
code. The program is bundled with ziran bundle --entry module:main and run
with ziran run on the portable runtime. In Kryon projects ▶ runs the Kryon
preview instead.
Platforms
The Platform dropdown beside the target checkboxes chooses what Native
lowers ZX to and where ▶ runs the program. It lists what the toolchain says
it can build: every row of ziran capabilities --json, checked against
zx2native's own --target, --platform and --emit choices and a probe of
each row, then Wasm from zx2wasm. A row the toolchain refuses is listed
but disabled, with its gap by name (for example
assembly.gap.machine-platform-service-unavailable), so the list follows the
toolchain without a table of its own here. The choice is saved to
ziran.previewPlatform.
The shared stages (Source, ZIR, LIR, Optimized, ZX) are the same on every platform; only Native's output changes:
- Linux x86-64: an ELF, run directly.
- Windows x86-64: a PE
.exe(zx2native --platform windows, lit up as soon aszx2nativeaccepts it), run under Wine with a privateWINEPREFIXin the extension's storage andWINEDEBUG=-all. - Linux or Android AArch64 and ARMv7: an ELF, run on an attached device
through adb.
ziran.adbCommandslists how to reach adb, such asadborssh user@host adbfor a phone on another machine; the first device whose primary Android ABI matches runs it, then any that supports it. With no device the platform still analyzes, and Run names what is missing. - Wasm: a
zx2wasmmodule, shown as WAT and Binary, run in Node by the extension'swasm-run.cjs.
Each run is one process, with its output in the Run pane; nothing falls back to another platform, and a missing route (no Wine, no device, no Node) is named. In the Kryon preview, Open in window follows the same choice and runs the build the Binary tab shows: on Linux x86-64, the executable itself.
A machine format's Assembly is the whole file. For an ELF: the ELF header,
the program headers and each region of the file in order. For a PE: the DOS
header and stub, the PE headers, the section table and the imports, then each
region, with calls through the import address table named as
<KERNEL32.dll!WriteFile>. Code is disassembled with a <module:function>
label at each function from the native map, and data is shown as bytes. Hide
ELF parts or Hide PE parts leaves only the program's own functions,
hiding the headers, the DOS stub, the import tables and the padding. Binary
is the whole file in hex, each region under a label row with its offsets; the
same toggle keeps only the program's code and data. Going to an offset the
toggle hides shows the whole file again. The disassembler follows the file's
machine: objdump reads x86-64 ELF and PE code (i386:x86-64), and AArch64
and ARM code goes to a cross objdump or, when that is missing, the Android
NDK's llvm-objdump.
zi2zx writes the LIR, the optimization report and final.zx, and lists the
verified ZX; zx2native lowers final.zx to the native map and ELF. Each is
found beside the ziran command or in a Ziran checkout (build them with
make), and a missing one is named.
C and Go also produce binaries, whose hex marks the ELF sections; WebAssembly
and ZX binaries mark their sections the same way.
There is one Native checkbox: ZX is a portable instruction stage within it, not
a second target. Native is enabled by default; an older previewTargets entry
of "zx" selects Native automatically without creating a duplicate option.
Direct native console output uses Ziran-owned formatting and syscall veneers, without libc or a dynamic linker. Unsupported services, targets and formatting (including floats) produce named gap errors; Native never falls back to another engine, and Run shows the same gap for the program. Build outputs stay in the extension's private storage and are removed when its Run pane closes; the original example is never replaced with generated stages.
Checking
Opening or saving a .zi file runs ziran check on it and lists any errors in
the Problems panel and under the source. A file checks with its own
directory as the root, as ziran check --root . file.zi would.
Type errors link to related declarations in the Problems panel. Missing-name
errors offer a Quick Fix when the compiler identifies an unambiguous source
replacement; a fix is discarded if the name has changed since checking.
Names, hover, and definitions
The extension asks ziran api which procedures, types, constants, and globals
a file's program declares, including those of its imports. Completion offers
them with their signatures, hovering a name shows its declaration and the
// comment above it, and Go to Definition opens the line that declares it.
A name the file's own module declares wins over an imported one of the same
name.
Finding the compiler
Checking, the Run pane, and .zir browsing use the ziran
command from ziran.command when set. Kryon packages otherwise use the installed
~/.local/bin/ziran wrapper (then PATH) so the package toolchain and local
overrides select the compiler. Other files use a Ziran checkout's
build/bin/ziran found above the file, in a Kryon project's [paths].ziran,
or beside the workspace folder, then ~/.local/bin/ziran, then PATH.
Kryon preview
Open an example source such as examples/button/button.zi in a Kryon app with
ziran.toml (or legacy kryon.toml), then click Run Kryon in the status
bar, Run Kryon Preview above the source, or Kryon: Preview in the Command
Palette. The nearest app manifest selects the entry; no app.zi filename is required.
The preview builds through build-queue -- kryon build --profile PROFILE and
embeds the generated HTML, JavaScript, WebAssembly and packaged assets in an isolated
interactive frame. It selects
portable_web, then web, then another canvas profile. Set ziran.previewProfile
to choose a canvas profile explicitly and ziran.kryonCommand to select the launcher.
The launcher uses the project's package toolchain and local overrides.
Saving sources in the workspace, or changing app manifests, overrides or locks, rebuilds the preview. Generated build files are excluded to prevent rebuild loops. Run again rebuilds on demand. Build errors appear below the preview; fixing and saving the source restores it. Preview builds cannot inherit the desktop display.
Under the live window the preview shows the same Targets as the Run pane for the previewed source, or the project's entry when it was opened from a folder; they rebuild beside the preview on every save.
Kryon programs
A .zi file that imports kryon/app and declares main, such as Kryon's
examples/window.zi, is a program that opens its own window. Running it, with
▶, ▶ Run or Kryon: Preview, opens this preview instead of the Run
pane, and the program's real interface runs live inside the frame. The
extension keeps a private project for the file in its own storage, with one
canvas profile, and the Kryon tool builds the program's main for the page.
Open in window bundles the program to the same ZX the ZX tab shows,
lowers it for the selected platform as the Binary tab does and runs that,
in one process; opening it again replaces that process, and closing the
preview ends it. On Linux x86-64 the executable links its host capabilities,
such as Kryon's window, from the host libraries registered beside the ZX
players (make install-user in Kryon registers its desktop library). On the
Wasm platform it runs the program's ZX in the page instead, in the frame the
web preview uses: a canvas profile with codegen = "zx" (wasm in a
single-file preview's own project) builds Kryon's canvas player around the
bundle, which lowers it to Wasm in the page and runs its main with the
page's canvas as its window. There is no fallback to C, a player or the
portable engine: a capability no registered library provides, or a program
that cannot run, shows the tool's named gap in the pane. The preview follows the active .zi
editor, and its live frame has no padding and a transparent page over the
editor's background.
The portable Run pane does not run such a program: the portable runtime has no
window host, so App.Run would return its failure status and the pane would
print that result, 1, as the program's value. It is main's return value,
not output, and in a C-generated executable the same integer is the process
exit status. The preview's targets show the program's own code first: for
window.zi, the C view opens window.c, not the Kryon modules the build also
writes. Every other
generated file, such as Kryon, the standard library and runtime support, is
listed under Dependencies and is read, compiled to assembly or inspected
only when you pick it. A target that cannot build the program shows a one-line
reason, with the tool's full output collapsed under it.
Browse checked modules
Open any .zir file in VS Code to see its inspected declarations and expressions
instead of binary bytes. The outline lists its types, functions, and globals.
Use Hex to see byte offsets and Open as Text for VS Code's normal search,
selection, and outline tools. The view refreshes when the .zir file changes.
For module directories outside the workspace, set ziran.modulePaths in VS Code
settings. Paths may be absolute or relative to the workspace folder. The
compiler still needs the corresponding --module-path arguments when building.
If several files have the same module name, Go to Definition offers every match.
Install
Download the .vsix from the latest GitHub Release, then run:
code --install-extension ziran-language-*.vsix
You can also use Extensions: Install from VSIX... in VS Code. Reload the
window after installing. New .zi tabs will open in Ziran mode automatically.
If an existing tab still says Plain Text in the status bar, use Change Language
Mode and select Ziran.
Build
npm ci
npm test
npm run package
GitHub Actions uploads a VSIX from every build. Maintainers can use the workflow's Run workflow button with Publish GitHub Release enabled to publish the package version as a public release.
Local preview tests
Selected files inside a Ziran package use --project for generated targets,
checked IR and portable execution. The package CLI supplies module roots,
dependency exports and local overrides even when the editor opens a parent
workspace. Standalone files retain their own directory as the module root.
Run npm test for the local suite and npm run test:preview for a fresh VSCode
extension host on a private Xvfb display. The latter verifies an interactive test
page, editor saves, build errors and recovery. For a real app build, set
ZIRAN_PREVIEW_PROJECT to its directory and ZIRAN_PREVIEW_ENTRY to its entry
filename before running npm run test:preview. This uses installed VSCode and
requires build-queue and the project toolchain on PATH.
Set ZIRAN_PREVIEW_FIXTURE=1 for a disposable real Button app using canonical
Kryon/compiler overrides. That test also compiles saved edits, verifies an actual
malformed-source error, repairs it, and checks restored interactive pixels.
Maintained example sources are never edited.
Set ZIRAN_PREVIEW_WINDOW=1 and ZIRAN_RUN_TEST=1 with ZIRAN_PREVIEW_PROJECT
at a Kryon checkout and ZIRAN_PREVIEW_ENTRY=examples/window.zi to test a Kryon
program: Run must open the live embedded canvas, Open in window must start
exactly one native executable, build no C and show one 320x160 window titled
"Window", and the targets under the window must show their stage tabs with
window.c first, the Kryon modules under Dependencies and Native's Assembly
of the linked executable. Kryon's desktop host library must be registered
(make install-user, or ZIRAN_HOST_PATH at a registry holding its
.library file); ZIRAN_PREVIEW_COMMAND points the editor at another
ziran command and the tools beside it.
For generated-code Preview on an existing source file, use
ZIRAN_PREVIEW_PROJECT=/path/to/package ZIRAN_PREVIEW_ENTRY=relative/file.zi npm run test:run.
Set ZIRAN_PREVIEW_WORKSPACE to a parent folder to test workspace nesting.
This mode reads the real source without saving edits and verifies its C and Go
views in a private VSCode window.
Add ZIRAN_RUN_NATIVE=1 to inspect the existing examples/hello.zi through every
Native stage instead. For example, set ZIRAN_PREVIEW_PROJECT to the canonical
Ziran checkout and ZIRAN_PREVIEW_ENTRY=examples/hello.zi. This also verifies
the full and filtered Assembly and Binary views without changing that source.
Run npm run test:laws to verify law token colors in an isolated native VSCode
window on private Xvfb. Set ZIRAN_INSTALLED_EXTENSION to an installed extension
folder to test that copy. This preserves the running editor and its profile.