# Functional Requirements

## 1. Building Programs

### 1.1 Visual Programming

1. **Render Bricks to Represent Atomic Program Constructs**

1. _As a user, I want each programming construct (variables/literals, expressions, statements, blocks) to be represented by a distinct visual brick, so that I can easily understand the program's structure._

2. _As a user, I want different types of bricks to have distinct visual properties, including:_
1. Shape: Different geometric shapes to distinguish between categories.
2. Color: Different colors to further differentiate brick types.
3. Borders: Distinct border styles to indicate specific properties or states.

3. _As a user, I want bricks to have clear text labels indicating their function or purpose._

2. **Brick Palette**

1. _As a user, I want to be able to access all available bricks from a categorized palette, including:_

1. A clear visual organization of bricks into categories (e.g., "Logic," "Art," "Music").
2. Sections within categories.
3. Thumbnails for each brick type.

2. _As a user, I want to be able to search the palette for specific bricks by keyword, with results displayed in real-time as I type._

3. _As a user, I want to see a tooltip or brief description of a brick when I hover over it in the palette._

4. _As a user, I want to be able to add bricks to my program by dragging them from the palette into the workspace._

3. **Support Bricks with Dynamically Configurable Arguments**

1. _As a user, I want to be able to configure the input values or parameters of a brick._

2. _As a user, I want to see input fields (text boxes, dropdowns, etc.) directly on the brick or in an associated panel when the brick is selected._

3. _As a user, I want input fields to dynamically adapt to the type of argument (e.g., a number field for numerical input, a text area for string input, a color picker for color input)._

4. _As a user, I want to see validation messages or visual indicators when I enter invalid values for arguments._

5. _As a user, I want to be able to use variables or other bricks as arguments._

4. **Support Different Types of Literal Bricks**

1. _As a user, I want to be able to create literal bricks representing different data types, including:_

1. Numbers (integers, floating-point)
2. Strings (text)
3. Booleans (true/false)
4. Arrays (lists of values)
5. Objects (key-value pairs)
6. Colors

2. _As a user, I want to be able to select values from a predefined list, including:_

1. Single-level lists (e.g., a list of instruments).
2. Multi-level lists (e.g., a pitch value).

3. _As a user, I want to be able to create custom data structures._

5. **Switch Between Variants of a Brick**

1. _As a user, I want to be able to change the behavior of a brick by selecting from predefined variants._

2. _As a user, I want to see a clear visual indication when a brick has multiple variants (e.g., a dropdown menu, a toggle button)._

1. Example: For a conditional brick, I want to switch between "if-then" and "if-then-else" variants.
2. Example: For a loop brick I want to switch between "for", "while" and "do-while" variants.

3. _As a user, I want the brick's appearance and available arguments to update dynamically when I switch variants._

6. **Snap Bricks Together to Form a Brick Tower Representing a Program Tree**

1. _As a user, I want to connect bricks by dragging and dropping them, so that they visually snap together._
2. _As a user, I want connections to represent the flow of data or control in the program._
3. _As a user, I want the snapping behavior to be intuitive and precise._
4. _As a user, I want to be able to create both linear sequences of bricks (a "wall") and hierarchical structures (a "tree")._

7. **Support Brick Connection Constraints**

1. _As a user, I want the system to enforce rules about which bricks can be connected to each other, preventing invalid program structures._

1. Example: A data input brick should only connect to an input of an instruction brick.

2. _As a user, I want to see visual indicators of valid connection points (e.g., highlighted areas, connection sockets)._

8. **Show Feedback When Connecting/Disconnecting Bricks**

1. _As a user, I want to receive visual feedback when attempting to make a connection or disconnection._

2. _As a user, I want to receive visual feedback when I successfully connect or disconnect bricks, such as:_

1. A snapping animation.
2. A change in the color or outline of the connected bricks.
3. A sound effect.
4. A brief highlighting of the connection.

3. _As a user, I want to receive visual feedback when I fail to connect bricks, such as:_

1. The bricks not snapping together.
2. A brief shaking or highlighting of the invalid connection.
3. An error message._

