initial working version

README.md

@@ -9,3 +9,216 @@ license: mit
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+# Mermaid Live Renderer Web Application
+
+This Flask application provides a web interface for rendering diagrams from [Mermaid](https://mermaid.js.org/) syntax code. It features a live preview that updates as you type and allows downloading the final diagram as PNG, SVG, or PDF.
+
+## Features
+
+*   Web-based interface for entering Mermaid code.
+*   Live preview of the diagram (SVG) that updates automatically as you type or change the theme.
+*   Selectable themes (Default, Forest, Dark, Neutral).
+*   Download the rendered diagram as PNG, SVG, or PDF.
+*   Uses `@mermaid-js/mermaid-cli` (mmdc) behind the scenes.
+
+## Project Structure
+
+```
+.
+├── app.py                  # Main Flask application logic
+├── mermaid_renderer.py     # Core class for calling mmdc
+├── requirements.txt        # Python dependencies (Flask)
+├── templates/
+│   └── index.html          # HTML template for the web interface
+├── venv/                   # Python virtual environment (created locally/on server)
+└── README.md               # This file
+```
+
+## Prerequisites
+
+### Local Machine (for testing)
+
+*   Python 3 & pip
+*   Node.js & npm
+*   `@mermaid-js/mermaid-cli` installed globally (`npm install -g @mermaid-js/mermaid-cli`)
+
+### Azure Ubuntu VM (for deployment)
+
+*   An Azure Virtual Machine running Ubuntu (e.g., Ubuntu 20.04 LTS or later).
+*   SSH access to the VM.
+*   Ability to configure Network Security Groups (NSGs) in Azure portal.
+*   `sudo` privileges on the VM.
+
+## Local Testing
+
+1.  **Clone/Download:** Get the application files (`app.py`, `mermaid_renderer.py`, `requirements.txt`, `templates/`).
+2.  **Install Prerequisites:** Ensure Python 3, pip, Node.js, npm, and `@mermaid-js/mermaid-cli` are installed locally.
+3.  **Create Virtual Environment:**
+    ```bash
+    cd /path/to/project/directory
+    python3 -m venv venv
+    source venv/bin/activate
+    ```
+4.  **Install Dependencies:**
+    ```bash
+    pip install -r requirements.txt
+    ```
+5.  **Run Development Server:**
+    ```bash
+    python app.py
+    ```
+6.  **Access:** Open your browser to `http://127.0.0.1:5001` (or the port specified in `app.py`).
+
+## Deployment to Azure Ubuntu VM
+
+These steps guide you through deploying the application using Gunicorn and Nginx.
+
+### 1. Connect to your VM
+
+Connect to your Azure Ubuntu VM using SSH:
+```bash
+ssh your_username@your_vm_ip_address
+```
+
+### 2. Install System Dependencies
+
+Update package lists and install necessary software:
+```bash
+sudo apt update
+sudo apt install -y python3 python3-pip python3-venv nodejs npm nginx gunicorn
+```
+*   `python3`, `python3-pip`, `python3-venv`: For running the Python application.
+*   `nodejs`, `npm`: Required by `@mermaid-js/mermaid-cli`.
+*   `nginx`: Web server to act as a reverse proxy.
+*   `gunicorn`: WSGI server to run the Flask application.
+
+Verify Node.js and npm installation: `node -v`, `npm -v`.
+
+### 3. (Optional but Recommended) Install Mermaid CLI Globally
+
+While the `mermaid_renderer.py` script attempts to install `mmdc` if not found, it's often more reliable to install it manually on the server first:
+```bash
+# Use --unsafe-perm if needed, especially when running as root/sudo
+sudo npm install -g @mermaid-js/mermaid-cli --unsafe-perm=true --allow-root
+# Verify installation
+mmdc --version
+```
+
+### 4. Transfer Application Files
+
+*   Create a directory for the application on the VM:
+    ```bash
+    sudo mkdir -p /var/www/mermaid-app
+    # Set appropriate ownership (replace 'your_vm_user' with your actual user)
+    sudo chown your_vm_user:your_vm_user /var/www/mermaid-app
+    cd /var/www/mermaid-app
+    ```
+*   From your **local machine**, copy the application files to the VM using `scp` or `rsync`. Replace placeholders:
+    ```bash
+    scp -r /path/to/local/app.py /path/to/local/mermaid_renderer.py /path/to/local/requirements.txt /path/to/local/templates your_username@your_vm_ip_address:/var/www/mermaid-app/
+    ```
+
+### 5. Set Up Python Virtual Environment
+
+On the VM, navigate to the application directory and set up the environment:
+```bash
+cd /var/www/mermaid-app
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+deactivate # Deactivate for now, systemd will handle activation
+```
+
+### 6. Configure systemd for Gunicorn
+
+Create a systemd service file to manage the Gunicorn process.
+
+*   Create the file:
+    ```bash
+    sudo nano /etc/systemd/system/mermaid-app.service
+    ```
+*   Paste the following content. **Important:**
+    *   Replace `your_vm_user` with the Linux user that should run the application (this user needs permissions for the app directory and potentially for npm global installs if `mmdc` wasn't pre-installed). Using your own user is fine for single-user setups. `www-data` is common if Nginx runs as `www-data`.
+    *   **Set a strong, unique `FLASK_SECRET_KEY`!** Generate one using `python -c 'import os; print(os.urandom(24))'`.
+
+    ```ini
+    [Unit]
+    Description=Gunicorn instance to serve Mermaid Live Renderer
+    After=network.target
+
+    [Service]
+    User=your_vm_user
+    Group=your_vm_user # Or www-data if User is www-data
+    WorkingDirectory=/var/www/mermaid-app
+    # Add venv's bin to the PATH and set the secret key
+    Environment="PATH=/var/www/mermaid-app/venv/bin"
+    Environment="FLASK_SECRET_KEY=replace_with_your_strong_random_secret_key"
+    # Command to start Gunicorn
+    ExecStart=/var/www/mermaid-app/venv/bin/gunicorn --workers 3 --bind unix:/var/www/mermaid-app/mermaid-app.sock -m 007 app:app
+
+    Restart=always
+
+    [Install]
+    WantedBy=multi-user.target
+    ```
+
+*   Save and close the file (Ctrl+X, then Y, then Enter in `nano`).
+*   Start and enable the service:
+    ```bash
+    sudo systemctl start mermaid-app
+    sudo systemctl enable mermaid-app
+    # Check status (look for 'active (running)')
+    sudo systemctl status mermaid-app
+    # Check for errors if it failed
+    # sudo journalctl -u mermaid-app
+    ```
+    *Troubleshooting:* If the service fails, check permissions on `/var/www/mermaid-app` and the socket file (`mermaid-app.sock` which Gunicorn creates). Ensure the `User` specified can write the socket file. The `-m 007` in the `ExecStart` makes the socket group-writable, which helps if Nginx runs as a different group (like `www-data`).
+
+### 7. Configure Nginx as Reverse Proxy
+
+Configure Nginx to forward web requests to the Gunicorn socket.
+
+*   Create an Nginx configuration file:
+    ```bash
+    sudo nano /etc/nginx/sites-available/mermaid-app
+    ```
+*   Paste the following, replacing `your_domain_or_vm_ip` with your VM's public IP address or a domain name pointing to it:
+    ```nginx
+    server {
+        listen 80;
+        server_name your_domain_or_vm_ip;
+
+        location / {
+            include proxy_params;
+            # Forward requests to the Gunicorn socket
+            proxy_pass http://unix:/var/www/mermaid-app/mermaid-app.sock;
+        }
+    }
+    ```
+*   Save and close the file.
+*   Enable the site by creating a symbolic link:
+    ```bash
+    # Remove default site if it exists and conflicts
+    # sudo rm /etc/nginx/sites-enabled/default
+    sudo ln -s /etc/nginx/sites-available/mermaid-app /etc/nginx/sites-enabled/
+    ```
+*   Test Nginx configuration and restart:
+    ```bash
+    sudo nginx -t
+    # If syntax is OK:
+    sudo systemctl restart nginx
+    ```
+
+### 8. Configure Firewall
+
+*   **Azure NSG:** In the Azure portal, go to your VM's Networking settings. Add an inbound security rule to allow traffic on port 80 (HTTP) from the internet (Source: `Any` or `Internet`).
+*   **VM Firewall (ufw):** If `ufw` is active on the VM, allow Nginx traffic:
+    ```bash
+    sudo ufw allow 'Nginx Full'
+    # Check status if needed: sudo ufw status
+    ```
+
+### 9. Access the Application
+
+Open your web browser and navigate to `http://your_domain_or_vm_ip`. You should see the Mermaid Live Renderer interface.

app.py

@@ -0,0 +1,185 @@
+# app.py
+import os
+import logging
+import base64
+import textwrap # Import the missing module
+from flask import Flask, request, render_template, send_file, flash, redirect, url_for, jsonify
+from mermaid_renderer import MermaidRenderer # Import the refactored class
+
+# Configure logging (optional but recommended)
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+
+app = Flask(__name__)
+# Required for flashing messages
+# In a real deployment, use a persistent, environment-variable-based secret key
+# Using a fixed key for simplicity here, replace in production
+app.secret_key = os.environ.get('FLASK_SECRET_KEY', 'a_very_secret_key_change_in_prod')
+
+# Initialize the renderer (could potentially be done once at startup)
+# Handle potential init errors
+renderer = None
+try:
+    renderer = MermaidRenderer()
+    logging.info("MermaidRenderer initialized successfully.")
+except RuntimeError as e:
+    logging.critical(f"Failed to initialize MermaidRenderer: {e}. The rendering endpoint will be unavailable.")
+    # Keep renderer as None to indicate failure
+
+@app.route('/', methods=['GET'])
+def index():
+    """Display the main page with the form, including default example code."""
+    default_mermaid_code = textwrap.dedent("""
+        graph TD
+            A[Start] --> B{Is it?};
+            B -- Yes --> C[OK];
+            C --> D[End];
+            B -- No --> E[Really?];
+            E --> C;
+    """).strip()
+
+    if renderer is None:
+         flash("Error: Mermaid rendering service is unavailable due to initialization failure. Please check server logs.", "error")
+    return render_template('index.html', default_code=default_mermaid_code)
+
+@app.route('/render', methods=['POST'])
+def render_mermaid():
+    """
+    Handle form submission.
+    Handle form submission for final download.
+    Re-renders the diagram based on form data and sends it as an attachment.
+    """
+    if renderer is None:
+        flash("Mermaid rendering service is unavailable. Cannot process request.", "error")
+        return redirect(url_for('index'))
+
+    mermaid_code = request.form.get('mermaid_code', '')
+    output_format = request.form.get('output_format', 'png')
+    theme = request.form.get('theme', 'default')
+
+    if not mermaid_code.strip():
+        flash("Mermaid code cannot be empty.", "warning")
+        return redirect(url_for('index'))
+
+    output_path = None
+    input_path = None
+    try:
+        logging.info(f"Download request: format={output_format}, theme={theme}")
+        if not renderer:
+            raise RuntimeError("Renderer not initialized.")
+
+        output_path, input_path = renderer.render(mermaid_code, output_format, theme)
+
+        mime_types = {'png': 'image/png', 'svg': 'image/svg+xml', 'pdf': 'application/pdf'}
+        mime_type = mime_types.get(output_format, 'application/octet-stream')
+
+        return send_file(
+            output_path,
+            mimetype=mime_type,
+            as_attachment=True,
+            download_name=f'diagram.{output_format}'
+        )
+    except (ValueError, RuntimeError) as e:
+        logging.error(f"Download rendering failed: {e}")
+        flash(f"Error generating download: {e}", "error")
+        return redirect(url_for('index'))
+    except Exception as e:
+        logging.exception("An unexpected error occurred during rendering.") # Log full traceback
+        flash("An unexpected server error occurred. Please try again later.", "error")
+        return redirect(url_for('index'))
+    finally:
+        # IMPORTANT: Clean up temporary files after sending the response or on error
+        if output_path and os.path.exists(output_path):
+            try:
+                # If it was PDF, send_file might hold the handle, but unlinking should still work on Unix-like systems
+                # On Windows, this might cause issues if send_file hasn't finished.
+                # A more robust solution might involve background tasks or different cleanup strategies.
+                os.unlink(output_path)
+                logging.info(f"Cleaned up temporary output file: {output_path}")
+            except OSError as e:
+                logging.error(f"Error deleting temporary output file {output_path}: {e}")
+        if input_path and os.path.exists(input_path):
+             try:
+                 os.unlink(input_path)
+                 logging.info(f"Cleaned up temporary input file: {input_path}")
+             except OSError as e:
+                 logging.error(f"Error deleting temporary input file {input_path}: {e}")
+
+@app.route('/preview', methods=['POST'])
+def preview_mermaid():
+    """
+    Handles asynchronous preview requests.
+    Renders PNG/SVG and returns image data as JSON.
+    """
+    if renderer is None:
+        return jsonify({"error": "Mermaid rendering service is unavailable."}), 503
+
+    data = request.get_json()
+    if not data:
+        return jsonify({"error": "Invalid request data."}), 400
+
+    mermaid_code = data.get('mermaid_code', '')
+    # Preview only supports PNG and SVG for embedding
+    output_format = data.get('output_format', 'svg') # Default to SVG for preview
+    if output_format not in ['png', 'svg']:
+         output_format = 'svg' # Force SVG if invalid format requested for preview
+    theme = data.get('theme', 'default')
+
+    if not mermaid_code.strip():
+        return jsonify({"error": "Mermaid code cannot be empty."}), 400
+
+    output_path = None
+    input_path = None
+    preview_data = None
+    try:
+        logging.info(f"Preview request: format={output_format}, theme={theme}")
+        if not renderer:
+            raise RuntimeError("Renderer not initialized.") # Should be caught above, but defensive
+
+        output_path, input_path = renderer.render(mermaid_code, output_format, theme)
+
+        with open(output_path, 'rb') as f:
+            file_content = f.read()
+
+        if output_format == 'png':
+            preview_data = base64.b64encode(file_content).decode('utf-8')
+        elif output_format == 'svg':
+            try:
+                preview_data = file_content.decode('utf-8')
+            except UnicodeDecodeError:
+                 logging.error("SVG content is not valid UTF-8 for preview.")
+                 raise RuntimeError("Generated SVG is not valid UTF-8.")
+
+        return jsonify({
+            "format": output_format,
+            "data": preview_data
+        })
+
+    except (ValueError, RuntimeError) as e:
+        logging.error(f"Preview rendering failed: {e}")
+        return jsonify({"error": f"Error rendering preview: {e}"}), 500
+    except Exception as e:
+        logging.exception("An unexpected error occurred during preview generation.")
+        return jsonify({"error": "An unexpected server error occurred during preview."}), 500
+    finally:
+        # Ensure cleanup after preview generation
+        if output_path and os.path.exists(output_path):
+            try:
+                os.unlink(output_path)
+                logging.info(f"Cleaned up temporary output file after download: {output_path}")
+            except OSError as e:
+                logging.error(f"Error deleting temporary output file {output_path} after download: {e}")
+        if input_path and os.path.exists(input_path):
+             try:
+                 os.unlink(input_path)
+                 logging.info(f"Cleaned up temporary input file after download: {input_path}")
+             except OSError as e:
+                 logging.error(f"Error deleting temporary input file {input_path} after download: {e}")
+
+
+if __name__ == '__main__':
+    # For local development only (use Gunicorn/Waitress in production)
+    # Use 0.0.0.0 to be accessible on the network
+    # Set debug=False for production-like testing, or True for development features
+    is_debug = os.environ.get('FLASK_DEBUG', 'false').lower() == 'true'
+    # Changed default port from 5000 to 5001 to avoid conflicts
+    app.run(debug=is_debug, host='0.0.0.0', port=int(os.environ.get('PORT', 5001)))

mermaid-rendering.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+# Instructions to install dependencies and run the program:
+#
+# 1. Install Node.js:
+#    - Download and install Node.js from https://nodejs.org/
+#    - Verify installation by running `node --version` in your terminal.
+#
+# 2. Install the Mermaid CLI (@mermaid-js/mermaid-cli):
+#    - Run `npm install -g @mermaid-js/mermaid-cli` in your terminal.
+#    - If you encounter permissions issues, you might need to use `sudo` (for macOS/Linux)
+#      or run the command prompt as an administrator (for Windows).
+#    - Verify installation by running `mmdc --version`.
+#
+# 3. Run the script:
+#    - You can run the script directly with the embedded example by uncommenting the lines in the `if __name__ == "__main__":` block and running:
+#      `python3 mermaid-rendering.py`
+#    - Alternatively, you can use the command-line interface:
+#      - To render Mermaid code from a string:
+#        `python3 mermaid-rendering.py -c "your_mermaid_code"`
+#      - To render Mermaid code from a file:
+#        `python3 mermaid-rendering.py -f /path/to/your/file.mmd`
+#      - You can specify the output file with `-o /path/to/output.png`, output type with `-t [png, pdf, svg]`, and theme with `--theme [default, forest, dark, neutral]`.
+#      - For example:
+#        `python3 mermaid-rendering.py -f input.mmd -o output.png -t png --theme default`
+
+import os
+import sys
+import subprocess
+import argparse
+import tempfile
+import json
+from pathlib import Path
+import textwrap
+
+class MermaidRenderer:
+    """
+    A Python class to render Mermaid diagrams to various formats
+    using puppeteer-mermaid behind the scenes
+    """
+    
+    def __init__(self):
+        """Initialize the renderer and check if dependencies are installed"""
+        self._check_dependencies()
+    
+    def _check_dependencies(self):
+        """Check if Node.js and puppeteer-mermaid are installed"""
+        try:
+            # Check for Node.js
+            subprocess.run(["node", "--version"], capture_output=True, check=True)
+        except (subprocess.SubprocessError, FileNotFoundError):
+            sys.exit("Error: Node.js is not installed. Please install Node.js from https://nodejs.org/")
+        
+        # Check if @mermaid-js/mermaid-cli is installed
+        result = subprocess.run(["npm", "list", "-g", "@mermaid-js/mermaid-cli"],
+                              capture_output=True, text=True)
+
+        if "mermaid-cli" not in result.stdout:
+            print("Installing @mermaid-js/mermaid-cli globally...")
+            try:
+                subprocess.run(["npm", "install", "-g", "@mermaid-js/mermaid-cli"], check=True)
+                print("@mermaid-js/mermaid-cli installed successfully.")
+            except subprocess.SubprocessError:
+                sys.exit("Error: Failed to install @mermaid-js/mermaid-cli. Please install manually using: npm install -g @mermaid-js/mermaid-cli")
+
+    def render(self, mermaid_code, output_file=None, output_format="png", theme="default"):
+        """
+        Render Mermaid code to the specified format
+        
+        Args:
+            mermaid_code (str): The Mermaid diagram code
+            output_file (str, optional): Output file path. If None, generates a filename based on format.
+            output_format (str, optional): Output format. Options: png, pdf, svg. Default: png
+            theme (str, optional): Mermaid theme. Default: default
+            
+        Returns:
+            str: Path to the generated file
+        """
+        # Validate output format
+        valid_formats = ["png", "pdf", "svg"]
+        if output_format not in valid_formats:
+            sys.exit(f"Error: Invalid output format. Choose from: {', '.join(valid_formats)}")
+        
+        # Create a temporary file for the Mermaid code
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.mmd', delete=False) as temp_file:
+            temp_file.write(mermaid_code)
+            input_path = temp_file.name
+        
+        # Generate output file name if not provided
+        if not output_file:
+            output_file = f"diagram.{output_format}"
+        
+        # Ensure output directory exists
+        output_dir = os.path.dirname(output_file)
+        if output_dir:
+            os.makedirs(output_dir, exist_ok=True)
+        
+        # Run puppeteer-mermaid
+        try:
+            cmd = [
+                "mmdc",
+                "-i", input_path,
+                "-o", output_file,
+                "-t", theme,
+                "-f", output_format
+            ]
+            
+            subprocess.run(cmd, check=True)
+            print(f"Diagram saved to: {output_file}")
+            
+            # Clean up the temporary file
+            os.unlink(input_path)
+            
+            return output_file
+            
+        except subprocess.SubprocessError as e:
+            os.unlink(input_path)
+            sys.exit(f"Error rendering diagram: {str(e)}")
+
+def main():
+    """Command line interface for the Mermaid renderer"""
+    parser = argparse.ArgumentParser(description="Render Mermaid diagrams to PNG, PDF, or SVG.")
+    
+    input_group = parser.add_mutually_exclusive_group(required=True)
+    input_group.add_argument("-c", "--code", help="Mermaid code as a string")
+    input_group.add_argument("-f", "--file", help="Path to a file containing Mermaid code")
+    
+    parser.add_argument("-o", "--output", help="Output file path")
+    parser.add_argument("-t", "--type", default="png", choices=["png", "pdf", "svg"],
+                        help="Output file type (default: png)")
+    parser.add_argument("--theme", default="default", 
+                        choices=["default", "forest", "dark", "neutral"],
+                        help="Mermaid theme (default: default)")
+    
+    args = parser.parse_args()
+    
+    # Get Mermaid code from string or file
+    if args.code:
+        mermaid_code = args.code
+    else:
+        try:
+            with open(args.file, 'r') as f:
+                mermaid_code = f.read()
+        except (IOError, FileNotFoundError):
+            sys.exit(f"Error: Could not read file {args.file}")
+    
+    # Create renderer and render the diagram
+    renderer = MermaidRenderer()
+    renderer.render(mermaid_code, args.output, args.type, args.theme)
+
+# Example usage with multiline string for easy copy-paste
+if __name__ == "__main__":
+    # You can replace this multiline string with your own Mermaid diagram code
+    MERMAID_CODE = """
+pie title NETFLIX
+         "Time spent looking for movie" : 90
+         "Time spent watching it" : 10
+    """
+    
+    # Uncomment and modify these lines to run directly
+    renderer = MermaidRenderer()
+    renderer.render(MERMAID_CODE, "flowchart.svg", "svg", "default")
+    renderer.render(MERMAID_CODE, "flowchart.pdf", "pdf", "default")
+
+    # Or use the command-line interface
+    #main()

mermaid_renderer.py

@@ -0,0 +1,118 @@
+# mermaid_renderer.py
+import os
+import sys
+import subprocess
+import tempfile
+import logging
+
+# Configure logging
+logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')
+
+class MermaidRenderer:
+    """
+    A Python class to render Mermaid diagrams using @mermaid-js/mermaid-cli.
+    """
+    def __init__(self):
+        """Initialize the renderer and check if dependencies are installed"""
+        self._check_dependencies()
+
+    def _check_dependencies(self):
+        """Check if Node.js and @mermaid-js/mermaid-cli are installed"""
+        try:
+            subprocess.run(["node", "--version"], capture_output=True, check=True, text=True)
+            logging.info("Node.js found.")
+        except (subprocess.SubprocessError, FileNotFoundError) as e:
+            logging.error(f"Node.js check failed: {e}")
+            # In a web context, exiting might not be ideal. Log error.
+            # Consider raising an exception or handling this state in the Flask app.
+            raise RuntimeError("Error: Node.js is not installed or not found in PATH.")
+
+        # Check if @mermaid-js/mermaid-cli is installed globally
+        # Note: Checking global npm packages can be slow and sometimes unreliable.
+        # A better approach in production might be to ensure it's installed during deployment.
+        try:
+            result = subprocess.run(["mmdc", "--version"], capture_output=True, check=True, text=True)
+            logging.info(f"@mermaid-js/mermaid-cli found: {result.stdout.strip()}")
+        except (subprocess.SubprocessError, FileNotFoundError):
+            logging.warning("@mermaid-js/mermaid-cli (mmdc) not found or failed to execute. Attempting installation...")
+            # Attempt installation if not found (consider security implications)
+            try:
+                # Using '--unsafe-perm' might be needed in some environments, but use with caution.
+                install_cmd = ["npm", "install", "-g", "@mermaid-js/mermaid-cli"]
+                subprocess.run(install_cmd, check=True, capture_output=True, text=True)
+                logging.info("@mermaid-js/mermaid-cli installed successfully via npm.")
+            except subprocess.SubprocessError as install_error:
+                logging.error(f"Failed to install @mermaid-js/mermaid-cli: {install_error.stderr}")
+                raise RuntimeError("Error: @mermaid-js/mermaid-cli (mmdc) is not installed and automatic installation failed. Please install manually: npm install -g @mermaid-js/mermaid-cli")
+
+    def render(self, mermaid_code, output_format="png", theme="default"):
+        """
+        Render Mermaid code to the specified format into a temporary file.
+
+        Args:
+            mermaid_code (str): The Mermaid diagram code.
+            output_format (str, optional): Output format (png, pdf, svg). Default: png.
+            theme (str, optional): Mermaid theme. Default: default.
+
+        Returns:
+            tuple: (path_to_temp_output_file, temp_input_file_path) or raises Exception on error.
+                   The caller is responsible for deleting these files.
+        """
+        valid_formats = ["png", "pdf", "svg"]
+        if output_format not in valid_formats:
+            raise ValueError(f"Invalid output format '{output_format}'. Choose from: {', '.join(valid_formats)}")
+
+        valid_themes = ["default", "forest", "dark", "neutral"]
+        if theme not in valid_themes:
+             raise ValueError(f"Invalid theme '{theme}'. Choose from: {', '.join(valid_themes)}")
+
+        # Create temporary files (ensure they are deleted by the caller)
+        # Input file for mermaid code
+        temp_input_file = tempfile.NamedTemporaryFile(mode='w', suffix='.mmd', delete=False)
+        # Output file for the generated diagram
+        temp_output_file = tempfile.NamedTemporaryFile(suffix=f'.{output_format}', delete=False)
+
+        input_path = temp_input_file.name
+        output_path = temp_output_file.name
+
+        try:
+            temp_input_file.write(mermaid_code)
+            temp_input_file.close() # Close file before passing to subprocess
+
+            cmd = [
+                "mmdc",
+                "-i", input_path,
+                "-o", output_path,
+                "-t", theme,
+                # No -f flag needed for mmdc, format is determined by -o extension
+                # However, explicitly setting background color might be needed for transparency
+                # "-b", "transparent" # Example: if you want transparent background for PNG/SVG
+            ]
+            logging.info(f"Running mmdc command: {' '.join(cmd)}")
+
+            result = subprocess.run(cmd, check=True, capture_output=True, text=True)
+            logging.info(f"mmdc execution successful. Output saved to: {output_path}")
+            if result.stderr:
+                 logging.warning(f"mmdc stderr: {result.stderr}")
+
+            # Return paths for Flask to handle; caller must delete files
+            return output_path, input_path
+
+        except subprocess.CalledProcessError as e:
+            logging.error(f"Error rendering diagram with mmdc: {e}")
+            logging.error(f"mmdc stderr: {e.stderr}")
+            # Clean up files on error before raising
+            temp_output_file.close()
+            os.unlink(output_path)
+            if os.path.exists(input_path): # Input file might already be closed/deleted
+                 os.unlink(input_path)
+            raise RuntimeError(f"Error rendering diagram: {e.stderr or e}")
+        except Exception as e:
+             # Catch any other unexpected errors
+             logging.error(f"Unexpected error during rendering: {e}")
+             # Ensure cleanup
+             temp_input_file.close()
+             temp_output_file.close()
+             if os.path.exists(input_path): os.unlink(input_path)
+             if os.path.exists(output_path): os.unlink(output_path)
+             raise # Re-raise the caught exception

requirements.txt

@@ -0,0 +1 @@
+Flask>=2.0

templates/index.html

@@ -0,0 +1,193 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Mermaid Live Renderer</title>
+    <style>
+        body { font-family: sans-serif; margin: 2em; background-color: #f4f4f4; color: #333; }
+        .container { max-width: 1200px; margin: auto; background: #fff; padding: 2em; border-radius: 8px; box-shadow: 0 0 10px rgba(0,0,0,0.1); display: flex; gap: 2em;}
+        .input-area { flex: 1; }
+        .preview-area { flex: 1; border-left: 1px solid #eee; padding-left: 2em; }
+        h1 { color: #555; text-align: center; margin-bottom: 1em; width: 100%;}
+        label { display: block; margin-top: 1em; font-weight: bold; }
+        textarea { width: 95%; min-height: 300px; margin-top: 0.5em; padding: 10px; border: 1px solid #ccc; border-radius: 4px; font-family: monospace; font-size: 1rem; }
+        select, button { padding: 0.8em 1.2em; margin-top: 0.5em; border: 1px solid #ccc; border-radius: 4px; font-size: 1rem; cursor: pointer; margin-right: 0.5em; }
+        button.primary { background-color: #5cb85c; color: white; border-color: #4cae4c; font-weight: bold; }
+        button.primary:hover { background-color: #4cae4c; }
+        button.secondary { background-color: #5bc0de; color: white; border-color: #46b8da; }
+        button.secondary:hover { background-color: #31b0d5; }
+        .options { display: flex; gap: 1em; align-items: center; margin-top: 1em; flex-wrap: wrap;}
+        .flash { padding: 1em; margin-bottom: 1em; border-radius: 5px; border: 1px solid transparent; }
+        .flash.error { background-color: #f8d7da; color: #721c24; border-color: #f5c6cb; }
+        .flash.warning { background-color: #fff3cd; color: #856404; border-color: #ffeeba; }
+        .flash.info { background-color: #d1ecf1; color: #0c5460; border-color: #bee5eb; }
+        #preview-box { margin-top: 1em; padding: 1em; border: 1px solid #ccc; border-radius: 4px; min-height: 300px; text-align: center; background-color: #fdfdfd; overflow: auto; display: flex; justify-content: center; align-items: center;}
+        #preview-box img { max-width: 100%; height: auto; }
+        #preview-box svg { max-width: 100%; height: auto; }
+        #preview-status { margin-top: 0.5em; font-style: italic; color: #777; min-height: 1.2em;}
+    </style>
+</head>
+</head>
+<body>
+    <div class="container">
+        <div class="input-area">
+            <h1>Mermaid Input</h1>
+
+            <!-- Flash messages -->
+        {% with messages = get_flashed_messages(with_categories=true) %}
+          {% if messages %}
+            {% for category, message in messages %}
+              <div class="flash {{ category }}">{{ message }}</div>
+            {% endfor %}
+          {% endif %}
+        {% endwith %}
+
+            <!-- Main form for final download -->
+            <form id="download-form" action="{{ url_for('render_mermaid') }}" method="post">
+                <label for="mermaid_code">Mermaid Code: (Edit the example below or paste your own)</label>
+                <textarea id="mermaid_code" name="mermaid_code" required>{{ default_code }}</textarea>
+
+                <div class="options">
+                    <div>
+                        <label for="output_format">Format:</label>
+                        <select id="output_format" name="output_format">
+                            <option value="png">PNG</option>
+                            <option value="svg" selected>SVG</option> <!-- Default to SVG for better preview -->
+                            <option value="pdf">PDF</option>
+                        </select>
+                    </div>
+
+                    <div>
+                        <label for="theme">Theme:</label>
+                        <select id="theme" name="theme">
+                            <option value="default" selected>Default</option>
+                            <option value="forest">Forest</option>
+                            <option value="dark">Dark</option>
+                            <option value="neutral">Neutral</option>
+                        </select>
+                    </div>
+                </div>
+
+                <br><br>
+                <!-- Download Button (submits the form) -->
+                <button type="submit" class="primary">Download Diagram</button>
+                <!-- Preview button removed, preview updates automatically -->
+            </form>
+        </div>
+
+        <div class="preview-area">
+            <h1>Live Preview</h1>
+            <div id="preview-status">Enter code and click Preview.</div>
+            <div id="preview-box">
+                <!-- Preview will be loaded here by JavaScript -->
+                <p style="color: #aaa;">Preview Area</p>
+            </div>
+        </div>
+    </div>
+
+    <script>
+        // Debounce function
+        function debounce(func, wait) {
+            let timeout;
+            return function executedFunction(...args) {
+                const later = () => {
+                    clearTimeout(timeout);
+                    func(...args);
+                };
+                clearTimeout(timeout);
+                timeout = setTimeout(later, wait);
+            };
+        }
+
+        const previewBox = document.getElementById('preview-box');
+        const previewStatus = document.getElementById('preview-status');
+        const mermaidCodeInput = document.getElementById('mermaid_code');
+        const outputFormatSelect = document.getElementById('output_format'); // Still needed for download format
+        const themeSelect = document.getElementById('theme');
+
+        // Function to fetch and update preview
+        const updatePreview = async () => {
+            const mermaidCode = mermaidCodeInput.value;
+            // Preview will always use SVG for best results and simplicity, download format is separate
+            const previewFormat = 'svg';
+            const theme = themeSelect.value;
+
+            if (!mermaidCode.trim()) {
+                // Don't show error for empty input, just clear preview
+                previewStatus.textContent = 'Enter code to see preview.';
+                previewStatus.style.color = '#777';
+                previewBox.innerHTML = '<p style="color: #aaa;">Preview Area</p>';
+                return;
+            }
+
+            previewStatus.textContent = 'Generating preview...';
+            previewStatus.style.color = '#777';
+
+
+            previewBox.innerHTML = '<p style="color: #aaa;">Loading...</p>'; // Show loading indicator
+
+            try {
+                const response = await fetch("{{ url_for('preview_mermaid') }}", {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        mermaid_code: mermaidCode,
+                        output_format: previewFormat, // Always request SVG for preview
+                        theme: theme,
+                    }),
+                });
+
+                if (!response.ok) {
+                    const errorData = await response.json();
+                    throw new Error(errorData.error || `HTTP error! status: ${response.status}`);
+                }
+
+                const result = await response.json();
+
+                previewBox.innerHTML = ''; // Clear previous preview/loading message
+                if (result.format === 'png') {
+                    const img = document.createElement('img');
+                    img.src = `data:image/png;base64,${result.data}`;
+                    img.alt = 'Mermaid Diagram Preview';
+                    previewBox.appendChild(img);
+                } else if (result.format === 'svg') {
+                    // Directly insert SVG markup
+                    previewBox.innerHTML = result.data;
+                     // Optional: Re-run mermaid script if needed for interactivity (if using mermaid.js library client-side)
+                     // if (typeof mermaid !== 'undefined') { mermaid.run({nodes: [previewBox]}); }
+                }
+                previewStatus.textContent = `Preview updated (SVG).`; // Preview is always SVG now
+                previewStatus.style.color = 'green';
+
+            } catch (error) {
+                console.error('Error fetching preview:', error);
+                previewStatus.textContent = `Error: ${error.message}`;
+                previewStatus.style.color = 'red';
+                previewBox.innerHTML = '<p style="color: red;">Failed to load preview.</p>';
+            }
+        };
+
+        // Debounced version of the updatePreview function
+        const debouncedUpdatePreview = debounce(updatePreview, 750); // 750ms delay
+
+        // Event listener for textarea input
+        mermaidCodeInput.addEventListener('input', debouncedUpdatePreview);
+
+        // Also update preview if theme changes
+        themeSelect.addEventListener('change', debouncedUpdatePreview);
+
+        // Initial preview load on page ready
+        document.addEventListener('DOMContentLoaded', () => {
+            if (mermaidCodeInput.value.trim()) {
+                 previewStatus.textContent = 'Rendering initial example...';
+                 updatePreview(); // Render the default code on load
+            } else {
+                 previewStatus.textContent = 'Enter code to see preview.';
+            }
+        });
+    </script>
+</body>
+</html>