import React, { useState, useEffect } from 'react';
import { Link, useParams, useNavigate } from 'react-router-dom';
import { useAuthStore } from '../store/useAuthStore';
import './DocsPage.css';

const GITHUB_URL = 'https://github.com/davidmonterocrespo24/velxio';
const BASE_URL = 'https://velxio.dev';
const AUTHOR = { '@type': 'Person', name: 'David Montero Crespo', url: 'https://github.com/davidmonterocrespo24' } as const;

/* ── Icons ─────────────────────────────────────────────── */
const IcoChip = () => (
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round">
    <rect x="5" y="5" width="14" height="14" rx="2" />
    <rect x="9" y="9" width="6" height="6" />
    <path d="M9 1v4M15 1v4M9 19v4M15 19v4M1 9h4M1 15h4M19 9h4M19 15h4" />
  </svg>
);

const IcoGitHub = () => (
  <svg viewBox="0 0 24 24" fill="currentColor">
    <path d="M12 0C5.37 0 0 5.37 0 12c0 5.3 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61-.546-1.385-1.335-1.755-1.335-1.755-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 21.795 24 17.295 24 12c0-6.63-5.37-12-12-12z" />
  </svg>
);

/* ── Doc sections ──────────────────────────────────────── */
type SectionId =
  | 'intro'
  | 'getting-started'
  | 'emulator'
  | 'components'
  | 'roadmap'
  | 'architecture'
  | 'wokwi-libs'
  | 'mcp'
  | 'setup';

const VALID_SECTIONS: SectionId[] = [
  'intro',
  'getting-started',
  'emulator',
  'components',
  'roadmap',
  'architecture',
  'wokwi-libs',
  'mcp',
  'setup',
];

interface NavItem {
  id: SectionId;
  label: string;
}

const NAV_ITEMS: NavItem[] = [
  { id: 'intro', label: 'Introduction' },
  { id: 'getting-started', label: 'Getting Started' },
  { id: 'emulator', label: 'Emulator Architecture' },
  { id: 'components', label: 'Components Reference' },
  { id: 'architecture', label: 'Project Architecture' },
  { id: 'wokwi-libs', label: 'Wokwi Libraries' },
  { id: 'mcp', label: 'MCP Server' },
  { id: 'setup', label: 'Project Status' },
  { id: 'roadmap', label: 'Roadmap' },
];

/* ── Per-section SEO metadata ──────────────────────────── */
interface SectionMeta { title: string; description: string; }
const SECTION_META: Record<SectionId, SectionMeta> = {
  'intro': {
    title: 'Introduction — Velxio Documentation',
    description: 'Learn about Velxio, the free open-source Arduino emulator with real AVR8 and RP2040 CPU emulation and 48+ interactive electronic components.',
  },
  'getting-started': {
    title: 'Getting Started — Velxio Documentation',
    description: 'Get started with Velxio: use the hosted editor, self-host with Docker, or set up a local development environment. Simulate your first Arduino sketch in minutes.',
  },
  'emulator': {
    title: 'Emulator Architecture — Velxio Documentation',
    description: 'How Velxio emulates AVR8 (ATmega328p) and RP2040 CPUs. Covers the execution loop, peripherals (GPIO, Timers, USART, ADC, SPI, I2C), and pin mapping.',
  },
  'components': {
    title: 'Components Reference — Velxio Documentation',
    description: 'Full reference for all 48+ interactive electronic components in Velxio: LEDs, displays, sensors, buttons, potentiometers, and more. Includes wiring and property details.',
  },
  'roadmap': {
    title: 'Roadmap — Velxio Documentation',
    description: "Velxio's feature roadmap: what's implemented, what's in progress, and what's planned for future releases.",
  },
  'architecture': {
    title: 'Project Architecture — Velxio Documentation',
    description: 'Detailed overview of the Velxio system architecture: frontend, backend, AVR8 emulation pipeline, data flows, Zustand stores, and wire system.',
  },
  'wokwi-libs': {
    title: 'Wokwi Libraries — Velxio Documentation',
    description: 'How Velxio integrates the official Wokwi open-source libraries: avr8js, wokwi-elements, and rp2040js. Covers configuration, updates, and the 48 available components.',
  },
  'mcp': {
    title: 'MCP Server — Velxio Documentation',
    description: 'Velxio MCP Server reference: integrate AI agents (Claude, Cursor) with Velxio via Model Context Protocol. Covers tools, transports, circuit format, and example walkthroughs.',
  },
  'setup': {
    title: 'Project Status — Velxio Documentation',
    description: 'Complete status of all implemented Velxio features: AVR emulation, component system, wire system, code editor, example projects, and next steps.',
  },
};

/* ── Section content ───────────────────────────────────── */
const IntroSection: React.FC = () => (
  <div className="docs-section">
    <span className="docs-label">// overview</span>
    <h1>Introduction</h1>
    <p>
      <strong>Velxio</strong> is a fully local, open-source Arduino emulator that runs entirely in your browser.
      Write Arduino C++ code, compile it with a real <code>arduino-cli</code> backend, and simulate it using
      true AVR8 / RP2040 CPU emulation — with 48+ interactive electronic components, all without installing
      any software on your machine.
    </p>

    <h2>Why Velxio?</h2>
    <ul>
      <li><strong>No installation required</strong> — everything runs in the browser.</li>
      <li><strong>Real emulation</strong> — not a simplified model, but accurate AVR8 / RP2040 CPU emulation.</li>
      <li><strong>Interactive components</strong> — LEDs, buttons, potentiometers, displays, sensors, and more.</li>
      <li><strong>Open-source</strong> — inspect, modify, and self-host it yourself.</li>
    </ul>

    <h2>Supported Boards</h2>
    <table>
      <thead>
        <tr><th>Board</th><th>CPU</th><th>Emulator</th></tr>
      </thead>
      <tbody>
        <tr><td>Arduino Uno</td><td>ATmega328p @ 16 MHz</td><td>avr8js</td></tr>
        <tr><td>Arduino Nano</td><td>ATmega328p @ 16 MHz</td><td>avr8js</td></tr>
        <tr><td>Arduino Mega</td><td>ATmega2560 @ 16 MHz</td><td>avr8js</td></tr>
        <tr><td>Raspberry Pi Pico</td><td>RP2040 @ 133 MHz</td><td>rp2040js</td></tr>
      </tbody>
    </table>

    <div className="docs-callout">
      <strong>Live Demo:</strong>{' '}
      <a href="https://velxio.dev" target="_blank" rel="noopener noreferrer">velxio.dev</a>
      {' '}— no installation needed, open the editor and start simulating immediately.
    </div>
  </div>
);

