OpenGroove firmware ABI 0.1

LOAD      og_abi_version  og_caps  [og_required_caps]  og_device_ptr  og_process_ctx_ptr
          host writes og_device ─► og_init()  ─► buffer pointers (read once, stable)
INACTIVE  [og_state_load]  og_param_*  og_render  og_reset  og_idle (may allocate, read assets)
          og_activate(sample_rate, max_block)            (may allocate, read assets)
ACTIVE    per block: host fills og_process_ctx ─► og_event / og_midi_in (sorted) ─► og_process
          between blocks: og_render · og_param_* · og_state_* · og_reset · og_idle   (all real time)
          og_deactivate() ─► INACTIVE

static og_controls controls = OG_CONTROLS_INIT;   /* firmware presets entry_size + capacity */
og_controls *og_controls_ptr(void) { return &controls; }
/* in og_init: for (i = 0; i < dev.control_count; i++) controls.entries[i] ... */

/* excerpt: opengroove.h */
void og_event(uint32_t type, uint32_t id, float value, uint32_t offset, float x, float y);
void og_midi_in(uint8_t status, uint8_t data1, uint8_t data2, uint32_t offset);

/* excerpt: opengroove.h */
void og_transport_request(uint32_t flags, double tempo_bpm);

/* excerpt: opengroove.h */
typedef struct og_param_info {
    uint32_t struct_size;
    uint32_t id;              /* stable across versions; never reuse an id */
    uint32_t flags;           /* STEPPED, AUTOMATABLE, HIDDEN */
    float    min, max, def;   /* plain units */
    char     name[32];
    char     unit[8];
    float    step;            /* UI step (0 = continuous) */
    uint16_t curve;           /* LINEAR, LOG, EXP */
    uint16_t label_count;     /* enumeration labels (<= 64) */
    uint32_t labels;          /* firmware address of the labels, or 0 */
    uint32_t _reserved[3];
} og_param_info;              /* 88 bytes (72 minimum) */

uint32_t             og_param_count(void);
const og_param_info *og_param_info_ptr(uint32_t index);   /* 0 if out of range */
void                 og_param_set(uint32_t id, float value);
float                og_param_get(uint32_t id);

/* excerpt: opengroove.h */
uint32_t og_state_size(void);       /* capacity: the largest blob */
uint8_t *og_state_ptr(void);        /* a firmware buffer of og_state_size() bytes, used both ways */
int32_t  og_state_save(void);       /* serialise into og_state_ptr(): bytes written, or < 0 */
int32_t  og_state_load(uint32_t len); /* parse len bytes at og_state_ptr(): OG_OK or < 0 */

/* excerpt: opengroove.h */
typedef struct og_state_header {
    uint32_t magic;   /* OG_STATE_MAGIC, "OGST" */
    uint32_t fw_tag;  /* the firmware's own identifier, e.g. a FOURCC */
    uint32_t schema;  /* the firmware's state schema version, starting at 1 */
    uint32_t size;    /* total bytes including this header */
} og_state_header;

{
  "id": "tape-drums",
  "name": "Tape Drums",
  "version": "1.2.0",
  "abi": "0.1",
  "caps": ["params", "state", "assets", "transport"],
  "description": "Sampled drum machine.",
  "author": { "name": "You", "url": "https://example.com" },
  "license": "Apache-2.0",
  "profiles": ["generic", "kick", "fire"],
  "assets": [
    { "path": "assets/kick.wav", "license": "CC0-1.0" },
    { "path": "assets/snare.wav", "license": "CC-BY-4.0" }
  ],
  "licenses": [{ "name": "Snare sample by …", "license": "CC-BY-4.0", "url": "https://…" }],
  "outcomes": ["audio"]
}

/* excerpt: opengroove.h */
int32_t og_asset_size(uint32_t id);                                          /* bytes, or < 0 */
int32_t og_asset_read(uint32_t id, void *dst, uint32_t offset, uint32_t len); /* bytes read, or < 0 */

clang --target=wasm32 -std=c11 -nostdlib -ffreestanding -O2
      -mbulk-memory -mnontrapping-fptoint -msimd128 -fno-math-errno -fvisibility=hidden
      -I include -I <sdk>/include -I <sdk>/examples/common
      -Wl,--no-entry -Wl,-z,stack-size=65536 -Wl,--max-memory=67108864 -Wl,--strip-debug

"checked": { "boots": true, "audio": true, "fuzz": true, "deadline": true, "levels": true,
             "state": true, "params": true, "sha256": "…", "abi": "0.1",
             "runtime": "og-runtime-node@0.3.0", "checked_at": "2026-10-27" }

{
  "profile": "kick",
  "seconds": 8,
  "events": [
    { "at": 0,   "button": "PLAY" },
    { "at": 0.5, "pad": 5, "velocity": 0.9, "length": 0.2 },
    { "at": 1,   "knob": 0, "delta": 4 },
    { "at": 1.5, "jog": -2 },
    { "at": 2,   "midi": [144, 60, 100] },
    { "at": 2.5, "touch": [400, 240], "length": 0.1 },
    { "at": 3,   "param": 1, "value": 128 },
    { "at": 4,   "transport": { "sync": true, "tempo": 100, "playing": true } },
    { "at": 6,   "type": "pad_down", "id": 3, "value": 1 }
  ]
}

{
  "rack": 1,
  "name": "Demo",
  "tracks": [
    { "name": "Drums", "instrument": { "fw": "pocket-drums.wasm", "params": { "1": 124 } },
      "fx": [ { "fw": "warm-delay.wasm", "params": { "5": 20 } } ],
      "gain": 0.8, "pan": 0, "send": 0.25, "focus": true, "transport_owner": true },
    { "name": "Bass", "instrument": { "fw": "acid-line.wasm" }, "gain": 0.7, "pan": -0.2 }
  ],
  "return": { "fx": [ { "fw": "warm-delay.wasm" } ], "gain": 0.6 },
  "master": { "gain": 1.0 }
}

"tracks": [ { "name": "Seq", "instrument": { "fw": "steps.wasm" } },
            { "name": "Bass", "instrument": { "fw": "acid-line.wasm" } } ],
