pulse-rb 1.2.24

package/README.md

@@ -0,0 +1,225 @@
+# Pulse — Reactive Component Framework for Roblox Lua
+
+<p align="center">
+  <a href="https://pulse-rb.vercel.app"><strong>pulse-rb.vercel.app</strong></a> &nbsp;·&nbsp;
+  <a href="https://pulse-rb.vercel.app/docs/intro">Docs</a> &nbsp;·&nbsp;
+  <a href="https://pulse-rb.vercel.app/docs/quick-start">Quick Start</a> &nbsp;·&nbsp;
+  <a href="https://pulse-rb.vercel.app/changelog">Changelog</a> &nbsp;·&nbsp;
+  <a href="https://discord.gg/xBtWjXRfe">Discord</a>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/version-1.2.16-7c3aed?style=flat-square" alt="version" />
+  <img src="https://img.shields.io/badge/platform-Windows-0ea5e9?style=flat-square" alt="platform" />
+  <img src="https://img.shields.io/badge/language-Lua%20%2F%20Python-f59e0b?style=flat-square" alt="language" />
+  <img src="https://img.shields.io/badge/UI-WindUI%20%7C%20Linoria-a78bfa?style=flat-square" alt="ui" />
+</p>
+
+---
+
+**Pulse** is a reactive component framework for Roblox Lua. Write your script as clean, separated `.rblua` component files. The `rb` CLI compiles, checks, and bundles everything into one deployable Lua file.
+
+```rblua
+component {
+    signal enabled = false
+    signal speed   = 50
+
+    init {
+        Pulse.Notify.onToggle(SpeedHack.enabled, "Speed Hack")
+    }
+
+    ui {
+        toggle "Speed Hack" -> enabled  tip="Override walk speed"
+        slider "Walk Speed" -> speed    [16, 250]
+    }
+
+    on CharacterAdded {
+        guard h = humanoid
+        h.WalkSpeed = enabled and speed or 16
+    }
+
+    on enabled, speed {
+        guard h = humanoid
+        h.WalkSpeed = enabled and speed or 16
+    }
+}
+```
+
+One file. No `require()`. No runtime overhead. State, UI, and events all in one self-contained component.
+
+---
+
+## Why Pulse?
+
+Roblox Lua projects grow fast. A single monolithic script becomes impossible to maintain, debug, or extend. Pulse gives you:
+
+- **Reactive signals** — declare state once; the UI, event handlers, and other components update automatically
+- **Component model** — one `.rblua` file = one feature; rename, move, or delete without touching anything else
+- **Flat compilation** — all files concatenate into one Lua chunk at build time; no module system overhead at runtime
+- **Built-in helpers** — `Pulse.Loop`, `Pulse.Draw`, `Pulse.Aim`, `Pulse.Hitbox`, `Pulse.Notify`, `Pulse.Log` and more
+- **Live dev overlay** — inject with `--dev` to get a draggable log viewer, feature toggles, and a live monitor bar
+- **One-command build** — `rb build` compiles, syntax-checks, and obfuscates in one step
+
+---
+
+## Install
+
+```powershell
+irm https://pulse-rb.vercel.app/install.ps1 | iex
+```
+
+Installs `rb` globally and adds it to PATH. Requires **Python 3.10+** and **Git**.
+
+---
+
+## Quick Start
+
+```powershell
+rb init my-project   # scaffold project + git repo
+cd my-project
+rb build             # compile → check → obfuscate
+rb watch             # auto-rebuild on save
+```
+
+A new project includes example components, a CLAUDE.md reference for AI assistants, and full WindUI layout configuration out of the box.
+
+---
+
+## Project Structure
+
+```
+my-project/
+├── src/
+│   ├── misc/helpers/globals.lua   ← compiled first — func table, shared state
+│   ├── misc/remotes.lua           ← RemoteEvent/Function wrappers
+│   ├── player/
+│   │   └── SpeedHack.rblua        ← Pulse component
+│   ├── visuals/
+│   │   └── PlayerESP.rblua
+│   └── ui/
+│       ├── layout.rblua           ← window config (title, theme, size, ...)
+│       └── pages/
+│           └── 1_Home.rblua       ← tab layout — mounts component widgets
+└── build/
+    ├── script.lua                 ← compiled output
+    └── script.obf.lua             ← obfuscated output
+```
+
+---
+
+## CLI Reference
+
+| Command | Description |
+|---|---|
+| `rb init <name>` | Scaffold a new project |
+| `rb build` | Compile → check → obfuscate |
+| `rb build --no-obfuscate` | Compile and check only |
+| `rb watch` | Auto-rebuild on file change |
+| `rb copy` | Compile and copy output to clipboard |
+| `rb new module <path>` | Add a new component |
+| `rb new remote <Name>` | Add a remote wrapper stub |
+| `rb lint` | Static analysis — dead signals, ghost refs |
+| `rb deploy` | Push build output to GitHub |
+| `rb docs` | Generate `PULSE_DOCS.md` full reference |
+
+Full CLI reference → [pulse-rb.vercel.app/docs/cli](https://pulse-rb.vercel.app/docs/cli)
+
+---
+
+## Pulse Helpers
+
+| Helper | Purpose |
+|---|---|
+| `Pulse.Loop` | Managed repeating task with safe start/stop |
+| `Pulse.Notify` | In-game toast notifications |
+| `Pulse.Draw` | Highlights, circles, selection boxes |
+| `Pulse.Aim` | FOV check, camera snap, nearest-entity search |
+| `Pulse.Hitbox` | BasePart size expansion with clean restore |
+| `Pulse.Cooldown` | Rate limiting — per-call or per-entity |
+| `Pulse.Store` | Cross-component reactive key-value state |
+| `Pulse.Track` | Entity lifecycle tracking with auto-cleanup |
+| `Pulse.Cache` | Timed function result caching |
+| `Pulse.Conn` | Named connection manager |
+| `Pulse.Log` | Structured dev logging (zero cost in prod) |
+| `Pulse.Monitor` | Live key-value dashboard in the dev overlay |
+| `Pulse.Memory` | Executor capability checks |
+| `Pulse.Team` | Configurable friend/enemy resolver |
+| `Pulse.Perf` | Rolling frame-time sampler |
+
+Full helper reference → [pulse-rb.vercel.app/docs/helpers](https://pulse-rb.vercel.app/docs/helpers)
+
+---
+
+## Component Syntax
+
+```rblua
+component {
+    signal enabled = false
+    signal radius  = 400
+
+    ui {
+        toggle   "Enable"  -> enabled  default=true  tip="Tooltip"
+        slider   "Radius"  -> radius   [50, 800]
+        button   "Reset"   -> Reset()
+    }
+
+    init {
+        -- private locals and helpers
+        local _loop = Pulse.Loop.new(0.5, function()
+            -- runs every 0.5 s while the loop is active
+        end)
+        Pulse.Notify.onToggle(MyComponent.enabled, "My Feature")
+    }
+
+    on enabled {
+        if v then _loop:start() else _loop:stop() end
+    }
+
+    on Heartbeat when enabled every 0.1 {
+        guard hrp
+        -- throttled to at most once per 0.1 s
+    }
+
+    on CharacterAdded { ... }
+
+    on InputBegan(input, gpe) when enabled debounce 0.2 {
+        if gpe then return end
+        -- ...
+    }
+
+    func Toggle() {
+        enabled(not enabled())
+    }
+}
+```
+
+Full framework reference → [pulse-rb.vercel.app/docs/intro](https://pulse-rb.vercel.app/docs/intro)
+
+---
+
+## Documentation
+
+Full documentation, scripting school, and helper reference at **[pulse-rb.vercel.app](https://pulse-rb.vercel.app)**.
+
+- [Introduction](https://pulse-rb.vercel.app/docs/intro)
+- [Quick Start](https://pulse-rb.vercel.app/docs/quick-start)
+- [Core Concepts](https://pulse-rb.vercel.app/docs/core/your-first-feature)
+- [Helpers (Pulse.*)](https://pulse-rb.vercel.app/docs/helpers)
+- [CLI Reference](https://pulse-rb.vercel.app/docs/cli)
+- [Changelog](https://pulse-rb.vercel.app/changelog)
+
+---
+
+## Requirements
+
+| Tool | Purpose | Auto-installed |
+|---|---|---|
+| Python 3.10+ | Running `rb` | No |
+| Lua 5.1 (`luac`) | Syntax checking + obfuscation | Yes (via winget) |
+| Git | Version control, Prometheus download | No |
+
+---
+
+<p align="center">
+  Built with <a href="https://pulse-rb.vercel.app">Pulse</a> · <a href="https://discord.gg/xBtWjXRfe">Discord</a>
+</p>

package/adapters/linoria.lua

@@ -0,0 +1,233 @@
+-- [adapters/linoria.lua]
+-- Linoria UI adapter for Pulse components.
+-- Injected by the compiler when src/ui/ exists. Provides _UIAdapter to layout
+-- and page files. _Library / _ThemeManager / _SaveManager are available as
+-- upvalues to all subsequent files (Settings.lua, etc.) via flat compilation.
+
+local _LIB_URL   = "https://raw.githubusercontent.com/violin-suzutsuki/LinoriaLib/main/Library.lua"
+local _THEME_URL = "https://raw.githubusercontent.com/violin-suzutsuki/LinoriaLib/main/addons/ThemeManager.lua"
+local _SAVE_URL  = "https://raw.githubusercontent.com/violin-suzutsuki/LinoriaLib/main/addons/SaveManager.lua"
+
+-- Safe filesystem wrappers — some executors error instead of returning nil
+do
+    local _mf = makefolder or function() end
+    makefolder = function(p) pcall(_mf, p) end
+
+    local _wf = writefile or function() end
+    writefile = function(p, d) pcall(_wf, p, d) end
+
+    local _rf = readfile or function() return "" end
+    readfile = function(p)
+        local ok, r = pcall(_rf, p)
+        return ok and r or ""
+    end
+
+    local _iff = isfolder or function() return false end
+    isfolder = function(p)
+        local ok, r = pcall(_iff, p)
+        return ok and r or false
+    end
+
+    local _isf = isfile or function() return false end
+    isfile = function(p)
+        local ok, r = pcall(_isf, p)
+        return ok and r or false
+    end
+
+    local _df = delfile or function() end
+    delfile = function(p) pcall(_df, p) end
+end
+
+local function _loadLib(url, name)
+    local ok, src = pcall(game.HttpGet, game, url)
+    if not ok then error("[AOT-R] HTTP failed for " .. name .. ": " .. tostring(src)) end
+    if type(src) ~= "string" or #src < 50 then
+        error("[AOT-R] Empty response for " .. name)
+    end
+    local fn, err = loadstring(src)
+    if not fn then error("[AOT-R] Compile failed for " .. name .. ": " .. tostring(err)) end
+    local ok2, result = pcall(fn)
+    if not ok2 then error("[AOT-R] Init failed for " .. name .. ": " .. tostring(result)) end
+    return result
+end
+
+local _Library      = _loadLib(_LIB_URL,   "Library")
+local _ThemeManager = _loadLib(_THEME_URL, "ThemeManager")
+local _SaveManager  = _loadLib(_SAVE_URL,  "SaveManager")
+
+-- ── Adapter ───────────────────────────────────────────────────────────────────
+
+local _UIS = game:GetService("UserInputService")
+local _UIAdapter = {}
+
+function _UIAdapter:CreateWindow(title, w, h, opts)
+    -- opts table from layout (theme/folder/notify_title) — Linoria handles
+    -- folder via ThemeManager/SaveManager in the settings page, not here.
+    return _Library:CreateWindow({
+        Title        = title,
+        Center       = true,
+        AutoShow     = true,
+        TabPadding   = 8,
+        MenuFadeTime = 0.2,
+    })
+end
+
+function _UIAdapter:RegisterTheme(_t) end   -- no-op for Linoria builds
+
+function _UIAdapter:GetThemeNames() return nil end  -- Linoria manages its own themes
+
+function _UIAdapter:SetToggleKey(keyCode)
+    _Library.ToggleKey = keyCode
+end
+
+-- ── Widget constructors ───────────────────────────────────────────────────────
+
+function _UIAdapter:addToggle(gb, id, opts)
+    -- opts: { label, signal, tip }
+    gb:AddToggle(id, {
+        Text     = opts.label,
+        Default  = opts.signal(),
+        Tooltip  = opts.tip or "",
+        Callback = function(v) opts.signal(v) end,
+    })
+    -- reverse: signal changes → update Linoria widget
+    opts.signal:onChange(function(v)
+        local t = Toggles and Toggles[id]
+        if t then t:SetValue(v) end
+    end)
+end
+
+function _UIAdapter:addSlider(gb, id, opts)
+    -- opts: { label, signal, min, max, tip, rounding? }
+    gb:AddSlider(id, {
+        Text     = opts.label,
+        Default  = opts.signal(),
+        Min      = opts.min,
+        Max      = opts.max,
+        Rounding = opts.rounding or 1,
+        Compact  = false,
+        Tooltip  = opts.tip or "",
+        Callback = function(v) opts.signal(v) end,
+    })
+    opts.signal:onChange(function(v)
+        local t = Options and Options[id]
+        if t then t:SetValue(v) end
+    end)
+end
+
+function _UIAdapter:addDropdown(gb, id, opts)
+    -- opts: { label, signal, options, tip }
+    gb:AddDropdown(id, {
+        Text     = opts.label,
+        Values   = opts.options,
+        Default  = opts.signal(),
+        Tooltip  = opts.tip or "",
+        Callback = function(v) opts.signal(v) end,
+    })
+    opts.signal:onChange(function(v)
+        local t = Options and Options[id]
+        if t then t:SetValue(v) end
+    end)
+end
+
+function _UIAdapter:addMultiDropdown(gb, id, opts)
+    -- opts: { label, signal, options, tip }
+    gb:AddDropdown(id, {
+        Text     = opts.label,
+        Values   = opts.options,
+        Default  = {},
+        Multi    = true,
+        Tooltip  = opts.tip or "",
+        Callback = function(v) opts.signal(v) end,
+    })
+    opts.signal:onChange(function(v)
+        local t = Options and Options[id]
+        if t then t:SetValue(v) end
+    end)
+end
+
+function _UIAdapter:addButton(gb, opts)
+    -- opts: { label, action, tip? }
+    gb:AddButton(opts.label, opts.action)
+end
+
+function _UIAdapter:addKeybind(gb, id, opts)
+    -- opts: { label, key, action }
+    gb:AddLabel(opts.label):AddKeyPicker(id, {
+        Default         = opts.key,
+        SyncToggleState = false,
+        Mode            = "Toggle",
+        Text            = opts.label,
+        Callback        = function()
+            -- Skip if the player is typing in any TextBox (chat, search, etc.)
+            if _UIS:GetFocusedTextBox() then return end
+            opts.action()
+        end,
+    })
+end
+
+function _UIAdapter:addLabel(gb, text)
+    gb:AddLabel(text)
+end
+
+function _UIAdapter:addParagraph(gb, title, desc)
+    gb:AddLabel(title)
+    if desc and desc ~= "" then
+        gb:AddLabel(desc)
+    end
+end
+
+function _UIAdapter:addSeparator(gb)
+    gb:AddBlank(6)
+end
+
+-- Notify — adapter-agnostic function called by the defaults runner.
+_PulseNotify = function(msg, duration)
+    pcall(function() _Library:Notify(msg, duration or 5) end)
+end
+
+-- Register Linoria teardown with the Pulse destroy system.
+-- _PulseDestroy() will call this before unmounting components.
+_PulseOnDestroy(function()
+    pcall(function()
+        if _Library.Unload then
+            _Library:Unload()
+        elseif _Library.GUI then
+            _Library.GUI:Destroy()
+        end
+    end)
+end)
+
+-- ── Mount a component's _ui table into a groupbox ────────────────────────────
+
+function _UIAdapter:mount(component, gb)
+    if not component then return end
+    local ui = component._ui
+    if not ui then return end
+    for _, w in ipairs(ui) do
+        local t   = w.type
+        local sig = component[w.signal]   -- Signal callable (nil for button/label/separator)
+        if t == "toggle" then
+            self:addToggle(gb, w.id, { label = w.label, signal = sig, tip = w.tip })
+        elseif t == "slider" then
+            self:addSlider(gb, w.id, { label = w.label, signal = sig,
+                                       min = w.min, max = w.max, tip = w.tip })
+        elseif t == "dropdown" then
+            self:addDropdown(gb, w.id, { label = w.label, signal = sig,
+                                         options = w.options, tip = w.tip })
+        elseif t == "multidropdown" then
+            self:addMultiDropdown(gb, w.id, { label = w.label, signal = sig,
+                                              options = w.options, tip = w.tip })
+        elseif t == "button" then
+            self:addButton(gb, { label = w.label, action = w.action })
+        elseif t == "keybind" then
+            self:addKeybind(gb, w.id, { label = w.label, key = w.key, action = w.action })
+        elseif t == "label" then
+            self:addLabel(gb, w.label)
+        elseif t == "paragraph" then
+            self:addParagraph(gb, w.title, w.desc)
+        elseif t == "separator" then
+            self:addSeparator(gb)
+        end
+    end
+end