const GettingStartedSection: React.FC = () => (
  <div className="docs-section">
    <span className="docs-label">// setup</span>
    <h1>Getting Started</h1>
    <p>Follow these steps to simulate your first Arduino sketch.</p>

    <h2>Option 1: Use the Hosted Version</h2>
    <p>
      No installation needed — go to{' '}
      <a href="https://velxio.dev" target="_blank" rel="noopener noreferrer">https://velxio.dev</a>{' '}
      and start coding immediately.
    </p>

    <h2>Option 2: Self-Host with Docker</h2>
    <p>Run a single Docker command to start a fully local instance:</p>
    <pre><code>{`docker run -d \\
  --name velxio \\
  -p 3080:80 \\
  -v $(pwd)/data:/app/data \\
  ghcr.io/davidmonterocrespo24/velxio:master`}</code></pre>
    <p>Then open <strong>http://localhost:3080</strong> in your browser.</p>

    <h2>Option 3: Manual Setup (Development)</h2>
    <p><strong>Prerequisites:</strong> Node.js 18+, Python 3.12+, <code>arduino-cli</code></p>

    <h3>1. Clone the repository</h3>
    <pre><code>{`git clone https://github.com/davidmonterocrespo24/velxio.git
cd velxio`}</code></pre>

    <h3>2. Start the backend</h3>
    <pre><code>{`cd backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8001`}</code></pre>

    <h3>3. Start the frontend</h3>
    <pre><code>{`cd frontend
npm install
npm run dev`}</code></pre>
    <p>Open <strong>http://localhost:5173</strong>.</p>

    <h3>4. Set up arduino-cli (first time)</h3>
    <pre><code>{`arduino-cli core update-index
arduino-cli core install arduino:avr

# For Raspberry Pi Pico support:
arduino-cli config add board_manager.additional_urls \\
  https://github.com/earlephilhower/arduino-pico/releases/download/global/package_rp2040_index.json
arduino-cli core install rp2040:rp2040`}</code></pre>

    <h2>Your First Simulation</h2>
    <ol>
      <li><strong>Open the editor</strong> at <a href="https://velxio.dev/editor" target="_blank" rel="noopener noreferrer">velxio.dev/editor</a>.</li>
      <li><strong>Select a board</strong> from the toolbar (e.g., <em>Arduino Uno</em>).</li>
      <li><strong>Write Arduino code</strong> in the Monaco editor, for example:</li>
    </ol>
    <pre><code>{`void setup() {
  pinMode(13, OUTPUT);
}

void loop() {
  digitalWrite(13, HIGH);
  delay(500);
  digitalWrite(13, LOW);
  delay(500);
}`}</code></pre>
    <ol start={4}>
      <li><strong>Click Compile</strong> — the backend calls <code>arduino-cli</code> and returns a <code>.hex</code> file.</li>
      <li><strong>Click Run</strong> — the AVR8 emulator executes the compiled program.</li>
      <li><strong>Add components</strong> using the component picker (click the <strong>+</strong> button on the canvas).</li>
      <li><strong>Connect wires</strong> by clicking a component pin and then another pin.</li>
    </ol>

    <h2>Troubleshooting</h2>
    <table>
      <thead>
        <tr><th>Problem</th><th>Solution</th></tr>
      </thead>
      <tbody>
        <tr>
          <td><code>arduino-cli: command not found</code></td>
          <td>Install <code>arduino-cli</code> and add it to your PATH.</td>
        </tr>
        <tr>
          <td>LED doesn't blink</td>
          <td>Check the browser console for port listener errors; verify pin assignment in the component property dialog.</td>
        </tr>
        <tr>
          <td>Serial Monitor is empty</td>
          <td>Ensure <code>Serial.begin()</code> is called inside <code>setup()</code> before any <code>Serial.print()</code>.</td>
        </tr>
        <tr>
          <td>Compilation errors</td>
          <td>Check the compilation console at the bottom of the editor for full <code>arduino-cli</code> output.</td>
        </tr>
      </tbody>
    </table>
  </div>
);

const EmulatorSection: React.FC = () => (
  <div className="docs-section">
    <span className="docs-label">// internals</span>
    <h1>Emulator Architecture</h1>
    <p>
      Velxio uses <strong>real CPU emulation</strong> rather than a simplified model.
      This document describes how each layer of the simulation works.
    </p>

    <h2>High-Level Data Flow</h2>
    <pre><code>{`User Code (Monaco Editor)
        │
        ▼
   Zustand Store (useEditorStore)
        │
        ▼
  FastAPI Backend ──► arduino-cli ──► .hex / .uf2 file
        │
        ▼
  AVRSimulator / RP2040Simulator
        │ loadHex()
        ▼
  CPU execution loop (~60 FPS via requestAnimationFrame)
        │
        ▼
  Port listeners (PORTB / PORTC / PORTD)
        │
        ▼
  PinManager ──► Component state ──► React re-renders`}</code></pre>

    <h2>AVR8 Emulation (Arduino Uno / Nano / Mega)</h2>
    <p>
      The AVR backend uses <a href="https://github.com/wokwi/avr8js" target="_blank" rel="noopener noreferrer">avr8js</a>,
      which implements a complete ATmega328p / ATmega2560 processor.
    </p>

    <h3>Execution Loop</h3>
    <p>Each animation frame executes approximately 267,000 CPU cycles (16 MHz ÷ 60 FPS):</p>
    <pre><code>{`avrInstruction(cpu);  // decode and execute one AVR instruction
cpu.tick();           // advance peripheral timers and counters`}</code></pre>

    <h3>Supported Peripherals</h3>
    <table>
      <thead>
        <tr><th>Peripheral</th><th>Details</th></tr>
      </thead>
      <tbody>
        <tr><td>GPIO</td><td>PORTB (pins 8–13), PORTC (A0–A5), PORTD (pins 0–7)</td></tr>
        <tr><td>Timer0 / Timer1 / Timer2</td><td><code>millis()</code>, <code>delay()</code>, PWM via <code>analogWrite()</code></td></tr>
        <tr><td>USART</td><td>Full transmit and receive — powers the Serial Monitor</td></tr>
        <tr><td>ADC</td><td>10-bit, 5 V reference on pins A0–A5</td></tr>
        <tr><td>SPI</td><td>Hardware SPI (enables ILI9341, SD card, etc.)</td></tr>
        <tr><td>I2C (TWI)</td><td>Hardware I2C with virtual device bus</td></tr>
      </tbody>
    </table>

    <h3>Pin Mapping</h3>
    <table>
      <thead>
        <tr><th>Arduino Pin</th><th>AVR Port</th><th>Bit</th></tr>
      </thead>
      <tbody>
        <tr><td>0–7</td><td>PORTD</td><td>0–7</td></tr>
        <tr><td>8–13</td><td>PORTB</td><td>0–5</td></tr>
        <tr><td>A0–A5</td><td>PORTC</td><td>0–5</td></tr>
      </tbody>
    </table>

    <h2>RP2040 Emulation (Raspberry Pi Pico)</h2>
    <p>
      The RP2040 backend uses <a href="https://github.com/wokwi/rp2040js" target="_blank" rel="noopener noreferrer">rp2040js</a>.
    </p>
    <ul>
      <li>Real RP2040 emulation at 133 MHz</li>
      <li>UART0 serial output displayed in the Serial Monitor</li>
      <li>12-bit ADC on GPIO 26–29 (A0–A3) with 3.3 V reference</li>
    </ul>

    <h2>HEX File Format</h2>
    <p>Arduino compilation produces <strong>Intel HEX</strong> format. The parser in <code>hexParser.ts</code>:</p>
    <ol>
      <li>Reads lines starting with <code>:</code></li>
      <li>Extracts the address, record type, and data bytes</li>
      <li>Returns a <code>Uint8Array</code> of program bytes</li>
      <li><code>AVRSimulator</code> converts this to a <code>Uint16Array</code> (16-bit words, little-endian)</li>
    </ol>

    <h2>Key Source Files</h2>
    <table>
      <thead>
        <tr><th>File</th><th>Purpose</th></tr>
      </thead>
      <tbody>
        <tr><td><code>frontend/src/simulation/AVRSimulator.ts</code></td><td>AVR8 CPU emulator wrapper</td></tr>
        <tr><td><code>frontend/src/simulation/PinManager.ts</code></td><td>Maps Arduino pins to UI components</td></tr>
        <tr><td><code>frontend/src/utils/hexParser.ts</code></td><td>Intel HEX parser</td></tr>
        <tr><td><code>frontend/src/components/simulator/SimulatorCanvas.tsx</code></td><td>Canvas rendering</td></tr>
        <tr><td><code>backend/app/services/arduino_cli.py</code></td><td>arduino-cli wrapper</td></tr>
        <tr><td><code>backend/app/api/routes/compile.py</code></td><td>Compilation API endpoint</td></tr>
      </tbody>
    </table>
  </div>
);