"midi": [ { "from": "Seq", "to": "Bass", "from_port": 0, "to_port": 0 } ]

{ "og_rack_state": 1, "rack": { "…": "the manifest: topology and mappings" }, "seed": 7,
  "transport": { "tempo": 122, "quantum": 4, "tsNum": 4, "tsDen": 4, "playing": true },
  "instances": [ { "id": 0, "track": 0, "slot": 0, "fw": "pocket-drums.wasm",
                   "sha256": "…", "state": "base64 or null" } ] }

{
  "rack": 2,
  "id": "song",
  "seed": 42,
  "nodes": [
    { "id": "seq",  "fw": "sequencer.ogpkg" },
    { "id": "lead", "fw": "synth.ogpkg", "state_ref": "lead.ogst" },
    { "id": "bass", "fw": "bass.ogpkg" },
    { "id": "fx",   "fw": "filter.ogpkg", "params": { "7": 0.4 } },
    { "id": "main", "host": "mixer" }
  ],
  "edges": [
    { "type": "midi",  "from": ["seq", 0],  "to": ["lead", 0] },
    { "type": "audio", "from": ["lead", 0], "to": ["fx", 0] },
    { "type": "audio", "from": ["fx", 0],   "to": ["main", 0] },
    { "type": "audio", "from": ["bass", 0], "to": ["main", 0] }
  ],
  "output": ["main", 0]
}

/*
 * OpenGroove Firmware ABI 0.1
 * SPDX-License-Identifier: Apache-2.0
 *
 * A firmware is ONE wasm32 module and ONE instrument. The same binary runs in
 * the browser, headless (tests, CI, rendering) and on Linux-class grooveboxes.
 * docs/ABI.md explains every rule below in prose; this header is normative.
 *
 * Model
 *   - The host owns the clock and calls the firmware on ONE thread, never
 *     concurrently. The firmware needs no locks.
 *   - The firmware owns its memory: one unshared linear memory, exported, with
 *     a declared maximum of at most OG_MAX_MEMORY_PAGES. Every struct or buffer
 *     the host reads or writes lives in firmware memory at an address the
 *     firmware exports (og_*_ptr), stable for the life of the instance.
 *   - Struct negotiation is directional. Extensible structs start with
 *     `struct_size`. The WRITER of a struct caches the destination capacity
 *     (the struct_size preset in the firmware's storage, or its own sizeof),
 *     writes the complete prefix it knows (reserved bytes zero) and stores the
 *     size written. READERS never write; they ignore bytes beyond struct_size
 *     and treat fields that are missing or only partly present as zero.
 *     Minimum sizes for ABI 0.1: og_device 68, og_process_ctx 64, og_param_info 72,
 *     og_control_info 32, og_instance_info 36, og_port_info 28.
 *   - All shared scalars are little-endian. Alignment: audio buffers, og_device
 *     and og_param_info 4 bytes, og_process_ctx 8, og_dirty_rect 2.
 *   - Inputs arrive as og_event()/og_midi_in() calls stamped with a frame
 *     offset into the NEXT og_process() block, and take effect at that frame.
 *   - While activated, NO callback may block, allocate or call memory.grow;
 *     each has a time budget (docs/ABI.md section 9). Allocation and asset
 *     reads happen in og_init, og_activate, or og_idle while inactive.
 *   - Unknown flag bits are 0 when written and ignored when read.
 *
 * Call order
 *   og_abi_version, og_caps, og_device_ptr (host writes og_device), og_init,
 *   buffer pointers (read once), [og_state_load], og_activate,
 *   { og_event / og_midi_in*, fill og_process_ctx, og_process }*,
 *   og_render / og_idle / og_param_* / og_state_save between blocks,
 *   og_deactivate (and possibly og_activate again with a new rate).
 *   og_process is only called while activated. og_render, og_param_*, og_state_*
 *   and og_reset may be called any time after og_init returned 0.
 *
 * Build: clang --target=wasm32 -nostdlib -mbulk-memory -mnontrapping-fptoint
 *        -Wl,--no-entry   (or `og build`; see docs/ABI.md section 11)
 */
#ifndef OPENGROOVE_H
#define OPENGROOVE_H

#include <stdint.h>

/* A firmware's version is the MINIMUM host revision it needs: a host
 * implementing major.minor runs firmwares of the same major and any minor up
 * to its own (it keeps every older revision working). Signatures of existing
 * exports and imports are frozen within a major version. */
#define OG_ABI_VERSION_MAJOR 0
#define OG_ABI_VERSION_MINOR 1
#define OG_ABI_VERSION ((OG_ABI_VERSION_MAJOR << 16) | OG_ABI_VERSION_MINOR)

/* Limits hosts enforce (docs/ABI.md sections 6, 9 and 11). */
#define OG_MAX_MEMORY_PAGES      1024   /* 64 MiB: declared memory maximum */
#define OG_MAX_PENDING_EVENTS    4096   /* host-side input queue; overflow = panic (og_reset) */
#define OG_MAX_OUTPUTS_PER_BLOCK 256    /* og_midi_out + og_cv_out + og_gate_out per og_process */

#if defined(__wasm__)
#define OG_EXPORT(name) __attribute__((export_name(#name), visibility("default")))
#define OG_IMPORT(name) __attribute__((import_module("og"), import_name(#name)))
#else
#define OG_EXPORT(name)
#define OG_IMPORT(name)
#endif