9. **Fold/Unfold Bricks with Nested Content**

1. _As a user, I want to be able to collapse (fold) bricks that contain other bricks (e.g., loop bodies, function definitions), so that I can simplify the view of complex programs._

2. _As a user, I want to be able to expand (unfold) folded bricks to see their contents._

3. _As a user, when a brick is folded, I want to see a summary of its contents, including:_

1. The type of brick (e.g., "Note.").
2. The values of its key arguments (e.g., duration, pitches).

4. _As a user, I want to be able to fold/unfold bricks individually or in groups._

10. **Brick Arrangement**

1. _As a user, I want to be able to arrange bricks freely within the workspace, including:_

1. Dragging bricks to any position.
2. Creating both horizontal and vertical arrangements.
3. Overlapping bricks (with a clear visual hierarchy, e.g., using z-order).

2. _As a user, I want to be able to align bricks in columns, with automatic rearrangement to prevent overlap, including:_

1. Automatic spacing adjustment.
2. Optional snapping to a grid.
3. Ability to define column width._

11. **Workspace Functionalities**

1. _As a user, I want the workspace to provide automatic arrangement features to help organize bricks, such as:_

1. Automatic layout algorithms (e.g., tree layout, grid layout).
2. The ability to align selected bricks (e.g., align left, align top).
3. The ability to distribute selected bricks evenly (e.g., distribute horizontally, distribute vertically).

2. _As a user, I want to be able to fold/unfold all bricks in the workspace at once, so that I can quickly get a high-level overview or see all details._

3. _As a user, I want to be able to zoom in and out of the workspace, so that I can adjust the visibility of bricks based on my screen size or preference._

12. **Macros and Trash Handling**

1. _As a user, I want to be able to use macros, which are pre-configured groups of bricks that can be inserted into the workspace as a unit, so that I can quickly create common program patterns._
2. _As a user, I want macros to generate a specific arrangement of interconnected bricks when dragged into the workspace._
3. _As a user, I want to be able to remove bricks or groups of bricks by dragging them to a designated trash area._
4. _As a user, I want to receive visual feedback when I drag bricks over the trash area (e.g., the trash area changes appearance)._
5. _As a user, I want to be able to restore recently deleted bricks or groups of bricks from the trash area, with a limit on how many items are stored in the trash and for how long._
6. _As a user, I want an option to permanently delete items from the trash._

### 1.2 Text-Based Programming

1. **Text-Based Program Builder**

1. _As a user, I want to be able to write and edit my program using a text-based interface, providing an alternative to visual programming._
2. _As a user, I want the text-based editor to provide syntax highlighting, to improve readability and help identify errors._
3. _As a user, I want the text-based editor to provide code completion, to speed up development and reduce typing errors._
4. _As a user, I want the text-based editor to provide error checking and feedback, to help me identify and correct mistakes in my code._
5. _As a user, I want to be able to switch seamlessly between the visual programming interface and the text-based interface, with changes in one reflected in the other._
6. _As a user, I want to be able to import and export programs in a standard text-based format._

### 1.3 Widgets

1. **Widgets or Wizards to Generate Blocks**

1. _As a user, I want to be able to use interactive widgets or wizards to guide me through the process of creating complex or common program structures, so that I can avoid manual construction of many bricks._
2. _As a user, I want widgets to present a series of steps or questions to gather the necessary information for generating the desired block structure._
3. _(More detailed requirements TBD)_

## 2. Running Programs

1. **Run the Whole Program**

1. _As a user, I want to initiate the execution of my entire program from the beginning, so that I can observe its complete behavior and output sequence._
2. _As a user, I want the program to run in a non-blocking way, so that the UI remains responsive._

2. **Pause Running Program**

1. _As a user, I want to temporarily halt the execution of a running program at its current state, so that I can:_

1. Inspect the values of variables or the state of the program.
2. Modify the program code and resume execution from the paused point.
3. Set breakpoints to pause execution at specific locations.

3. **Stop Running Program**

1. _As a user, I want to terminate the execution of a running program immediately, so that I can:_

1. Halt an infinite loop or a program that is taking too long.
2. Free up system resources.
3. Abort an unwanted execution.