const ComponentsSection: React.FC = () => (
  <div className="docs-section">
    <span className="docs-label">// reference</span>
    <h1>Components Reference</h1>
    <p>
      Velxio ships with <strong>48+ interactive electronic components</strong> powered by{' '}
      <a href="https://github.com/wokwi/wokwi-elements" target="_blank" rel="noopener noreferrer">wokwi-elements</a>.
      All components can be placed on the simulation canvas, connected with wires, and interact with your Arduino sketch in real time.
    </p>

    <h2>Adding Components</h2>
    <ol>
      <li>Click the <strong>+</strong> button on the simulation canvas.</li>
      <li>Use <strong>search</strong> or browse by <strong>category</strong> in the component picker.</li>
      <li>Click a component to place it on the canvas.</li>
      <li><strong>Drag</strong> to reposition; click to open the <strong>Property Dialog</strong>.</li>
    </ol>

    <h2>Connecting Components</h2>
    <ol>
      <li>Click a <strong>pin</strong> on any component — a wire starts from that pin.</li>
      <li>Click a <strong>destination pin</strong> to complete the connection.</li>
      <li>Wires are <strong>color-coded</strong> by signal type:</li>
    </ol>
    <table>
      <thead>
        <tr><th>Color</th><th>Signal Type</th></tr>
      </thead>
      <tbody>
        <tr><td><span className="wire-dot" style={{ background: '#ef4444' }} /> Red</td><td>VCC (power)</td></tr>
        <tr><td><span className="wire-dot" style={{ background: '#374151' }} /> Black</td><td>GND (ground)</td></tr>
        <tr><td><span className="wire-dot" style={{ background: '#3b82f6' }} /> Blue</td><td>Analog</td></tr>
        <tr><td><span className="wire-dot" style={{ background: '#22c55e' }} /> Green</td><td>Digital</td></tr>
        <tr><td><span className="wire-dot" style={{ background: '#a855f7' }} /> Purple</td><td>PWM</td></tr>
        <tr><td><span className="wire-dot" style={{ background: '#eab308' }} /> Gold</td><td>I2C (SDA/SCL)</td></tr>
        <tr><td><span className="wire-dot" style={{ background: '#f97316' }} /> Orange</td><td>SPI (MOSI/MISO/SCK)</td></tr>
        <tr><td><span className="wire-dot" style={{ background: '#06b6d4' }} /> Cyan</td><td>USART (TX/RX)</td></tr>
      </tbody>
    </table>

    <h2>Component Categories</h2>

    <h3>Output</h3>
    <table>
      <thead><tr><th>Component</th><th>Description</th></tr></thead>
      <tbody>
        <tr><td>LED</td><td>Single LED with configurable color</td></tr>
        <tr><td>RGB LED</td><td>Three-color LED (red, green, blue channels)</td></tr>
        <tr><td>7-Segment Display</td><td>Single digit numeric display</td></tr>
        <tr><td>LCD 16×2</td><td>2-line character LCD (I2C or parallel)</td></tr>
        <tr><td>LCD 20×4</td><td>4-line character LCD</td></tr>
        <tr><td>ILI9341 TFT</td><td>240×320 color TFT display (SPI)</td></tr>
        <tr><td>Buzzer</td><td>Passive piezo buzzer</td></tr>
        <tr><td>NeoPixel</td><td>Individually addressable RGB LED strip</td></tr>
      </tbody>
    </table>

    <h3>Input</h3>
    <table>
      <thead><tr><th>Component</th><th>Description</th></tr></thead>
      <tbody>
        <tr><td>Push Button</td><td>Momentary push button</td></tr>
        <tr><td>Slide Switch</td><td>SPDT slide switch</td></tr>
        <tr><td>Potentiometer</td><td>Analog voltage divider (ADC input)</td></tr>
        <tr><td>Rotary Encoder</td><td>Incremental rotary encoder</td></tr>
        <tr><td>Keypad 4×4</td><td>16-button matrix keypad</td></tr>
        <tr><td>Joystick</td><td>Dual-axis analog joystick</td></tr>
      </tbody>
    </table>

    <h3>Sensors</h3>
    <table>
      <thead><tr><th>Component</th><th>Description</th></tr></thead>
      <tbody>
        <tr><td>HC-SR04</td><td>Ultrasonic distance sensor</td></tr>
        <tr><td>DHT22</td><td>Temperature and humidity sensor</td></tr>
        <tr><td>PIR Motion</td><td>Passive infrared motion sensor</td></tr>
        <tr><td>Photoresistor</td><td>Light-dependent resistor (LDR)</td></tr>
        <tr><td>IR Receiver</td><td>38 kHz infrared receiver</td></tr>
      </tbody>
    </table>

    <h3>Passive Components</h3>
    <table>
      <thead><tr><th>Component</th><th>Description</th></tr></thead>
      <tbody>
        <tr><td>Resistor</td><td>Standard resistor (configurable value)</td></tr>
        <tr><td>Capacitor</td><td>Electrolytic capacitor</td></tr>
        <tr><td>Inductor</td><td>Coil inductor</td></tr>
      </tbody>
    </table>

    <h2>Component Properties</h2>
    <p>Each component has a <strong>Property Dialog</strong> accessible by clicking it on the canvas:</p>
    <table>
      <thead><tr><th>Property</th><th>Description</th></tr></thead>
      <tbody>
        <tr><td>Arduino Pin</td><td>The digital or analog pin this component is connected to</td></tr>
        <tr><td>Color</td><td>Visual color (LEDs, wires)</td></tr>
        <tr><td>Value</td><td>Component value (e.g., resistance in Ω)</td></tr>
        <tr><td>Rotation</td><td>Rotate in 90° increments</td></tr>
        <tr><td>Delete</td><td>Remove the component from the canvas</td></tr>
      </tbody>
    </table>
  </div>
);

