docs: rework documentation, prepare pre-release

Signed-off-by: Henry <mail@henrygressmann.de>

Author: explodingcamera

ARCHITECTURE.md

@@ -1,23 +1,62 @@
-# TinyWasm's Architecture
+# TinyWasm Architecture
 
-TinyWasm follows the general Runtime Structure described in the [WebAssembly Specification](https://webassembly.github.io/spec/core/exec/runtime.html).
+TinyWasm follows the general runtime model described in the [WebAssembly specification](https://webassembly.github.io/spec/core/exec/runtime.html), but lowers validated WebAssembly into a compact internal instruction format before execution.
 
-Key runtime layout:
+## Runtime Layout
 
-- Values are stored in four fixed-capacity typed stacks: `stack_32` (`i32`/`f32`/`funcref`/`externref`), `stack_64` (`i64`/`f64`), `stack_128` (`v128`)
-- Locals are allocated in those value stacks. Each `CallFrame` stores `locals_base`, and local ops index from that base.
-- Calls use a separate fixed-capacity `CallStack` of `CallFrame`s.
-- Structured control (`block`/`loop`/`if`/`br*`) is lowered during parsing to jump-oriented instructions: `Jump`, `JumpIfZero`, `BranchTable*`, `DropKeep*`, and `Return`.
-- The interpreter executes this lowered bytecode in a single iterative loop.
+- Values are stored in untyped stacks:
+  - `stack_32` for `i32`, `f32`, `funcref`, and `externref`
+  - `stack_64` for `i64` and `f64`
+  - `stack_128` for `v128`
+- Locals are stored directly in the value stacks. Each `CallFrame` stores a `locals_base`, and local instructions index from that base.
+- Structured control flow (`block`, `loop`, `if`, `br*`) is lowered during parsing to jump-oriented internal instructions such as `Jump`, `JumpIfZero`, `BranchTable*`, `DropKeep*`, and `Return`.
+- Execution is a single iterative interpreter loop over the lowered instruction stream.
 
-## Precompiled Modules
+## Internal Bytecode
 
-Modules can be serialized to `.twasm` (`serialize_twasm`) and loaded later (`from_twasm`).
-This allows deployments that execute precompiled modules without enabling the parser in the runtime binary.
+TinyWasm does not interpret WebAssembly instructions directly. During parsing and validation, WebAssembly is translated into TinyWasm's internal bytecode format.
 
-See:
+This internal representation is designed to make execution simpler and cheaper:
 
-- [visit.rs](./crates/parser/src/visit.rs)
-- [instructions.rs](./crates/types/src/instructions.rs)
-- [value_stack.rs](./crates/tinywasm/src/interpreter/stack/value_stack.rs)
-- [call_stack.rs](./crates/tinywasm/src/interpreter/stack/call_stack.rs)
+- structured control flow is resolved ahead of time
+- stack effects are made explicit
+- common instruction sequences can be fused into superinstructions
+- modules can optionally be serialized as `.twasm` for reuse
+
+## Optimizer
+
+During parsing, a peephole optimizer (`optimize.rs`) fuses common instruction sequences into superinstructions. These reduce interpreter dispatch overhead by combining multiple logical operations into one internal instruction.
+
+Examples include:
+
+- **Fused binops**: `BinOpLocalLocal*`, `BinOpLocalConst*`, `BinOpStackGlobal*`  
+  Combine local/global access, a binary operation, and sometimes a store/tee.
+- **Fused jumps**: `JumpCmpLocalConst*`, `JumpCmpLocalLocal*`, `JumpCmpStackConst*`  
+  Combine comparison and conditional branch logic.
+
+## Memory Backends
+
+Linear memory is implemented through the `LinearMemory` trait. The backend is selected with `engine::Config::with_memory_backend()`.
+
+Available backends:
+
+- `VecMemory` - contiguous `Vec<u8>` backing; the default backend.
+- `PagedMemory` - chunk-based allocation, useful when growing memory without reallocating one large buffer.
+- `LazyLinearMemory` - wraps another backend and allocates memory on first access.
+- Custom backends through `MemoryBackend::custom()`.
+
+## Future Experiments
+
+TinyWasm's interpreter is intentionally simple today: validated WebAssembly is lowered to internal instructions, optimized with peephole fusion, and executed by an iterative dispatch loop.
+
+Future work may explore additional dispatch and code-generation strategies, including Rust's experimental `loop_match` state-machine work, explicit tail calls, more aggressive superinstruction fusion, top-of-stack register allocation, or even optional JIT compilation.
+
+## Code Map
+
+- [visit.rs](./crates/parser/src/visit.rs) - WebAssembly binary visitor
+- [optimize.rs](./crates/parser/src/optimize.rs) - peephole optimizer and superinstruction fusion
+- [parallel.rs](./crates/parser/src/parallel.rs) - multithreaded function parsing
+- [instructions.rs](./crates/types/src/instructions.rs) - internal instruction set
+- [value_stack.rs](./crates/tinywasm/src/interpreter/stack/value_stack.rs) - typed value stacks
+- [call_stack.rs](./crates/tinywasm/src/interpreter/stack/call_stack.rs) - call frame stack
+- [memory/mod.rs](./crates/tinywasm/src/store/memory/mod.rs) - memory backend trait and implementations

CHANGELOG.md

@@ -7,67 +7,62 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+This release is a major runtime and API rework. It adds support for several newer WebAssembly proposals, introduces the new `Engine` configuration API, rewrites large parts of execution and validation, and changes the internal `twasm` archive format. Benchmarks in the repository currently show roughly 30-90% improvement over 0.8.0 depending on workload and execution mode.
+
 ### Added
 
 - Support for the `custom_page_sizes` proposal ([#22](https://github.com/explodingcamera/tinywasm/pull/22) by [@danielstuart14](https://github.com/danielstuart14))
-- Support for the `tail_call` proposal
-- Support for the `memory64` proposal
-- Support for the `simd` proposal
-- Support for the `relaxed_simd` proposal
-- Support for the `wide_arithmetic` proposal
+- Support for the `tail_call`, `memory64`, `simd`, `relaxed_simd`, `wide_arithmetic`, and `extended_const` proposals ([#37](https://github.com/explodingcamera/tinywasm/pull/37), [#38](https://github.com/explodingcamera/tinywasm/pull/38), [#39](https://github.com/explodingcamera/tinywasm/pull/39))
+- Parse-only support for the `annotations` proposal
 - New `Engine` API (`tinywasm::Engine` and `engine::Config`) for runtime configuration
-- Resumable function execution with fuel/time-budget APIs (`call_resumable`, `resume_with_fuel`, `resume_with_time_budget`, `ExecProgress`)
+- Resumable execution APIs: `call_resumable`, `resume_with_fuel`, `resume_with_time_budget`, and `ExecProgress`
 - Host-function fuel APIs: `FuncContext::charge_fuel` and `FuncContext::remaining_fuel`
-- `engine::FuelPolicy` and `engine::Config::fuel_policy` for fuel accounting behavior
-- New `canonicalize_nans` feature flag to enable canonicalizing NaN values in the `f32`, `f64`, and `v128` types
-- Public API rework for runtime object access:
-  - export lookups: `func_untyped`/`func`, `memory`, `table`, `global`
-  - table/global value access: `global_get`, `global_set`
-  - generic export access: `extern_item` and `ExternItem`
-  - export iteration: `ModuleInstance::exports`
-  - module descriptors: `Module::imports`, `Module::exports`
-  - handle-based runtime objects with explicit store access: `Memory`, `Table`, `Global`, `Function`
+- `engine::Config` support for fuel policy, stack sizing, memory backend selection, and trap-on-OOM behavior
+- New feature flags: `canonicalize-nans`, `simd-x86`, `guest-debug`, `debug`, and `parallel-parser`
+- Top-level parser re-exports behind the `parser` feature: `parse_bytes`, `parse_file`, and `parse_stream`
 
 ### Changed
 
-- Locals are now stored in the typed value stacks instead of a separate locals structure
-- Structured control flow is fully lowered to jump-oriented internal instructions during parsing
-- Stack and call-stack limits can now be configured via `engine::Config`
-- Module-internal by-index inspection APIs are now gated behind the `guest_debug` feature
-
-### Breaking Changes
-
-- New backwards-incompatible version of the twasm format based on `postcard` (thanks [@dragonnn](https://github.com/dragonnn))
-- `RefNull` has been removed and replaced with new `FuncRef` and `ExternRef` structs
-- `Store::new` now takes an `Engine`; use `Store::default()` for default settings
-- `Error`, `Trap`, and `LinkingError` are now `#[non_exhaustive]`
-- `Trap` variant discriminant values changed (if you cast variants to integers)
-- `tinywasm::interpreter` is no longer a public module; `InterpreterRuntime` and `TinyWasmValue` are no longer public API
-- `FuncHandle::name` was removed
-- Cargo feature `simd` was removed
-- Cargo feature `tinywasm-parser` was renamed to`parser`
-- Cargo feature `logging` was renamed to `log`
-- Increased MSRV to 1.90
-- `Error::ParseError` was renamed to `Error::Parser`, and `Error::Twasm` was added
-- `ModuleInstance` export lookup APIs were renamed:
-  - `exported_func_untyped` -> `func_untyped`
-  - `exported_func` -> `func`
-  - `exported_memory` -> `memory`
-- `ModuleInstance` mutable export lookup variants were removed:
-  - `memory_mut`, `table_mut`, `global_mut`
-  - `extern_item_mut`
-- `FuncHandle` / `FuncHandleTyped` were renamed to `Function` / `FunctionTyped`
-- `HostFunction::new` / `HostFunction::func` / `HostFunction::typed` now require `&mut Store`
-- `Imports::link_module` now takes a `ModuleInstance` instead of a raw module instance id
-- `func_typed` now validates the exact wasm signature at lookup time and fails immediately on mismatches
+- `Store::new` now takes an `Engine`; use `Store::default()` for default settings.
+- `ModuleInstance::func` now validates exact Wasm signatures at lookup time and fails immediately on mismatches.
+- Stack and call-stack limits now come from `engine::Config`, and memory allocation is lazy until first access.
+- Module-internal by-index inspection APIs are now gated behind `guest-debug`, and runtime `Debug` implementations are gated behind `debug`.
+- `Module` is now re-exported directly from `tinywasm_types`; the `module` submodule was removed.
+- MSRV increased to 1.95 and the crate now uses Rust 2024.
+- `Error`, `Trap`, and `LinkingError` are now `#[non_exhaustive]`.
+- `Trap` variant discriminants changed; do not rely on casting variants to integers.
+- `HostFunction::new`, `HostFunction::func`, and `HostFunction::typed` now require `&mut Store`, and `Imports::link_module` now takes a `ModuleInstance` instead of a raw module instance id.
+- Cargo features were renamed from `tinywasm-parser` to `parser` and from `logging` to `log`.
+- `Error::ParseError` was renamed to `Error::Parser`, and `Error::Twasm` was added.
+- `FuncHandle` and `FuncHandleTyped` were renamed to `Function` and `FunctionTyped`, and module export lookups moved from `exported_*` to `func_untyped`, `func`, and `memory`.
+- The `twasm` archive format is now postcard-based and backwards-incompatible with previous versions (thanks [@dragonnn](https://github.com/dragonnn)).
+- The interpreter was refactored around more superinstruction fusion, lower-overhead dispatch, typed-stack locals, jump-oriented lowering, and optional parallel parsing.
+
+### Removed
+
+- Cargo feature `simd` was removed.
+- `RefNull` was removed and replaced with `FuncRef` and `ExternRef`.
+- `tinywasm::interpreter` is no longer a public module.
+- `InterpreterRuntime` and `TinyWasmValue` are no longer public API.
+- `FuncHandle::name` was removed.
+- Mutable `ModuleInstance` export lookup variants `memory_mut`, `table_mut`, `global_mut`, and `extern_item_mut` were removed.
 
 ### Fixed
 
-- Fixed archive **no_std** support which was broken in the previous release, and added more tests to ensure it stays working
-- `ModuleInstance::exported_memory` and `FuncContext::exported_memory` are now actually immutable ([#41](https://github.com/explodingcamera/tinywasm/pull/41))
-- Check returns in untyped host functions ([#27](https://github.com/explodingcamera/tinywasm/pull/27)) (thanks [@WhaleKit](https://github.com/WhaleKit))
-- `MemoryRefMut::copy_within(src, dst, len)` now follows its documented argument order
-- Imported tables created with `Extern::table(ty, init)` now honor the provided init value
+- Fixed archive **no_std** support, which was broken in the previous release, and added tests to ensure it stays working.
+- `ModuleInstance::memory` and `FuncContext::memory` are now actually immutable ([#41](https://github.com/explodingcamera/tinywasm/pull/41)).
+- Untyped host functions now check return values correctly ([#27](https://github.com/explodingcamera/tinywasm/pull/27)) by [@WhaleKit](https://github.com/WhaleKit).
+- `MemoryRefMut::copy_within(src, dst, len)` now follows its documented argument order.
+- Imported tables created with `Extern::table(ty, init)` now honor the provided init value.
+- Fixed unchecked memory offsets causing issues on 32-bit platforms.
+
+### Migration Notes
+
+- Replace `Store::new()` with `Store::default()` for default settings, or `Store::new(Engine::new(config))` for custom runtime configuration.
+- Rename the cargo features `tinywasm-parser` to `parser` and `logging` to `log`.
+- Rename `FuncHandle` to `Function` and `FuncHandleTyped` to `FunctionTyped`.
+- Rename module export lookups from `exported_*` methods to `func`, `func_untyped`, and `memory`.
+- Regenerate any persisted `twasm` archives; the format is now postcard-based and not backwards compatible with earlier releases.
 
 ## [0.8.0] - 2024-08-29
 
@@ -184,7 +179,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Lots of bug fixes
 - Full `no_std` support
 
-## [0.3.0] - 2024-01-11
+## [0.2.0] - 2024-01-11
 
 **All Commits**: https://github.com/explodingcamera/tinywasm/compare/v0.1.0...v0.2.0
 

CONTRIBUTING.md

@@ -48,7 +48,7 @@ Example usage:
 
 ```bash
 cargo install --locked samply
-samply record -- cargo run --release --example wasm-rust -- selfhosted
+samply record -- cargo run --release --example wasm-rust -- tinywasm
 ```
 
 ## Commits

Cargo.toml

@@ -24,8 +24,8 @@ edition="2024"
 license="MIT OR Apache-2.0"
 authors=["Henry Gressmann <crates@henrygressmann.de>"]
 repository="https://github.com/explodingcamera/tinywasm"
-categories=["wasm", "no-std"]
-keywords=["tinywasm"]
+categories=["wasm", "no-std", "compilers", "virtualization", "embedded"]
+keywords=["tinywasm", "wasm", "webassembly", "interpreter", "no-std"]
 
 [package]
 name="tinywasm-root"