4. **Reset Stopped Program**

1. _As a user, I want to revert the state of a stopped program to its initial condition, so that I can:_

1. Prepare the program for a new execution with a clean slate.
2. Clear any residual data or side effects from the previous run.
3. Reset all variables to their initial values._

5. **Show Output for Each Toolkit Based on Configuration (Logic, Art, Music)**

1. _As a user, I want the system to display the appropriate output windows based on the active toolkits in my program, including:_

1. A text console for logic and textual output.
2. A graphical canvas for art and visual display.
3. An audio player for music and sound output.

2. _As a user, I want the output windows to be clearly labeled and organized, so that I can easily distinguish between different types of output._

3. _As a user, I want the system to automatically create the necessary output windows._

6. **Switch Between Fullscreen Output and Integrated View**

1. _As a user, I want to be able to toggle the output display between two modes:_

1. Fullscreen mode: The output window occupies the entire screen, allowing for focused viewing of the program's results.
2. Integrated view: The output window is displayed alongside the program editor, enabling simultaneous viewing of code and output.

2. _As a user, I want the system to remember my preferred output mode._

7. **Art Output Window Functions**

1. _As a user, I want to be able to select a 2D coordinate system as a background for the art output window, including:_

1. Cartesian: A standard rectangular grid system.
2. Radial: A circular coordinate system.

2. _As a user, I want to be able to position and manipulate multiple sprites (graphical objects) within the art output window, including:_

1. Setting their initial position.
2. Moving them over time.
3. Rotating and scaling them.
4. Controlling their visibility.

3. _As a user, I want to be able to toggle sprite wrapping behavior, which determines what happens when a sprite moves outside the window boundaries:_

1. Wrap: The sprite reappears on the opposite side of the window.
2. Clip: The sprite is clipped at the window edges.

4. _As a user, I want the art output window to resize gracefully, maintaining the aspect ratio and scaling the content appropriately, so that the visuals remain coherent across different window sizes._

8. **Reset Output Windows**

1. _As a user, I want to be able to restore all output windows to their default settings, clearing any displayed content and resetting any user-configurable options, so that I can:_

1. Start a new program execution with a clean output environment.
2. Remove any visual or audio clutter from previous runs.
3. Return the output windows to their initial layout and size._

9. **Show a Timeline of Program Events**

1. _As a user, I want to see a chronological visualization of significant events during program execution._
2. _As a user, I want to be able to filter the timeline._
3. _As a user, I want to be able to zoom in and out of the timeline._
4. _As a user, I want to be able to see the program state (e.g., variable values, object properties) at any given point in the timeline._
5. (More detailed requirements TBD)

10. **Show Warnings/Errors When Running Programs**

1. _As a user, I want the system to display informative warning and error messages during program execution, so that I can quickly identify and resolve issues._

2. _As a user, I want error messages to include:_

1. A clear description of the problem.
2. Visual highlighting of the brick or code element causing the error.

3. _As a user, I want warning messages to indicate potential problems or performance issues that may not prevent the program from running but should be addressed._

4. _As a user, I want to be able to configure the verbosity of warnings._

11. **Show Toast Messages**

1. _As a user, I want the system to display brief, non-intrusive, temporary messages (toast messages) for important events or status updates, such as:_

1. Successful saving of a program.
2. Completion of a long-running operation.
3. Notifications about changes in the program state._

2. _As a user, I want toast messages to appear briefly and automatically disappear after a short duration._

3. _As a user, I want toast messages to be visually distinct from other messages._

12. **Standard Output Window for Messages**

1. _As a user, I want a dedicated, persistent output window to display general messages, including:_

1. Debug output from the program.
2. Log messages from the system.
3. Compilation or build information.

2. _As a user, I want to be able to scroll through the messages in the output window._

3. _As a user, I want to be able to clear the messages in the output window._

## 3. Debugging

1. **Show Program Statistics Based on Bricks in the Project**

1. _As a user, I want to see a count of each type of brick used in my program, so that I can understand the composition of my code._

