konjure_wasm/

language.rs

//! Browser boundary for the persistent language runtime and source services.
use konjure_lang::inspection::{InspectionError, InspectionTarget};
use konjure_lang::{
    Value,
    live::{LiveCommand, LiveEvent, LiveHistory, LiveRuntime as CoreLiveRuntime},
    spatial::SpatialRuntime,
};
use konjure_sdk::presentation::UiEvent;
use std::collections::BTreeMap;
use wasm_bindgen::prelude::*;

const MAX_MODULE_BYTES: usize = 1024 * 1024;

/// Validates semantic UI and routes it through the supplied device topology.
/// Unresolved world placement is rejected; adapters must supply tracking elsewhere.
#[wasm_bindgen]
pub fn presentation_plan(document_json: &str, target_json: &str) -> Result<String, JsValue> {
    use konjure_sdk::presentation::{
        DeviceTarget, PresentationContext, PresentationPlan, UiDocument,
    };
    if document_json.len() > 1024 * 1024 || target_json.len() > 4096 {
        return Err(JsValue::from_str("presentation input exceeds its bound"));
    }
    let document: UiDocument = serde_json::from_str(document_json).map_err(super::json_error)?;
    let target: DeviceTarget = serde_json::from_str(target_json).map_err(super::json_error)?;
    let plan = PresentationPlan::build(&document, &target, &PresentationContext::default())
        .map_err(|error| JsValue::from_str(&error.to_string()))?;
    super::encode(&plan)
}

/// A checked participant join URL rendered as a camera-readable SVG by Rust.
#[wasm_bindgen]
pub fn live_pairing_qr_svg(join_url: &str) -> Result<String, JsValue> {
    konjure_lang::live::pairing::qr_svg(join_url)
        .map_err(|error| JsValue::from_str(&error.to_string()))
}

/// Parses a pasted participant invitation without joining a room or authorizing transport.
/// The returned JSON is the same validated pairing link accepted from a native QR scan.
#[wasm_bindgen]
pub fn live_pairing_parse_json(join_url: &str) -> Result<String, JsValue> {
    let link = konjure_lang::live::pairing::PairingLink::parse(join_url)
        .map_err(|error| JsValue::from_str(&error.to_string()))?;
    super::encode(&link)
}

fn modules(json: &str) -> Result<BTreeMap<String, String>, JsValue> {
    if json.len() > MAX_MODULE_BYTES {
        return Err(JsValue::from_str("module bundle exceeds 1 MiB"));
    }
    serde_json::from_str(json).map_err(super::json_error)
}
fn error(value: &impl serde::Serialize) -> JsValue {
    JsValue::from_str(
        &serde_json::to_string(value)
            .unwrap_or_else(|_| "language diagnostic encoding failed".into()),
    )
}

/// Standard names, signatures and reference URLs, generated from the Rust catalog.
#[wasm_bindgen]
pub fn language_catalog() -> Result<String, JsValue> {
    super::encode(&konjure_lang::catalog::catalog())
}

/// Analyze source without running initializers, systems, or native effects.
/// Every offset is a UTF-8 byte offset in the indicated source module.
#[wasm_bindgen]
pub fn language_analyze(source: &str, modules_json: &str) -> Result<String, JsValue> {
    let supplied = modules(modules_json)?;
    let (symbols, methods, references, diagnostics) = match konjure_lang::compile(source, &supplied) {
        Ok(program) => (program.metadata().symbols.iter().map(|s| serde_json::json!({
            "name":s.name, "kind":s.kind, "start":s.span.start, "end":s.span.end,
            "module":s.span.module, "signature":s.signature, "qualified_name":s.qualified_name,
        })).collect::<Vec<_>>(), program.metadata().methods.clone(), program.metadata().references.clone(), Vec::new()),
        Err(diagnostics) => (Vec::new(), Vec::new(), Vec::new(), diagnostics),
    };
    let tokens = konjure_lang::parser::tokenize(source, "main").unwrap_or_default();
    super::encode(&serde_json::json!({
        "tokens":tokens.iter().map(|t| serde_json::json!({
            "start":t.span.start,"end":t.span.end,"kind":t.kind,"text":t.text,
        })).collect::<Vec<_>>(), "symbols":symbols, "methods":methods, "references":references, "diagnostics":diagnostics,
    }))
}

/// Persistent, explicitly stepped interpreter and physics world.
/// Call `free()` when replacing a program or disposing its editor.
#[wasm_bindgen]
pub struct LanguageRuntime {
    inner: SpatialRuntime,
}

/// Bounded replayable live-session protocol. The browser transports only JSON;
/// compilation, callbacks, simulation, and render validation remain in Rust.
#[wasm_bindgen]
#[derive(Default)]
pub struct LiveRuntime {
    inner: CoreLiveRuntime,
}

#[wasm_bindgen]
impl LiveRuntime {
    /// Reads semantic controls; source revision and callbacks are owned by Rust.
    pub fn ui_json(&self) -> Result<String, JsValue> {
        super::encode(&self.inner.ui_document().map_err(|value| error(&value))?)
    }
    /// Creates an empty session. Apply a `load` command before stepping or rendering.
    #[wasm_bindgen(constructor)]
    pub fn new() -> Self {
        Self {
            inner: CoreLiveRuntime::new(),
        }
    }

