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(input_size).

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_rgba8_srgb_bytes() -> i32
• key_event(x11_key: i32, flags: i32, now_ms: i64) -> i32
• pointer_event(button_mask: i32, x_px: i32, y_px: i32, now_ms: i64) -> i32
• tick(now_ms: i64) -> i64
• render(input_size: i32) -> i32
  • If no input bytes are being passed for this frame, host must pass 0.
  • The ABI uses one fixed signature to avoid per-runtime export arity/type branching.

Output Format

• Pixel format is fixed: color component bytes in memory order [R, G, B, A].
• Output is row-major, top-left origin, tightly packed.
• Stride is fixed: bytes_per_row = render_width_px * 4 (no row padding).
• Alpha is straight (not premultiplied) in module memory.
• Colors are in sRGB colorspace with 2.2 gamma.
• 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.

Rendering Target Interop

We chose rgba8_srgb with stride = width * 4 for direct compatibility with browser <canvas> 2D context’s putImageData(), which expects RGBA bytes in that logical order.

• WebGL: ABI bytes map to standard RGBA8 upload paths, e.g. RGBA + UNSIGNED_BYTE.
• WebGPU: canvas surface may prefer bgra8unorm/bgra8unorm-srgb; conversion may happen in the renderer.
• Native runtimes can convert once at the edge, for example they may prefer premultiplied BGRA with aligned stride.

Event Semantics

key_event(...):

• x11_key uses X11 keysym values (aligned with VNC Remote Framebuffer 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 (i64) 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.
• When the pointer leaves the rendering surface, the host sends button_mask=0, x_px=-1, and y_px=-1.
• now_ms is monotonic elapsed milliseconds (i64) from the same timeline used by tick(now_ms).
• Return 1 when accepted, 0 when ignored.

Track pointer state at the same granularity as the interaction. Normalize pointer coordinates once into a semantic hit target, such as { cell_index, subcell_index }, and use that result for both hover and click handling. Compare the proposed hover target with the current one and ignore moves that would render identical pixels. Entering a different target or leaving it is accepted. This avoids calling tick for every raw pointer coordinate while preserving responsive hover feedback.

Tick + Render Flow

We intentionally split simulation from rendering.

• tick(now_ms) advances state.
• render(input_size) writes out output bytes using current state.

tick(now_ms) return value:

• 0: no scheduled wakeup needed
• >0: absolute next wake timestamp (next_wake_at_ms) in the same monotonic timeline as now_ms

Time source requirements:

• now_ms should be monotonically-increasing time in milliseconds.
• Hosts should call tick(0) first, then pass current monotonic elapsed milliseconds.
• Do not use wall-clock time for simulation as it is likely not monotonic.

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_rgba8_srgb_bytes() == render_width_px()*render_height_px()*4.

Host Loop Pattern #

Typical host flow:

1. Deliver input as it arrives via key_event(...) / pointer_event(...).
2. Call tick(now_ms) when at least one event is accepted, or when host time reaches next_wake_at_ms. Do not tick a batch containing only ignored events.
3. Call render(0) after each tick that was run, then read output_ptr() bytes.
4. Schedule the next host wake from the returned next_wake_at_ms (if non-zero) and pending input times.

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

Browser Presentation #

The interactive ABI describes framebuffer pixels, not CSS layout. Browser hosts can scale a fixed framebuffer at presentation time.

For <qip-play>, the page can set presentation attributes:

• canvas-width: CSS width for the internal canvas.
• canvas-height: CSS height for the internal canvas, default auto.

The same sizing values can also come from CSS custom properties when a page wants layout to live in stylesheets:

• --qip-play-canvas-width: CSS width for the internal canvas.
• --qip-play-canvas-height: CSS height for the internal canvas, default auto.

Attributes win over CSS custom properties.

<qip-play> leaves image-rendering at the browser default. That is the better default for high-DPI downscaling, and 1:1 rendering is unaffected.

Pointer events are still converted from the displayed canvas box into render-space pixels. This lets a component render a 2x backing buffer, while the page displays it at a 1x CSS size for high-DPI screens.

The stats line starts with stable module facts before live frame timings: Wasm byte size and current linear memory size. memory is the module's current linear memory buffer size, not allocator live-use inside the component. Byte sizes are formatted with decimal kB and MB units to match Chrome DevTools: divide bytes by 1000, then by 1000 again for megabytes. WebAssembly memory still grows in 64 KiB pages, so one page is shown as 65.5 kB. tick and render show a space-padded count followed by the latest timing, so the line moves less while the component runs.

For debug instrumentation, add debug to <qip-play>. In debug mode the host compares each rendered framebuffer with the previous frame, reports unchanged renders, and shows the latest exact-compare time. This is opt-in because scanning the framebuffer can be as expensive as, or more expensive than, drawing it to the canvas.

Browser Module Policy #

<qip-play> can reject modules before WebAssembly.instantiate:

<qip-play max-memory="1048576" fixed-memory>
  <source src="/components/interactive/sudoku.wasm" type="application/wasm" />
</qip-play>

• max-memory="<bytes>" rejects a module whose declared memory minimum or maximum exceeds the cap. If a module has memory but no declared maximum, it is rejected.
• fixed-memory rejects a module that can grow linear memory while it runs.

Why This Shape #

This ABI keeps packet parsing out of the Wasm module. Hosts adapt browser or native input at the edge, then modules handle a familiar game/UI loop: receive input events, advance state with tick, and render the current frame.

See Testing Interactive Components for direct Wasm, host-loop, framebuffer, and browser testing approaches.