2. _As a user, I want to view meaningful statistics specific to the toolkits used, so that I can analyze creative aspects of my project. For example:_

1. For the Art toolkit: number of shape creation actions, number of color changes, number of animations.

2. For the Music toolkit: number of notes played, number of instruments used, number of tempo changes.

3. _As a user, I want to see general statistics about my program, so that I can measure complexity and scale. For example:_

1. Total number of instructions.
2. Maximum depth of nested brick structures.
3. Number of variables used.
4. Number of event listeners.

2. **Run a Tree Step-by-Step**

1. _As a user, I want to execute a specific brick tower one step at a time, so that I can trace the logic precisely._

2. _As a user, I want a button or visual indicator to appear near a selected brick tower that, when activated, puts that brick tower into step-by-step mode, so that I can easily debug individual sections._

3. _As a user, when in step-by-step mode, I want to see the current execution state highlighted as the debugger moves from one brick to the next, so that I can follow the control flow clearly. This includes:_

1. Highlighting the currently executing brick.
2. Displaying the values of any input arguments to the brick before execution.
3. Displaying the output value of the brick after execution.

4. _As a user, I want a debugger window that shows relevant state information, so that I can inspect variables, arguments, and outputs during debugging. This window should include:_

1. A list of all variables and their current values.
2. The current call stack, showing the sequence of function or block invocations.
3. The values of any relevant registers or internal state variables.
4. The output of the current brick.

3. **Run a Tree Slowly**

1. _As a user, I want to run a brick tower slowly, without needing to click for each step, so that I can observe behavior passively._

2. _As a user, I want the slow-run mode to still show transitions between bricks and internal states, with a clear visual indication of the current step, so that I don’t miss key details. This includes:_

1. Highlighting the currently executing brick as it is executed.
2. A delay slider to control the speed of execution.

4. **Inspect States in a Running Program**

1. _As a user, I want to inspect the internal state of my program while it is running at full speed, so that I can debug values, branches, and conditions in real time._
2. _As a user, I want to be able to see the values of variables change as the program executes._
3. _As a user I want to be able to see the flow of execution._

5. **Debugger Window**

1. _As a user, I want a dedicated debugger window that presents the current execution context, variables, stack frames, and outputs, so that I can understand what my program is doing at any moment. This window should include:_

1. The current line or brick being executed.
2. A list of all in-scope variables and their values.
3. The call stack, showing the sequence of function calls.
4. The output of the currently executing code._

6. **Breakpoints**

1. _As a user, I want to add visual breakpoint indicators to bricks or editor lines, so that the program execution pauses at specific points for inspection._
2. _As a user, I want execution to stop when it reaches a breakpoint, so that I can examine the state at that moment before continuing._
3. _As a user, I want to be able to set conditional breakpoints that only pause execution when a specific condition is met._
4. _As a user, I want to be able to see a list of all set breakpoints._

## 4. Configuring Environment

1. **Core Functionality and Plugins**

1. _As a user, I want the environment to include only a minimal set of core programming features by default, providing a lightweight and focused experience. This core functionality should include:_

1. Basic data types (numbers, strings, booleans).
2. Variable declaration and assignment.
3. Basic input/output operations.
4. Sequential execution.
5. Functions
6. Threads

2. _As a user, I want to extend the environment's capabilities by installing plugins for specific toolkits, such as logic, art, music, and future extensions, allowing me to add only the features relevant to my project._

2. **Plugin Capabilities**

1. _As a user, I want plugins to extend the programming environment by adding new bricks and code constructs, providing access to specialized functionality tailored to specific domains._

2. _As a user, I want plugins to introduce their own output windows when necessary, enabling me to visualize or interact with results in a way that is appropriate for the specific domain (e.g., a graphical canvas for art, an audio player for music, a text console for logic)._

3. _As a user, I want plugins to provide custom widgets or wizards, which offer guided processes for generating blocks of functionality, simplifying the creation of complex or domain-specific code structures._

4. _As a user, I want plugins to expose specific configuration options, allowing me to fine-tune the behavior of the toolkit. For example:_

