Documentation & Roadmap

Workflows & Architecture

The MAPF Arena is built using SvelteKit (frontend) and Rust (solvers), orchestrated by a Taskfile.yaml in the root.

Key Commands

• task dev: Starts the frontend development server.
• task test: Runs all tests (Rust unit tests, Frontend unit tests, and E2E tests).
• task build:wasm: Compiles the built-in Rust solver (`mapf-astar`) to WASM.
• task build:test-component: Compiles the example Component Model solver.

Architecture

The system runs solvers entirely in the browser using Web Workers. Two types of WASM modules are supported:

1. Built-in Solver (wasm-bindgen): The reference A* implementation runs in the browser using wasm-bindgen.
2. Custom Solvers (Component Model): User-uploaded WASM Components (.wasm files) are verified on the backend server using Wasmtime. Custom solvers cannot run in the browser on Cloudflare Pages.

Solver Interface

Solvers must implement the WIT interface defined in solvers/wit/mapf-solver.wit. The system expects a WASM Component (not a core WASM module) that exports this interface.

Function Signature

solve: func(
    map-data: list<u8>,         // Flattened grid (row-major). 1 = passable, 0 = blocked.
    width: u32,                  // Grid width
    height: u32,                 // Grid height
    starts: list<coordinate>,   // Start positions [{x,y}, ...]
    goals: list<coordinate>     // Goal positions [{x,y}, ...]
) -> result<solution, string>;

Data Types

• Coordinate: record { x: u32, y: u32 }
• Path: record { steps: list<coordinate> } (Must include start and goal)
• Solution: record { paths: list<path>, cost: u64 }

How to Build a Solver (Rust)

To create a compatible solver using Rust:

1. Setup Crate: Create a lib crate with crate-type = ["cdylib"].
2. Add Dependencies: In Cargo.toml, add:

   [dependencies]
   wit-bindgen = "0.36.0"

3. Implement Interface: Use wit_bindgen::generate! to reference the WIT file and implement the Guest trait.
4. Build Core WASM:

   cargo build --target wasm32-unknown-unknown --release

5. Componentize: Convert the core WASM to a Component. You can use jco or wasm-tools.

   # Using jco componentize
   npx jco componentize target/wasm32-unknown-unknown/release/my_solver.wasm \
       -w wit/mapf-solver.wit -o my-solver-component.wasm
   
   # Or using wasm-tools
   wasm-tools component new target/wasm32-unknown-unknown/release/my_solver.wasm \
       -o my-solver-component.wasm

6. Upload: Upload the resulting my-solver-component.wasm file to the Arena. Custom solvers run on the backend server (not in browser) and provide deterministic instruction counting.