const RoadmapSection: React.FC = () => (
  <div className="docs-section">
    <span className="docs-label">// future</span>
    <h1>Roadmap</h1>
    <p>Features that are implemented, in progress, and planned for future releases of Velxio.</p>

    <h2>✅ Implemented</h2>
    <ul>
      <li>Monaco Editor with C++ syntax highlighting, autocomplete, and minimap</li>
      <li>Multi-file workspace — create, rename, delete, and switch between files</li>
      <li>Arduino compilation via <code>arduino-cli</code> (multi-file sketch support)</li>
      <li>Real ATmega328p / ATmega2560 emulation at 16 MHz via avr8js</li>
      <li>Full GPIO, Timers, USART, ADC, SPI, I2C support</li>
      <li>Real RP2040 emulation at 133 MHz via rp2040js</li>
      <li>48+ wokwi-elements components with component picker</li>
      <li>Wire creation, orthogonal routing, and segment-based editing</li>
      <li>Serial Monitor with auto baud-rate detection and send support</li>
      <li>Library Manager (browse and install Arduino libraries)</li>
      <li>Email/password and Google OAuth authentication</li>
      <li>Project save, update, delete with permanent URLs</li>
      <li>8 built-in example projects</li>
      <li>Single-container Docker image published to GHCR + Docker Hub</li>
    </ul>

    <h2>🔄 In Progress</h2>
    <ul>
      <li>Functional wire connections — electrical signal routing and validation</li>
      <li>Wire connection error handling — detect short circuits and invalid connections</li>
    </ul>

    <h2>🗓 Planned — Near-Term</h2>
    <ul>
      <li>Undo / redo for code edits and canvas changes</li>
      <li>Export / import projects as <code>.zip</code> files</li>
      <li>More boards — ESP32, Arduino Leonardo</li>
      <li>Breadboard — place components with automatic wire routing</li>
    </ul>

    <h2>🗓 Planned — Mid-Term</h2>
    <ul>
      <li>TypeDoc API documentation — auto-generated from source code</li>
      <li>GitHub Pages docs site — automatic deployment on push to <code>main</code></li>
      <li>More sensor simulations — HC-SR04, DHT22, IR receiver</li>
      <li>EEPROM emulation — persistent read/write across simulation restarts</li>
      <li>Oscilloscope component — plot analog pin voltages over time</li>
    </ul>

    <h2>🗓 Planned — Long-Term</h2>
    <ul>
      <li>Multiplayer — share and co-edit simulations in real time</li>
      <li>Embedded tutorial system — step-by-step guided projects inside the editor</li>
      <li>Custom component SDK — define new components with a JSON/TypeScript API</li>
      <li>Mobile / tablet support — responsive layout for touch devices</li>
    </ul>

    <div className="docs-callout">
      <strong>Want to contribute?</strong>{' '}
      Feature requests, bug reports, and pull requests are welcome at{' '}
      <a href={GITHUB_URL} target="_blank" rel="noopener noreferrer">github.com/davidmonterocrespo24/velxio</a>.
    </div>
  </div>
);