1. For a music plugin: setting the key signature, tempo, or available instruments.
2. For an art plugin: setting the coordinate system, background color, or default shape style.
3. For a logic plugin: setting the input/output format or enabling/disabling specific logical operators.
1. _As a user, I want the logic plugin to provide control flow structures (loops, conditionals)._

3. **Project Configuration**

1. _As a user, I want to configure which plugins are enabled for a specific project, ensuring that the environment includes only the necessary functionality and avoids unnecessary clutter._

2. _As a user, I want to control which functions or features are active within each plugin on a per-project basis, allowing for granular customization of functionality. This could involve:_

1. Enabling or disabling specific bricks or code constructs provided by the plugin.
2. Setting plugin-specific options that affect the behavior of its features.

3. _As a user, I want to configure toolkit-specific settings for each project, tailoring the environment precisely to the creative or logical goals of my program. This includes saving and loading configuration presets._

## 5. Project Management

1. **Create a New Project**

1. _As a user, I want to start a new project from scratch, so that I can begin working on a fresh program with a clean environment._
2. _As a user, I want to be able to name my new project._

2. **Load an Existing Project**

1. _As a user, I want to open a saved project, so that I can continue my previous work._
2. _As a user, I want to choose whether loading a project replaces my current one or merges with it, so that I can combine ideas or maintain continuity._
3. _As a user, when loading a project that replaces the current one, I want to be prompted to save my current project first, to prevent accidental data loss._
4. _As a user, when loading a project that merges with the current one, I want to be able to resolve any conflicts between the two projects (e.g., duplicate brick names, conflicting variable definitions) in a clear and intuitive way._

3. **Save Project to File**

1. _As a user, I want to save my project to a file, including all code and environment configurations, so that I can archive or share my work with complete context._
2. _As a user, I want to be able to save different versions of my project, so that I can track changes and revert to earlier states if needed._
3. _As a user, I want to save the code written in the text-based editor (when this feature is available), so that I can preserve both visual and textual representations of my program._
4. _As a user, I want the text-based editor code to be saved automatically along with the visual representation of the project, ensuring consistency between the two._

4. **Local Project Caching**

1. _As a user, I want the application to cache my current project locally, so that my work is automatically preserved across browser sessions even if I forget to save manually._
2. _As a user, I want to be notified when a project is successfully cached, so that I have confirmation that my work is being saved._
3. _As a user, I want to be able to manually trigger a cache save._

5. **Export Artifacts**

1. _As a user, I want to export my artwork as image files (PNG or SVG), so that I can use the visuals outside the program._
2. _As a user, I want to be able to select the resolution and quality of the exported image files._
3. _As a user, I want to export my music as an audio file (WAV), so that I can share or publish my compositions._
4. _As a user, I want to be able to choose the audio format (e.g., WAV, MP3) and quality settings (e.g., sample rate, bit depth) for the exported audio files._
5. _As a user, I want to export sheet music in multiple formats (ABC, Lilypond, MusicXML), so that I can print, edit, or import it into other notation tools._
6. _As a user, I want the sheet music export to accurately represent the musical notation of my composition, including notes, rhythms, and other musical symbols._
7. _As a user, I want to be able to export all the artifacts at once, or in batches._

6. **Save Project Bricks as SVG**

1. _As a user, I want to export the visual layout of my program bricks as an SVG, so that I can document or present the structure of my code._
2. _As a user, I want the exported SVG to accurately represent the arrangement, connections, and labels of the bricks in my program._
3. _As a user, I want to be able to customize the appearance of the exported SVG, such as the colors, fonts, and layout._
4. _As a user, I want to be able to export a high-resolution image of the bricks._

7. **Planet (Online Repository)**

1. _As a user, I want access to an online repository of projects called Planet, so that I can find, share, and reuse community creations._
2. _As a user, I want to search for projects by keyword and tags, so that I can discover relevant content quickly._
3. _As a user, I want version control for projects in Planet, so that I can track changes and revert if needed._
4. _As a user, I want to merge online projects from Planet with my current project, so that I can integrate external ideas or extensions._
5. _As a user, I want to be able to upload my own projects to Planet, so that I can share them with the community._
6. _As a user, I want to be able to rate and comment on projects in Planet, so that I can provide feedback and contribute to the community._
7. _As a user, I want to be able to organize projects with collections._

