Feat/algorithm builder framework

ReaAaS-N-frontend/README.md

@@ -0,0 +1,98 @@
+# ReaAaS-N Frontend
+
+## Overview
+
+This project contains the frontend user interfaces for the ReaAaS-N (Reactive Algorithm and Automata Simulation - Next-gen) platform. It includes tools for visual algorithm building and classical digital circuit design and simulation. The frontend is built using React, TypeScript, Vite, and Material-UI.
+
+## Features
+
+### Algorithm Builder
+
+*   **Description:** A tool for visually creating, managing, and simulating linear algorithms. Users can define steps, reorder them via drag-and-drop, and observe a step-by-step visualization of the algorithm's execution. It also supports generating algorithm steps from natural language input by parsing multiline text.
+*   **User Guide:** For detailed usage instructions, see the [Algorithm Builder User Guide](./docs/AlgorithmBuilderGuide.md).
+
+### Classical Circuit Designer
+
+*   **Description:** A drag-and-drop interface for designing and simulating classical digital logic circuits. It supports basic logic gates (AND, OR, NOT), input sources (toggleable boolean values), and output sinks to observe results. The circuit state is simulated in real-time. Users can save their circuit designs to and load them from the browser's local storage.
+*   **User Guide:** For detailed usage instructions, see the [Classical Circuit Designer User Guide](./docs/CircuitDesignerGuide.md).
+
+## Getting Started
+
+### Prerequisites
+
+*   Node.js (version 18.x or higher recommended, as per project dependencies like Vite and React Router DOM v7)
+*   npm (version 9.x or higher, typically comes with Node.js) or Yarn.
+
+### Installation
+
+1.  Clone the repository (if you haven't already).
+2.  Navigate to the `ReaAaS-N-frontend` directory:
+    ```bash
+    cd ReaAaS-N-frontend
+    ```
+3.  Install the dependencies:
+    ```bash
+    npm install
+    ```
+    (or `yarn install` if you prefer Yarn)
+
+### Running the Development Server
+
+1.  Ensure you are in the `ReaAaS-N-frontend` directory.
+2.  Start the Vite development server:
+    ```bash
+    npm run dev
+    ```
+    (or `yarn dev`)
+3.  Open your browser and navigate to the local URL provided (usually `http://localhost:5173` or a similar port).
+
+### Note on Backend
+
+This frontend is designed to be served by the `ReaAaS-N-backend` server, which also provides API functionalities (though current features are client-side focused). For full application behavior as intended in a complete deployment, ensure the `ReaAaS-N-backend` server is also set up and running. The backend typically serves the built frontend application from its `dist` folder and can be started on a different port (e.g., 3001).
+
+## Testing
+
+Unit and component tests are implemented using [Vitest](https://vitest.dev/) and [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/).
+
+*   **Running Tests:**
+    To run all tests in watch mode:
+    ```bash
+    npm test
+    ```
+    or
+    ```bash
+    npx vitest
+    ```
+    To run tests with a UI:
+    ```bash
+    npm run test:ui
+    ```
+    To generate a coverage report:
+    ```bash
+    npm run coverage
+    ```
+
+*   **End-to-End (E2E) Testing:**
+    For guidelines on E2E testing scenarios and features to cover, please refer to the [E2E Test Scenarios document](./docs/E2E_Test_Scenarios.md).
+
+## Project Structure
+
+A brief overview of key directories within `ReaAaS-N-frontend`:
+
+*   **`public/`**: Contains static assets that are directly copied to the build output (e.g., `index.html` template, favicons).
+*   **`src/`**: Contains all the source code for the React application.
+    *   **`components/`**: Reusable UI components.
+        *   `CircuitDesigner/nodes/`: Custom node components for the Circuit Designer.
+        *   `CircuitDesigner/PropertiesPanel.tsx`: The properties panel for the Circuit Designer.
+    *   **`docs/`**: Contains user guides and design documents in Markdown format. (This is a project-specific documentation folder within `src` if it contains docs directly related to source, or at the root if more general. As created, it's in `ReaAaS-N-frontend/docs/` relative to the project root).
+    *   **`pages/`**: Components representing full pages/views of the application (e.g., `AlgorithmBuilderPage.tsx`, `CircuitDesignerPage.tsx`).
+    *   **`test/`**: Test setup files (e.g., `setup.ts` for Vitest).
+    *   **`App.tsx`**: Main application component, handles routing and global layout.
+    *   **`main.tsx`**: Entry point of the React application.
+    *   **`theme.ts`**: MUI theme configuration.
+*   **`vite.config.ts`**: Vite configuration file, including Vitest setup.
+*   **`package.json`**: Project dependencies and scripts.
+*   **`README.md`**: This file.
+
+(Note: The actual `docs` folder was created at `ReaAaS-N-frontend/docs/`, so links like `./docs/AlgorithmBuilderGuide.md` are correct relative to this README in the same directory.)
+```

ReaAaS-N-frontend/docs/AlgorithmBuilderGuide.md

@@ -0,0 +1,95 @@
+# Algorithm Builder User Guide
+
+## Overview
+
+Welcome to the Algorithm Builder! This tool is designed to help you create, visualize, and simulate linear algorithms step-by-step. You can define the logic of your algorithm, reorder steps, and watch a visual representation of its execution.
+
+## Accessing the Algorithm Builder
+
+To access the Algorithm Builder:
+1.  Open the ReaAaS-N application in your web browser.
+2.  Click on the **"Algorithm Builder"** link, typically found in the main navigation bar at the top of the page. This is usually the default page when the application loads.
+
+## Interface Overview
+
+The Algorithm Builder interface is composed of several key areas:
+
+*   **New Step Input Field:**
+    *   Located at the top of the main content area, labeled **"New Step Description"**.
+    *   This is where you type the textual description for a new algorithm step.
+*   **"Add Step" Button:**
+    *   Positioned next to the "New Step Description" input field.
+    *   Clicking this button adds the text from the input field as a new step to your algorithm.
+*   **Algorithm Steps List:**
+    *   This central area displays all the steps you've added to your algorithm.
+    *   Each step is shown as a card with its sequential number and description.
+    *   You can **drag-and-drop** these cards to reorder the steps.
+    *   Each step card has a **"Delete"** button to remove it from the algorithm.
+*   **Natural Language Input Area (AI Tools):**
+    *   Labeled **"Generate Algorithm with AI"**. This is a text area where you can input multiple steps at once, typically by writing each step on a new line.
+    *   The **"Generate with AI"** button below this text area processes the input. (Currently, this replaces all existing steps with the new ones from the text area).
+*   **"Run Algorithm" Button:**
+    *   A prominent button, usually below the steps list.
+    *   Clicking this button starts the simulation of your algorithm.
+*   **Algorithm Visualization Area:**
+    *   Appears when you run an algorithm.
+    *   This section displays the steps of your algorithm, highlighting the currently executing step.
+
+## Working with Algorithm Steps
+
+### Adding Steps Manually
+
+1.  Locate the input field labeled **"New Step Description"**.
+2.  Type the description of your algorithm step into this field (e.g., "Initialize variable X to 0").
+3.  Click the **"Add Step"** button.
+4.  The new step will appear in the Algorithm Steps List below, automatically numbered. The input field will be cleared, ready for your next step.
+
+### Reordering Steps
+
+1.  In the Algorithm Steps List, identify the step you wish to move.
+2.  Click and hold the mouse button down on the step card.
+3.  Drag the card up or down to the desired new position in the list.
+4.  Release the mouse button.
+5.  The steps will re-number themselves automatically to reflect the new order.
+
+### Deleting Steps
+
+1.  In the Algorithm Steps List, find the step you want to remove.
+2.  On the right side of the step card, click the **"Delete"** button.
+3.  The step will be removed from the list, and the remaining steps will be re-numbered.
+
+## Using Natural Language Input
+
+The Algorithm Builder provides a way to quickly create multiple steps using the "Generate Algorithm with AI" feature.
+
+1.  Locate the text area labeled **"Generate Algorithm with AI"** (usually found under the "AI Tools" section).
+2.  Type or paste your algorithm steps into this area. Each line of text you enter will become a distinct step.
+    *Example Input:*
+    ```
+    Start
+    Read input A
+    Read input B
+    If A > B, then print A
+    Else, print B
+    End
+    ```
+3.  Click the **"Generate with AI"** button.
+4.  **Important:** Currently, this action will **replace all existing steps** in your algorithm with the ones generated from the text area. Empty lines in your input will be ignored.
+5.  The text area will be cleared after the steps are generated.
+
+## Running and Visualizing Your Algorithm
+
+Once you have defined the steps of your algorithm, you can simulate its execution:
+
+1.  Ensure your algorithm steps are in the desired order.
+2.  Click the **"Run Algorithm"** button.
+3.  The button's text will change to **"Running Algorithm..."** (or similar) and it may become disabled during execution.
+4.  The **Algorithm Visualization** area will become active.
+    *   Each step of your algorithm will be highlighted sequentially as it "executes".
+    *   There is a short delay between steps to allow you to observe the flow.
+5.  Once the simulation completes (all steps have been highlighted):
+    *   The **"Run Algorithm"** button will return to its original state and become enabled again.
+    *   The highlighting in the visualization area will reset.
+
+This allows you to visually trace the flow of your algorithm and verify its logic. Happy building!
+```

ReaAaS-N-frontend/docs/CircuitDesignerGuide.md

@@ -0,0 +1,120 @@
+# Classical Circuit Designer User Guide
+
+## Overview
+
+Welcome to the Classical Circuit Designer! This tool allows you to visually create, simulate, and manage digital logic circuits. You can build circuits using standard logic gates, input sources, and output sinks, then observe their behavior in real-time. You can also save your designs to your browser's local storage and load them back later.
+
+## Accessing the Circuit Designer
+
+To access the Classical Circuit Designer:
+1.  Open the ReaAaS-N application in your web browser.
+2.  Click on the **"Circuit Designer"** link, typically found in the main navigation bar at the top of the page.
+
+## Interface Overview
+
+The Circuit Designer interface is primarily composed of three main areas, along with save/load controls:
+
+*   **Component Palette:**
+    *   Located on the **left sidebar**.
+    *   This palette lists the available classical logic components you can use to build your circuit:
+        *   **Input Source:** Provides a boolean input (0 or 1, LOW or HIGH) that you can toggle.
+        *   **Output Sink:** Displays a boolean output value from the circuit.
+        *   **AND Gate:** Performs a logical AND operation.
+        *   **OR Gate:** Performs a logical OR operation.
+        *   **NOT Gate:** Performs a logical NOT (inversion) operation.
+*   **Canvas:**
+    *   The large central area of the page.
+    *   This is your main workspace where you drag components and draw wires to build your circuit.
+    *   You can pan (move around) and zoom within the canvas.
+*   **Properties Panel:**
+    *   Located on the **right sidebar**.
+    *   When you select a component (node) on the canvas, this panel displays its properties, such as its ID, type, and an editable **Label**.
+*   **Save/Load Buttons:**
+    *   Located at the top-left of the canvas area.
+    *   **"Save Circuit" Button:** Saves your current circuit design.
+    *   **"Load Circuit" Button:** Loads a previously saved circuit design.
+
+## Building Your Circuit
+
+### Adding Components
+
+1.  Locate the desired component in the **Component Palette** on the left.
+2.  Click and hold the mouse button down on the component in the palette.
+3.  Drag the component from the palette onto the **Canvas**.
+4.  Release the mouse button to place the component on the canvas.
+5.  You can add multiple instances of any component.
+
+### Wiring Components (Creating Edges)
+
+Components are connected using wires (also called edges) between their connection points (handles).
+
+1.  Identify the components you want to connect on the canvas.
+2.  Hover your mouse over a component; small circular **handles** will appear on its sides.
+    *   Output handles (typically on the right side of a node) are where a signal originates.
+    *   Input handles (typically on the left side of a node) are where a signal is received.
+3.  Click and hold the mouse button on an output handle of one component.
+4.  Drag the mouse to an input handle of another component.
+5.  Release the mouse button when the target handle is highlighted (or when your cursor is over it).
+6.  A wire will be drawn connecting the two handles. Wires are animated and typically colored (e.g., teal).
+
+### Interacting with Components
+
+*   **Selecting Nodes/Wires:**
+    *   Click on any component (node) or wire (edge) on the canvas to select it.
+    *   Selected elements are usually highlighted. When a node is selected, its details appear in the **Properties Panel**.
+*   **Moving Nodes:**
+    *   Click and drag any component (node) on the canvas to move it to a new position.
+*   **Deleting Nodes/Wires:**
+    1.  Select the node or wire you wish to delete by clicking on it.
+    2.  Press the **Delete** key or the **Backspace** key on your keyboard.
+    3.  The selected element will be removed. If you delete a node, any wires connected to it will also be automatically removed.
+
+### Editing Component Labels
+
+Each component on the canvas can have a custom label.
+
+1.  Click on a component (node) on the canvas to select it.
+2.  The **Properties Panel** on the right will update to show the properties of the selected node.
+3.  Locate the **"Label"** field in the Properties Panel.
+4.  Click into the "Label" text field and type your desired label (e.g., "Main Input A", "Final Output").
+5.  The label change is saved automatically as you type. This label is part of the data saved with your circuit. (Note: The visual display of this label on the node itself depends on the specific custom node's design; currently, most nodes display their type or value rather than this editable data label).
+
+## Simulating Your Circuit
+
+The circuit simulation runs in real-time as you build and interact with it.
+
+*   **Using `InputSourceNode`:**
+    *   The `InputSourceNode` is your primary way to provide input to the circuit.
+    *   It displays its current boolean value (0 for LOW/false, 1 for HIGH/true).
+    *   Click the **Switch** control on the `InputSourceNode` to toggle its value between 0 and 1.
+*   **Automatic Propagation:**
+    *   When you change the value of an `InputSourceNode`, the change automatically propagates through the connected wires and logic gates.
+*   **Observing the Simulation:**
+    *   **`OutputSinkNode`:** Displays the final boolean value (0 or 1) it receives from its connected input. Its background color also changes (e.g., to a light green for '1' and light red for '0') to indicate its state.
+    *   **Logic Gates (`AND`, `OR`, `NOT`):** These gates also visually indicate their current output value. They will display text like "Out: 1" or "Out: 0" and their background color will change similarly to the `OutputSinkNode` to reflect their output state.
+    *   **Wires (Edges):** Wires are animated to suggest signal flow but do not change color based on the boolean value they carry.
+
+By toggling input sources and observing the outputs and intermediate gate states, you can test and verify the logic of your circuit design.
+
+## Saving and Loading Your Work
+
+You can save your circuit designs to your browser's local storage and load them back later.
+
+### Saving a Circuit
+
+1.  Once you are happy with your circuit design, click the **"Save Circuit"** button located at the top-left of the canvas area.
+2.  An alert message (e.g., "Circuit saved!") will appear to confirm that your circuit has been saved.
+3.  Your circuit design, including the positions of all nodes, their connections (wires), their current data (like labels and input source values), and the current viewport (zoom and pan settings), is saved in your browser's local storage.
+
+### Loading a Circuit
+
+1.  To load a previously saved circuit, click the **"Load Circuit"** button, also located at the top-left of the canvas area.
+2.  If a saved circuit is found in your browser's local storage, it will be loaded onto the canvas.
+    *   The nodes, wires, and their states will be restored.
+    *   The viewport (pan and zoom) will also be restored to how it was when saved.
+    *   An alert message (e.g., "Circuit loaded!") will confirm the load.
+3.  If no saved circuit data is found, an alert message (e.g., "No saved circuit found.") will be displayed.
+4.  After loading, the circuit is fully interactive, and the simulation will be active.
+
+This allows you to persist your work between sessions on the same browser.
+```