Replace ASCII diagrams with Mermaid (architecture, FSM, timeline)

Added astro-mermaid integration for client-side rendering.
Converted: composition diagram (flowchart), IbusHandler state machine
(stateDiagram-v2), and OBD-II protocol timeline.
Circuit schematic stays ASCII — Mermaid can't do pin-level schematics.

site/astro.config.mjs

@@ -1,11 +1,13 @@
 import { defineConfig } from 'astro/config';
 import starlight from '@astrojs/starlight';
+import mermaid from 'astro-mermaid';
 
 export default defineConfig({
   site: 'https://k-line.warehack.ing',
   telemetry: false,
   devToolbar: { enabled: false },
   integrations: [
+    mermaid(),
     starlight({
       title: 'K-Line',
       description: 'BMW I/K-Bus + OBD-II K-line interface for ESP32 with PC817 optocoupler isolation',

site/package.json

@@ -17,6 +17,7 @@
   "dependencies": {
     "@astrojs/starlight": "^0.37.6",
     "astro": "^5.17.1",
+    "astro-mermaid": "^1.3.1",
     "sharp": "^0.34.5"
   }
 }

site/src/content/docs/reference/architecture.mdx

@@ -7,58 +7,23 @@ Multi-protocol automotive bus library for ESP32. Handles BMW I/K-Bus and OBD-II
 
 ## Composition Diagram
 
-```
+```mermaid
-                    Application Layer
+graph TD
-     +-----------------------------------------+
+    APP["<b>Application Layer</b><br/>main.cpp / obd2_scanner.cpp"]
-     |             main.cpp (sniffer)           |
+    APP -->|"facade: zero-change migration"| FACADE["<b>IbusEsp32</b><br/>Backward-compatible wrapper"]
-     |                                          |
+    FACADE --> IBUS
-     |   IbusEsp32 ibus;                        |
-     |   ibus.begin(Serial1, RX, TX, LED);      |
-     |   ibus.onPacket(callback);               |
-     |   ibus.run();                             |
-     +-----------------------------------------+
 
-                       |   (facade: zero-change migration)
+    subgraph Protocol Handlers
-                       v
+        IBUS["<b>IbusHandler</b><br/>BMW I/K-Bus FSM<br/>XOR checksum<br/>Source filtering<br/>Packet callback"]
+        OBD2["<b>KLineObd2</b><br/>ISO 9141 slow init<br/>ISO 14230 fast init<br/>Echo clearing<br/>Frame parsing<br/>TesterPresent"]
+    end
 
-     +-------------------+   +-------------------+
+    IBUS -->|"reads RX ring<br/>delegates TX"| TRANSPORT
-     |    IbusHandler    |   |    KLineObd2      |
+    OBD2 -->|"reads RX ring<br/>sends via serial()<br/>flushes RX"| TRANSPORT
-     |                   |   |                   |
-     | BMW I/K-Bus FSM   |   | ISO 9141 slow init|
-     | XOR checksum      |   | ISO 14230 fast    |
-     | Source filtering   |   |   init            |
-     | Packet callback   |   | Echo clearing     |
-     |                   |   | Frame parsing     |
-     |                   |   | TesterPresent     |
-     +--------+----------+   +---------+---------+
-              |                         |
-              |  reads RX ring          |  reads RX ring
-              |  delegates TX           |  sends via serial()
-              |                         |  flushes RX
-              v                         v
-     +-----------------------------------------+
-     |            KLineTransport                |
-     |                                          |
-     | UART (HardwareSerial)                    |
-     | GPIO ISR (IRAM_ATTR, RX pin)             |
-     | esp_timer (periodic idle check)          |
-     | RX ring buffer (256 bytes)               |
-     | TX ring buffer (128 bytes)               |
-     | Bus idle detection                       |
-     | TX inversion (uart_set_line_inverse)     |
-     | Configurable: KLineConfig struct         |
-     +-----------------------------------------+
 
-              |
+    TRANSPORT["<b>KLineTransport</b><br/>UART · GPIO ISR · esp_timer<br/>RX ring 256B · TX ring 128B<br/>Bus idle detection<br/>TX inversion · KLineConfig"]
-              v
 
-     +-----------------------------------------+
+    TRANSPORT --> RING["<b>RingBuffer</b><br/>malloc'd circular buffer<br/>Bounds-checked peek/remove"]
-     |             RingBuffer                   |
-     |                                          |
-     | malloc'd circular buffer                 |
-     | Bounds-checked peek(n), remove(n)        |
-     | capacity = size - 1 (standard ring)      |
-     +-----------------------------------------+
 ```
 
 IbusHandler and KLineObd2 sit as parallel protocol handlers on top of a shared KLineTransport. Neither knows about the other. IbusEsp32 is a facade that composes one transport and one handler, preserving the original API for existing sketches.
@@ -164,13 +129,17 @@ BMW I/K-Bus protocol parser. Takes a reference to KLineTransport and reads from
 
 ### State Machine
 
-```
+```mermaid
-FIND_SOURCE --> FIND_LENGTH --> FIND_MESSAGE --> GOOD_CHECKSUM --> (callback, back to FIND_SOURCE)
+stateDiagram-v2
-     ^              |                |                   |
+    [*] --> FIND_SOURCE
-     |              |                |                   v
+    FIND_SOURCE --> FIND_LENGTH
-     +----- bad ----+         timeout (100ms)      BAD_CHECKSUM ----> remove 1 byte, retry
+    FIND_LENGTH --> FIND_MESSAGE
-     |                         remove 1 byte
+    FIND_LENGTH --> FIND_SOURCE : bad length
-     +<-----------------------------+
+    FIND_MESSAGE --> GOOD_CHECKSUM
+    FIND_MESSAGE --> FIND_SOURCE : timeout 100ms\nremove 1 byte
+    GOOD_CHECKSUM --> FIND_SOURCE : callback fired
+    GOOD_CHECKSUM --> BAD_CHECKSUM
+    BAD_CHECKSUM --> FIND_SOURCE : remove 1 byte\nretry
 ```
 
 The FSM peeks into the RX ring without consuming bytes until it has a complete, checksum-validated message. On `GOOD_CHECKSUM`, it reads the bytes out of the ring and fires the callback. On `BAD_CHECKSUM`, it removes one byte (the presumed bad source byte) and restarts -- this slides the window forward through noise or framing errors.

site/src/content/docs/reference/vehicle-compatibility.mdx

@@ -63,22 +63,19 @@ In the United States, OBD-II has been mandatory since 1996 for all passenger veh
 
 ### Protocol Timeline
 
-```
+```mermaid
-1996 ├─── OBD-II mandatory (US) ───────────────────────────────────┤
+timeline
-     │    Manufacturers choose: ISO 9141, KWP2000, J1850, or CAN  │
+    title OBD-II Protocol Evolution
-     │                                                              │
+    1996 : OBD-II mandatory (US)
-2001 ├─── European OBD (EOBD) mandatory ──────────────────────────┤
+         : Manufacturers choose ISO 9141, KWP2000, J1850, or CAN
-     │    Same protocols, EU emission standards                     │
+    2001 : European OBD (EOBD) mandatory
-     │                                                              │
+         : Same protocols, EU emission standards
-2003 ├─── CAN bus begins appearing ────────────────────────────────┤
+    2003 : CAN bus begins appearing
-     │    Manufacturers start transitioning to CAN                  │
+         : Manufacturers start transitioning to CAN
-     │                                                              │
+    2008 : CAN mandatory (US)
-2008 ├─── CAN mandatory (US) ─────────────────────────────────────┤
+         : All new US vehicles must use ISO 15765 (CAN)
-     │    All new US vehicles must use ISO 15765 (CAN)             │
+    2014 : CAN mandatory (EOBD)
-     │    K-line protocols no longer required                       │
+         : EU catches up, CAN required for all new vehicles
-     │                                                              │
-2014 ├─── CAN mandatory (EOBD) ───────────────────────────────────┤
-          EU catches up, CAN required for all new vehicles
 ```
 
 ### K-line by Manufacturer