8. **Collaboration**

1. _As a user, I want to work on a project with other users collaboratively, so that we can build and improve a project together in real time or asynchronously._
2. _As a user, I want to be able to invite other users to collaborate on a project._
3. _As a user, I want to be able to see the changes made by other collaborators in real time._
4. _As a user, I want to be able to communicate with other collaborators through a chat feature._
5. _As a user, I want to be able to manage collaborator permissions._

## 6. Modes and Preferences

1. **Configurable Application Modes**

1. _As a user, I want to choose between different application modes based on my goals, so that the interface remains streamlined and relevant:_

1. **IDE Mode** - Full editing and execution capabilities for program development.

1. _As a user, I want access to all tools and features, including visual brick programming, text-based coding (if available), a comprehensive debugger, and the ability to run and test programs._

2. **Runtime-Only Mode** - Only runs prebuilt programs without any editing tools.

1. _As a user, I want a simplified interface focused on program execution, suitable for showcasing or deploying finished projects._
2. _As a user I want to be able to see the outputs of the program._

3. **Read-Only Mode** - View-only access to brick programs:

1. _As a user, I want to fold and unfold bricks to inspect program logic compactly or in detail, without the risk of accidental modification._
2. _As a user, I want to rearrange bricks visually without affecting the actual project, so I can explore structure freely and understand the program's flow._
3. _As a user, I want to be restricted from making changes in this mode to prevent unintended edits, with clear visual cues indicating the read-only status._

2. **Internationalization (Language Switching)**

1. _As a user, I want to change the application language, so that I can work in my preferred or native language._
2. _As a user, I want to see all user interface elements, including menus, labels, messages, and documentation, translated into the selected language._
3. _As a user, I want to be able to easily switch between available languages through a clear and accessible language selection menu._
4. _As a user, I want the application to remember my language preference across sessions._

3. **Fullscreen Toggle**

1. _As a user, I want to switch the application into fullscreen mode, so that I can focus better or present my work more cleanly._

4. **Guided Help and Examples**

1. _As a user, I want access to a guide that explains key UI components and features (such as buttons), so I can get familiar with the interface quickly._
2. _As a user, I want the guide to be interactive and context-sensitive, providing information relevant to the currently selected tool or area of the interface._
3. _As a user, I want to explore brick examples that show how various bricks can be used, so I can learn by example._
4. _As a user, I want the examples to be organized and searchable, allowing me to quickly find relevant code snippets or program structures._
5. _As a user, I want to load example brick programs into my workspace, so that I can experiment with and build upon existing logic._
6. _As a user, I want to see code-based examples once that functionality is implemented, so that I can understand textual equivalents and the relationship between visual and textual programming._

5. **Theme and Visual Preferences**

1. _As a user, I want to switch between light and dark themes (or others), so that I can work comfortably in different lighting conditions._
2. _As a user, I want the themes to apply consistently across all parts of the application, including the program editor, output windows, and menus._
3. _As a user, I want to change the color scheme of the interface, so that it matches my visual preference or improves readability._
4. _As a user, I want to be able to customize various color aspects of the UI, such as background colors, text colors, and accent colors._
5. _As a user, I want to be able to save and load custom color schemes._

6. **Potential Enhancements**

1. _As a user, I might want to adjust font size or interface scaling independently of brick scaling, for accessibility and comfort._
2. _As a user, I might want to have fine-grained control over font sizes for different UI elements, such as the editor, output windows, and menus._
3. _As a user, I might want to toggle tooltips or inline help, so that I can get contextual assistance without opening external documentation._
4. _As a user, I might want to control the verbosity of tooltips and inline help, choosing between brief explanations and more detailed information._
5. _As a user, I might want to pin or collapse panels (palette, output windows, etc.), so that I can customize the workspace layout and maximize screen space for the program I'm working on._
6. _As a user, I might want to be able to create and save custom layouts, arranging panels and windows to suit my specific workflow._