    /// Applies one command and returns the assigned sequence event as JSON.
    pub fn apply_json(&mut self, command_json: &str) -> Result<String, JsValue> {
        if command_json.len() > 4 * 1024 * 1024 {
            return Err(JsValue::from_str("live command exceeds 4 MiB"));
        }
        let command: LiveCommand = serde_json::from_str(command_json).map_err(super::json_error)?;
        super::encode(&self.inner.apply(command).map_err(|value| error(&value))?)
    }

    /// Validates and applies a semantic control event for a locally hosted or detached session.
    /// Connected clients must send UI input to the live authority, which orders the command.
    pub fn apply_ui_json(&mut self, event_json: &str) -> Result<String, JsValue> {
        if event_json.len() > 8 * 1024 {
            return Err(JsValue::from_str("UI event exceeds 8 KiB"));
        }
        let event: UiEvent = serde_json::from_str(event_json).map_err(super::json_error)?;
        let command = self
            .inner
            .ui_command(&event)
            .map_err(|value| error(&value))?;
        super::encode(&self.inner.apply(command).map_err(|value| error(&value))?)
    }

    /// Accepts one exact-next replay event. Gaps and duplicates preserve state.
    pub fn accept_json(&mut self, event_json: &str) -> Result<(), JsValue> {
        if event_json.len() > 4 * 1024 * 1024 {
            return Err(JsValue::from_str("live event exceeds 4 MiB"));
        }
        let event: LiveEvent = serde_json::from_str(event_json).map_err(super::json_error)?;
        self.inner.accept(event).map_err(|value| error(&value))
    }

    /// Replaces this session with a transactionally replayed history.
    pub fn restore_json(&mut self, history_json: &str) -> Result<(), JsValue> {
        if history_json.len() > konjure_lang::live::MAX_JOURNAL_BYTES {
            return Err(JsValue::from_str("live history exceeds 16 MiB"));
        }
        let history: LiveHistory = serde_json::from_str(history_json).map_err(super::json_error)?;
        self.inner.restore(history).map_err(|value| error(&value))
    }

    /// Returns the retained event suffix and its base sequence as JSON.
    pub fn history_json(&self) -> Result<String, JsValue> {
        super::encode(self.inner.history())
    }

    /// Returns the accepted snapshot, or JSON `null` before the first load.
    pub fn snapshot_json(&self) -> Result<String, JsValue> {
        super::encode(&self.inner.snapshot())
    }

    /// Returns validated generated render data for the accepted revision.
    pub fn render_json(&self) -> Result<String, JsValue> {
        super::encode(&self.inner.render().map_err(|value| error(&value))?)
    }

    /// Inspects accepted tensor data without executing source or mutating the session.
    pub fn inspect_tensor_json(&self, target_json: &str) -> String {
        let result = if target_json.len() > 4096 {
            Err(InspectionError::InvalidTarget)
        } else {
            self.inner
                .snapshot()
                .ok_or(InspectionError::InvalidTarget)
                .and_then(|snapshot| {
                    serde_json::from_str::<InspectionTarget>(target_json)
                        .map_err(|_| InspectionError::InvalidTarget)
                        .and_then(|target| snapshot.tensor_inspection(&target))
                })
        };
        serde_json::to_string(&result).unwrap_or_else(|_| "{\"Err\":\"encoding\"}".into())
    }
}

#[wasm_bindgen]
impl LanguageRuntime {
    /// Reads semantic controls for this standalone interpreter instance.
    pub fn ui_json(&self) -> Result<String, JsValue> {
        super::encode(
            &self
                .inner
                .ui_document()
                .map_err(|value| JsValue::from_str(&value.to_string()))?,
        )
    }

