Updated download guide and getting-started guide

added new guides: element-loading and debugging

docs/.vitepress/config.mts

@@ -71,15 +71,37 @@ export default defineConfig({
 
     sidebar: {
       '/guides/': [
-        { text: 'Getting started', link: '/guides/getting-started' },
+        {
-        { text: 'Download', link: '/guides/download' },
+          text: 'Getting Started',
-        { text: 'Annotations', link: '/guides/annotations' },
+          items: [
-        { text: 'Animations', link: '/guides/animations' },
+            { text: 'Introduction', link: '/guides/getting-started' },
-        { text: 'Benchmark', link: '/guides/benchmarks' },
+            { text: 'Download & Installation', link: '/guides/download' },
-        { text: 'Canvas', link: 'guides/canvas'},
+          ]
-        { text: 'Properties', link: '/guides/properties' },
+        },
-        { text: 'States', link: '/guides/states' },
+        {
-        { text: 'XML', link: '/guides/xml' },
+          text: 'Core Concepts',
+          items: [
+            { text: 'Properties', link: '/guides/properties' },
+            { text: 'States', link: '/guides/states' },
+            { text: 'Animations', link: '/guides/animations' },
+          ]
+        },
+        {
+          text: 'Advanced',
+          items: [
+            { text: 'XML', link: '/guides/xml' },
+            { text: 'Canvas', link: '/guides/canvas'},
+            { text: 'Element Loading', link: '/guides/element-loading' },
+          ]
+        },
+        {
+          text: 'Development',
+          items: [
+            { text: 'Debugging', link: '/guides/debugging' },
+            { text: 'Benchmarks', link: '/guides/benchmarks' },
+            { text: 'LuaLS Annotations', link: '/guides/annotations' },
+          ]
+        },
         { text: 'FAQ', link: '/guides/faq' },
       ],
 

docs/guides/debugging.md

@@ -0,0 +1,122 @@
+# Debugging
+
+Basalt provides a built-in logging system to help you track and debug your applications.
+
+## Logging System
+
+### Enabling Logging
+
+```lua
+local basalt = require("basalt")
+
+-- Enable logging
+basalt.LOGGER.setEnabled(true)
+
+-- Optional: Log to file
+basalt.LOGGER.setLogToFile(true)  -- Creates basalt.log
+```
+
+### Log Levels
+
+```lua
+basalt.LOGGER.debug("Detailed debugging information")
+basalt.LOGGER.info("General information")
+basalt.LOGGER.warn("Warning message")
+basalt.LOGGER.error("Error message")
+```
+
+### Example
+
+```lua
+local basalt = require("basalt")
+basalt.LOGGER.setEnabled(true)
+basalt.LOGGER.setLogToFile(true)
+
+local main = basalt.getMainFrame()
+
+local button = main:addButton()
+    :setText("Click Me")
+    :setPosition(2, 2)
+    :onClick(function(self)
+        basalt.LOGGER.debug("Button clicked")
+        
+        local data = loadData()
+        basalt.LOGGER.info("Loaded " .. #data .. " items")
+        
+        local success = processData(data)
+        if not success then
+            basalt.LOGGER.error("Failed to process data")
+        end
+    end)
+
+basalt.run()
+```
+
+## Debug Console
+
+If you have the debug plugin, you can open a visual console that displays log messages in real-time:
+
+```lua
+local basalt = require("basalt")
+basalt.LOGGER.setEnabled(true)
+
+local main = basalt.getMainFrame()
+
+-- Open debug console
+main:openConsole()
+
+basalt.LOGGER.info("Console is now open!")
+basalt.run()
+```
+
+The console shows all log messages with color-coded levels and is scrollable.
+
+### Debug Element Issues
+
+```lua
+local element = frame:addButton()
+    :setText("Test")
+    :setPosition(10, 5)
+
+local x, y = element:getPosition()
+local w, h = element:getSize()
+basalt.LOGGER.debug("Element at " .. x .. ", " .. y .. " size " .. w .. "x" .. h)
+basalt.LOGGER.debug("Visible: " .. tostring(element:getVisible()))
+```
+
+### Error Handling
+
+```lua
+local function safeOperation()
+    local success, result = pcall(function()
+        return riskyFunction()
+    end)
+    
+    if not success then
+        basalt.LOGGER.error("Operation failed: " .. tostring(result))
+        return nil
+    end
+    
+    basalt.LOGGER.info("Operation successful")
+    return result
+end
+```
+
+### Component-Based Logging
+
+```lua
+local function createLogger(component)
+    return {
+        debug = function(msg) basalt.LOGGER.debug("[" .. component .. "] " .. msg) end,
+        info = function(msg) basalt.LOGGER.info("[" .. component .. "] " .. msg) end,
+        warn = function(msg) basalt.LOGGER.warn("[" .. component .. "] " .. msg) end,
+        error = function(msg) basalt.LOGGER.error("[" .. component .. "] " .. msg) end,
+    }
+end
+
+local dbLogger = createLogger("Database")
+local uiLogger = createLogger("UI")
+
+dbLogger.info("Connection established")
+uiLogger.debug("Button created")
+```

docs/guides/download.md

@@ -1,31 +1,124 @@
 # Download
 
-Basalt is available in two versions: the dev version, ideal for develpoement and the release version which is meant for production. Basalt is also available on [PineStore](https://pinestore.cc/projects/15/basalt)
+Basalt is available in multiple versions to suit different needs: the **Core** version for smaller projects, the **Full** version with all elements and plugins, the **Dev** version for development, and a **Custom** version for specific requirements. Basalt is also available on [PineStore](https://pinestore.cc/projects/15/basalt).
 
-## Downloading Basalt
+## Quick Start
 
-To download the Basalt Installer-UI using a ComputerCraft shell command, use the following:
+To download the Basalt Installer UI using a ComputerCraft shell command:
 
-```
+```lua
 wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua
 ```
 
-## Download Basalt without UI
+This launches an interactive installer where you can choose your preferred version and configuration.
 
-If you want to skip the UI and just download the essentials, here are some other commands:
+## Available Versions
 
-### Developer
+### Release (Core) - Recommended
+The **Core** version includes only the essential elements. It's lighter, optimized for smaller projects, and perfect for most use cases.
 
-This is the full dev version of Basalt, containing all available files.
+**What's included:**
+- All core systems (layouts, properties, rendering, etc.)
+- Essential elements (Button, Label, Frame, List, Input, etc.)
 
+**What's excluded:**
+- Optional elements (TextBox, Display, Image, ComboBox, DropDown, Graph, LineChart, BigFont)
+- Plugin files (core features are built-in)
+
+**Best for:** Smaller projects, production use, limited storage environments
+
+```lua
+wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -r
 ```
+
+### Release (Full)
+The **Full** version contains all elements and plugins. Use this if you need advanced or optional components in your project.
+
+**What's included:**
+- Everything from Core version
+- Optional elements (TextBox, Image, ComboBox, DropDown, etc.)
+- All available plugins (animation, theme, xml, etc.)
+
+**Best for:** Large projects, advanced features, full flexibility
+
+```lua
+wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -f
+```
+
+### Dev Version
+The **Dev** version downloads the complete source code as individual files, maintaining the original folder structure. Perfect for development, debugging, or contributing to Basalt.
+
+**Use cases:**
+- Development and debugging
+- Contributing to the project
+- Learning how Basalt works internally
+- Hot-reloading during development
+
+**Note:** The source code is identical to the release versions - only the file structure differs. Contains all files uncompressed.
+
+**Best for:** Development environments, debugging, contributions
+
+```lua
 wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -d
 ```
 
-### Release
+### Custom Version
+Available through the interactive installer, the **Custom** version lets you select exactly which elements and plugins you need.
 
-This is the default bundle version of Basalt, containing the full framework, but minified.
+**Features:**
+- Pick individual elements and plugins
+- Optional minification
+- Optional single-file bundle
+- Optional LuaLS type definitions
 
+**To access:** Run the installer without arguments and select "Custom" from the dropdown.
+
+## Command-Line Options
+
+```bash
+# Show help
+wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -h
+
+# Install Core version (default, recommended)
+wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -r [path]
+
+# Install Full version (all elements)
+wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -f [path]
+
+# Install Dev version (source files)
+wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -d [path]
 ```
-wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -r
+
+**Optional `[path]` argument:**
+- For Release versions: Specifies the output filename (default: `basalt.lua`)
+- For Dev version: Specifies the directory name (default: `basalt/`)
+
+## Which Version Should I Choose?
+
+| Version | Best For | Structure | Includes Plugins |
+|---------|----------|-----------|------------------|
+| **Core** | Smaller projects, limited storage | Single file | No (built-in) |
+| **Full** | Large projects, all features | Single file | Yes |
+| **Dev** | Development, debugging | Multiple files | Yes |
+| **Custom** | Specific requirements | Configurable | Configurable |
+
+## Examples
+
+```lua
+-- Install Core version as "myapp.lua"
+wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -r myapp.lua
+
+-- Install Full version with default name
+wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -f
+
+-- Install Dev version in "basalt-dev" folder
+wget run https://raw.githubusercontent.com/Pyroxenium/Basalt2/main/install.lua -d basalt-dev
+```
+
+## After Installation
+
+Once installed, you can load Basalt in your program:
+
+```lua
+local basalt = require("basalt")
 ```

docs/guides/element-loading.md

@@ -0,0 +1,175 @@
+# Element Loading System
+
+Basalt's Element Loading System allows you to load elements from different sources: local files, disk mounts, and even directly from the web.
+
+## Getting the Element Manager
+
+```lua
+local basalt = require("basalt")
+local elementManager = basalt.getElementManager()
+```
+
+## Configuration
+
+Configure the loading behavior:
+
+```lua
+elementManager.configure({
+    autoLoadMissing = true,           -- Auto-load elements that aren't found
+    allowRemoteLoading = true,        -- Enable loading from URLs
+    allowDiskLoading = true,          -- Enable loading from disk mounts
+    useGlobalCache = true,            -- Cache loaded elements in _G
+    globalCacheName = "_BASALT_CACHE" -- Name of the global cache variable
+})
+```
+
+## Loading from Disk
+
+Register disk mount points to load elements from external locations:
+
+```lua
+-- Register a disk mount
+elementManager.registerDiskMount("/disk/basalt-elements")
+
+-- Elements in /disk/basalt-elements/elements/ are now available
+local main = basalt.getMainFrame()
+local customButton = main:addCustomButton()  -- Loads from disk
+```
+
+## Loading from Remote URLs
+
+Load elements directly from the web:
+
+```lua
+-- Enable remote loading
+elementManager.configure({
+    allowRemoteLoading = true
+})
+
+-- Register a remote source
+elementManager.registerRemoteSource(
+    "CustomElement",
+    "https://example.com/elements/CustomElement.lua"
+)
+
+-- Use the element
+local main = basalt.getMainFrame()
+local custom = main:addCustomElement()
+```
+
+## Manual Element Loading
+
+Load elements manually when needed:
+
+```lua
+-- Load a specific element
+elementManager.loadElement("Button")
+
+-- Get an element (loads it if not already loaded)
+local ButtonClass = elementManager.getElement("Button")
+
+-- Check if an element exists
+if elementManager.hasElement("CustomWidget") then
+    elementManager.loadElement("CustomWidget")
+end
+
+-- Check if an element is loaded
+if not elementManager.isElementLoaded("Label") then
+    elementManager.loadElement("Label")
+end
+```
+
+## Preloading Elements
+
+Preload multiple elements at startup for better performance:
+
+```lua
+-- Preload commonly used elements
+elementManager.preloadElements({
+    "Button",
+    "Label",
+    "Frame",
+    "Input"
+})
+```
+
+## Cache Management
+
+When using `useGlobalCache`, elements are cached in `_G` for reuse:
+
+```lua
+-- Get cache statistics
+local stats = elementManager.getCacheStats()
+print("Cached elements: " .. stats.size)
+for _, name in ipairs(stats.elements) do
+    print("- " .. name)
+end
+
+-- Clear the cache
+elementManager.clearGlobalCache()
+```
+
+## Complete Example
+
+```lua
+local basalt = require("basalt")
+local elementManager = basalt.getElementManager()
+
+-- Configure loading system
+elementManager.configure({
+    autoLoadMissing = true,
+    allowRemoteLoading = true,
+    allowDiskLoading = true,
+    useGlobalCache = true
+})
+
+-- Register disk mount for custom elements
+if fs.exists("/disk") then
+    elementManager.registerDiskMount("/disk")
+end
+
+-- Register remote element
+elementManager.registerRemoteSource(
+    "SpecialButton",
+    "https://raw.githubusercontent.com/user/repo/main/SpecialButton.lua"
+)
+
+-- Preload common elements
+elementManager.preloadElements({"Button", "Label", "Frame"})
+
+-- Use elements normally
+local main = basalt.getMainFrame()
+
+local btn = main:addButton()
+    :setText("Standard Button")
+    :setPosition(2, 2)
+
+-- This will be loaded from disk or remote if available
+local special = main:addSpecialButton()
+    :setText("Special Button")
+    :setPosition(2, 4)
+
+basalt.run()
+```
+
+## Use Cases
+
+### Remote Element Library
+
+Load elements from a central repository:
+
+```lua
+local repository = "https://raw.githubusercontent.com/Basalt2/main/src/elements/"
+
+elementManager.configure({allowRemoteLoading = true})
+elementManager.registerRemoteSource("Chart", repository .. "Chart.lua")
+elementManager.registerRemoteSource("DataGrid", repository .. "DataGrid.lua")
+```
+
+## Notes
+
+- Remote loading requires HTTP API to be enabled in CC:Tweaked config
+- Disk loading looks for `elements/` subfolder in the mount path
+- Elements must follow Basalt's element structure
+- Global cache persists across `basalt.run()` calls if not cleared
+- Auto-loading tries disk mounts first, then remote sources

docs/guides/getting-started.md

@@ -2,7 +2,7 @@
 
 ## Installation
 
-Checkout [download](download) to learn how to get basalt on your CC:Tweaked computer.
+Check out the [download guide](download) to learn how to get Basalt on your CC:Tweaked computer.
 
 ## Creating Your First UI
 
@@ -18,11 +18,11 @@ local main = basalt.getMainFrame()
 main:addButton()
     :setText("Click me!")
     :setPosition(4, 4)
-    :onClick(function()
+    :onClick(function(self)
-        -- Do something when clicked
+        self:setText("Clicked!")
     end)
 
--- Start Basalt
+-- Start Basalt (starts the event loop)
 basalt.run()
 ```
 
@@ -63,46 +63,53 @@ element:setForeground(color)     -- Set text color
 
 Elements can respond to user interaction:
 ```lua
-element:onClick(function()
+element:onClick(function(self)
     -- Called when clicked
+    -- 'self' refers to the element that was clicked
 end)
 
-element:onEnter(function()
+element:onEnter(function(self)
-    -- Called when mouse enters the element (only available on CraftOS-PC)
+    -- Called when mouse enters (CraftOS-PC only)
 end)
 
-element:onChange(function(self, value)
+element:onChange("text", function(self, value)
-    -- Called when value changes (inputs, lists, etc)
+    -- Called when the "text" property changes
+    -- 'value' contains the new value
 end)
 ```
 
 ## Using monitors instead
 
-Basalt can render to monitors instead of the terminal. Here's how to use monitors:
+Basalt can also render to monitors. Here's how:
 
 ```lua
 local basalt = require("basalt")
 
+local main = basalt.getMainFrame()
+
 -- Get a reference to the monitor
 local monitor = peripheral.find("monitor") 
--- Or specific side: peripheral.wrap("right")
+-- Or use a specific side: peripheral.wrap("right")
 
--- Create frame for monitor
+-- Create a frame for the monitor
-local monitorFrame = basalt.createFrame():setTerm(monitor) -- :setTerm is the important method here
+local monitorFrame = basalt.createFrame()
+    :setTerm(monitor)
 
 -- Add elements like normal
 monitorFrame:addButton()
     :setText("Monitor Button")
-    :setWidth(24)
+    :setSize(24, 3)
     :setPosition(2, 2)
 
--- Start Basalt
+-- Start Basalt (handles all frames automatically)
 basalt.run()
 ```
 
+You can have multiple frames on different screens - just call `basalt.run()` once at the end!
+
 ## Next Steps
 
 - Check out the [Examples](https://github.com/Pyroxenium/Basalt2/tree/main/examples) for more complex UIs
 - Learn about [Animations](animations) for smooth transitions
-- Explore [States](states) for data management
+- Explore [States](states) for state management
 - Read the [API Reference](/references/main) for detailed documentation