themastercoder007/embedded-react-runtime

Readme

# runtime

The parts of the device runtime that no JavaScript engine owns, and the Flow B runtime. Plain C99
that links only the engine: no QuickJS, no allocation in the container reader or the Flow B runtime,
no platform headers. The QuickJS bridge links `er-runtime`; Flow B firmware links `erb-runtime`.

| File                  | What it does                                                                                                                                                          |
|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `er_container.c`      | Reads an ERCF container (`.erpkg`): checks the magic, the format version, every section bound and the CRC, and hands back the tag and sections. Also `er_crc32`.      |
| `er_assets.c`         | Checks an ERPK asset pack (images and fonts) and registers it with the engine, with font tables in caller storage.                                                    |
| `er_assets_heap.c`    | The same with font tables from the heap, in place or from a copy. Its own file, so Flow B firmware never links the allocator.                                         |
| `er_hotreload.c`      | Parses ERHR hot-reload frames from a byte stream into a staging buffer and checks their CRC.                                                                          |
| `erb_runtime.c`       | Flow B: loads a package (`erb_load`), lays out the arena, builds templates, runs events, timers, effects and animations, and shows the error screen.                  |
| `erb_verify.c`        | Flow B: checks a whole package before anything is built (the spec's verifier rules).                                                                                  |
| `erb_vm.c`            | Flow B: the register VM, with its arithmetic rules.                                                                                                                |
| `erb_package_slots.c` | Flow B: the two flash slots a board keeps packages in, and the fall back to the last good one. `port/` maps them on ESP-IDF, the one file here with platform headers. |
| `erb_package_reload.c`| Flow B: on-device hot reload. Takes a package over ERHR frames into the staging slot, and loads it.                                                                    |
| `erb_format.h`        | Flow B: the package format and the opcode list the compiler and the runtime share.                                                                                    |
| `erb_props.c`         | Flow B: the engine ABI's prop ids, mapped to `ERProps` fields.                                                                                                        |
| `tests/`              | CTests: the container reader, one test per Flow B verifier rule, the VM, and the package slots.                                                                       |

Running a container's program is the caller's job: `er_runtime_load_container` in
`bridges/quickjs/er_runtime.h` checks the QuickJS tag and runs the bytecode, and `er_hotreload_apply`
there loads a received frame. A Flow B package (tag `erb`) goes to `erb_load` in `erb_runtime.h`.

Flow B's limits (how large an app the firmware accepts) are CMake options: `ERB_EVENT_BUDGET`,
`ERB_MAX_FUNCTIONS`, `ERB_MAX_FUNCTION_WORDS`, `ERB_MAX_LOOPS`, `ERB_MAX_IMPORTS`,
`ERB_MAX_KEYBOARD_KEYS`, `ERB_MAX_TEMPLATE_DEPTH` and `ERB_REPORT_PLACES`. In an ESP-IDF or PlatformIO install they are
compile definitions you set from your project. Engine pool sizes stay the engine's `ERUI_*` options; the runtime reads
them at load time.

```bash
cmake -S runtime -B runtime/build
cmake --build runtime/build
ctest --test-dir runtime/build --output-on-failure
```

CI also fuzzes the Flow B loader and VM; see [`tools/erb-fuzz`](../tools/erb-fuzz/README.md).

**Docs:** [Architecture](https://embedded-react.dev/internals/architecture),
[Flow B packages](https://embedded-react.dev/internals/flow-b-packages) and
[Hot reload](https://embedded-react.dev/guides/hot-reload).