# BlockWerk

> BlockWerk is a visual block diagram editor for system modeling and dynamic simulation, running entirely in the browser.

## Tech Stack
- **Frontend**: React (TypeScript), Zustand for state management, Framer Motion for animations.
- **Simulation Engine**: High-performance Rust engine compiled to WebAssembly (WASM).
- **Architecture**: A Main thread manages the UI while a Web Worker runs the WASM simulation engine, communicating via SharedArrayBuffers for zero-copy, real-time data visualization.

## Important Links & Documentation
- **Architecture & System Design**: `/docs/ARCHITECTURE.md` - Details the Zustand store dependencies, WASM boundary, and component hierarchy.
- **Agent API (Scripting Interface)**: `/docs/AGENT_API.md` - **CRITICAL FOR AI AGENTS**. Provides documentation on `window.blockwerk.agent` which allows complete programmatic control over the canvas (adding blocks, routing connections, changing params) without interacting with the DOM.
- **WASM Engine**: `/docs/wasm-engine.md` - Details about the solvers (Euler, RK4, RK45) and block implementations in Rust.
- **Block SDK**: `/docs/BLOCK_SDK.md` - Guidelines for defining custom blocks via JSON and mapping them to React components and Rust physics.
- **Connect AI (remote MCP connector)**: `/connect-ai` - Server URL `https://blockwerk-mcp-worker.blockwerk.workers.dev/` (streamable HTTP, no auth), setup steps for Claude, ChatGPT, Cursor and VS Code, and example prompts.
- **MCP Server Guide**: `/docs/mcp_implementation_guide.md` - Instructions and architectural overview for connecting Claude Desktop or Cursor to a live BlockWerk session via the official Model Context Protocol (MCP) server.

## Tips for AI Agents
1. **Agent API over UI**: When asked to create or modify a diagram, always use `window.blockwerk.agent` or the MCP tools rather than trying to simulate drag-and-drop DOM events. The API is robust and designed specifically for code-first interactions.
2. **Automatic Parameter Normalization**: Parameter keys are normalized automatically via `ParamResolver`. Standard engineering symbols and casing (e.g., `Kp`/`Ki`/`Kd`/`N` → `kp`/`ki`/`kd`/`n`, `frequency` → `naturalFrequency`, `lower`/`upper` → `lowerLimit`/`upperLimit`, `duty_cycle` → `dutyCycle`) work for both inline block creation (`add_block`) and `update_params`.
3. **Scope & Sink Signal Data**: Sink blocks (`uPlotDisplay`, `NumericDisplay`, `XYPlot`) do not produce outputs directly. Data retrieval tools (`get_signal_data`, `calculate_metrics`) automatically trace upstream source connections (`fromBlockId`) and support both SharedArrayBuffer (SAB) and Non-SAB fallback modes.
4. **State Queries**: Use `window.blockwerk.agent.describeCanvas()` or `describe_canvas` to "see" what is currently on the screen.
5. **Performance Boundary**: Be mindful of crossing the JS-WASM boundary. State is passed via `postMessage` and memory buffers (`SharedArrayBuffer`). Do not attempt to read the Rust memory directly from the UI thread unless using the provided buffered views.
6. **Data Sync**: The application heavily relies on Yjs for multiplayer real-time synchronization. Shared data structures (`Y.Map`, `Y.Array`) should be handled carefully to avoid race conditions.

## Directory Overview
- `/src/components/`: React UI, including Canvas, Toolbar, PropertyEditors, and Block implementations.
- `/src/store/`: Zustand state management (e.g., `useStore`, `useSimulationStore`).
- `/src/api/`: The AgentAPI implementation.
- `/wasm-engine/`: The Rust backend and simulation solvers.
- `/public/`: Static assets.

For full developer context, refer to the files in the `/docs` directory.