/* ── Architecture Section ─────────────────────────────── */
const ArchitectureSection: React.FC = () => (
  <div className="docs-section">
    <span className="docs-label">// system design</span>
    <h1>Project Architecture</h1>
    <p>
      Velxio is a fully local Arduino emulator using official Wokwi repositories for maximum
      compatibility. It features real AVR8 CPU emulation, 48+ interactive electronic components,
      a comprehensive wire system, and a build-time component discovery pipeline.
    </p>

    <h2>High-Level Overview</h2>
    <pre><code>{`Browser (React + Vite)
  ├── Monaco Editor ──► useEditorStore (Zustand)
  ├── SimulatorCanvas ──► useSimulatorStore (Zustand)
  │     ├── AVRSimulator (avr8js)   16 MHz AVR8 CPU
  │     ├── RP2040Simulator (rp2040js)
  │     ├── PinManager              pin → component mapping
  │     ├── PartSimulationRegistry  16 interactive parts
  │     └── 48+ wokwi-elements      Lit Web Components
  └── HTTP (Axios) ──► FastAPI Backend (port 8001)
        └── ArduinoCLIService ──► arduino-cli subprocess`}</code></pre>

    <h2>Data Flows</h2>

    <h3>1. Compilation</h3>
    <pre><code>{`Click "Compile"
  → EditorToolbar reads all workspace files
  → POST /api/compile/  { files, board_fqbn }
  → Backend: ArduinoCLIService writes temp dir
  → arduino-cli compile --fqbn <board> --output-dir build/
  → Returns hex_content (Intel HEX string)
  → useSimulatorStore.setCompiledHex() → loadHex()`}</code></pre>

    <h3>2. Simulation Loop</h3>
    <pre><code>{`Click "Run"
  → AVRSimulator.start()
  → requestAnimationFrame loop @ ~60 FPS
  → Each frame: Math.floor(267 000 × speed) cycles
    ├── avrInstruction(cpu)   — decode + execute one AVR instruction
    └── cpu.tick()            — advance Timer0/1/2, USART, ADC
  → PORTB/C/D write listeners fire
  → PinManager.updatePort() → per-pin callbacks
  → PartSimulationRegistry.onPinStateChange()
  → wokwi-elements update visually`}</code></pre>

    <h3>3. Input Components</h3>
    <pre><code>{`User presses button on canvas
  → wokwi web component fires 'button-press' event
  → DynamicComponent catches event
  → PartSimulationRegistry.attachEvents() handler
  → AVRSimulator.setPinState(arduinoPin, LOW)
  → AVRIOPort.setPin() injects external pin state
  → CPU reads pin in next instruction`}</code></pre>

    <h2>Key Frontend Stores (Zustand)</h2>
    <table>
      <thead>
        <tr><th>Store</th><th>Key State</th><th>Purpose</th></tr>
      </thead>
      <tbody>
        <tr><td><code>useEditorStore</code></td><td>files[], activeFileId</td><td>Multi-file Monaco workspace</td></tr>
        <tr><td><code>useSimulatorStore</code></td><td>simulator, components, wires, running</td><td>Simulation + canvas state</td></tr>
        <tr><td><code>useAuthStore</code></td><td>user, token</td><td>Auth (persisted localStorage)</td></tr>
        <tr><td><code>useProjectStore</code></td><td>projectId, slug</td><td>Currently open project</td></tr>
      </tbody>
    </table>

    <h2>Backend Routes</h2>
    <table>
      <thead>
        <tr><th>Route</th><th>Description</th></tr>
      </thead>
      <tbody>
        <tr><td><code>POST /api/compile/</code></td><td>Compile sketch files → Intel HEX / UF2</td></tr>
        <tr><td><code>GET  /api/compile/boards</code></td><td>List available boards</td></tr>
        <tr><td><code>GET/POST /api/auth/*</code></td><td>Email/password + Google OAuth</td></tr>
        <tr><td><code>GET/POST /api/projects/*</code></td><td>CRUD project persistence (SQLite)</td></tr>
        <tr><td><code>GET  /api/libraries/*</code></td><td>Arduino Library Manager integration</td></tr>
        <tr><td><code>GET  /health</code></td><td>Health check endpoint</td></tr>
      </tbody>
    </table>

    <h2>Wire System</h2>
    <p>Wires are stored as objects with start/end endpoints tied to component pin positions:</p>
    <pre><code>{`{
  id: string
  start: { componentId, pinName, x, y }
  end:   { componentId, pinName, x, y }
  color: string
  signalType: 'digital' | 'analog' | 'power-vcc' | 'power-gnd'
}`}</code></pre>
    <ul>
      <li>Orthogonal routing — no diagonal segments</li>
      <li>Segment drag — drag perpendicular to segment orientation</li>
      <li>Auto-update — wire positions recalculate when components move</li>
      <li>Grid snapping — 20 px grid for all wire endpoints</li>
    </ul>

    <div className="docs-callout">
      <strong>Full details:</strong>{' '}
      See{' '}
      <a href={`${GITHUB_URL}/blob/master/docs/ARCHITECTURE.md`} target="_blank" rel="noopener noreferrer">
        docs/ARCHITECTURE.md
      </a>{' '}
      in the repository.
    </div>
  </div>
);

/* ── Wokwi Libraries Section ──────────────────────────── */
const WokwiLibsSection: React.FC = () => (
  <div className="docs-section">
    <span className="docs-label">// open-source libs</span>
    <h1>Wokwi Libraries</h1>
    <p>
      Velxio uses official Wokwi open-source repositories cloned locally in <code>wokwi-libs/</code>.
      This gives you up-to-date, compatible emulation engines and visual components without npm registry
      dependencies.
    </p>

    <h2>Cloned Repositories</h2>
    <table>
      <thead>
        <tr><th>Library</th><th>Location</th><th>Purpose</th></tr>
      </thead>
      <tbody>
        <tr>
          <td><a href="https://github.com/wokwi/wokwi-elements" target="_blank" rel="noopener noreferrer">wokwi-elements</a></td>
          <td><code>wokwi-libs/wokwi-elements/</code></td>
          <td>48+ Lit Web Components (LEDs, LCDs, sensors, buttons…)</td>
        </tr>
        <tr>
          <td><a href="https://github.com/wokwi/avr8js" target="_blank" rel="noopener noreferrer">avr8js</a></td>
          <td><code>wokwi-libs/avr8js/</code></td>
          <td>ATmega328p / ATmega2560 CPU emulator at 16 MHz</td>
        </tr>
        <tr>
          <td><a href="https://github.com/wokwi/rp2040js" target="_blank" rel="noopener noreferrer">rp2040js</a></td>
          <td><code>wokwi-libs/rp2040js/</code></td>
          <td>Raspberry Pi Pico (RP2040) emulator</td>
        </tr>
      </tbody>
    </table>

    <h2>Vite Configuration</h2>
    <p><code>frontend/vite.config.ts</code> uses path aliases so imports resolve to the local builds:</p>
    <pre><code>{`resolve: {
  alias: {
    'avr8js':          '../wokwi-libs/avr8js/dist/esm',
    '@wokwi/elements': '../wokwi-libs/wokwi-elements/dist/esm',
  },
}`}</code></pre>

    <h2>Updating the Libraries</h2>
    <h3>All at once (recommended)</h3>
    <pre><code>{`# Windows
update-wokwi-libs.bat`}</code></pre>

    <h3>Manually</h3>
    <pre><code>{`cd wokwi-libs/wokwi-elements
git pull origin main
npm install && npm run build

cd ../avr8js
git pull origin main
npm install && npm run build

cd ../rp2040js
git pull origin main
npm install && npm run build`}</code></pre>

    <h3>After updating wokwi-elements</h3>
    <p>Regenerate component metadata so new components appear in the picker:</p>
    <pre><code>{`cd frontend
npx tsx ../scripts/generate-component-metadata.ts`}</code></pre>

    <h2>Available Wokwi Components (48)</h2>
    <table>
      <thead>
        <tr><th>Category</th><th>Components</th></tr>
      </thead>
      <tbody>
        <tr><td>Boards</td><td>Arduino Uno, Mega, Nano, ESP32 DevKit</td></tr>
        <tr><td>Sensors</td><td>DHT22, HC-SR04, PIR, Photoresistor, NTC, Joystick</td></tr>
        <tr><td>Displays</td><td>LCD 16×2, LCD 20×4, 7-Segment</td></tr>
        <tr><td>Input</td><td>Push button, 6mm button, Slide switch, DIP switch 8, Potentiometer</td></tr>
        <tr><td>Output</td><td>LED, RGB LED, LED bar graph, Buzzer, NeoPixel</td></tr>
        <tr><td>Motors</td><td>Servo, Stepper motor</td></tr>
        <tr><td>Passive</td><td>Resistor, Slide potentiometer, LED ring, Matrix keypad</td></tr>
        <tr><td>Other</td><td>IR receiver, DS1307 RTC, breadboards, etc.</td></tr>
      </tbody>
    </table>

    <h2>How avr8js Powers the Simulation</h2>
    <pre><code>{`import { CPU, avrInstruction, AVRTimer, AVRUSART, AVRADC, AVRIOPort } from 'avr8js';

const cpu   = new CPU(programMemory);          // ATmega328p at 16 MHz
const portB = new AVRIOPort(cpu, portBConfig); // digital pins 8-13
const portC = new AVRIOPort(cpu, portCConfig); // analog pins A0-A5
const portD = new AVRIOPort(cpu, portDConfig); // digital pins 0-7

function runFrame() {
  const cycles = Math.floor(267_000 * speed);
  for (let i = 0; i < cycles; i++) {
    avrInstruction(cpu); // execute one AVR instruction
    cpu.tick();          // advance timers + peripherals
  }
  requestAnimationFrame(runFrame);
}`}</code></pre>

    <div className="docs-callout">
      <strong>Full details:</strong>{' '}
      See{' '}
      <a href={`${GITHUB_URL}/blob/master/docs/WOKWI_LIBS.md`} target="_blank" rel="noopener noreferrer">
        docs/WOKWI_LIBS.md
      </a>{' '}
      in the repository.
    </div>
  </div>
);

/* ── MCP Server Section ───────────────────────────────── */
const McpSection: React.FC = () => (
  <div className="docs-section">
    <span className="docs-label">// AI integration</span>
    <h1>MCP Server</h1>
    <p>
      Velxio exposes a{' '}
      <a href="https://modelcontextprotocol.io/" target="_blank" rel="noopener noreferrer">
        Model Context Protocol
      </a>{' '}
      (MCP) server that lets AI agents (Claude, Cursor, and others) create circuits,
      generate code, and compile Arduino sketches directly.
    </p>

    <h2>Available Tools</h2>
    <table>
      <thead>
        <tr><th>Tool</th><th>Description</th></tr>
      </thead>
      <tbody>
        <tr><td><code>compile_project</code></td><td>Compile Arduino sketch files → Intel HEX / binary</td></tr>
        <tr><td><code>run_project</code></td><td>Compile and mark artifact as simulation-ready</td></tr>
        <tr><td><code>import_wokwi_json</code></td><td>Parse a Wokwi <code>diagram.json</code> → Velxio circuit</td></tr>
        <tr><td><code>export_wokwi_json</code></td><td>Serialise a Velxio circuit → Wokwi <code>diagram.json</code></td></tr>
        <tr><td><code>create_circuit</code></td><td>Create a new circuit definition</td></tr>
        <tr><td><code>update_circuit</code></td><td>Merge changes into an existing circuit</td></tr>
        <tr><td><code>generate_code_files</code></td><td>Generate starter <code>.ino</code> code from a circuit</td></tr>
      </tbody>
    </table>

    <h2>Transport Options</h2>

    <h3>1. stdio — Claude Desktop / CLI agents</h3>
    <pre><code>{`cd backend
python mcp_server.py`}</code></pre>
    <p>Claude Desktop config (<code>~/.claude/claude_desktop_config.json</code>):</p>
    <pre><code>{`{
  "mcpServers": {
    "velxio": {
      "command": "python",
      "args": ["/absolute/path/to/velxio/backend/mcp_server.py"]
    }
  }
}`}</code></pre>

    <h3>2. SSE / HTTP — Cursor IDE / web agents</h3>
    <pre><code>{`cd backend
python mcp_sse_server.py --port 8002`}</code></pre>
    <p>MCP client config:</p>
    <pre><code>{`{
  "mcpServers": {
    "velxio": { "url": "http://localhost:8002/sse" }
  }
}`}</code></pre>

    <h2>Circuit Data Format</h2>
    <p>Velxio circuits are plain JSON objects:</p>
    <pre><code>{`{
  "board_fqbn": "arduino:avr:uno",
  "version": 1,
  "components": [
    { "id": "led1", "type": "wokwi-led", "left": 200, "top": 100,
      "rotate": 0, "attrs": { "color": "red" } }
  ],
  "connections": [
    { "from_part": "uno", "from_pin": "13",
      "to_part": "led1", "to_pin": "A", "color": "green" }
  ]
}`}</code></pre>

    <h3>Supported Board FQBNs</h3>
    <table>
      <thead>
        <tr><th>Board</th><th>FQBN</th></tr>
      </thead>
      <tbody>
        <tr><td>Arduino Uno</td><td><code>arduino:avr:uno</code></td></tr>
        <tr><td>Arduino Mega</td><td><code>arduino:avr:mega</code></td></tr>
        <tr><td>Arduino Nano</td><td><code>arduino:avr:nano</code></td></tr>
        <tr><td>Raspberry Pi Pico</td><td><code>rp2040:rp2040:rpipico</code></td></tr>
      </tbody>
    </table>

    <h2>Example — Blink LED from Scratch</h2>
    <pre><code>{`// Step 1 — Create a circuit
{
  "tool": "create_circuit",
  "arguments": {
    "board_fqbn": "arduino:avr:uno",
    "components": [
      { "id": "led1", "type": "wokwi-led",
        "left": 150, "top": 100, "attrs": { "color": "red" } },
      { "id": "r1", "type": "wokwi-resistor",
        "left": 150, "top": 180, "attrs": { "value": "220" } }
    ],
    "connections": [
      { "from_part": "uno", "from_pin": "13",
        "to_part": "led1", "to_pin": "A", "color": "green" },
      { "from_part": "led1", "from_pin": "C",
        "to_part": "r1",   "to_pin": "1", "color": "black" },
      { "from_part": "r1",   "from_pin": "2",
        "to_part": "uno",  "to_pin": "GND.1", "color": "black" }
    ]
  }
}

// Step 2 — Generate code
{
  "tool": "generate_code_files",
  "arguments": {
    "circuit": "<result from Step 1>",
    "sketch_name": "blink",
    "extra_instructions": "Blink the red LED every 500ms"
  }
}

// Step 3 — Compile
{
  "tool": "compile_project",
  "arguments": {
    "files": [
      {
        "name": "blink.ino",
        "content": "void setup(){pinMode(13,OUTPUT);}\\nvoid loop(){digitalWrite(13,HIGH);delay(500);digitalWrite(13,LOW);delay(500);}"
      }
    ],
    "board": "arduino:avr:uno"
  }
}`}</code></pre>

    <h2>Setup</h2>
    <pre><code>{`cd backend
pip install -r requirements.txt

# Ensure arduino-cli is installed
arduino-cli version
arduino-cli core update-index
arduino-cli core install arduino:avr

# Run tests
python -m pytest tests/test_mcp_tools.py -v`}</code></pre>

    <div className="docs-callout">
      <strong>Full reference:</strong>{' '}
      See{' '}
      <a href={`${GITHUB_URL}/blob/master/docs/MCP.md`} target="_blank" rel="noopener noreferrer">
        docs/MCP.md
      </a>{' '}
      in the repository.
    </div>
  </div>
);

/* ── Setup / Project Status Section ──────────────────── */
const SetupSection: React.FC = () => (
  <div className="docs-section">
    <span className="docs-label">// project status</span>
    <h1>Project Status</h1>
    <p>A comprehensive overview of all features currently implemented in Velxio.</p>

    <h2>AVR Emulation (avr8js)</h2>
    <table>
      <thead><tr><th>Feature</th><th>Status</th></tr></thead>
      <tbody>
        <tr><td>ATmega328p CPU at 16 MHz</td><td>✅ Working</td></tr>
        <tr><td>Timer0, Timer1, Timer2</td><td>✅ Working</td></tr>
        <tr><td>USART (Serial)</td><td>✅ Working</td></tr>
        <tr><td>ADC (<code>analogRead</code>)</td><td>✅ Working</td></tr>
        <tr><td>Full GPIO (PORTB / PORTC / PORTD)</td><td>✅ Working</td></tr>
        <tr><td>~60 FPS loop (267k cycles/frame)</td><td>✅ Working</td></tr>
        <tr><td>Speed control (0.1× – 10×)</td><td>✅ Working</td></tr>
        <tr><td>PWM monitoring (6 channels)</td><td>✅ Working</td></tr>
        <tr><td>External pin injection (inputs)</td><td>✅ Working</td></tr>
      </tbody>
    </table>

    <h2>Component System (48+)</h2>
    <table>
      <thead><tr><th>Feature</th><th>Status</th></tr></thead>
      <tbody>
        <tr><td>Automatic discovery via AST</td><td>✅ 48 components detected</td></tr>
        <tr><td>ComponentPickerModal with search</td><td>✅ Working</td></tr>
        <tr><td>9 categories with filters</td><td>✅ Working</td></tr>
        <tr><td>Generic DynamicComponent renderer</td><td>✅ Working</td></tr>
        <tr><td>Drag-and-drop on canvas</td><td>✅ Working</td></tr>
        <tr><td>Rotation (90° increments)</td><td>✅ Working</td></tr>
        <tr><td>Properties dialog (single-click)</td><td>✅ Working</td></tr>
        <tr><td>Pin overlay (clickable cyan dots)</td><td>✅ Working</td></tr>
      </tbody>
    </table>

    <h2>Interactive Parts (16 simulated)</h2>
    <table>
      <thead><tr><th>Part</th><th>Type</th><th>Status</th></tr></thead>
      <tbody>
        <tr><td>LED</td><td>Output</td><td>✅</td></tr>
        <tr><td>RGB LED</td><td>Output (digital + PWM)</td><td>✅</td></tr>
        <tr><td>LED Bar Graph (10 LEDs)</td><td>Output</td><td>✅</td></tr>
        <tr><td>7-Segment Display</td><td>Output</td><td>✅</td></tr>
        <tr><td>Pushbutton</td><td>Input</td><td>✅</td></tr>
        <tr><td>Pushbutton 6mm</td><td>Input</td><td>✅</td></tr>
        <tr><td>Slide Switch</td><td>Input</td><td>✅</td></tr>
        <tr><td>DIP Switch 8</td><td>Input</td><td>✅</td></tr>
        <tr><td>Potentiometer</td><td>Input (ADC)</td><td>✅</td></tr>
        <tr><td>Slide Potentiometer</td><td>Input (ADC)</td><td>✅</td></tr>
        <tr><td>Photoresistor</td><td>Input / Output</td><td>✅</td></tr>
        <tr><td>Analog Joystick</td><td>Input (ADC + digital)</td><td>✅</td></tr>
        <tr><td>Servo</td><td>Output</td><td>✅</td></tr>
        <tr><td>Buzzer</td><td>Output (Web Audio)</td><td>✅</td></tr>
        <tr><td>LCD 1602</td><td>Output (full HD44780)</td><td>✅</td></tr>
        <tr><td>LCD 2004</td><td>Output (full HD44780)</td><td>✅</td></tr>
      </tbody>
    </table>

    <h2>Wire System</h2>
    <table>
      <thead><tr><th>Feature</th><th>Status</th></tr></thead>
      <tbody>
        <tr><td>Pin-to-pin creation with click</td><td>✅ Working</td></tr>
        <tr><td>Real-time preview (green dashed)</td><td>✅ Working</td></tr>
        <tr><td>Orthogonal routing (no diagonals)</td><td>✅ Working</td></tr>
        <tr><td>Segment editing (perpendicular drag)</td><td>✅ Working</td></tr>
        <tr><td>8 colours by signal type</td><td>✅ Working</td></tr>
        <tr><td>Auto-update when moving components</td><td>✅ Working</td></tr>
        <tr><td>Grid snapping (20 px)</td><td>✅ Working</td></tr>
        <tr><td>Wire selection and deletion</td><td>✅ Working</td></tr>
      </tbody>
    </table>

    <h2>Example Projects (8)</h2>
    <table>
      <thead><tr><th>Example</th><th>Category</th><th>Difficulty</th></tr></thead>
      <tbody>
        <tr><td>Blink LED</td><td>Basics</td><td>Beginner</td></tr>
        <tr><td>Traffic Light</td><td>Basics</td><td>Beginner</td></tr>
        <tr><td>Button Control</td><td>Basics</td><td>Beginner</td></tr>
        <tr><td>Fade LED (PWM)</td><td>Basics</td><td>Beginner</td></tr>
        <tr><td>Serial Hello World</td><td>Communication</td><td>Beginner</td></tr>
        <tr><td>RGB LED Colors</td><td>Basics</td><td>Intermediate</td></tr>
        <tr><td>Simon Says Game</td><td>Games</td><td>Advanced</td></tr>
        <tr><td>LCD 20×4 Display</td><td>Displays</td><td>Intermediate</td></tr>
      </tbody>
    </table>

    <h2>Troubleshooting</h2>
    <table>
      <thead><tr><th>Problem</th><th>Solution</th></tr></thead>
      <tbody>
        <tr>
          <td>Components not displayed</td>
          <td><pre style={{margin:0}}><code>cd wokwi-libs/wokwi-elements{'\n'}npm run build</code></pre></td>
        </tr>
        <tr>
          <td><code>Cannot find module 'avr8js'</code></td>
          <td><pre style={{margin:0}}><code>cd wokwi-libs/avr8js{'\n'}npm install && npm run build</code></pre></td>
        </tr>
        <tr>
          <td>LED doesn't blink</td>
          <td>Compile first, then click Run. Check pin assignment in the component property dialog.</td>
        </tr>
        <tr>
          <td>New component not in picker</td>
          <td><pre style={{margin:0}}><code>cd frontend{'\n'}npx tsx ../scripts/generate-component-metadata.ts</code></pre></td>
        </tr>
      </tbody>
    </table>

    <div className="docs-callout">
      <strong>Full status:</strong>{' '}
      See{' '}
      <a href={`${GITHUB_URL}/blob/master/docs/SETUP_COMPLETE.md`} target="_blank" rel="noopener noreferrer">
        docs/SETUP_COMPLETE.md
      </a>{' '}
      in the repository.
    </div>
  </div>
);

const SECTION_MAP: Record<SectionId, React.FC> = {
  intro: IntroSection,
  'getting-started': GettingStartedSection,
  emulator: EmulatorSection,
  components: ComponentsSection,
  roadmap: RoadmapSection,
  architecture: ArchitectureSection,
  'wokwi-libs': WokwiLibsSection,
  mcp: McpSection,
  setup: SetupSection,
};

/* ── Page ─────────────────────────────────────────────── */
export const DocsPage: React.FC = () => {
  const { section } = useParams<{ section?: string }>();
  const navigate = useNavigate();
  const [sidebarOpen, setSidebarOpen] = useState(false);
  const user = useAuthStore((s) => s.user);

  // Derive active section from URL; fall back to 'intro'
  const activeSection: SectionId =
    section && VALID_SECTIONS.includes(section as SectionId)
      ? (section as SectionId)
      : 'intro';

  // Redirect bare /docs → /docs/intro so every section has a canonical URL
  useEffect(() => {
    if (!section) {
      navigate('/docs/intro', { replace: true });
    }
  }, [section, navigate]);

  // Capture the original <head> values once on mount and restore them on unmount
  useEffect(() => {
    const origTitle = document.title;

    // Helper to capture an element and its original attribute value
    const captureAttr = <E extends Element>(selector: string, attr: string): [E | null, string] => {
      const el = document.querySelector<E>(selector);
      return [el, el?.getAttribute(attr) ?? ''];
    };

    const [descEl, origDesc] = captureAttr<HTMLMetaElement>('meta[name="description"]', 'content');
    const [canonicalEl, origCanonical] = captureAttr<HTMLLinkElement>('link[rel="canonical"]', 'href');
    const [ogTitleEl, origOgTitle] = captureAttr<HTMLMetaElement>('meta[property="og:title"]', 'content');
    const [ogDescEl, origOgDesc] = captureAttr<HTMLMetaElement>('meta[property="og:description"]', 'content');
    const [ogUrlEl, origOgUrl] = captureAttr<HTMLMetaElement>('meta[property="og:url"]', 'content');
    const [twTitleEl, origTwTitle] = captureAttr<HTMLMetaElement>('meta[name="twitter:title"]', 'content');
    const [twDescEl, origTwDesc] = captureAttr<HTMLMetaElement>('meta[name="twitter:description"]', 'content');

    return () => {
      document.title = origTitle;
      descEl?.setAttribute('content', origDesc);
      canonicalEl?.setAttribute('href', origCanonical);
      ogTitleEl?.setAttribute('content', origOgTitle);
      ogDescEl?.setAttribute('content', origOgDesc);
      ogUrlEl?.setAttribute('content', origOgUrl);
      twTitleEl?.setAttribute('content', origTwTitle);
      twDescEl?.setAttribute('content', origTwDesc);
      document.getElementById('docs-jsonld')?.remove();
    };
  }, []); // runs once on mount; cleanup runs once on unmount

  // Update all head metadata + JSON-LD per section.
  // No cleanup here — the mount effect above restores defaults on unmount,
  // and on a section change the next run of this effect immediately overwrites.
  useEffect(() => {
    const meta = SECTION_META[activeSection];
    const pageUrl = `${BASE_URL}/docs/${activeSection}`;

    document.title = meta.title;

    const set = (selector: string, value: string) =>
      document.querySelector<HTMLMetaElement>(selector)?.setAttribute('content', value);

    set('meta[name="description"]', meta.description);
    set('meta[property="og:title"]', meta.title);
    set('meta[property="og:description"]', meta.description);
    set('meta[property="og:url"]', pageUrl);
    set('meta[name="twitter:title"]', meta.title);
    set('meta[name="twitter:description"]', meta.description);

    const canonicalEl = document.querySelector<HTMLLinkElement>('link[rel="canonical"]');
    if (canonicalEl) canonicalEl.setAttribute('href', pageUrl);

    // Build the breadcrumb section label for JSON-LD
    const activeNav = NAV_ITEMS.find((i) => i.id === activeSection);
    const sectionLabel = activeNav?.label ?? activeSection;

    // Inject / update JSON-LD structured data for this doc page
    const ldId = 'docs-jsonld';
    let ldScript = document.getElementById(ldId) as HTMLScriptElement | null;
    if (!ldScript) {
      ldScript = document.createElement('script');
      ldScript.id = ldId;
      ldScript.type = 'application/ld+json';
      document.head.appendChild(ldScript);
    }
    ldScript.textContent = JSON.stringify({
      '@context': 'https://schema.org',
      '@graph': [
        {
          '@type': 'TechArticle',
          headline: meta.title,
          description: meta.description,
          url: pageUrl,
          isPartOf: { '@type': 'WebSite', url: `${BASE_URL}/`, name: 'Velxio' },
          inLanguage: 'en-US',
          author: AUTHOR,
        },
        {
          '@type': 'BreadcrumbList',
          itemListElement: [
            { '@type': 'ListItem', position: 1, name: 'Home', item: `${BASE_URL}/` },
            { '@type': 'ListItem', position: 2, name: 'Documentation', item: `${BASE_URL}/docs/intro` },
            { '@type': 'ListItem', position: 3, name: sectionLabel, item: pageUrl },
          ],
        },
      ],
    });
  }, [activeSection]);

  const ActiveContent = SECTION_MAP[activeSection];
  const activeIdx = NAV_ITEMS.findIndex((i) => i.id === activeSection);

  return (
    <div className="docs-page">
      {/* Nav */}
      <nav className="docs-nav">
        <Link to="/" className="docs-nav-brand">
          <IcoChip />
          <span>Velxio</span>
        </Link>
        <span className="docs-nav-divider">/</span>
        <span className="docs-nav-section">Docs</span>
        <div className="docs-nav-links">
          <Link to="/" className="docs-nav-link">Home</Link>
          <Link to="/examples" className="docs-nav-link">Examples</Link>
          <Link to="/editor" className="docs-nav-link">Editor</Link>
          <a href={GITHUB_URL} target="_blank" rel="noopener noreferrer" className="docs-nav-link">
            <IcoGitHub /> GitHub
          </a>
          {user ? (
            <Link to={`/${user.username}`} className="docs-nav-btn">My Projects</Link>
          ) : (
            <Link to="/login" className="docs-nav-btn">Sign in</Link>
          )}
        </div>
        <button
          className="docs-sidebar-toggle"
          onClick={() => setSidebarOpen((v) => !v)}
          aria-label="Toggle sidebar"
        >
          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round">
            <line x1="3" y1="6" x2="21" y2="6" />
            <line x1="3" y1="12" x2="21" y2="12" />
            <line x1="3" y1="18" x2="21" y2="18" />
          </svg>
        </button>
      </nav>

      <div className="docs-body">
        {/* Sidebar */}
        <aside className={`docs-sidebar${sidebarOpen ? ' docs-sidebar--open' : ''}`}>
          <div className="docs-sidebar-title">Documentation</div>
          <nav className="docs-sidebar-nav">
            {NAV_ITEMS.map((item) => (
              <Link
                key={item.id}
                to={`/docs/${item.id}`}
                className={`docs-sidebar-item${activeSection === item.id ? ' docs-sidebar-item--active' : ''}`}
                onClick={() => setSidebarOpen(false)}
              >
                {item.label}
              </Link>
            ))}
          </nav>
          <div className="docs-sidebar-divider" />
          <div className="docs-sidebar-title docs-sidebar-title--pages">Pages</div>
          <nav className="docs-sidebar-nav">
            <Link to="/" className="docs-sidebar-item docs-sidebar-link" onClick={() => setSidebarOpen(false)}>Home</Link>
            <Link to="/editor" className="docs-sidebar-item docs-sidebar-link" onClick={() => setSidebarOpen(false)}>Editor</Link>
            <Link to="/examples" className="docs-sidebar-item docs-sidebar-link" onClick={() => setSidebarOpen(false)}>Examples</Link>
          </nav>
          <div className="docs-sidebar-footer">
            <a href={GITHUB_URL} target="_blank" rel="noopener noreferrer" className="docs-sidebar-gh">
              <IcoGitHub /> View on GitHub
            </a>
          </div>
        </aside>

        {/* Main content */}
        <main className="docs-main">
          <ActiveContent />

          {/* Prev / Next navigation */}
          <div className="docs-pagination">
            {activeIdx > 0 && (
              <Link
                to={`/docs/${NAV_ITEMS[activeIdx - 1].id}`}
                className="docs-pagination-btn docs-pagination-btn--prev"
                onClick={() => window.scrollTo(0, 0)}
              >
                ← {NAV_ITEMS[activeIdx - 1].label}
              </Link>
            )}
            {activeIdx < NAV_ITEMS.length - 1 && (
              <Link
                to={`/docs/${NAV_ITEMS[activeIdx + 1].id}`}
                className="docs-pagination-btn docs-pagination-btn--next"
                onClick={() => window.scrollTo(0, 0)}
              >
                {NAV_ITEMS[activeIdx + 1].label} →
              </Link>
            )}
          </div>
        </main>
      </div>
    </div>
  );
};