Architecture

The website is Konjure’s primary project surface: the book, guides, tutorials, reference, examples, research and devlog belong to one static publication. Rust owns executable SDK contracts and their in-source documentation. The site includes generated API reference and runnable Rust example outputs alongside its authored material. See Develop the Rust SDK for the component-by-component workflow.

Applications and Konjure Kreate explains how a standalone workshop and its target builds use these contracts without owning SDK semantics.

Language programs and scene documents

konjure-lang owns the reusable programming language and its running ECS world: types, enums, traits, functions, modules, systems, bounded evaluation, and source inspection. Its spatial bridge couples supported rigid-body components to Rapier and produces the same validated geometry/frame contracts consumed by browser adapters. konjure-sdk owns the portable numeric, buffer, tensor and decoded-media foundation alongside scene documents, the retained declarative compiler and its no_std + alloc profile.

The full language interpreter and physics bridge require std; the embedded scene-document profile does not include them. They are separate dependency boundaries, with one implementation of each behavior in Rust.

One semantic source of truth

The konjure-sdk crate owns the domain model, compiler, validation, geometry and deterministic runtime. Public JSON Schema and TypeScript definitions are generated from these Rust types. The C header is generated from the Rust FFI exports.

Konjure DSL ── compiler ── validated SceneDocument
                                  │
                         Rust runtime + geometry
                                  │
                   frames · events · effect proposals
                     /             |             \
             WASM / browser    C ABI / Unity    native / Python

The runtime does not own a window, device SDK, graphics handle, database, model connection or network socket. It accepts explicit state and events and produces inspectable outputs.

Modules

konjure-web is a Rust crate for browser capabilities, presentation clocks and lifecycle contracts. konjure-wasm exposes SDK, language and browser APIs through generated bindings. The TypeScript @konjure/web package supplies DOM wiring, Three.js rendering, camera controls and WebXR session presentation. Unity owns its renderer. The C ABI owns handles and buffer contracts. Applications decide where to store documents and how to connect models or devices.

Generated schemas describe structural shapes. Rust validation additionally checks units, finite ranges, references, topology and resource budgets; a schema validator alone is not an SDK validator.

Live authority and local rendering

Desktop editor / controls ──┐                   ┌── Browser Rust/WASM → local GPU
                          ├── Rust relay ─────┤
Device controls / editor ──┘    ordered events  └── Native Rust → device GPU

The relay owns the accepted source revision, simulation clock and ordered command journal for one live room. Every client runs that journal through the same Rust interpreter and physics implementation. The RayNeo application renders geometry on its own GPU; the live link does not transmit desktop pixels. Camera position, hardware input and rendering cadence belong to each client.

Any paired participant can send controls or an EditSource request. An edit carries the source revision it was based on. The relay rejects stale edits and compiler errors without replacing the accepted program. A successful edit starts a new run and pauses playback. Only the owner controls the shared clock and closes the room. Input requests are never silently retried after an uncertain disconnect.

The Rust definitions are the source of truth for meaning; the relay’s accepted journal is the source of truth for the current live run. Browser/device runtimes are replicas, and unsubmitted editor drafts remain local. The public Worker persists accepted events and credentials in SQLite until the room expires; its WASM authority restores that history after a restart. The local Rust host keeps rooms in memory. Kreate separately stores project source in IndexedDB and portable files. The protocol does not provide character-by-character merging or lockstep display.

Semantic UI and device targets

Language Button / Slider       Pairing feature
           │                         │
       Rust projection         semantic document
           └────────────┬────────────┘
                    UiDocument
             nodes · actions · placement
                        │
       DeviceTarget + resolved anchor context
                        │
                 PresentationPlan
           ┌────────────┴─────────────┐
      browser screen          RayNeo left + right
           └────────────┬─────────────┘
                     UiEvent
           Rust validation → checked callback

konjure_sdk::presentation defines the contract. Features describe text, buttons, sliders, bounded text inputs, toggles and grouping panels. They request screen, head-relative or anchor-relative placement. They never select eyes, create platform dialogs, or decide how many times to draw. modal distinguishes a popup that owns navigation from controls over a visible scene.

The adapter supplies a DeviceTarget: a logical surface with one mono view or explicit left/right viewports. Rust validates surface bounds and view separation, then produces a route for each view. The native scene renderer and Android UI adapter share the same RayNeo surface topology. The adapter owns layout, projection, pixels, focus feedback and conversion of physical input into semantic events.

An action is an opaque numeric ID associated with a node. An input contains the document ID, interaction revision, node ID and typed value. Rust rejects mismatched actions, disabled nodes, stale program revisions and invalid ranges. For language controls, Rust resolves that action to the stored function value; transports never reconstruct a callable from a displayed label or a function-name string.

Try the native round trip and its browser agreement test:

cargo run -p konjure-lang --example ui_roundtrip
cargo test -p konjure-lang --test ui
npm run sdk:wasm
node --test packages/web/test/ui.test.mjs

Supported presentation

World requires an actual resolved anchor transform in PresentationContext. The SDK keeps that transform in the resulting plan. An unavailable anchor is an error, not permission to head-lock the content. Resource references similarly do not establish image decoding, video playback, sensor access or robot control.

The Java adapter currently reads the Rust JSON contract through JNI; TypeScript declarations are generated. Adding another target means implementing and testing its presentation adapter, not adding hardware conditionals to each UI feature.

The language RenderOutput carries geometry and semantic controls from one validated transaction. RayNeo publishes those controls after submitting that output to both eye views; receiving a newer network event cannot put its controls over an older rendered scene. The UI thread reads a small committed cache rather than waiting on interpreter replay.

Separate authored state from evidence

A scene document describes intent. An observation reports evidence with a source frame, clock, sequence, confidence and provenance. An assistant may propose a change using that evidence. The consumer validates the proposal before changing its scene or executing an effect.

Loading a document does not resolve a room anchor. A model confidence score does not prove spatial alignment. An effect proposal does not mean a robot moved.

Runtime profiles

The default crate includes the compiler. A no_std + alloc profile accepts precompiled Rust documents and runs the bounded geometry and behavior without a browser, OS, model provider or WASM engine. It still needs an allocator and floating-point math support.

WASM is a distribution target for the same core. JavaScript remains a small host adapter because browsers expose DOM, input and XR through their own APIs. Bulk geometry and frame transfers reduce boundary overhead; performance still needs measurement on each device.