diff --git a/modules/masonry/docs/Masonry_Design_Document.md b/modules/masonry/docs/Masonry_Design_Document.md
deleted file mode 100644
index 78cc85e1..00000000
--- a/modules/masonry/docs/Masonry_Design_Document.md
+++ /dev/null
@@ -1,359 +0,0 @@
-
----
-
-# Music Blocks v4 : Masonry Design Document
-
-## Overview
-1. **Short Description of the Product**
- - The Masonry (previously called Project Builder) in Music Blocks v4 facilitates graphical brick-based music composition, offering various Brick types such as Start, Rhythm, Note, Pitch, and Instrument Bricks. Each brick represents a specific functionality, enabling users, especially children, to visually create music programs. The Masonry module simplifies the process of selecting and arranging bricks to generate music sequences.
-
-2. **Key Features**
- - Enhance the brick library with comprehensive functionalities and render the stack of bricks.
- - Implement collision detection and enhance the user interface for a seamless user experience.
- - Add text to bricks (SVGs) for customization and personalization.
- - Introduce a palette feature, allowing for effortless music composition through intuitive drag-and-drop functionality.
- - Integrate Music Blocks v4 with Masonry to streamline music program creation.
- - Address bugs and make overall improvements to enhance the tool's performance and usability.
-
-3. **Main User Activities**
- - Interacting with the bricks using the palette.
- - Composing music using visual programming bricks/stack of bricks.
- - Editing music sequences dynamically.
-
-4. **Subsystems**
- - Palette Subsystem: Manages the palette interface within Music Blocks, providing a selection of bricks for users to drag and drop into the workspace.
- - Workspace Subsystem: Controls the workspace area where users can arrange bricks and create music compositions.
- - Brick Stack Subsystem: Handles the creation and management of stacks of bricks within the workspace, allowing users to combine bricks to form musical sequences.
- - Collision Detection Subsystem: Implements collision detection functionality within the workspace, ensuring that bricks interact appropriately to prevent overlapping or conflicting arrangements.
-
-5. **Additional Functionality and Design**
- - Implementation of a MusicBlocks guide button at the top of the interface for user convenience.
- - Integration of a collision detection UI inspired by the Brickly game by Google, enhancing user experience and interaction feedback.
- - Optimization of the palette by combining similar types of bricks, reducing clutter and improving usability.
- - Enhancement of the search functionality to facilitate easier navigation and selection of bricks within the palette.
-
-6. **Purpose**
- - The purpose of this document is to outline the design and architecture of Masonry framework for Music Blocks v4
-
-7. **Scope**
- - This document covers the technical details and design considerations of Music Blocks v4, including its features and subsystems.
-
-8. **Audience**
- - The intended audience includes developers, contributors, and members involved in the development and maintenance of Music Blocks v4.
-
-9. **Definitions and Abbreviations**
- - **Masonry:** The term used to describe the replication and enhancement of the functionality related to bricks from the palette, stack of bricks, and other related components of the project, aimed at improving their functionality and effectiveness.
-
-[Screencast from 13-05-24 12:15:30 PM IST.webm](https://github.com/Karan-Palan/musicblocks-v4/assets/143683619/ae9df412-8b3a-4930-8635-ad89da828ba9)
-
-10. **References**
- - [Link to Music Blocks v3 project](https://github.com/sugarlabs/musicblocks)
- - [Link to Masonry Framework](https://github.com/sugarlabs/musicblocks-v4/tree/develop/modules/code-builder)
-
-## Requirements, Wiki Storages and Docs
-1. **Requirements**
- - Functional requirements: Dynamic editing, text addition, UI enhancements, palette feature, integration with Music Blocks v4 project.
- - Non-functional requirements: Performance, scalability, maintainability.
-
-2. **Wiki Storages**
- - [Link to project documentation](https://github.com/sugarlabs/musicblocks/blob/master/guide/README.md)
-
-4. **Docs and Responsible Entities**
- - Documentation maintained by project contributors.
- - Responsible entities: Project maintainers, contributors.
-
-5. **Roles, Responsibilities, and Assumptions**
- - Roles: Developers, contributors, project maintainers.
- - Responsibilities: Implementing features, reviewing code, documenting changes.
- - Assumptions: Basic understanding of React, JavaScript/TypeScript, and information about Music Blocks software.
-
-## Architecture and Requirements Diagram
-To be added
-
-## Design Specification
-
-#### 1. Workspace:
- - Canvas Area:
- - Large central area for creating and manipulating musical compositions
- - Resizable canvas to accommodate compositions of varying sizes
- - Optional background grid or ruled lines for precise Brick placement
-
- - Grid System:
- - Configurable grid spacing and subdivisions
- - Snap-to-grid functionality for aligning Bricks to grid lines
- - Visual indicators (e.g., dotted lines, highlights) for grid lines and snap points
-
- - Staff Rendering:
- - Multiple staff lines for representing different instruments or voices
- - Customizable staff parameters (number of lines, clef, key signature, time signature)
- - Dynamic staff layout and spacing based on the composition's content
-
- - Brick Connections:
- - Visual representation of connections between Bricks (e.g., lines, curves, bezier paths)
- - Color-coding or highlighting for different connection types or data flows
- - Animated transitions or visual cues when establishing or breaking connections
-
- - Visual Feedback:
- - Error indicators (e.g., red outlines, warning icons) for invalid Brick placements or connections
- - Compatibility indicators (e.g., green highlights) for valid Brick combinations
- - Tooltips or popups for providing additional information or guidance
-
- - Navigation and Viewing:
- - Panning and scrolling functionality for navigating large compositions
- - Zoom controls for adjusting the workspace scale and level of detail
- - Minimap or overview panel for a bird's-eye view of the entire composition
-
- - Workspace Customization:
- - Options to hide or show grid lines, staff lines, or other visual aids
- - Configurable workspace background color or theme
- - Ability to save and load workspace layouts or configurati
-
-#### 2. Palette:
- - Layout and Organization:
- - Collapsible/expandable categories or sections for different Brick types
- - Customizable order and arrangement of categories
- - Visual separators or dividers between categories
-
- - Brick Previews:
- - Thumbnail or icon previews for each Brick within a category
- - Tooltips or pop-ups displaying Brick names and brief descriptions
- - Color-coding or visual cues for distinguishing different Brick types
-
- - Search and Filtering:
- - Search bar or input field for locating specific Bricks by name or keyword
- - Filter options for narrowing down Bricks based on category, type, or properties
- - Live search results or suggestions as the user types
-
- - Drag and Drop:
- - Ability to drag and drop Bricks from the palette onto the workspace
- - Visual indicators (e.g., ghost preview, outline) for valid drop locations
- - Snap-to-grid or precise positioning when dropping Bricks
-
- - Brick Creation:
- - Options for creating new Bricks or Brick instances directly from the palette
- - Context menus or shortcuts for duplicating or cloning existing Bricks
- - Visual feedback or animations when creating or instantiating new Bricks
-
- - Customization:
- - User-defined categories or custom groupings for organizing Bricks
- - Ability to rename, reorder, or hide/show specific categories
- - Import/export functionality for sharing or backing up custom palette configurations
-
- - Palette Behavior:
- - Dockable or floating palette panel for flexible positioning
- - Resizable palette window or panel for adjusting its size
- - Auto-hide or collapse functionality for maximizing workspace area
-
-#### 3. Bricks:
- - Shape and Appearance:
- - Distinct geometric shapes (rectangles, circles, hexagons) for different Brick categories
- - Color schemes and palettes for visually differentiating Brick types
- - Textured or patterned backgrounds for certain Brick categories (e.g., control structures)
-
- - Brick Labels and Icons:
- - Clear and concise text labels describing the Brick's function
- - Intuitive icons or symbols representing the Brick's purpose
- - Customizable font styles, sizes, and colors for labels and icons
-
- - Input/Output Ports:
- - Shaped ports or connectors for linking Bricks together
- - Color-coding or visual cues for indicating compatible port types
- - Tooltips or labels explaining the purpose and data type of each port
-
- - Brick Parameters:
- - Editable fields within Bricks for adjusting parameters (e.g., note values, durations)
- - Drop-down menus or selectors for choosing from predefined parameter options
- - Visual indicators like sliders, knobs, or dials for continuous parameter adjustments
-
- - Resizing and Scaling:
- - Resize handles (corners, edges) for adjusting Brick dimensions
- - Proportional scaling or aspect ratio locking options
- - Dynamic scaling of Brick contents (text, icons) during resizing
-
- - Rotation and Flipping:
- - Rotation handles or controls for changing Brick orientation
- - Flip or mirror functionality for reversing Brick placement
- - Snap-to-angle or constrained rotation options (e.g., 90-degree increments)
-
- - Cloning and Duplication:
- - Duplicate or clone functionality for creating copies of existing Bricks
- - Visual previews or ghosted outlines for cloned Brick instances
- - Options for shallow cloning (duplicating the Brick) or deep cloning (including nested Bricks)
-
- - Advanced Editing:
- - Context menus or dedicated editors for advanced Brick customization
- - Visual indicators or badges for displaying Brick metadata (e.g., unique IDs)
- - Color-coding or visual cues for distinguishing different Brick states or modes
-
-#### 4. Brick Connections:
- - Connection Styles:
- - Various visual styles for rendering connections (straight lines, curves, bezier paths)
- - Customizable line thickness, colors, and patterns for different connection types
- - Animated transitions or visual effects when establishing or breaking connections
-
- - Connection Routing:
- - Automatic routing algorithms for avoiding overlaps and minimizing crossed connections
- - Manual routing options for overriding automatic layouts
- - Visual guides or markers for assisting with precise connection routing
-
- - Connection Labels:
- - Ability to add labels or annotations along connections
- - Customizable label styles (font, color, background) for different connection types
- - Positioning options for labels (centered, aligned to start/end)
-
- - Data Flow Visualization:
- - Visual indicators or animations for showing data flow direction along connections
- - Color-coding or highlighting for different data types or flows
- - Tooltips or pop-ups for displaying data values or previews
-
- - Connection Validation:
- - Visual feedback for valid and invalid connections (e.g., green/red highlights)
- - Error messages or tooltips explaining incompatible connections
- - Ability to temporarily disable validation for advanced use cases
-
- - Connection Editing:
- - Options for rerouting, splitting, or merging connections
- - Context menus or shortcuts for quickly editing connection properties
- - Undo/redo functionality for connection editing operations
-
- - Connection Grouping:
- - Ability to group multiple connections together for better organization
- - Visual boundaries or outlines for defining connection groups
- - Collapsible or expandable groups for managing complexity
-
-#### 5. Collision Detection and Snapping:
- - Brick Bounding Boxes:
- - Visual representations of Brick bounding boxes or hit areas
- - Configurable padding or margins around Brick boundaries
- - Color-coding or highlighting of bounding boxes for debugging or visualization
-
- - Proximity Detection:
- - Visual indicators or highlights when Bricks are within a specified proximity
- - Adjustable proximity thresholds or ranges for different snapping behaviors
- - Tooltips or pop-ups displaying the current proximity distance
-
- - Snap-to-Grid:
- - Visual guides or markers for grid lines and snap points
- - Configurable grid spacing and subdivision settings
- - Adjustable snapping strength or magnetic attraction to the grid
-
- - Snap-to-Brick:
- - Alignment guides or visual cues for snapping Bricks to other Brick edges or centers
- - Customizable snapping priorities (e.g., snap to centers first, then edges)
- - Temporary visual previews of snapped positions before releasing the Brick
-
- - Snap-to-Connection:
- - Visual indicators or highlights for compatible connection points between Bricks
- - Automatic connection establishment when Bricks are snapped together
- - Animations or visual effects during the snapping and connection process
-
- - Overlap Prevention:
- - Visual feedback or error indicators for overlapping or invalid Brick placements
- - Automatic repositioning or nudging of Bricks to avoid overlaps
- - User-defined rules or constraints for allowing or preventing Brick overlaps
-
- - Snapping Customization:
- - Options to enable or disable specific snapping behaviors (grid, Brick, connection)
- - User-defined snapping preferences or profiles
- - Import/export functionality for sharing custom snapping configurations
-
-#### 6. Brick Editing and Customization:
- - Inline Editing:
- - Editable text fields within Bricks for modifying labels, values, or parameters
- - Visual indicators or highlights for active inline editing mode
- - Validation and error feedback for invalid inputs or out-of-range values
-
- - Drop-down Menus:
- - Drop-down lists or selectors within Bricks for choosing from predefined options
- - Customizable visual styles (fonts, colors, icons) for drop-down menu items
- - Tooltips or previews for displaying additional information about each option
-
- - Context Menus:
- - Right-click or long-press context menus for accessing Brick-specific actions
- - Hierarchical or nested menus for organizing related actions and options
- - Keyboard shortcuts or mnemonics for quick access to frequently used actions
-
- - Dedicated Editors:
- - Modal dialogs or dedicated panels for advanced Brick customization
- - Visual editing interfaces (e.g., piano roll, rhythm editors) for specialized parameters
- - Undo/redo functionality within dedicated editors for tracking changes
-
- - Undo/Redo Indicators:
- - Visual indicators or badges for displaying the current undo/redo state
- - Animations or visual effects when undoing or redoing Brick editing actions
- - Tooltips or pop-ups showing a preview of the undo/redo operation
-
-#### 7. Musical Notation Rendering:
- - Notation Styles:
- - Traditional staff notation with notes, rests, and other musical symbols
- - Alternative representations like piano roll, guitar tablature, or custom notations
- - Customizable notation styles (fonts, colors, line spacing) for different instruments
-
- - Real-time Updates:
- - Synchronized updates to the notation as Bricks are added, removed, or modified
- - Smooth transitions or animations when updating the notation
- - Visual indicators or highlights for recently changed or updated notation elements
-
- - Notation Switching:
- - Options or controls for switching between different notation styles or views
- - Visual previews or thumbnails of each notation style for easy identification
- - Customizable keyboard shortcuts or hotkeys for quickly switching notations
-
- - Notation Overlays:
- - Ability to overlay multiple notation styles or representations simultaneously
- - Visual separators or dividers between different notation layers
- - Customizable transparency or opacity settings for each notation layer
-
- - Playback Integration:
- - Synchronized highlighting or animations within the notation during audio playback
- - Visual indicators or markers for the current playback position
- - Customizable playback cursors or beat markers for different notation styles
-
-#### 8. Audio Playback and Visualization:
- - Playback Controls:
- - Intuitive play, pause, stop, and seek buttons or controls
- - Visual feedback for playback state (playing, paused, stopped)
- - Seek bar or timeline for navigating through the composition
-
- - Audio Visualizations:
- - Synchronized visualizations like piano roll, waveform, or custom graphical representations
- - Configurable visualization styles (colors, themes, rendering modes)
- - Visual indicators or animations synchronized with the audio playback
-
- - Instrument Selection:
- - Visual representations (icons, thumbnails) for different instrument sounds
- - Categorization or grouping of instruments (e.g., by family, genre)
- - Tooltips or previews for auditioning instrument sounds
-
- - Playback Overlays:
- - Ability to overlay multiple visualizations or instrument views simultaneously
- - Visual separators or dividers between different overlay layers
- - Customizable transparency or opacity settings for each overlay layer
-
-#### 9. User Interface and Interactions:
- - Responsive Layout:
- - Adaptive and responsive design for different screen sizes and resolutions
- - Automatic layout adjustments and reflow for optimal viewing experience
- - Optional full-screen or immersive mode for maximizing workspace area
-
- - Keyboard Shortcuts:
- - Visual indicators or tooltips for available keyboard shortcuts and hotkeys
- - Customizable keyboard shortcut mappings and assignments
- - Conflict resolution or priority handling for overlapping shortcut combinations
-
- - Toolbars and Menus:
- - Configurable toolbars and menus for quick access to frequently used features
- - Customizable toolbar and menu layouts (docking, floating, auto-hide)
- - Visual indicators or badges for displaying tool states or modes
-
- - Themes and Customization:
- - Predefined color themes and visual styles for different preferences
- - Customizable color schemes, font styles, and icon sets
- - Import/export functionality for sharing custom theme configurations
-
- - Accessibility:
- - High-contrast mode or themes for improved visibility
- - Screen reader support and appropriate labeling for accessibility
- - Adjustable font sizes and zoom levels for better readability
-
----
diff --git a/modules/masonry/docs/PRD.md b/modules/masonry/docs/PRD.md
deleted file mode 100644
index d35c7609..00000000
--- a/modules/masonry/docs/PRD.md
+++ /dev/null
@@ -1,147 +0,0 @@
-
-# Product Requirements Document (PRD): Masonry Framework
-
-## 1. Bricks
-
-### a. Brick Types
-
-#### 1. Data Bricks: These serve as inputs for other bricks and come in two types: hardcoded and editable.
- - Hardcoded Data Brick: Fixed values that cannot be changed by the user. Examples include predefined note values, counts, etc.
-
- ![alt text](./images/image.png)
- - Editable Data Brick: Values that can be modified by the user. When clicked, these bricks open a text editor or a dropdown menu for user input, allowing customization of note names, pitches, etc.
-
- ![editable bricks](./images/image-1.png)
-
-
-
-#### 2. Expression Bricks: Takes values as input, returns a value as output.
-
- ![alt text](./images/image-2.png)
-
-#### 3. Statement Bricks: These define actions to be taken.
-
- ![example](./images/image-3.png)
-
-#### 4. Block Bricks: Contain nesting, also execute something like the statement bricks. Takes 0 or more arguments.
-
- ![alt text](./images/image-14.png)
-
-### b. Brick Appearance
- - **Distinct Shapes**: Each brick type has a unique shape to differentiate its function visually.
- - **Colors**:
- 1. **Original Color**: Each brick has a unique color that represents its type.
- 2. **Hover Color**: When a user hovers over a brick, it changes to a distinct color to indicate it is selectable.
- 3. **Disconnected Color**: If a brick is not connected to the stack, it turns gray to indicate it is inactive.
- 4. **Execution Color**: When a brick is executed, it changes to a darker shade of its original color to show that it has been activated.
- - **Sprites**: Visual symbols that indicate specific functions or properties of the brick. Some bricks may have sprites (like the start brick), while others may not.
- - **Labels**:
- 1. **Functionality Labels**: Text labels that indicate the function of the brick.
- 2. **Argument Labels**: Text labels that indicate the arguments or parameters that need to be provided for the brick's function.
- - **Input/Output Ports**: Connectors that visually represent where bricks can attach to each other.
- - **Editable Text Labels/Fields**: Users can input data directly into the bricks, such as note names, durations, and numerical values.
-
- **Side Note:** If we want to implement a design similar to Scratch in the future, we can consider the following approach for connecting blocks:
- - In Scratch, blocks are connected horizontally in a row for sequential execution. Each block has a tab at the bottom and a notch at the top, allowing them to snap together in a linear sequence. This design makes it clear which blocks will execute in order.
-
-### c. Brick Interactions
- - **Inline Text Editing**: Users can click on text fields within bricks to edit labels and values directly.
- - Some bricks only open an inline text editor when clicked.
-
-
- ![inline text editing](./images/image-4.png)
-
-
- - Other bricks open both an inline text editor and a context menu for additional options.
-
- ![inline text editor with context menu](./images/image-15.png)
- - **Context Menus**: For more complex properties, a separate interface allows detailed configuration.
-
- ![dedicated editors](./images/image-5.png)
- - **Connection Types**:
- 1. **Argument Connections**: Bricks can be connected to input arguments of other bricks. This allows for passing data or parameters into the brick’s function.
- 2. **Brick-to-Brick or Stack Connections**: Bricks can be connected directly to other bricks or to a stack of bricks. This enables building complex sequences and structures by chaining bricks together.
-
- ![alt text](./images/image-8.png)
-
-
-
-
-## 2. Stack of Bricks
-
-### a. Stack Validation:
- - **Visual Feedback**: Indicators show whether brick combinations are valid.
-
- ![alt text](./images/image-6.png)
-
- - **Error Indicators**: Explanations for incompatible connections help users troubleshoot.
- - Add a reddish boundary for users to easily tell whether the bricks are mergeable or not.
-
- ![alt text](./images/image-7.png)
-
-
- - **Disable Validation**: Temporarily turn off validation for complex or experimental setups.
-
-
- **Note** - this is up for further discussion
-
-### b. Stack Editing:
- - **Connection Editing**: Options for re-positioning, disconnecting, or connecting.
- - **Quick Edit Shortcuts**: Context menus or keyboard shortcuts speed up editing.
-
-### c. Stack Grouping:
- - **Collapsible Groups**: Groups can be collapsed or expanded to manage complexity.
-
- ![alt text](./images/image-9.png)
-
-
-## 3. Palette:
-### a. **Layout and Organization**:
- - Collapsible/expandable categories or sections for different Brick types
- - Visual separators or dividers between categories
- - Customizable order and arrangement of categories
-
-
- ![alt text](./images/image-10.png)
-
-### b. **Brick Previews**:
- - Tooltips or pop-ups displaying Brick names and brief descriptions
-
- ![alt text](./images/image-16.png)
-
- - Color-coding or visual cues for distinguishing different Brick types
-
-### c. **Search and Filtering**:
- - Search bar or input field for locating specific Bricks by name or keyword
- - Filter options for narrowing down Bricks based on category, type, or properties
- - Live search results or suggestions as the user types
- - Searchbar in Musicblocks as of now:
-
- ![alt text](./images//image-11.png)
-
- - Searchbar design to be implemented:
-
- ![alt text](./images/image-17.png)
- The idea here is to have a fixed searchbar on the left side of the workspace through which users can search for bricks, group them etc.
- Note - It is just a one big list and categories on the left are positions on the list.
-
-### d. **Drag and Drop**:
- - Ability to drag and drop Bricks from the palette onto the workspace.
- - Visual indicators (e.g., ghost preview, outline) for valid drop locations.
-
-
- ![drag and drop](./images/image-12.png)
-
- - While dragging a brick from the palette, the brick should temporarily disappear from the palette until it is placed in the workspace.
-
-
-## 4. Workspace:
-
-
-![alt text](./images/image-13.png)
-
-
- - **Cloning/Duplication**: Users can easily create copies of bricks for repeated use.
- - **Scaling and Rotation**: Bricks can be resized and rotated to fit the workspace better.
- - **Undo/Redo**: Users can revert or reapply changes to their stacks.
- - **Removal/Deletion of Bricks** : Users can remove/delete bricks
\ No newline at end of file
diff --git a/modules/masonry/docs/PRD/Masonry_Design_Document.md b/modules/masonry/docs/PRD/Masonry_Design_Document.md
new file mode 100644
index 00000000..b73c2c2d
--- /dev/null
+++ b/modules/masonry/docs/PRD/Masonry_Design_Document.md
@@ -0,0 +1,372 @@
+
+---
+
+# Music Blocks v4 : Masonry Design Document
+
+## Overview
+
+1. **Short Description of the Product**
+ - The Masonry (previously called Project Builder) in Music Blocks v4 facilitates graphical brick-based music composition, offering various Brick types such as Start, Rhythm, Note, Pitch, and Instrument Bricks. Each brick represents a specific functionality, enabling users, especially children, to visually create music programs. The Masonry module simplifies the process of selecting and arranging bricks to generate music sequences.
+
+2. **Key Features**
+ - Enhance the brick library with comprehensive functionalities and render the stack of bricks.
+ - Implement collision detection and enhance the user interface for a seamless user experience.
+ - Add text to bricks (SVGs) for customization and personalization.
+ - Introduce a palette feature, allowing for effortless music composition through intuitive drag-and-drop functionality.
+ - Integrate Music Blocks v4 with Masonry to streamline music program creation.
+ - Address bugs and make overall improvements to enhance the tool's performance and usability.
+
+3. **Main User Activities**
+ - Interacting with the bricks using the palette.
+ - Composing music using visual programming bricks/stack of bricks.
+ - Editing music sequences dynamically.
+
+4. **Subsystems**
+ - Palette Subsystem: Manages the palette interface within Music Blocks, providing a selection of bricks for users to drag and drop into the workspace.
+ - Workspace Subsystem: Controls the workspace area where users can arrange bricks and create music compositions.
+ - Brick Stack Subsystem: Handles the creation and management of stacks of bricks within the workspace, allowing users to combine bricks to form musical sequences.
+ - Collision Detection Subsystem: Implements collision detection functionality within the workspace, ensuring that bricks interact appropriately to prevent overlapping or conflicting arrangements.
+
+5. **Additional Functionality and Design**
+ - Implementation of a MusicBlocks guide button at the top of the interface for user convenience.
+ - Integration of a collision detection UI inspired by the Brickly game by Google, enhancing user experience and interaction feedback.
+ - Optimization of the palette by combining similar types of bricks, reducing clutter and improving usability.
+ - Enhancement of the search functionality to facilitate easier navigation and selection of bricks within the palette.
+
+6. **Purpose**
+ - The purpose of this document is to outline the design and architecture of Masonry framework for Music Blocks v4
+
+7. **Scope**
+ - This document covers the technical details and design considerations of Music Blocks v4, including its features and subsystems.
+
+8. **Audience**
+ - The intended audience includes developers, contributors, and members involved in the development and maintenance of Music Blocks v4.
+
+9. **Definitions and Abbreviations**
+ - **Masonry:** The term used to describe the replication and enhancement of the functionality related to bricks from the palette, stack of bricks, and other related components of the project, aimed at improving their functionality and effectiveness.
+
+[Screencast from 13-05-24 12:15:30 PM IST.webm](https://github.com/Karan-Palan/musicblocks-v4/assets/143683619/ae9df412-8b3a-4930-8635-ad89da828ba9)
+
+10. **References**
+
+- [Link to Music Blocks v3 project](https://github.com/sugarlabs/musicblocks)
+- [Link to Masonry Framework](https://github.com/sugarlabs/musicblocks-v4/tree/develop/modules/code-builder)
+
+## Requirements, Wiki Storages and Docs
+
+1. **Requirements**
+ - Functional requirements: Dynamic editing, text addition, UI enhancements, palette feature, integration with Music Blocks v4 project.
+ - Non-functional requirements: Performance, scalability, maintainability.
+
+2. **Wiki Storages**
+ - [Link to project documentation](https://github.com/sugarlabs/musicblocks/blob/master/guide/README.md)
+
+4. **Docs and Responsible Entities**
+ - Documentation maintained by project contributors.
+ - Responsible entities: Project maintainers, contributors.
+
+5. **Roles, Responsibilities, and Assumptions**
+ - Roles: Developers, contributors, project maintainers.
+ - Responsibilities: Implementing features, reviewing code, documenting changes.
+ - Assumptions: Basic understanding of React, JavaScript/TypeScript, and information about Music Blocks software.
+
+## Architecture and Requirements Diagram
+
+To be added
+
+## Design Specification
+
+#### 1. Workspace
+
+- Canvas Area:
+ - Large central area for creating and manipulating musical compositions
+ - Resizable canvas to accommodate compositions of varying sizes
+ - Optional background grid or ruled lines for precise Brick placement
+
+- Grid System:
+ - Configurable grid spacing and subdivisions
+ - Snap-to-grid functionality for aligning Bricks to grid lines
+ - Visual indicators (e.g., dotted lines, highlights) for grid lines and snap points
+
+- Staff Rendering:
+ - Multiple staff lines for representing different instruments or voices
+ - Customizable staff parameters (number of lines, clef, key signature, time signature)
+ - Dynamic staff layout and spacing based on the composition's content
+
+- Brick Connections:
+ - Visual representation of connections between Bricks (e.g., lines, curves, bezier paths)
+ - Color-coding or highlighting for different connection types or data flows
+ - Animated transitions or visual cues when establishing or breaking connections
+
+- Visual Feedback:
+ - Error indicators (e.g., red outlines, warning icons) for invalid Brick placements or connections
+ - Compatibility indicators (e.g., green highlights) for valid Brick combinations
+ - Tooltips or popups for providing additional information or guidance
+
+- Navigation and Viewing:
+ - Panning and scrolling functionality for navigating large compositions
+ - Zoom controls for adjusting the workspace scale and level of detail
+ - Minimap or overview panel for a bird's-eye view of the entire composition
+
+- Workspace Customization:
+ - Options to hide or show grid lines, staff lines, or other visual aids
+ - Configurable workspace background color or theme
+ - Ability to save and load workspace layouts or configurati
+
+#### 2. Palette
+
+- Layout and Organization:
+ - Collapsible/expandable categories or sections for different Brick types
+ - Customizable order and arrangement of categories
+ - Visual separators or dividers between categories
+
+- Brick Previews:
+ - Thumbnail or icon previews for each Brick within a category
+ - Tooltips or pop-ups displaying Brick names and brief descriptions
+ - Color-coding or visual cues for distinguishing different Brick types
+
+- Search and Filtering:
+ - Search bar or input field for locating specific Bricks by name or keyword
+ - Filter options for narrowing down Bricks based on category, type, or properties
+ - Live search results or suggestions as the user types
+
+- Drag and Drop:
+ - Ability to drag and drop Bricks from the palette onto the workspace
+ - Visual indicators (e.g., ghost preview, outline) for valid drop locations
+ - Snap-to-grid or precise positioning when dropping Bricks
+
+- Brick Creation:
+ - Options for creating new Bricks or Brick instances directly from the palette
+ - Context menus or shortcuts for duplicating or cloning existing Bricks
+ - Visual feedback or animations when creating or instantiating new Bricks
+
+- Customization:
+ - User-defined categories or custom groupings for organizing Bricks
+ - Ability to rename, reorder, or hide/show specific categories
+ - Import/export functionality for sharing or backing up custom palette configurations
+
+- Palette Behavior:
+ - Dockable or floating palette panel for flexible positioning
+ - Resizable palette window or panel for adjusting its size
+ - Auto-hide or collapse functionality for maximizing workspace area
+
+#### 3. Bricks
+
+- Shape and Appearance:
+ - Distinct geometric shapes (rectangles, circles, hexagons) for different Brick categories
+ - Color schemes and palettes for visually differentiating Brick types
+ - Textured or patterned backgrounds for certain Brick categories (e.g., control structures)
+
+- Brick Labels and Icons:
+ - Clear and concise text labels describing the Brick's function
+ - Intuitive icons or symbols representing the Brick's purpose
+ - Customizable font styles, sizes, and colors for labels and icons
+
+- Input/Output Ports:
+ - Shaped ports or connectors for linking Bricks together
+ - Color-coding or visual cues for indicating compatible port types
+ - Tooltips or labels explaining the purpose and data type of each port
+
+- Brick Parameters:
+ - Editable fields within Bricks for adjusting parameters (e.g., note values, durations)
+ - Drop-down menus or selectors for choosing from predefined parameter options
+ - Visual indicators like sliders, knobs, or dials for continuous parameter adjustments
+
+- Resizing and Scaling:
+ - Resize handles (corners, edges) for adjusting Brick dimensions
+ - Proportional scaling or aspect ratio locking options
+ - Dynamic scaling of Brick contents (text, icons) during resizing
+
+- Rotation and Flipping:
+ - Rotation handles or controls for changing Brick orientation
+ - Flip or mirror functionality for reversing Brick placement
+ - Snap-to-angle or constrained rotation options (e.g., 90-degree increments)
+
+- Cloning and Duplication:
+ - Duplicate or clone functionality for creating copies of existing Bricks
+ - Visual previews or ghosted outlines for cloned Brick instances
+ - Options for shallow cloning (duplicating the Brick) or deep cloning (including nested Bricks)
+
+- Advanced Editing:
+ - Context menus or dedicated editors for advanced Brick customization
+ - Visual indicators or badges for displaying Brick metadata (e.g., unique IDs)
+ - Color-coding or visual cues for distinguishing different Brick states or modes
+
+#### 4. Brick Connections
+
+- Connection Styles:
+ - Various visual styles for rendering connections (straight lines, curves, bezier paths)
+ - Customizable line thickness, colors, and patterns for different connection types
+ - Animated transitions or visual effects when establishing or breaking connections
+
+- Connection Routing:
+ - Automatic routing algorithms for avoiding overlaps and minimizing crossed connections
+ - Manual routing options for overriding automatic layouts
+ - Visual guides or markers for assisting with precise connection routing
+
+- Connection Labels:
+ - Ability to add labels or annotations along connections
+ - Customizable label styles (font, color, background) for different connection types
+ - Positioning options for labels (centered, aligned to start/end)
+
+- Data Flow Visualization:
+ - Visual indicators or animations for showing data flow direction along connections
+ - Color-coding or highlighting for different data types or flows
+ - Tooltips or pop-ups for displaying data values or previews
+
+- Connection Validation:
+ - Visual feedback for valid and invalid connections (e.g., green/red highlights)
+ - Error messages or tooltips explaining incompatible connections
+ - Ability to temporarily disable validation for advanced use cases
+
+- Connection Editing:
+ - Options for rerouting, splitting, or merging connections
+ - Context menus or shortcuts for quickly editing connection properties
+ - Undo/redo functionality for connection editing operations
+
+- Connection Grouping:
+ - Ability to group multiple connections together for better organization
+ - Visual boundaries or outlines for defining connection groups
+ - Collapsible or expandable groups for managing complexity
+
+#### 5. Collision Detection and Snapping
+
+- Brick Bounding Boxes:
+ - Visual representations of Brick bounding boxes or hit areas
+ - Configurable padding or margins around Brick boundaries
+ - Color-coding or highlighting of bounding boxes for debugging or visualization
+
+- Proximity Detection:
+ - Visual indicators or highlights when Bricks are within a specified proximity
+ - Adjustable proximity thresholds or ranges for different snapping behaviors
+ - Tooltips or pop-ups displaying the current proximity distance
+
+- Snap-to-Grid:
+ - Visual guides or markers for grid lines and snap points
+ - Configurable grid spacing and subdivision settings
+ - Adjustable snapping strength or magnetic attraction to the grid
+
+- Snap-to-Brick:
+ - Alignment guides or visual cues for snapping Bricks to other Brick edges or centers
+ - Customizable snapping priorities (e.g., snap to centers first, then edges)
+ - Temporary visual previews of snapped positions before releasing the Brick
+
+- Snap-to-Connection:
+ - Visual indicators or highlights for compatible connection points between Bricks
+ - Automatic connection establishment when Bricks are snapped together
+ - Animations or visual effects during the snapping and connection process
+
+- Overlap Prevention:
+ - Visual feedback or error indicators for overlapping or invalid Brick placements
+ - Automatic repositioning or nudging of Bricks to avoid overlaps
+ - User-defined rules or constraints for allowing or preventing Brick overlaps
+
+- Snapping Customization:
+ - Options to enable or disable specific snapping behaviors (grid, Brick, connection)
+ - User-defined snapping preferences or profiles
+ - Import/export functionality for sharing custom snapping configurations
+
+#### 6. Brick Editing and Customization
+
+- Inline Editing:
+ - Editable text fields within Bricks for modifying labels, values, or parameters
+ - Visual indicators or highlights for active inline editing mode
+ - Validation and error feedback for invalid inputs or out-of-range values
+
+- Drop-down Menus:
+ - Drop-down lists or selectors within Bricks for choosing from predefined options
+ - Customizable visual styles (fonts, colors, icons) for drop-down menu items
+ - Tooltips or previews for displaying additional information about each option
+
+- Context Menus:
+ - Right-click or long-press context menus for accessing Brick-specific actions
+ - Hierarchical or nested menus for organizing related actions and options
+ - Keyboard shortcuts or mnemonics for quick access to frequently used actions
+
+- Dedicated Editors:
+ - Modal dialogs or dedicated panels for advanced Brick customization
+ - Visual editing interfaces (e.g., piano roll, rhythm editors) for specialized parameters
+ - Undo/redo functionality within dedicated editors for tracking changes
+
+- Undo/Redo Indicators:
+ - Visual indicators or badges for displaying the current undo/redo state
+ - Animations or visual effects when undoing or redoing Brick editing actions
+ - Tooltips or pop-ups showing a preview of the undo/redo operation
+
+#### 7. Musical Notation Rendering
+
+- Notation Styles:
+ - Traditional staff notation with notes, rests, and other musical symbols
+ - Alternative representations like piano roll, guitar tablature, or custom notations
+ - Customizable notation styles (fonts, colors, line spacing) for different instruments
+
+- Real-time Updates:
+ - Synchronized updates to the notation as Bricks are added, removed, or modified
+ - Smooth transitions or animations when updating the notation
+ - Visual indicators or highlights for recently changed or updated notation elements
+
+- Notation Switching:
+ - Options or controls for switching between different notation styles or views
+ - Visual previews or thumbnails of each notation style for easy identification
+ - Customizable keyboard shortcuts or hotkeys for quickly switching notations
+
+- Notation Overlays:
+ - Ability to overlay multiple notation styles or representations simultaneously
+ - Visual separators or dividers between different notation layers
+ - Customizable transparency or opacity settings for each notation layer
+
+- Playback Integration:
+ - Synchronized highlighting or animations within the notation during audio playback
+ - Visual indicators or markers for the current playback position
+ - Customizable playback cursors or beat markers for different notation styles
+
+#### 8. Audio Playback and Visualization
+
+- Playback Controls:
+ - Intuitive play, pause, stop, and seek buttons or controls
+ - Visual feedback for playback state (playing, paused, stopped)
+ - Seek bar or timeline for navigating through the composition
+
+- Audio Visualizations:
+ - Synchronized visualizations like piano roll, waveform, or custom graphical representations
+ - Configurable visualization styles (colors, themes, rendering modes)
+ - Visual indicators or animations synchronized with the audio playback
+
+- Instrument Selection:
+ - Visual representations (icons, thumbnails) for different instrument sounds
+ - Categorization or grouping of instruments (e.g., by family, genre)
+ - Tooltips or previews for auditioning instrument sounds
+
+- Playback Overlays:
+ - Ability to overlay multiple visualizations or instrument views simultaneously
+ - Visual separators or dividers between different overlay layers
+ - Customizable transparency or opacity settings for each overlay layer
+
+#### 9. User Interface and Interactions
+
+- Responsive Layout:
+ - Adaptive and responsive design for different screen sizes and resolutions
+ - Automatic layout adjustments and reflow for optimal viewing experience
+ - Optional full-screen or immersive mode for maximizing workspace area
+
+- Keyboard Shortcuts:
+ - Visual indicators or tooltips for available keyboard shortcuts and hotkeys
+ - Customizable keyboard shortcut mappings and assignments
+ - Conflict resolution or priority handling for overlapping shortcut combinations
+
+- Toolbars and Menus:
+ - Configurable toolbars and menus for quick access to frequently used features
+ - Customizable toolbar and menu layouts (docking, floating, auto-hide)
+ - Visual indicators or badges for displaying tool states or modes
+
+- Themes and Customization:
+ - Predefined color themes and visual styles for different preferences
+ - Customizable color schemes, font styles, and icon sets
+ - Import/export functionality for sharing custom theme configurations
+
+- Accessibility:
+ - High-contrast mode or themes for improved visibility
+ - Screen reader support and appropriate labeling for accessibility
+ - Adjustable font sizes and zoom levels for better readability
+
+---
diff --git a/modules/masonry/docs/PRD/PRD.md b/modules/masonry/docs/PRD/PRD.md
new file mode 100644
index 00000000..04443c79
--- /dev/null
+++ b/modules/masonry/docs/PRD/PRD.md
@@ -0,0 +1,144 @@
+
+# Product Requirements Document (PRD): Masonry Framework
+
+## 1. Bricks
+
+### a. Brick Types
+
+#### 1. Data Bricks: These serve as inputs for other bricks and come in two types: hardcoded and editable
+
+- Hardcoded Data Brick: Fixed values that cannot be changed by the user. Examples include predefined note values, counts, etc.
+
+ ![alt text](./images/image.png)
+- Editable Data Brick: Values that can be modified by the user. When clicked, these bricks open a text editor or a dropdown menu for user input, allowing customization of note names, pitches, etc.
+
+ ![editable bricks](./images/image-1.png)
+
+#### 2. Expression Bricks: Takes values as input, returns a value as output
+
+ ![alt text](./images/image-2.png)
+
+#### 3. Statement Bricks: These define actions to be taken
+
+ ![example](./images/image-3.png)
+
+#### 4. Block Bricks: Contain nesting, also execute something like the statement bricks. Takes 0 or more arguments
+
+ ![alt text](./images/image-14.png)
+
+### b. Brick Appearance
+
+- **Distinct Shapes**: Each brick type has a unique shape to differentiate its function visually.
+- **Colors**:
+ 1. **Original Color**: Each brick has a unique color that represents its type.
+ 2. **Hover Color**: When a user hovers over a brick, it changes to a distinct color to indicate it is selectable.
+ 3. **Disconnected Color**: If a brick is not connected to the stack, it turns gray to indicate it is inactive.
+ 4. **Execution Color**: When a brick is executed, it changes to a darker shade of its original color to show that it has been activated.
+- **Sprites**: Visual symbols that indicate specific functions or properties of the brick. Some bricks may have sprites (like the start brick), while others may not.
+- **Labels**:
+ 1. **Functionality Labels**: Text labels that indicate the function of the brick.
+ 2. **Argument Labels**: Text labels that indicate the arguments or parameters that need to be provided for the brick's function.
+- **Input/Output Ports**: Connectors that visually represent where bricks can attach to each other.
+- **Editable Text Labels/Fields**: Users can input data directly into the bricks, such as note names, durations, and numerical values.
+
+ **Side Note:** If we want to implement a design similar to Scratch in the future, we can consider the following approach for connecting blocks:
+
+- In Scratch, blocks are connected horizontally in a row for sequential execution. Each block has a tab at the bottom and a notch at the top, allowing them to snap together in a linear sequence. This design makes it clear which blocks will execute in order.
+
+### c. Brick Interactions
+
+- **Inline Text Editing**: Users can click on text fields within bricks to edit labels and values directly.
+ - Some bricks only open an inline text editor when clicked.
+
+ ![inline text editing](./images/image-4.png)
+
+ - Other bricks open both an inline text editor and a context menu for additional options.
+
+ ![inline text editor with context menu](./images/image-15.png)
+- **Context Menus**: For more complex properties, a separate interface allows detailed configuration.
+
+ ![dedicated editors](./images/image-5.png)
+- **Connection Types**:
+ 1. **Argument Connections**: Bricks can be connected to input arguments of other bricks. This allows for passing data or parameters into the brick’s function.
+ 2. **Brick-to-Brick or Stack Connections**: Bricks can be connected directly to other bricks or to a stack of bricks. This enables building complex sequences and structures by chaining bricks together.
+
+ ![alt text](./images/image-8.png)
+
+## 2. Stack of Bricks
+
+### a. Stack Validation
+
+- **Visual Feedback**: Indicators show whether brick combinations are valid.
+
+ ![alt text](./images/image-6.png)
+
+- **Error Indicators**: Explanations for incompatible connections help users troubleshoot.
+ - Add a reddish boundary for users to easily tell whether the bricks are mergeable or not.
+
+ ![alt text](./images/image-7.png)
+
+- **Disable Validation**: Temporarily turn off validation for complex or experimental setups.
+
+ **Note** - this is up for further discussion
+
+### b. Stack Editing
+
+- **Connection Editing**: Options for re-positioning, disconnecting, or connecting.
+- **Quick Edit Shortcuts**: Context menus or keyboard shortcuts speed up editing.
+
+### c. Stack Grouping
+
+- **Collapsible Groups**: Groups can be collapsed or expanded to manage complexity.
+
+ ![alt text](./images/image-9.png)
+
+## 3. Palette
+
+### a. **Layout and Organization**
+
+- Collapsible/expandable categories or sections for different Brick types
+- Visual separators or dividers between categories
+- Customizable order and arrangement of categories
+
+ ![alt text](./images/image-10.png)
+
+### b. **Brick Previews**
+
+- Tooltips or pop-ups displaying Brick names and brief descriptions
+
+ ![alt text](./images/image-16.png)
+
+- Color-coding or visual cues for distinguishing different Brick types
+
+### c. **Search and Filtering**
+
+- Search bar or input field for locating specific Bricks by name or keyword
+- Filter options for narrowing down Bricks based on category, type, or properties
+- Live search results or suggestions as the user types
+ - Searchbar in Musicblocks as of now:
+
+ ![alt text](./images//image-11.png)
+
+ - Searchbar design to be implemented:
+
+ ![alt text](./images/image-17.png)
+ The idea here is to have a fixed searchbar on the left side of the workspace through which users can search for bricks, group them etc.
+ Note - It is just a one big list and categories on the left are positions on the list.
+
+### d. **Drag and Drop**
+
+- Ability to drag and drop Bricks from the palette onto the workspace.
+- Visual indicators (e.g., ghost preview, outline) for valid drop locations.
+
+ ![drag and drop](./images/image-12.png)
+
+ - While dragging a brick from the palette, the brick should temporarily disappear from the palette until it is placed in the workspace.
+
+## 4. Workspace
+
+![alt text](./images/image-13.png)
+
+- **Cloning/Duplication**: Users can easily create copies of bricks for repeated use.
+- **Scaling and Rotation**: Bricks can be resized and rotated to fit the workspace better.
+- **Undo/Redo**: Users can revert or reapply changes to their stacks.
+- **Removal/Deletion of Bricks** : Users can remove/delete bricks
diff --git a/modules/masonry/docs/Architecture/MasonryDFD.drawio b/modules/masonry/docs/architecture/MasonryDFD.drawio
similarity index 100%
rename from modules/masonry/docs/Architecture/MasonryDFD.drawio
rename to modules/masonry/docs/architecture/MasonryDFD.drawio
diff --git a/modules/masonry/docs/Architecture/MasonryDFD.drawio.png b/modules/masonry/docs/architecture/MasonryDFD.drawio.png
similarity index 100%
rename from modules/masonry/docs/Architecture/MasonryDFD.drawio.png
rename to modules/masonry/docs/architecture/MasonryDFD.drawio.png
diff --git a/modules/masonry/docs/Architecture/Processes.md b/modules/masonry/docs/architecture/Processes.md
similarity index 98%
rename from modules/masonry/docs/Architecture/Processes.md
rename to modules/masonry/docs/architecture/Processes.md
index 9ba07c40..89471f88 100644
--- a/modules/masonry/docs/Architecture/Processes.md
+++ b/modules/masonry/docs/architecture/Processes.md
@@ -1,6 +1,7 @@
# Processes for Data Flow Diagram
## Level 0: Masonry Framework Communication with MusicBlocks
+
1. **Load Configuration**:
- Input: Configuration File
- Output: Initialized System
@@ -19,7 +20,8 @@
## Level 1: Interaction between Brick, Palette, Workspace, and Stack of Bricks
-### Bricks:
+### Bricks
+
1. **Initialize Brick**:
- Input: Brick Properties
- Output: Initialized Brick
@@ -28,7 +30,8 @@
- Input: Brick ID from Workspace
- Output: Brick Properties to Workspace
-### Palette:
+### Palette
+
1. **Load Brick List**:
- Input: Configuration Settings
- Output: List of Bricks
@@ -38,7 +41,8 @@
- Output: Selected Brick Properties to Workspace
(How this works is, The palette will have a loaded list of SVGs. When you drag one from palette onto the workspace, the brick will be created on the workspace whos id matches to the one in brick)
-### Workspace:
+### Workspace
+
1. **Add Brick to Workspace**:
- Input: Brick Properties from Palette
- Output: Updated Workspace
@@ -59,7 +63,8 @@
- Input: Current Workspace Data
- Output: Saved Workspace State
-### Stack of Bricks:
+### Stack of Bricks
+
1. **Initialize Stack**:
- Input: Brick Stack Data
- Output: Initialized Stack
@@ -70,8 +75,8 @@
## Level 2: Detailed Interaction within MVC Architecture
+### Model
-### Model:
1. BrickModel:
- Properties:
- brickType
@@ -133,7 +138,8 @@
- undo()
- redo()
-### View:
+### View
+
1. BrickView:
- Methods:
- renderBrick(brick)
@@ -161,7 +167,8 @@
- renderZoomControls(zoomLevel)
- renderUndoRedoButtons(undoRedoStack)
-### Controller:
+### Controller
+
1. BrickController:
- Methods:
- handleBrickPropertyChange(brick, properties)
diff --git a/modules/masonry/docs/tech-spec/TechSpec.md b/modules/masonry/docs/tech-spec/TechSpec.md
new file mode 100644
index 00000000..eb108ea3
--- /dev/null
+++ b/modules/masonry/docs/tech-spec/TechSpec.md
@@ -0,0 +1,385 @@
+# Masonry Framework Tech Spec
+
+This tech spec outlines the implementation details for the Masonry Framework, a core component of the MusicBlocks V4 project built with React and TypeScript.
+
+## Project Structure
+
+```
+├── src
+│ ├── utils
+│ │ ├── dragAndDropUtils.ts
+│ │ ├── validationUtils.ts
+│ │ ├── dataUtils.ts
+│ │ ├── quadtreeUtils.ts
+│ │ └──...
+│ ├── components
+│ │ ├── brick
+│ │ │ ├── Brick.tsx
+│ │ │ ├── BrickInput.tsx
+│ │ │ ├── BrickOutput.tsx
+│ │ │ ├── DataBrick.tsx
+│ │ │ ├── ExpressionBrick.tsx
+│ │ │ ├── StatementBrick.tsx
+│ │ │ ├── BlockBrick.tsx
+│ │ │ └──...
+│ │ ├── palette
+│ │ │ ├── Palette.tsx
+│ │ │ ├── PaletteCategory.tsx
+│ │ │ └── PaletteSearch.tsx
+│ │ ├── workspace
+│ │ │ ├── Workspace.tsx
+│ │ │ ├── WorkspaceGrid.tsx
+│ │ │ ├── WorkspaceToolbar.tsx
+│ │ │ └──...
+│ ├── hooks
+│ │ ├── useBrick.ts
+│ │ ├── useStack.ts
+│ │ ├── useWorkspace.ts
+│ │ └──...
+│ ├── models
+│ │ ├── Brick.ts
+│ │ ├── Stack.ts
+│ │ ├── Workspace.ts
+│ │ └──...
+│ ├── services
+│ │ ├── BrickService.ts
+│ │ ├── StackService.ts
+│ │ ├── WorkspaceService.ts
+│ │ ├── QuadtreeService.ts
+│ │ ├── ErrorHandlingService.ts
+│ │ └──...
+│ ├── App.tsx
+│ └── index.tsx
+├──...
+```
+
+## Dependencies
+
+- React
+- TypeScript
+- React-aria (for drag-and-drop functionality)
+- ... (other relevant libraries)
+
+## Description
+
+### Components
+
+#### a) Brick
+
+- **Brick.tsx:**
+ - Properties:
+ - `brick`: The brick model instance.
+ - `onDragStart`: Callback for drag start event.
+ - `onDragOver`: Callback for drag-over event.
+ - `onDrop`: Callback for drop event.
+ - `onDragEnd`: Callback for drag end event.
+ - `onClick`: Callback for click event.
+ - `onDoubleClick`: Callback for double-click event.
+ - `onContextMenu`: Callback for context menu event.
+ - `onInputChange`: Callback for input change event.
+ - `onOutputChange`: Callback for output change event.
+ - Functions:
+ - `render()`: Renders the brick component with its visual appearance and input/output ports.
+ - `handleDragStart()`: Handles the drag start event for the brick.
+ - `handleDragOver()`: Handles the drag-over event for the brick.
+ - `handleDrop()`: Handles the drop event for the brick.
+ - `handleDragEnd()`: Handles the drag end event for the brick.
+ - `handleClick()`: Handles the click event for the brick.
+ - `handleDoubleClick()`: Handles the double-click event for the brick.
+ - `handleContextMenu()`: Handles the context menu event for the brick.
+ - `handleInputChange()`: Handles the input change event for the brick.
+ - `handleOutputChange()`: Handles the output change event for the brick.
+- **BrickInput.tsx:**
+ - Properties:
+ - `brick`: The brick model instance.
+ - `onConnect`: Callback for connect event.
+ - `onDisconnect`: Callback for disconnect event.
+ - Functions:
+ - `render()`: Renders the input port of the brick.
+ - `handleConnect()`: Handles the connect event for the input port.
+ - `handleDisconnect()`: Handles the disconnect event for the input port.
+- **BrickOutput.tsx:**
+ - Properties:
+ - `brick`: The brick model instance.
+ - `onConnect`: Callback for connect event.
+ - `onDisconnect`: Callback for disconnect event.
+ - Functions:
+ - `render()`: Renders the output port of the brick.
+ - `handleConnect()`: Handles the connect event for the output port.
+ - `handleDisconnect()`: Handles the disconnect event for the output port.
+- **DataBrick.tsx:**
+ - Properties:
+ - `brick`: The brick model instance.
+ - `onInputChange`: Callback for input change event.
+ - `onOutputChange`: Callback for output change event.
+ - Functions:
+ - `render()`: Renders the data brick component with its visual appearance and input/output ports.
+ - `handleInputChange()`: Handles the input change event for the data brick.
+ - `handleOutputChange()`: Handles the output change event for the data brick.
+- **ExpressionBrick.tsx:**
+ - Properties:
+ - `brick`: The brick model instance.
+ - `onInputChange`: Callback for input change event.
+ - `onOutputChange`: Callback for output change event.
+ - Functions:
+ - `render()`: Renders the expression brick component with its visual appearance and input/output ports.
+ - `handleInputChange()`: Handles the input change event for the expression brick.
+ - `handleOutputChange()`: Handles the output change event for the expression brick.
+- **StatementBrick.tsx:**
+ - Properties:
+ - `brick`: The brick model instance.
+ - `onInputChange`: Callback for input change event.
+ - `onOutputChange`: Callback for output change event.
+ - Functions:
+ - `render()`: Renders the statement brick component with its visual appearance and input/output ports.
+ - `handleInputChange()`: Handles the input change event for the statement brick.
+ - `handleOutputChange()`: Handles the output change event for the statement brick.
+- **BlockBrick.tsx:**
+ - Properties:
+ - `brick`: The brick model instance.
+ - `onInputChange`: Callback for input change event.
+ - `onOutputChange`: Callback for output change event.
+ - `children`: An array of nested brick instances.
+ - Functions:
+ - `render()`: Renders the block brick component with its visual appearance and input/output ports.
+ - `handleInputChange()`: Handles the input change event for the block brick.
+ - `handleOutputChange()`: Handles the output change event for the block brick.
+ - `handleNesting()`: Handles the nesting logic for nested bricks.
+ - `handleArguments()`: Manages the arguments for block bricks.
+
+#### b) Palette
+
+- **Palette.tsx:**
+ - Properties:
+ - `bricks`: An array of brick model instances.
+ - `onDragStart`: Callback for drag start event.
+ - `onDragOver`: Callback for drag-over event.
+ - `onDrop`: Callback for drop event.
+ - `onSearch`: Callback for search event.
+ - `searchQuery`: The current search query.
+ - Functions:
+ - `render()`: Renders the palette component with its visual appearance and categories.
+ - `handleDragStart()`: Handles the drag start event for the palette.
+ - `handleDragOver()`: Handles the drag-over event for the palette.
+ - `handleDrop()`: Handles the drop event for the palette.
+ - `handleSearch()`: Handles the search event for the palette.
+- **PaletteCategory.tsx:**
+ - Properties:
+ - `category`: The category model instance.
+ - `bricks`: An array of brick model instances.
+ - Functions:
+ - `render()`: Renders the category component with its visual appearance and bricks.
+- **PaletteSearch.tsx:**
+ - Properties:
+ - `searchQuery`: The current search query.
+ - `onSearch`: Callback for search event.
+ - Functions:
+ - `render()`: Renders the search component with its visual appearance and input field.
+ - `handleSearch()`: Handles the search event for the search component.
+
+#### c) Workspace
+
+- **Workspace.tsx:**
+ - Properties:
+ - `workspace`: The workspace model instance.
+ - `onBrickAdd`: Callback for brick add event.
+ - `onBrickRemove`: Callback for brick remove event.
+ - `onBrickConnect`: Callback for brick connect event.
+ - `onBrickDisconnect`: Callback for brick disconnect event.
+ - `onBrickMove`: Callback for brick move event.
+ - `onBrickResize`: Callback for brick resize event.
+ - `onBrickRotate`: Callback for brick rotate event.
+ - `onUndo`: Callback for undo event.
+ - `onRedo`: Callback for redo event.
+ - Functions:
+ - `render()`: Renders the workspace component with its visual appearance and bricks.
+ - `handleBrickAdd()`: Handles the brick add event for the workspace.
+ - `handleBrickRemove()`: Handles the brick remove event for the workspace.
+ - `handleBrickConnect()`: Handles the brick connect event for the workspace.
+ - `handleBrickDisconnect()`: Handles the brick disconnect event for the workspace.
+ - `handleBrickMove()`: Handles the brick move event for the workspace.
+ - `handleBrickResize()`: Handles the brick resize event for the workspace.
+ - `handleBrickRotate()`: Handles the brick rotate event for the workspace.
+ - `handleUndo()`: Handles the undo event for the workspace.
+ - `handleRedo()`: Handles the redo event for the workspace.
+- **WorkspaceGrid.tsx:**
+ - Properties:
+ - `gridSize`: The size of the grid.
+ - `onGridClick`: Callback for grid click event.
+ - Functions:
+ - `render()`: Renders the grid component with its visual appearance and grid lines.
+ - `handleGridClick()`: Handles the grid click event for the grid component.
+- **WorkspaceToolbar.tsx:**
+ - Properties:
+ - `onUndo`: Callback for undo event.
+ - `onRedo`: Callback for redo event.
+ - Functions:
+ - `render()`: Renders the toolbar component with its visual appearance and buttons.
+ - `handleUndo()`: Handles the undo event for the toolbar.
+ - `handleRedo()`: Handles the redo event for the toolbar.
+
+### Utilities
+
+- **dragAndDropUtils.ts:**
+ - Functions:
+ - `handleDragStart()`: Handles the drag start event for draggable elements.
+ - `handleDragOver()`: Handles the drag-over event for draggable elements.
+ - `handleDrop()`: Handles the drop event for draggable elements.
+ - `handleDragEnd()`: Handles the drag end event for draggable elements.
+- **validationUtils.ts:**
+ - Functions:
+ - `validateBrickConnection()`: Validates the connection between two bricks.
+ - `validateBrickPosition()`: Validates the position of a brick in the workspace.
+ - `validateBrickData()`: Validates the data within a brick.
+- **dataUtils.ts:**
+ - Functions:
+ - `saveWorkspace()`: Saves the workspace state to local storage or server.
+ - `loadWorkspace()`: Loads the workspace state from local storage or server.
+ - `exportWorkspace()`: Exports the workspace state to a file.
+ - `importWorkspace()`: Imports the workspace state from a file.
+- **quadtreeUtils.ts:**
+ - Functions:
+ - `insertBrick()`: Inserts a brick into the quadtree for spatial indexing.
+ - `removeBrick()`: Removes a brick from the quadtree.
+ - `updateBrick()`: Updates the position of a brick in the quadtree.
+ - `findNearbyBricks()`: Finds nearby bricks within a certain radius using the quadtree.
+
+### Hooks
+
+**a) useBrick:**
+
+- A hook for managing a single brick.
+- Provides an instance of the `Brick` model.
+- Handles updating the brick's properties and arguments.
+- Properties:
+ - `brick`: The brick model instance.
+ - `setBrick()`: A function to update the brick instance.
+- Functions:
+ - `useEffect()`: A React hook for handling side effects.
+ - `fetchBrick()`: A function to fetch the brick data from the server.
+ - `useCallback()`: A React hook for memoizing functions.
+ - `handleInputChange()`: A function to handle input changes for the brick.
+ - `handleOutputChange()`: A function to handle output changes for the brick.
+
+**b) useStack:**
+
+- A hook for managing a stack of bricks.
+- Provides an instance of the `Stack` model.
+- Handles updating the stack's bricks and connections.
+- Properties:
+ - `stack`: The stack model instance.
+ - `setStack()`: A function to update the stack instance.
+- Functions:
+ - `useEffect()`: A React hook for handling side effects.
+ - `fetchStack()`: A function to fetch the stack data from the server.
+ - `useCallback()`: A React hook for memoizing functions.
+ - `handleBrickAdd()`: A function to handle adding a brick to the stack.
+ - `handleBrickRemove()`: A function to handle removing a brick from the stack.
+ - `handleBrickConnect()`: A function to handle connecting bricks in the stack.
+ - `handleBrickDisconnect()`: A function to handle disconnecting bricks in the stack.
+
+**c) useWorkspace:**
+
+- A hook for managing the workspace state.
+- Provides an instance of the `Workspace` model.
+- Handles updating the workspace's bricks, connections, and layout.
+- Properties:
+ - `workspace`: The workspace model instance.
+ - `setWorkspace()`: A function to update the workspace instance.
+- Functions:
+ - `useEffect()`: A React hook for handling side effects.
+ - `fetchWorkspace()`: A function to fetch the workspace data from the server.
+ - `useCallback()`: A React hook for memoizing functions.
+ - `handleBrickAdd()`: A function to handle adding a brick to the workspace.
+ - `handleBrickRemove()`: A function to handle removing a brick from the workspace.
+ - `handleBrickConnect()`: A function to handle connecting bricks in the workspace.
+ - `handleBrickDisconnect()`: A function to handle disconnecting bricks in the workspace.
+ - `handleBrickMove()`: A function to handle moving a brick in the workspace.
+ - `handleBrickResize()`: A function to handle resizing a brick in the workspace.
+ - `handleBrickRotate()`: A function to handle rotating a brick in the workspace.
+
+### Models
+
+Certainly! Below, I'll expand on the properties and functionalities of the `Brick` model to include bounding boxes (b-boxes) and related methods:
+
+### Models
+
+- **Brick.ts:**
+ - Properties:
+ - `id`: Unique identifier for the brick.
+ - `type`: Type of the brick (data, expression, statement, block).
+ - `position`: Position of the brick in the workspace.
+ - `inputs`: Array of input ports for the brick.
+ - `outputs`: Array of output ports for the brick.
+ - `data`: Data associated with the brick.
+ - `boundingBox`: Bounding box coordinates of the brick for collision detection and spatial indexing.
+ - Functions:
+ - `connect()`: Connects the brick to another brick.
+ - `disconnect()`: Disconnects the brick from another brick.
+ - `move()`: Moves the brick to a new position.
+ - `resize()`: Resizes the brick.
+ - `rotate()`: Rotates the brick.
+ - `calculateBoundingBox()`: Calculates the bounding box of the brick based on its size and position.
+ - `checkCollision()`: Checks for collision with other bricks or boundaries.
+ - `handleCollision()`: Handles collision events by adjusting the position or behavior of the brick.
+ - `updatePosition()`: Updates the position of the brick based on collision resolution or user interaction.
+
+- **Stack.ts:**
+ - Properties:
+ - `id`: Unique identifier for the stack.
+ - `bricks`: Array of bricks in the stack.
+ - Functions:
+ - `addBrick()`: Adds a brick to the stack.
+ - `removeBrick()`: Removes a brick from the stack.
+ - `connectBricks()`: Connects two bricks in the stack.
+ - `disconnectBricks()`: Disconnects two bricks in the stack.
+- **Workspace.ts:**
+ - Properties:
+ - `id`: Unique identifier for the workspace.
+ - `stacks`: Array of stacks in the workspace.
+ - `gridSize`: Size of the grid in the workspace.
+ - `zoomLevel`: Zoom level of the workspace.
+ - Functions:
+ - `addStack()`: Adds a stack to the workspace.
+ - `removeStack()`: Removes a stack from the workspace.
+ - `findBrickById()`: Finds a brick in the workspace by its ID.
+ - `validateWorkspace()`: Validates the workspace state.
+ - `exportWorkspace()`: Exports the workspace state to a file.
+ - `importWorkspace()`: Imports the workspace state from a file.
+
+### Services
+
+- **BrickService.ts:**
+ - Functions:
+ - `createBrick()`: Creates a new brick instance.
+ - `deleteBrick()`: Deletes a brick instance.
+ - `updateBrick()`: Updates a brick instance.
+ - `findBrickById()`: Finds a brick instance by its ID.
+- **StackService.ts:**
+ - Functions:
+ - `createStack()`: Creates a new stack instance.
+ - `deleteStack()`: Deletes a stack instance.
+ - `updateStack()`: Updates a stack instance.
+ - `findStackById()`: Finds a stack instance by its ID.
+- **WorkspaceService.ts:**
+ - Functions:
+ - `createWorkspace()`: Creates a new workspace instance.
+ - `deleteWorkspace()`: Deletes a workspace instance.
+ - `updateWorkspace()`: Updates a workspace instance.
+ - `findWorkspaceById()`: Finds a workspace instance by its ID.
+- **QuadtreeService.ts:**
+ - Functions:
+ - `insertBrick()`: Inserts a brick into the quadtree for spatial indexing.
+ - `removeBrick()`: Removes a brick from the quadtree.
+ - `updateBrick()`: Updates the position of a brick in the quadtree.
+ - `findNearbyBricks()`: Finds nearby bricks within a certain radius using the quadtree.
+- **ErrorHandlingService.ts:**
+ - Functions:
+ - `handleError()`: Handles errors and exceptions in the application.
+ - `logError()`: Logs errors to a server or local storage.
+
+## Testing
+
+- Write unit tests for components, utilities, and hooks using Jest and React Testing Library.
+- Write integration tests for drag-and-drop functionality and state management.
+- Write end-to-end tests for the overall workflow using Cypress or Selenium.
diff --git a/modules/masonry/docs/tech-spec/Techspec.md b/modules/masonry/docs/tech-spec/Techspec.md
new file mode 100644
index 00000000..2bc99422
--- /dev/null
+++ b/modules/masonry/docs/tech-spec/Techspec.md
@@ -0,0 +1,163 @@
+# Masonry Framework
+
+## Palette
+
+#### Config (Inputs)
+
+- **Categories**:
+ - **Attributes**: names, icons
+ - **Sections**:
+ - **Attributes**: name, icon, color
+ - **Bricks**:
+ - **Attributes**: id, name, description, thumbnail, BBox
+
+#### Search
+
+- **Search text**:
+ - Substring match on name
+ - Substring match on description
+ - Minimum 3 characters
+
+#### Drag & Drop
+
+- **For a brick**:
+ 1. Start drag operation
+ 2. Transfer brick's logo to workspace
+ 3. Replace thumbnail with silhouette (silhouette is a grayed-out thumbnail at 50% opacity)
+
+- **Drag Ended**:
+ - Replace silhouette with the original thumbnail
+
+- **Workspace (WS)**:
+ - Handles drag operations
+ - Stops drag within the palette
+ - Stops drag outside the palette
+
+## Brick
+
+#### Brick Types
+
+- **Data Bricks**
+ - Returns values
+ - Connects only as arguments
+ - Example: input
+- **Expression Bricks**
+ - Returns values
+ - Can take 0 or more arguments
+ - Connects only as arguments
+- **Statement Bricks**
+ - Execute actions
+ - Connects with other statement/block types
+ - Can take 0 or more arguments
+- **Block Bricks**
+ - Can nest other bricks
+ - Connects with other statement/block types
+ - Can take 0 or more arguments
+
+#### Brick Appearance
+
+- **Attributes**:
+ - Color
+ - Shape
+ - Primary label
+ - Any labels (copied)
+ - Any connectors
+
+#### Brick Interactions
+
+- **Inline Edit**:
+ - Only applicable to Data bricks
+ - Example: input text
+
+#### Brick Structure Overview
+
+- **Brick**:
+ - Color
+ - Argument connectors
+ - Connectors for expression
+- **Argument**:
+ - Can connect to data bricks
+- **Data**:
+ - Inputs, labels, nodes
+- **Expression**:
+ - Contains data bricks
+- **Statement**:
+ - Instructions, connected to block
+- **Block**:
+ - Can nest other bricks
+
+## Stack
+
+### Stack Validation
+
+- **Visual Feedback**:
+ - Indicators show whether brick combinations are valid.
+ - Example: A green outline appears for a valid connection, while a red outline indicates an invalid connection.
+- **Error Indicators**:
+ - Provide explanations for incompatible connections to help users troubleshoot.
+ - Example: A reddish boundary and error message explain why the connection is invalid.
+
+### Stack Editing
+
+- **Connection Editing**:
+ - Options for repositioning, disconnecting, or connecting bricks.
+ - Visual indicators show possible connections.
+ - Example: Highlight potential connection points when a brick is moved.
+
+### Stack Grouping
+
+- **Collapsible Groups**:
+ - Groups can be collapsed or expanded to manage complexity.
+ - Example: Users can organize bricks into groups that can be collapsed to reduce visual clutter.
+ - Collapsed groups can be moved as a single unit.
+
+## Workspace
+
+### Layout and Interaction
+
+- **Cloning**:
+ - Users can easily create copies of bricks for repeated use.
+ - Example: Right-click on a brick and select "Duplicate".
+- **Scaling and Rotation**:
+ - Bricks can be resized and rotated to fit the workspace better.
+ - Example: Click and drag corner handles to resize, or use rotation handles to rotate.
+- **Undo/Redo**:
+ - Users can revert or reapply changes to their stacks.
+ - Example: Undo the last action with Ctrl+Z, redo with Ctrl+Y.
+- **Deletion of Bricks**:
+ - Users can remove or delete bricks.
+ - Example: Drag a brick to the trash icon or press the delete key.
+
+### Data Flow and Interaction
+
+#### Adding Bricks
+
+- **From Palette to Workspace**:
+ 1. User drags a brick from the palette.
+ 2. Workspace detects the drag operation and shows a drop area.
+ 3. User drops the brick in the workspace.
+ 4. Workspace creates a new brick instance at the drop location.
+
+#### Connecting Bricks
+
+- **Within Workspace**:
+ 1. User selects a connection point on a brick.
+ 2. User drags to another brick's connection point.
+ 3. Workspace validates the connection.
+ 4. If valid, a connection is established and visual feedback is provided.
+ 5. If invalid, an error message is shown.
+
+#### Editing Connections
+
+- **Repositioning and Disconnecting**:
+ 1. User clicks on a connection line.
+ 2. User can drag the connection to a new point or disconnect it.
+ 3. Workspace updates the connections and provides visual feedback.
+
+#### Grouping Bricks
+
+- **Creating and Managing Groups**:
+ 1. User selects multiple bricks.
+ 2. User groups them into a collapsible unit.
+ 3. Workspace treats the group as a single entity for movement and scaling.
+ 4. User can collapse or expand the group to manage workspace complexity.
diff --git a/modules/masonry/playground/index.html b/modules/masonry/playground/index.html
new file mode 100644
index 00000000..47565672
--- /dev/null
+++ b/modules/masonry/playground/index.html
@@ -0,0 +1,13 @@
+
+
+