Interactive ABI

This ABI is for stateful, event-driven modules that render an output frame. We prefer a small host/module contract over protocol complexity: send key and pointer events directly, advance state with tick, then pull pixels with render_output.

The design goal is practical interoperability: browser and native hosts can adapt input to this ABI, and modules stay tiny.

Core Contract

Required exports:

• memory
• output_ptr() -> i32
• output_bytes_cap() -> i32
• key_event(x11_key: i32, flags: i32, now_ms: i32) -> i32
• pointer_event(button_mask: i32, x_px: i32, y_px: i32, now_ms: i32) -> i32
• tick(now_ms: i32) -> i32
• render_output() -> i32

Output Format

• Pixel format is fixed: RGBA8 bytes in memory order [R, G, B, A].
• Output is row-major, top-left origin, tightly packed.
• Total bytes for a full frame: render_width_px * render_height_px * 4.

Little-endian note:

• Hosts that view pixels as u32 will see each pixel as 0xAABBGGRR on little-endian systems.
• For portability, treat output as byte-addressed RGBA8, not host-endian u32 values.

Event Semantics

key_event(...):

• x11_key uses X11 keysym values (aligned with RFB KeyEvent semantics).
• flags is a bitfield:
  • bit 0: key down (1) / key up (0)
  • bit 1: repeat
  • bit 2: shift
  • bit 3: ctrl
  • bit 4: alt
  • bit 5: meta
• now_ms is monotonic elapsed milliseconds from the same timeline used by tick(now_ms).
• Return 1 when accepted, 0 when ignored.

pointer_event(...):

• button_mask uses only the low 3 bits: primary=1, middle=2, secondary=4.
• x_px and y_px are integer pixel coordinates in current render space.
• now_ms is monotonic elapsed milliseconds from the same timeline used by tick(now_ms).
• Return 1 when accepted, 0 when ignored.

Tick + Render Flow

We intentionally split simulation from rendering.

• tick(now_ms) advances state.
• render_output() writes/returns output bytes from current state.

tick(now_ms) return value:

• 0: no visual change (host may skip render_output())
• 1: output changed (host should call render_output())

This dirty bit pattern is common in interactive systems and helps avoid unnecessary redraw work.

Time source requirements:

• now_ms should be monotonic time in milliseconds.
• Hosts should call tick(0) first, then pass elapsed milliseconds since that start tick.
• Do not use wall-clock time for simulation.

Sizing Variants

Use the same core ABI for both variants.

Static Size Variant

Module decides size at instantiation and keeps it fixed.

Additional required exports:

• render_width_px() -> i32
• render_height_px() -> i32

Rules:

• Size does not change during instance lifetime.
• Host validates output_bytes_cap() >= render_width_px()*render_height_px()*4.

Dynamic Size Variant

Host/user can request size changes within declared limits.

Additional required exports:

• render_width_px() -> i32
• render_height_px() -> i32
• render_max_width_px() -> i32
• render_max_height_px() -> i32
• render_resize(width_px: i32, height_px: i32) -> i32

Rules:

• render_resize(...) returns 1 on success, 0 on rejection.
• Rejection should be used for out-of-range or unsupported sizes.
• Width/height getters must reflect current active size.
• Host validates capacity after resize using current size.

Host Loop Pattern

Typical host flow:

1. Deliver input as it arrives via key_event(...) / pointer_event(...).
2. On frame callback (for example requestAnimationFrame), call tick(now_ms).
3. If tick returns 1, call render_output() and read output_ptr() bytes.

This gives low-latency input handling while keeping frame scheduling host-driven.

Why This Shape

Claim: this ABI is a better default than embedding a full protocol stream.

Reason:

• It keeps wasm modules free of packet parsing logic.
• It aligns with familiar game/UI separation (tick then render).
• It composes with multiple hosts (browser/native) by adapting input at the edge.

Tradeoff:

• You lose protocol-level extensibility in v1.
• If batching or replay is needed later, add an optional batched event API in a future version without breaking this core.