#ifdef __cplusplus
extern "C" {
#endif

/* ------------------------------------------------------------------ */
/* Result codes                                                        */
/* ------------------------------------------------------------------ */

enum og_result {
    OG_OK              = 0,
    OG_ERR             = -1, /* unspecified failure */
    OG_ERR_UNSUPPORTED = -2, /* feature not provided (missing capability) */
    OG_ERR_RANGE       = -3, /* id, index, offset or length out of range */
    OG_ERR_FORMAT      = -4, /* malformed data (bad magic, size, checksum) */
    OG_ERR_VERSION     = -5, /* data from an unknown schema version */
    OG_ERR_RT          = -6, /* not allowed from og_process() */
};

/* ------------------------------------------------------------------ */
/* Capabilities                                                        */
/* ------------------------------------------------------------------ */

/* One bit set, two meanings: og_device.caps = what the HOST provides,
 * og_caps() = what the FIRMWARE implements or uses (optional: degrade
 * gracefully), og_required_caps() = what the firmware cannot run without.
 * A host calls an optional export group only if the firmware declares its bit
 * (and exports the functions). A firmware must check og_device.caps before
 * relying on a host feature; imports for missing features are harmless
 * no-ops or return OG_ERR_UNSUPPORTED. A host MAY refuse to load a firmware
 * whose og_required_caps() it lacks; it never refuses over og_caps(). */
enum og_cap {
    OG_CAP_PARAMS         = 1u << 0, /* og_param_* (host: shows/automates them) */
    OG_CAP_STATE          = 1u << 1, /* og_state_* (host: persists state) */
    OG_CAP_ASSETS         = 1u << 2, /* og_asset_* imports (host: package assets available) */
    OG_CAP_MIDI_OUT       = 1u << 3, /* og_midi_out (host: reaches a port) */
    OG_CAP_CV             = 1u << 4, /* og_cv_out / og_gate_out (host: cv_out or gate_out > 0) */
    OG_CAP_TOUCH          = 1u << 5, /* OG_TOUCH_* events (host: display is a touch screen) */
    OG_CAP_TRANSPORT      = 1u << 6, /* host: og_process_ctx carries tempo/transport;
                                        firmware: follows it when OG_CTX_SYNC is set */
    OG_CAP_AUDIO_IN       = 1u << 7, /* audio input (host: audio_in > 0) */
    OG_CAP_IDLE           = 1u << 8, /* firmware exports og_idle(); host calls it */
    OG_CAP_NATIVE_DISPLAY = 1u << 9, /* firmware only: framebuffer is in og_device.display_format
                                        with display_stride (otherwise always RGBA8888, w*4 stride) */
    OG_CAP_KEYS           = 1u << 10, /* OG_KEY_* and OG_TEXT events (a keyboard) */
    OG_CAP_CONTROLS       = 1u << 11, /* host: fills og_controls_ptr() with control descriptors */
    OG_CAP_TRANSPORT_CONTROL = 1u << 12, /* host: honours og_transport_request();
                                           firmware: may call it */
    OG_CAP_RACK           = 1u << 13, /* firmware: may run as one of several instances in a
                                         host graph (og_instance_ptr is filled). A firmware
                                         that does NOT declare it always runs alone. */
    OG_CAP_PORTS          = 1u << 14, /* host: reads og_port_* (og_port_info_ext ids, channel
                                         layouts) and enforces OG_PORT_REQUIRED: a required
                                         port it cannot connect makes the load fail */
    OG_CAP_MIDI_PORTS     = 1u << 15, /* host: routes MIDI by port (og_midi_in_port export,
                                         og_midi_out_port import); firmware: uses them */
    OG_CAP_GRAPH_CTX      = 1u << 16, /* host: writes og_graph_ctx_ptr() before every
                                         og_process (block id, graph generation, seed) */
};

/* ------------------------------------------------------------------ */
/* Kind and racks (multi-instance hosts)                               */
/* ------------------------------------------------------------------ */

/* What a firmware is (export og_kind(); absent = OG_KIND_INSTRUMENT; also the
 * manifest's "kind").
 *  - INSTRUMENT: events/MIDI in, stereo audio out.
 *  - EFFECT: audio_in = 2; processes og_audio_in_ptr() into og_audio_out_ptr().
 *  - MIDI_FX and UTILITY are ZERO-AUDIO: the host writes audio_in = audio_out = 0,
 *    og_audio_out_ptr() may return 0 and is never read. MIDI_FX turns MIDI in into
 *    MIDI out (arpeggiators, transposers); UTILITY produces MIDI or nothing from its
 *    own state (sequencers, clocks). Both emit with og_midi_out / og_midi_out_port.
 *  - CONTROLLER is reserved for 0.2 (og_param_send). */
enum og_kind {
    OG_KIND_INSTRUMENT = 0,
    OG_KIND_EFFECT     = 1,
    OG_KIND_MIDI_FX    = 2, /* zero-audio: MIDI in -> MIDI out */
    OG_KIND_CONTROLLER = 3, /* reserved for 0.2 */
    OG_KIND_UTILITY    = 4, /* zero-audio: MIDI (or nothing) out */
};

/* Host -> firmware (OG_CAP_RACK): which instance this is. Written to
 * og_instance_ptr() before og_init, directional like og_device. */
enum og_instance_flags {
    OG_INSTANCE_HAS_FOCUS       = 1u << 0, /* the device's controls and screen are this instance's */
    OG_INSTANCE_TRANSPORT_OWNER = 1u << 1, /* its og_transport_request() calls are honoured */
};
/* Serialisation: the host never calls into one instance concurrently; all of an
 * instance's callbacks are ordered. They may run on different threads over time
 * (the host can migrate an instance between workers or cores); a firmware keeps
 * no thread-local state. Automation addresses (instance_id, param id). */
typedef struct og_instance_info {
    uint32_t struct_size;
    uint32_t instance_id;     /* PERSISTENT: saved with the rack and stable across
                                 reloads (rack:1 = position in manifest order) */
    uint32_t slot;            /* position in its chain or the rack (0-based) */
    uint32_t slot_count;
    uint32_t flags;           /* enum og_instance_flags (may change between blocks) */
    uint32_t _reserved[4];
} og_instance_info;           /* 36 bytes */
#define OG_INSTANCE_INIT { .struct_size = sizeof(og_instance_info) }

/* Ports beyond the main stereo pair (og_audio_in_ptr / og_audio_out_ptr stay the
 * main audio ports; MIDI port 0 is og_midi_in / og_midi_out). Firmware -> host,
 * enumerated after og_init with og_port_count / og_port_info_ptr. An entry whose
 * struct_size >= sizeof(og_port_info_ext) carries a stable id and a channel layout;
 * a 28-byte entry has id = its index and the layout of `channels`.
 * Negotiation (OG_CAP_PORTS hosts): an optional port the host cannot connect is
 * left unconnected (silence in, output discarded); a port flagged REQUIRED that it
 * cannot connect fails the load with an error naming the port. Never silent. */
enum og_port_dir  { OG_PORT_IN = 0, OG_PORT_OUT = 1 };
enum og_port_type { OG_PORT_AUDIO = 0, OG_PORT_MIDI = 1 };
enum og_port_flags {
    OG_PORT_MAIN      = 1u << 0,
    OG_PORT_SIDECHAIN = 1u << 1,
    OG_PORT_REQUIRED  = 1u << 2, /* the firmware cannot work without it connected */
};
/* channel_mask: bit n = channel n present. */
#define OG_CH_MONO   0x1u
#define OG_CH_STEREO 0x3u
typedef struct og_port_info {
    uint32_t struct_size;
    uint8_t  dir;             /* og_port_dir */
    uint8_t  type;            /* og_port_type */
    uint8_t  channels;        /* audio: 1..2 */
    uint8_t  _reserved0;
    uint32_t flags;           /* og_port_flags */
    char     name[16];
} og_port_info;               /* 28 bytes */

typedef struct og_port_info_ext {
    og_port_info base;        /* base.struct_size = sizeof(og_port_info_ext) */
    uint32_t id;              /* stable port id: edges and saved racks refer to it.
                                 MIDI port ids address og_midi_in_port/og_midi_out_port */
    uint32_t channel_mask;    /* audio: OG_CH_MONO, OG_CH_STEREO, ...; MIDI: 16-bit
                                 channel filter (0 = all) */
} og_port_info_ext;           /* 36 bytes */

/* Graph context (OG_CAP_GRAPH_CTX), host -> firmware before every og_process,
 * directional like og_process_ctx. Use `seed` for all randomness: it is fixed per
 * (rack seed, persistent instance id), so a rack renders the same on any host and
 * thread count. block_id counts og_process calls since og_activate. */
typedef struct og_graph_ctx {
    uint32_t struct_size;
    uint32_t generation;      /* changes when the host rebuilt the graph (topology,
                                 restore, worker replacement); results are tagged with it */
    uint64_t block_id;
    uint64_t seed;
} og_graph_ctx;               /* 24 bytes */
#define OG_GRAPH_CTX_INIT { .struct_size = sizeof(og_graph_ctx) }

/* ------------------------------------------------------------------ */
/* Device description (host -> firmware, written to og_device_ptr())   */
/* ------------------------------------------------------------------ */

enum og_profile {
    OG_PROFILE_GENERIC = 0, /* 4x4 pads, 4 knobs, 8 buttons, 800x480 touch */
    OG_PROFILE_KICK    = 1, /* BE 0700-AAM class: 4x4 pads, 4 knobs, jog, 1024x600 touch */
    OG_PROFILE_FIRE    = 2, /* Akai Fire class: 4x16 pads, 4 knobs, select encoder, 128x64 mono */
    OG_PROFILE_OTHER   = 3, /* no layout hint: use the counts and the control descriptors */
};

enum og_display_format {
    OG_FMT_RGBA8888 = 0, /* 4 bytes per pixel, R,G,B,A; A must be 255 */
    OG_FMT_RGB565   = 1, /* little-endian u16 per pixel */
    OG_FMT_MONO1    = 2, /* 1 bit per pixel, MSB = leftmost, 1 = lit */
};

/* Summary in og_device.knob_kind; per-knob truth is in the control descriptors. */
enum og_knob_kind {
    OG_KNOB_RELATIVE = 0, /* endless encoder: OG_KNOB value = delta in detents */
    OG_KNOB_ABSOLUTE = 1, /* potentiometer: OG_KNOB value = position 0..1 */
    OG_KNOB_MIXED    = 2, /* both kinds present: read og_control_info per knob */
};

typedef struct og_device {
    uint32_t struct_size;     /* see "Model" */
    uint32_t abi_version;     /* host's OG_ABI_VERSION */
    uint32_t caps;            /* enum og_cap bits the host provides */
    uint32_t profile;         /* enum og_profile: a layout hint; adapt to the counts below */
    uint32_t sample_rate;     /* expected rate; og_activate() is authoritative */
    uint32_t max_block;       /* og_process() never gets more frames (<= 512) */
    uint16_t display_w;       /* pixels; 0 x 0 = no display (headless) */
    uint16_t display_h;
    uint32_t display_format;  /* enum og_display_format: the host's native format */
    uint32_t display_stride;  /* bytes per row in display_format */
    uint32_t buttons_present; /* bit n set = button id n exists (ids 0..31; enum og_button) */
    uint8_t  pad_rows;
    uint8_t  pad_cols;
    uint8_t  knobs;
    uint8_t  knob_kind;       /* enum og_knob_kind (summary) */
    uint8_t  audio_in;        /* channels 0..2 */
    uint8_t  audio_out;       /* channels 1..2 */
    uint8_t  cv_out;
    uint8_t  gate_out;
    uint8_t  has_jog;         /* jog wheel / select encoder (OG_JOG) */
    uint8_t  pad_pressure;    /* 1 if pads send OG_PAD_PRESSURE */
    uint16_t control_count;   /* entries written to og_controls_ptr() (OG_CAP_CONTROLS), else 0 */
    uint32_t buttons_present_hi; /* bit n set = panel button id 32+n exists (0 on older hosts) */
    uint32_t _reserved[3];
} og_device;

/* ------------------------------------------------------------------ */
/* Control descriptors (host -> firmware, OG_CAP_CONTROLS)              */
/* ------------------------------------------------------------------ */

/* The counts in og_device say how many pads/knobs/buttons exist; descriptors say
 * what each physical control IS, so mixed hardware (pots next to encoders, a
 * push-encoder, a key bed, a touch strip) can be described exactly. */
enum og_control_kind {
    OG_CTL_BUTTON       = 1, /* OG_BUTTON_DOWN/UP, event_id = og_button id */
    OG_CTL_ENCODER      = 2, /* OG_KNOB relative deltas, event_id = knob index */
    OG_CTL_POT          = 3, /* OG_KNOB absolute 0..1, event_id = knob index */
    OG_CTL_PUSH_ENCODER = 4, /* relative deltas; `paired` = button id of its push.
                                event_id = knob index, or OG_CTL_JOG_ID for OG_JOG */
    OG_CTL_PADS         = 5, /* OG_PAD_*, event_id = first pad index, count = pads */
    OG_CTL_TOUCH        = 6, /* OG_TOUCH_* on the display (event_id 0) */
    OG_CTL_KEYS         = 7, /* OG_KEY_* / OG_TEXT (a keyboard) */
};
#define OG_CTL_JOG_ID 0xFFFFu   /* event_id of a control that sends OG_JOG */
#define OG_CTL_NONE   0xFFFFu   /* `paired` when there is no association */

/* What the control is for on the hardware's panel (a hint for default maps). */
enum og_control_role {
    OG_ROLE_GENERIC   = 0,
    OG_ROLE_PARAM     = 1, /* assignable parameter knob */
    OG_ROLE_DATA      = 2, /* main value/navigation encoder (jog, select, data wheel) */
    OG_ROLE_NAVIGATE  = 3, /* arrows, back, menu, page */
    OG_ROLE_TRANSPORT = 4, /* play, stop, rec */
    OG_ROLE_MODIFIER  = 5, /* shift, alt */
    OG_ROLE_PERFORM   = 6, /* pads, keys played musically */
    OG_ROLE_MODE      = 7, /* mode/bank/page/screen selectors */
    OG_ROLE_EDIT      = 8, /* undo, copy, erase, save: editing commands */
};

typedef struct og_control_info {
    uint32_t struct_size;
    uint16_t kind;            /* enum og_control_kind */
    uint16_t role;            /* enum og_control_role */
    uint16_t event_id;        /* id carried by this control's events (see kind) */
    uint16_t paired;          /* push-encoder: its button id; else OG_CTL_NONE */
    uint16_t count;           /* pads: number of pads; else 1 */
    uint16_t _reserved0;
    float    resolution;      /* encoders: detents per turn; pots: steps (0 = smooth);
                                 pads: velocity levels (0 = continuous) */
    char     label[12];       /* short panel label, UTF-8, NUL-terminated */
} og_control_info;            /* 32 bytes */

/* Firmware storage the host fills before og_init (directional: the host writes,
 * the firmware reads). The firmware presets entry_size and capacity; the host
 * writes min(capacity, its controls) entries with stride entry_size, each with
 * its own struct_size, then sets og_device.control_count. */
#define OG_MAX_CONTROLS 64
typedef struct og_controls {
    uint32_t entry_size;      /* preset by the firmware: sizeof(og_control_info) */
    uint32_t capacity;        /* preset by the firmware: entries available */
    og_control_info entries[OG_MAX_CONTROLS];
} og_controls;
#define OG_CONTROLS_INIT { sizeof(og_control_info), OG_MAX_CONTROLS, { { 0 } } }

/* ------------------------------------------------------------------ */
/* Per-block context (host -> firmware, written before og_process())   */
/* ------------------------------------------------------------------ */

enum og_ctx_flags {
    OG_CTX_TEMPO_VALID = 1u << 0, /* tempo_bpm and ts_num/ts_den are meaningful */
    OG_CTX_PLAYING     = 1u << 1, /* host transport is running; beat_pos advances */
    OG_CTX_RECORDING   = 1u << 2,
    OG_CTX_EXT_CLOCK   = 1u << 3, /* tempo/position follow an external clock */
    OG_CTX_SYNC        = 1u << 4, /* host is transport master: sequencers follow
                                     PLAYING, beat_pos and tempo_bpm instead of
                                     free-running (implies TEMPO_VALID) */
    OG_CTX_DISCONTINUITY = 1u << 5, /* beat_pos does not continue the previous block
                                     (first block after og_activate, seek, loop,
                                     rewind): re-derive position, release notes */
    OG_CTX_LINKED      = 1u << 6, /* tempo/position are shared with peers (e.g. Ableton Link) */
    OG_CTX_COUNT_IN    = 1u << 7, /* PLAYING with beat_pos < 0: pre-roll before a quantized
                                     start at beat 0 (count-ins, anticipation; no notes yet) */
};
/* Transport rules (docs/ABI.md section 7):
 *  - beat_pos = quarter notes since the host's transport origin at the
 *    PRESENTATION time of frame 0 (when that sample reaches the output). The
 *    host aligns the origin to a quantum boundary of its timeline; it is not a
 *    song position. It is finite; it is negative only while COUNT_IN is set.
 *  - tempo_bpm is finite and > 0; quantum (beats per phase cycle, e.g. one bar)
 *    is > 0 when known, else 0. SYNC implies TEMPO_VALID.
 *  - The host fills the context, then delivers the block's events, then calls
 *    og_process. Transport changes happen only at block boundaries. Stopping
 *    keeps beat_pos; rewinding sets it to 0 with DISCONTINUITY. Leaving SYNC
 *    stops a following sequencer. Musical time advances only with rendered
 *    frames (underruns don't). */

typedef struct og_process_ctx {
    uint32_t struct_size;
    uint32_t frames;          /* == the og_process() argument */
    uint64_t sample_pos;      /* frames processed since og_activate() */
    double   tempo_bpm;       /* quarter notes per minute */
    double   beat_pos;        /* quarter notes since transport start, at frame 0 */
    uint16_t ts_num;          /* time signature, e.g. 4/4 (advisory) */
    uint16_t ts_den;
    uint32_t flags;           /* enum og_ctx_flags */
    double   quantum;         /* beats per phase cycle (bar length for quantized starts), 0 = unknown */
    uint32_t peers;           /* LINKED: number of other participants, else 0 */
    uint32_t _reserved[3];
} og_process_ctx;

/* ------------------------------------------------------------------ */
/* Input events (host -> firmware)                                     */
/* ------------------------------------------------------------------ */

/* Ordering: within a block, events (og_event and og_midi_in together) arrive
 * sorted by offset (0 <= offset < frames), ties in arrival order, and take
 * effect at that frame. Late events (their block was already rendered) are
 * delivered at offset 0. At most OG_MAX_EVENTS_PER_BLOCK per block: the rest
 * are deferred as a FIFO delivered at offset 0 of the next blocks, AHEAD of
 * that block's own events. If more than OG_MAX_PENDING_EVENTS wait, the host
 * drops the queue and calls og_reset() (panic: nothing keeps sounding). */
#define OG_MAX_EVENTS_PER_BLOCK 256
#define OG_EVENT_VENDOR_FIRST 0x80000000u /* 0x80000000..0xffffffff: negotiated vendor extensions */

enum og_event_type {
    OG_PAD_DOWN     = 1,  /* id = pad index (row * pad_cols + col, row 0 = top), value = velocity 0..1 */
    OG_PAD_UP       = 2,  /* id = pad index, value = 0 */
    OG_PAD_PRESSURE = 3,  /* id = pad index, value = pressure 0..1 */
    OG_KNOB         = 4,  /* id = knob index, value per og_device.knob_kind */
    OG_BUTTON_DOWN  = 5,  /* id = enum og_button */
    OG_BUTTON_UP    = 6,
    OG_JOG          = 7,  /* id = 0, value = delta in detents */
    OG_TOUCH_DOWN   = 8,  /* id = finger 0..9, x/y in display pixels */
    OG_TOUCH_MOVE   = 9,
    OG_TOUCH_UP     = 10,
    OG_PARAM_CHANGE = 11, /* id = param id, value = new value in the param's units */
    OG_KEY_DOWN     = 12, /* OG_CAP_KEYS: id = USB HID usage (page 7), value = modifier bits */
    OG_KEY_UP       = 13, /* id = USB HID usage, value = modifier bits */
    OG_TEXT         = 14, /* OG_CAP_KEYS: id = one Unicode scalar value typed (text input) */
    OG_TOUCH_CANCEL = 15, /* id = finger: the gesture was cancelled; undo it, don't commit */
};
/* Modifier bits in OG_KEY_* values. */
enum og_key_mod { OG_MOD_SHIFT = 1, OG_MOD_CTRL = 2, OG_MOD_ALT = 4, OG_MOD_META = 8 };
/* Firmwares must ignore event types they don't know. Non-finite values in any
 * event are never sent by hosts and must be ignored by firmwares. */

enum og_button {
    OG_BTN_PLAY = 0, OG_BTN_STOP = 1, OG_BTN_REC = 2, OG_BTN_SHIFT = 3,
    OG_BTN_LEFT = 4, OG_BTN_RIGHT = 5, OG_BTN_UP = 6, OG_BTN_DOWN = 7,
    OG_BTN_MODE_1 = 8, OG_BTN_MODE_2 = 9, OG_BTN_MODE_3 = 10, OG_BTN_MODE_4 = 11,
    OG_BTN_BANK = 12, OG_BTN_SELECT = 13, OG_BTN_BACK = 14, OG_BTN_MENU = 15,
    /* Panel buttons: ids 16..63 have no conventional meaning. Their og_control_info
     * (label, role) says what they are; a profile document lists them (KICK:
     * docs/KICK-PROFILE.md). Present bits: buttons_present (16..31) and
     * buttons_present_hi (32..63). Hosts send them as OG_BUTTON_DOWN/UP like any
     * other id; a firmware ignores ids it does not use (always bounds-check ids). */
    OG_BTN_PANEL = 16,
};
#define OG_MAX_BUTTONS    16  /* conventional ids; og_button_leds_ptr() length */
#define OG_MAX_BUTTON_IDS 64  /* all ids, panel buttons included */

/* ------------------------------------------------------------------ */
/* Parameters (OG_CAP_PARAMS)                                          */
/* ------------------------------------------------------------------ */

enum og_param_flags {
    OG_PARAM_STEPPED     = 1u << 0, /* integer values only (min..max) */
    OG_PARAM_AUTOMATABLE = 1u << 1, /* host may send OG_PARAM_CHANGE in real time */
    OG_PARAM_HIDDEN      = 1u << 2, /* don't show in generic UIs */
};

/* How a UI maps a control position to the value (presentation only). */
enum og_param_curve {
    OG_CURVE_LINEAR = 0,
    OG_CURVE_LOG    = 1, /* equal ratios per step (Hz, times); needs min > 0 */
    OG_CURVE_EXP    = 2, /* fine control near min */
};

#define OG_PARAM_LABEL_LEN 16  /* bytes per enumeration label, NUL-padded */
#define OG_PARAM_MAX_LABELS 64

typedef struct og_param_info {
    uint32_t struct_size;
    uint32_t id;              /* stable across versions; never reuse an id */
    uint32_t flags;           /* enum og_param_flags */
    float    min, max, def;   /* plain units */
    char     name[32];        /* UTF-8, NUL-terminated */
    char     unit[8];         /* e.g. "Hz", "%", "BPM", "" */
    float    step;            /* UI step in plain units (0 = continuous / 1 for STEPPED) */
    uint16_t curve;           /* enum og_param_curve */
    uint16_t label_count;     /* STEPPED enums: labels for min..min+label_count-1 (<= 64) */
    uint32_t labels;          /* firmware address of label_count x OG_PARAM_LABEL_LEN bytes, or 0 */
    uint32_t _reserved[3];
} og_param_info;              /* 88 bytes; fields past 72 read as 0 from older firmware */

/* ------------------------------------------------------------------ */
/* State (OG_CAP_STATE)                                                */
/* ------------------------------------------------------------------ */

/* Every state blob starts with this 16-byte little-endian envelope, frozen
 * forever (a different envelope needs a different magic). The host checks
 * magic and size; the firmware checks fw_tag and schema (its payload version)
 * and returns OG_ERR_FORMAT or OG_ERR_VERSION. og_state_load is transactional:
 * on any error the firmware's state is unchanged. Serialized padding is zero.
 * Hosts key stored state by package identity, never by fw_tag. */
#define OG_STATE_MAGIC 0x5453474Fu /* "OGST" */
typedef struct og_state_header {
    uint32_t magic;           /* OG_STATE_MAGIC */
    uint32_t fw_tag;          /* firmware-chosen identifier, e.g. a FOURCC */
    uint32_t schema;          /* firmware's state schema version, starting at 1 */
    uint32_t size;            /* total blob bytes including this header */
} og_state_header;

/* ------------------------------------------------------------------ */
/* Display dirty rectangle (optional)                                  */
/* ------------------------------------------------------------------ */

/* Half-open pixel rectangle [x, x+w) x [y, y+h), clipped by the host to the
 * display. w == 0: whole frame; w > 0 && h == 0: no pixels changed (LEDs may
 * still have). LED updates never depend on the rectangle. The host copies
 * what it needs before calling into the firmware again. */
typedef struct og_dirty_rect { uint16_t x, y, w, h; } og_dirty_rect;

/* ------------------------------------------------------------------ */
/* Required exports                                                    */
/* ------------------------------------------------------------------ */

uint32_t        og_abi_version(void)     OG_EXPORT(og_abi_version);    /* return OG_ABI_VERSION */
uint32_t        og_caps(void)            OG_EXPORT(og_caps);           /* enum og_cap bits used (optional) */
og_device      *og_device_ptr(void)      OG_EXPORT(og_device_ptr);     /* static storage, struct_size preset */
og_process_ctx *og_process_ctx_ptr(void) OG_EXPORT(og_process_ctx_ptr);

/* Called once after the host wrote og_device. Allocate here. 0 = OK. */
int32_t og_init(void) OG_EXPORT(og_init);

/* Prepare to process at this rate and block size (1 <= max_block <=
 * og_device.max_block). og_process_ctx.sample_pos and og_time() restart at 0.
 * May be called again after og_deactivate(), possibly with a new rate. 0 = OK.
 * The audio buffer stride stays og_device.max_block regardless. */
int32_t og_activate(uint32_t sample_rate, uint32_t max_block) OG_EXPORT(og_activate);
void    og_deactivate(void) OG_EXPORT(og_deactivate);   /* host input queues are cleared */

/* Silence: drop voices, tails, delay lines and held-input state (pressed pads,
 * buttons, notes: the host now considers everything released and clears its
 * queues). Keep params, patterns, state and the firmware's own play/stop state. */
void    og_reset(void) OG_EXPORT(og_reset);

/* Input for the next og_process() block. x/y only for touch events. */
void og_event(uint32_t type, uint32_t id, float value, uint32_t offset,
              float x, float y) OG_EXPORT(og_event);
void og_midi_in(uint8_t status, uint8_t data1, uint8_t data2,
                uint32_t offset) OG_EXPORT(og_midi_in);

/* Render `frames` frames, 1 <= frames <= the activated max_block. og_process_ctx
 * is filled. Planar float32 buffers: channel c at ptr + c * og_device.max_block
 * (always the DEVICE max_block, not the activated one). Real time. */
void og_process(uint32_t frames) OG_EXPORT(og_process);

/* Draw the framebuffer and set LEDs. Return 1 if anything changed, else 0.
 * Must be cheap and must not advance musical state; the host calls it at
 * <= 60 Hz and may skip calls under load. */
int32_t og_render(void) OG_EXPORT(og_render);

/* Buffer addresses, read once after og_init(). Return 0 for "none". */
float   *og_audio_out_ptr(void)   OG_EXPORT(og_audio_out_ptr);   /* audio_out * max_block floats */
float   *og_audio_in_ptr(void)    OG_EXPORT(og_audio_in_ptr);    /* audio_in * max_block floats */
uint8_t *og_framebuffer_ptr(void) OG_EXPORT(og_framebuffer_ptr); /* RGBA8888 w*h*4, or native format */
uint8_t *og_pad_leds_ptr(void)    OG_EXPORT(og_pad_leds_ptr);    /* pad_rows*pad_cols RGB triplets */
uint8_t *og_button_leds_ptr(void) OG_EXPORT(og_button_leds_ptr); /* OG_MAX_BUTTONS brightness bytes, by og_button id */

/* ------------------------------------------------------------------ */
/* Optional exports                                                    */
/* ------------------------------------------------------------------ */

uint32_t og_required_caps(void) OG_EXPORT(og_required_caps); /* og_cap bits needed to run (absent = 0) */
/* Added output latency in frames (default 0). Read after og_activate; it must stay
 * constant until the next og_activate (hosts compensate graph delays with it). */
uint32_t og_latency(void) OG_EXPORT(og_latency);
/* OG_CAP_IDLE: housekeeping. While INACTIVE it may allocate and read assets;
 * while activated it follows the real-time rules (no allocation, no assets). */
void     og_idle(void) OG_EXPORT(og_idle);
og_dirty_rect *og_dirty_rect_ptr(void) OG_EXPORT(og_dirty_rect_ptr); /* filled when og_render returns 1 */
og_controls   *og_controls_ptr(void) OG_EXPORT(og_controls_ptr);     /* descriptor storage (OG_CAP_CONTROLS) */
/* LEDs of panel buttons: OG_MAX_BUTTON_IDS - OG_MAX_BUTTONS (48) brightness bytes,
 * byte n = button id 16+n. Absent = panel button LEDs stay dark. */
uint8_t       *og_panel_leds_ptr(void) OG_EXPORT(og_panel_leds_ptr);

/* Kind and racks. og_kind absent = INSTRUMENT. og_instance_ptr: OG_CAP_RACK. */
uint32_t          og_kind(void) OG_EXPORT(og_kind);
og_instance_info *og_instance_ptr(void) OG_EXPORT(og_instance_ptr);
/* Frames of output that can follow once the input (and all notes) went silent:
 * delay/reverb tails. 0 = none (default), 0xFFFFFFFF = unbounded (self-oscillating,
 * loopers): the host must keep processing. Read after og_activate. */
uint32_t          og_tail_frames(void) OG_EXPORT(og_tail_frames);
/* Extra ports (buffers planar, channels x og_device.max_block floats, stable). */
uint32_t            og_port_count(void) OG_EXPORT(og_port_count);
const og_port_info *og_port_info_ptr(uint32_t index) OG_EXPORT(og_port_info_ptr); /* may point at an og_port_info_ext */
float              *og_port_buffer_ptr(uint32_t index) OG_EXPORT(og_port_buffer_ptr);
/* OG_CAP_GRAPH_CTX: storage the host fills (preset struct_size, OG_GRAPH_CTX_INIT). */
og_graph_ctx       *og_graph_ctx_ptr(void) OG_EXPORT(og_graph_ctx_ptr);
/* OG_CAP_MIDI_PORTS: MIDI for input port `port` (its og_port_info_ext.id). Port 0
 * may arrive here or through og_midi_in; same ordering rules as og_midi_in. */
void                og_midi_in_port(uint32_t port, uint8_t status, uint8_t data1, uint8_t data2, uint32_t offset) OG_EXPORT(og_midi_in_port);

/* OG_CAP_PARAMS. Called between blocks. og_param_set and OG_PARAM_CHANGE have
 * identical effect (derived coefficients included); NaN/Inf are ignored;
 * STEPPED values round to nearest (ties away from zero), then all values
 * clamp to min..max; og_param_get returns the effective value. Changes made
 * by the firmware itself (e.g. a knob) are visible via og_param_get. */
uint32_t             og_param_count(void) OG_EXPORT(og_param_count);
const og_param_info *og_param_info_ptr(uint32_t index) OG_EXPORT(og_param_info_ptr); /* 0 = bad index */
void                 og_param_set(uint32_t id, float value) OG_EXPORT(og_param_set);
float                og_param_get(uint32_t id) OG_EXPORT(og_param_get);

/* OG_CAP_STATE. Called between blocks (hosts may autosave at any time).
 * og_state_ptr() is a firmware buffer of og_state_size() bytes used both ways. */
uint32_t og_state_size(void) OG_EXPORT(og_state_size);   /* capacity: largest blob */
uint8_t *og_state_ptr(void) OG_EXPORT(og_state_ptr);
int32_t  og_state_save(void) OG_EXPORT(og_state_save);   /* bytes written, or < 0 */
int32_t  og_state_load(uint32_t len) OG_EXPORT(og_state_load); /* OG_OK or < 0 */

/* ------------------------------------------------------------------ */
/* Host imports (module "og")                                          */
/* ------------------------------------------------------------------ */

void og_log(const char *msg, uint32_t len) OG_IMPORT(log);   /* one UTF-8 line */

/* Outputs at a frame offset into the current block (clamped to frames-1).
 * Only legal inside og_process: elsewhere, and beyond OG_MAX_OUTPUTS_PER_BLOCK
 * per block, they are dropped (and counted). No-ops without the cap. */
void og_midi_out(uint8_t status, uint8_t data1, uint8_t data2, uint32_t offset) OG_IMPORT(midi_out);
/* OG_CAP_MIDI_PORTS: MIDI out on output port `port` (og_midi_out == port 0). Same
 * limits as og_midi_out; a port with no connection drops the message. */
void og_midi_out_port(uint32_t port, uint8_t status, uint8_t data1, uint8_t data2, uint32_t offset) OG_IMPORT(midi_out_port);
void og_cv_out(uint32_t index, float volts, uint32_t offset) OG_IMPORT(cv_out); /* clamped -5..+10 V */
void og_gate_out(uint32_t index, uint32_t on, uint32_t offset) OG_IMPORT(gate_out);

/* Seconds since og_activate() at the start of the current block
 * (== og_process_ctx.sample_pos / sample_rate). */
double og_time(void) OG_IMPORT(time);

/* OG_CAP_TRANSPORT_CONTROL: ask the host to change its transport (e.g. a tempo
 * param or a menu "Play" while the host is master). Applied at the next block
 * boundary, if at all (the host decides; the last request per block wins).
 * A no-op without the capability. tempo_bpm is used with OG_TREQ_TEMPO. */
enum og_transport_request_flags { OG_TREQ_PLAY = 1, OG_TREQ_STOP = 2, OG_TREQ_TEMPO = 4 };
void og_transport_request(uint32_t flags, double tempo_bpm) OG_IMPORT(transport_request);

/* OG_CAP_ASSETS: files from the firmware package (manifest "assets", by
 * index). The host preloads them. Callable only in og_init, og_activate and
 * og_idle while inactive; elsewhere they return OG_ERR_RT. Reading at or past
 * the end returns a short count or 0 (EOF); an offset beyond the size is
 * OG_ERR_RANGE. */
int32_t og_asset_size(uint32_t id) OG_IMPORT(asset_size); /* bytes, or < 0 */
int32_t og_asset_read(uint32_t id, void *dst, uint32_t offset, uint32_t len) OG_IMPORT(asset_read); /* bytes read, or < 0 */

/* ------------------------------------------------------------------ */
/* WASI                                                                */
/* ------------------------------------------------------------------ */
/* SIMD: plain simd128 is allowed. Relaxed-SIMD opcodes are rejected at load
 * (their results differ between hosts, which breaks bit-exact racks). */

/* A firmware MAY import exactly these wasi_snapshot_preview1 functions, with
 * their standard signatures: fd_write (fd 1/2 -> og_log; <= 16 iovecs and
 * 4096 bytes per call), random_get (<= 65536 bytes), clock_time_get,
 * proc_exit (the firmware stops; the host shows an error), environ_get,
 * environ_sizes_get, args_get, args_sizes_get (all empty), and fd_close,
 * fd_seek, fd_read, fd_fdstat_get, fd_prestat_get, fd_prestat_dir_name
 * (ENOSYS / EBADF). Any other import, or a wrong signature, fails the load. */

#if defined(__wasm32__) && !defined(__cplusplus)
_Static_assert(sizeof(og_device) == 68, "og_device layout");
_Static_assert(sizeof(og_process_ctx) == 64, "og_process_ctx layout");
_Static_assert(sizeof(og_param_info) == 88, "og_param_info layout");
_Static_assert(sizeof(og_control_info) == 32, "og_control_info layout");
_Static_assert(sizeof(og_instance_info) == 36, "og_instance_info layout");
_Static_assert(sizeof(og_port_info) == 28, "og_port_info layout");
_Static_assert(sizeof(og_port_info_ext) == 36, "og_port_info_ext layout");
_Static_assert(sizeof(og_graph_ctx) == 24, "og_graph_ctx layout");
_Static_assert(sizeof(og_state_header) == 16, "og_state_header layout");
#endif

/* Static initialisers for the exported structs. */
#define OG_DEVICE_INIT      { .struct_size = sizeof(og_device) }
#define OG_PROCESS_CTX_INIT { .struct_size = sizeof(og_process_ctx) }

#ifdef __cplusplus
}
#endif

#endif /* OPENGROOVE_H */