    /// Validates a semantic input and invokes its Rust-owned callback transactionally.
    pub fn invoke_ui(&mut self, event_json: &str) -> Result<String, JsValue> {
        if event_json.len() > 8192 {
            return Err(JsValue::from_str("UI event exceeds 8 KiB"));
        }
        let event = serde_json::from_str(event_json).map_err(super::json_error)?;
        super::encode(
            &self
                .inner
                .invoke_ui(&event)
                .map_err(|value| error(&value))?,
        )
    }
    /// Constructs and initializes a program. Imports come only from `modules_json`.
    #[wasm_bindgen(constructor)]
    pub fn new(source: &str, modules_json: &str) -> Result<Self, JsValue> {
        Ok(Self {
            inner: SpatialRuntime::new(source, &modules(modules_json)?).map_err(|e| error(&e))?,
        })
    }
    /// Advances a bounded number of fixed simulation ticks.
    pub fn step(&mut self, count: f64) -> Result<String, JsValue> {
        if !count.is_finite() || count.fract() != 0.0 || !(0.0..=600.0).contains(&count) {
            return Err(JsValue::from_str(
                "step count must be an integer between 0 and 600",
            ));
        }
        super::encode(&self.inner.step(count as u32).map_err(|e| error(&e))?)
    }
    /// Runs pending system `done` callbacks once. A failure preserves the run.
    /// Use `free()` separately to release the WebAssembly allocation.
    pub fn finish(&mut self) -> Result<String, JsValue> {
        super::encode(&self.inner.finish().map_err(|e| error(&e))?)
    }
    /// Reads serializable component values, logs and source-linked execution trace.
    pub fn snapshot_json(&self) -> Result<String, JsValue> {
        super::encode(&self.inner.snapshot())
    }
    /// Returns an algebraic JSON result for read-only tensor inspection.
    ///
    /// `target_json` encodes a language [`InspectionTarget`], limited to 4 KiB.
    /// The result is `{"Ok": TensorInspection}` or `{"Err": InspectionError}`.
    /// It never evaluates source, dispatches callbacks, or alters accepted state.
    /// The SDK bounds sampling and preserves exact numeric previews and extrema.
    pub fn inspect_tensor_json(&self, target_json: &str) -> String {
        let result = if target_json.len() > 4096 {
            Err(InspectionError::InvalidTarget)
        } else {
            serde_json::from_str::<InspectionTarget>(target_json)
                .map_err(|_| InspectionError::InvalidTarget)
                .and_then(|target| self.inner.snapshot().tensor_inspection(&target))
        };
        serde_json::to_string(&result).unwrap_or_else(|_| "{\"Err\":\"encoding\"}".into())
    }
    /// Exports one global tensor as an owned, packed little-endian byte array.
    ///
    /// Strided views are materialized in logical row-major order. The returned
    /// Uint8Array owns its bytes, so later stepping, allocation or `free()` cannot
    /// invalidate it. Read [`Self::tensor_metadata_json`] for the element format.
    pub fn tensor_bytes(&self, name: &str) -> Result<Vec<u8>, JsValue> {
        let snapshot = self.inner.snapshot();
        let Some(Value::Tensor(tensor)) = snapshot.globals.get(name) else {
            return Err(JsValue::from_str("global must name a Tensor"));
        };
        Ok(tensor.to_le_bytes())
    }
    /// Describes the independent packed export, rather than its internal view strides.
    pub fn tensor_metadata_json(&self, name: &str) -> Result<String, JsValue> {
        let snapshot = self.inner.snapshot();
        let Some(Value::Tensor(tensor)) = snapshot.globals.get(name) else {
            return Err(JsValue::from_str("global must name a Tensor"));
        };
        super::encode(&serde_json::json!({
            "dtype": tensor.dtype(), "shape": tensor.shape(),
            "byte_length": tensor.byte_len(), "byte_order": "little", "order": "row-major",
        }))
    }
    /// Generates validated render data. Browser code owns GPU and DOM resources.
    pub fn render_json(&self) -> Result<String, JsValue> {
        super::encode(&self.inner.render().map_err(|e| error(&e))?)
    }
    /// Dispatches a component method such as `click` without browser-owned behavior.
    pub fn invoke_entity(
        &mut self,
        entity: f64,
        method: &str,
        args_json: &str,
    ) -> Result<String, JsValue> {
        if args_json.len() > 64 * 1024 {
            return Err(JsValue::from_str("arguments exceed 64 KiB"));
        }
        if !entity.is_finite()
            || entity.fract() != 0.0
            || !(1.0..=9_007_199_254_740_991.0).contains(&entity)
        {
            return Err(JsValue::from_str(
                "entity ID must be a positive exact integer",
            ));
        }
        let args: Vec<Value> = serde_json::from_str(args_json).map_err(super::json_error)?;
        super::encode(
            &self
                .inner
                .invoke_entity(entity as u64, method, &args)
                .map_err(|e| error(&e))?,
        )
    }
    /// Invokes the typed callback held in a Rust-owned component field.
    /// The browser supplies only entity, component and field identity.
    pub fn invoke_component(
        &mut self,
        entity: f64,
        component: &str,
        field: &str,
        args_json: &str,
    ) -> Result<String, JsValue> {
        if args_json.len() > 64 * 1024 {
            return Err(JsValue::from_str("arguments exceed 64 KiB"));
        }
        if !entity.is_finite()
            || entity.fract() != 0.0
            || !(1.0..=9_007_199_254_740_991.0).contains(&entity)
        {
            return Err(JsValue::from_str(
                "entity ID must be a positive exact integer",
            ));
        }
        let args: Vec<Value> = serde_json::from_str(args_json).map_err(super::json_error)?;
        super::encode(
            &self
                .inner
                .invoke_component(entity as u64, component, field, &args)
                .map_err(|e| error(&e))?,
        )
    }
    /// Calls a language action with typed JSON arguments. Invalid calls preserve state.
    pub fn invoke(&mut self, name: &str, args_json: &str) -> Result<String, JsValue> {
        if args_json.len() > 64 * 1024 {
            return Err(JsValue::from_str("arguments exceed 64 KiB"));
        }
        let args: Vec<Value> = serde_json::from_str(args_json).map_err(super::json_error)?;
        super::encode(&self.inner.invoke(name, &args).map_err(|e| error(&e))?)
    }
}