Xript.Runtime 0.7.0

Xript.Runtime

C# runtime for xript: sandboxed JavaScript execution via Jint, a pure C# JavaScript interpreter. No native dependencies.

Install

dotnet add package Xript.Runtime

Usage

using System.Text.Json;
using Xript.Runtime;

var manifest = """
{
    "xript": "0.7",
    "name": "my-app",
    "bindings": {
        "greet": {
            "description": "Returns a greeting.",
            "params": [{ "name": "name", "type": "string" }],
            "returns": "string"
        }
    }
}
""";

var bindings = new HostBindings();
bindings.AddFunction("greet", args =>
{
    var name = args.Length > 0 ? args[0].GetString() : "World";
    return JsonSerializer.SerializeToElement($"Hello, {name}!");
});

using var runtime = XriptRuntime.Create(manifest, new RuntimeOptions
{
    HostBindings = bindings,
    Capabilities = [],
    Console = new ConsoleHandler
    {
        Log = msg => Console.WriteLine(msg),
        Warn = msg => Console.WriteLine($"WARN: {msg}"),
        Error = msg => Console.Error.WriteLine(msg),
    },
});

var result = runtime.Execute("greet(\"World\")");
// result.Value => "Hello, World!"
// result.DurationMs => 0.1 (approx)

What it does

• Runs user-provided JavaScript inside a Jint sandbox (pure C#, no native interop)
• Only functions declared in the manifest are available to scripts; everything else is blocked
• Supports capability-gated bindings, namespace bindings, hooks, and resource limits
• Fragment processing with data-bind and data-if support
• Mod loading via LoadMod() with cross-validation against the host manifest
• No eval, no Function, no access to the host environment

v0.5.0

• cooperative cancellation via a CancellationToken on RuntimeOptions; it interrupts in-flight execution and surfaces a distinct cancellation error (not a timeout), with Jint interrupting mid-run via its token
• opt-in capability audit channel: a hook reporting every allowed host-binding invocation as { binding, capability, at }
• console severity: ConsoleHandler gained a severity enum (log/info/warn/error/debug) plus a trace channel
• sandbox hard caps: host ceilings on memory, CPU time, and stack depth
• manifest extends with deep-merge so a manifest can inherit and override host bindings; mod manifests gained an optional family field for grouping
• host-invoke exports: mods declare named exports the host calls by name and whose return value it honors
• ES module mods via entry.format: "module", which evaluates the entry as a real ES module through Jint's module API; top-level named exports auto-register as host-invokable, and external imports stay denied
• provider-role resolution: mods declare contributions.provides and the host calls ResolveRole(role) (first-installed-wins, settings-overridable) to bind a logical role to a concrete export
• slot runtime resolver: ordering by priority, single/multiple cardinality, and capability enforcement on contributions
• DAP-shaped debug protocol: set/clear breakpoints by source position, pause/resume/step in/over/out, and inspect scopes, locals, and stack frames (Jint pauses synchronously on the engine thread)

API

XriptRuntime.Create(manifestJson, options?) -> XriptRuntime

Creates a sandboxed runtime from a JSON manifest string. Validates the manifest on creation.

XriptRuntime.CreateFromFile(path, options?) -> XriptRuntime

Reads a manifest JSON file from disk and creates a runtime.

XriptRuntime.CreateFromValue(doc, options?) -> XriptRuntime

Creates a runtime from a JsonDocument.

runtime.Execute(code) -> ExecutionResult

Executes JavaScript code in the sandbox. Returns ExecutionResult { Value, DurationMs }.

runtime.FireHook(name, options?) -> JsonElement[]

Fires a hook by name, calling all registered handlers. Returns an array of handler return values.

runtime.LoadMod(modManifestJson, fragmentSources?) -> ModInstance

Loads a mod manifest, cross-validates it against the host manifest, and returns a ModInstance with fragment sources.

runtime.Dispose()

Releases sandbox resources. XriptRuntime implements IDisposable, so using works.

When to use this vs other runtimes

Use this package when your host application is .NET. Use xript-runtime for Rust hosts. Use @xriptjs/runtime for JavaScript environments that need universal portability. Use @xriptjs/runtime-node for Node.js-only applications.

Documentation

xript.dev: full docs, getting started guide, and live demos.

License

MIT