Island
Guide: Islands.
Server side
| Export | Signature |
|---|---|
island | (ctx, IslandOpts, inner: *Node) *Node |
IslandOpts | { name: []const u8, props: ?[]const u8 = null, state: ?[]const u8 = null } |
encodeProps | (ctx, props_struct) ![]const u8 |
ctx.islandState | (fields: anytype) ![]const u8 — named i32/f32/bool/string |
ctx.islandStateStruct | (key, value) ![]const u8 — one serialized struct |
Registry contract (src/app/islands.zig): pub const <Name> = struct
{ pub const props_schema: []const u8; pub const Props = struct …; } — implementation at src/client/islands/<Name>.zig, fallback _default.zig.
Chunk side (@import("verve") inside a chunk)
| Export | Signature |
|---|---|
hydrate | your export: fn (props_ptr: u32, props_len: u32, root_id: u32) void |
decodeProps | (comptime T, bytes, alloc) !T — positional mirror of registry Props |
islandStateValue | (comptime T, key) ?T |
DOM access: queryRef(ref) ?i32 → handle, then setRefText, setRefTextI32, setRefAttr, setRefValue, setRefStyle, setRefClass, focusRef, removeRef, refValueI32/F32, refValueStr(h, buf), refSelect, refBlur, refScrollIntoView, refRequestSubmit, refRect, viewport(), matchMedia(q).
Events: registerEvent(handler) u32 (stamp the id as z-on-*-id), dispatchEvent(id); staged reads eventKey(buf), eventMods(), eventCoordX/Y(), eventDeltaY(), eventButton(), eventTargetAttr(name, buf); flags eventPreventDefault(), eventStopPropagation(), eventCapturePointer().
Timers & capabilities: setTimeout/setInterval(ms, handler) u32, requestAnimationFrame(handler), queueMicrotask, clearTimer(id), storage.get/set/len/remove, clipboardWrite(text).
Lists & templates: listDiff(parent_bind, old_keys, new_keys,
new_html), appendToBind, cloneTemplate, slotText, slotAttr.
JSON: parseJson(bytes) ?JsonDoc → .get(key) .at(i) .int() .float() .boolean() .str(buf) .kind() .free(); readStruct(Reply, doc, alloc); per-dispatch arena chunkArena() / chunkArenaMark() / chunkArenaReset(mark).
Lifecycle: cleanup(handler) registers teardown.
Serialization
encode(value, &buf, alloc) · serializeDecode(T, bytes, alloc) · serializeEncodeToBytes(value, alloc). Structs encode in declaration order — see Serialization for the positional contract.
Memory rules
Chunks share the main client's linear memory; stateful chunks (any globals) link data at 0x1000 — at most one per page. 4 KB stack per chunk: large buffers go in globals or the chunk arena.