Extensions

The ModuleRegistry provides a hook-based extension system for adding modular capabilities to the runtime.

Module structure

Each module has an info block, a context pointer, and optional lifecycle hooks:

const MyModule = struct {
    data: u32 = 0,

    fn start(context: *anyopaque, runtime: zero_native.extensions.RuntimeContext) anyerror!void {
        _ = runtime;
        const self: *@This() = @ptrCast(@alignCast(context));
        self.data = 42;
    }

    fn command(context: *anyopaque, runtime: zero_native.extensions.RuntimeContext, cmd: zero_native.extensions.Command) anyerror!void {
        _ = runtime;
        const self: *@This() = @ptrCast(@alignCast(context));
        if (std.mem.eql(u8, cmd.name, "reset")) self.data = 0;
    }
};

Registering modules

var my_module = MyModule{};
const caps = [_]zero_native.extensions.Capability{.{ .kind = .native_module }};
const modules = [_]zero_native.extensions.Module{.{
    .info = .{ .id = 1, .name = "my-module", .capabilities = &caps },
    .context = &my_module,
    .hooks = .{ .start_fn = MyModule.start, .command_fn = MyModule.command },
}};
const registry = zero_native.extensions.ModuleRegistry{ .modules = &modules };

var runtime = zero_native.Runtime.init(.{
    .platform = my_platform,
    .extensions = registry,
});

Module fields

Field	Type	Description
`info.id`	`u64`	Unique numeric identifier (duplicates rejected at validation)
`info.name`	`[]const u8`	Human-readable module name
`info.capabilities`	`[]const Capability`	Capabilities this module provides
`context`	`*anyopaque`	Opaque pointer to module state
`hooks.start_fn`	optional	Called when the runtime starts
`hooks.stop_fn`	optional	Called when the runtime stops (reverse registration order)
`hooks.command_fn`	optional	Called when a command is dispatched to modules

Registry methods

Method	Description
`validate()`	Check for duplicate module IDs
`startAll(runtime)`	Call `start_fn` on all modules
`stopAll(runtime)`	Call `stop_fn` on all modules (reverse order)
`dispatchCommand(runtime, command)`	Call `command_fn` on all modules
`hasCapability(kind)`	Check if any module provides a capability

Capability kinds

Kind	Description
`native_module`	A native Zig module
`webview`	WebView rendering
`js_bridge`	JavaScript bridge
`filesystem`	File system access
`network`	Network access
`clipboard`	Clipboard access
`custom`	Custom capability (with a `name` field)

These map to the capabilities field in app.zon. The runtime can query whether any module provides a given capability using registry.hasCapability(.filesystem).

Native JS engine (experimental)

The js module provides an abstraction layer for calling into a native JavaScript engine from Zig. This is separate from the WebView bridge and is intended for future native module integrations.

Type	Description
`Value`	Tagged union: `null`, `boolean`, `number`, `string`
`Call`	A function call: `module`, `function`, `args`
`Bridge`	Validates and dispatches calls via `RuntimeHooks`
`NullEngine`	Stub that returns `EngineUnavailable`