@rb-pulse/core 1.2.24 → 1.3.1

package/index.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @rb-pulse/core — TypeScript declarations for the Pulse Roblox scripting framework.
+ *
+ * Add `"types": ["@rb-pulse/core"]` to your tsconfig `compilerOptions` and every
+ * Pulse global (`signal`, `defineComponent`, `on.*`, widget factories, `Pulse`, …)
+ * plus the full Roblox API (`game`, `workspace`, `task`, all instance types, …)
+ * become available in every `.ts` file without any imports.
+ *
+ * Package layout:
+ *   types/signals.d.ts    — PulseSignal<T>, signal(), computed()
+ *   types/events.d.ts     — HandlerOpts, on.* subscriptions
+ *   types/widgets.d.ts    — widget interfaces + factory functions
+ *   types/components.d.ts — defineComponent, definePage, groupbox, LayoutConfig
+ *   types/runtime.d.ts    — Pulse namespace, _PulseGet* character helpers
+ *
+ * Roblox API types are provided by @rbxts/types (auto-included — no extra config needed).
+ *
+ * @example tsconfig.json
+ * {
+ *   "compilerOptions": {
+ *     "strict": true,
+ *     "noEmit": true,
+ *     "skipLibCheck": true,
+ *     "target": "ESNext",
+ *     "moduleResolution": "bundler",
+ *     "types": ["@rb-pulse/core"]
+ *   }
+ * }
+ */
+
+// Pulse framework globals
+/// <reference path="./types/globals.d.ts" />
+/// <reference path="./types/signals.d.ts" />
+/// <reference path="./types/events.d.ts" />
+/// <reference path="./types/widgets.d.ts" />
+/// <reference path="./types/components.d.ts" />
+/// <reference path="./types/runtime.d.ts" />
+
+// ── Named re-exports ───────────────────────────────────────────────────────────
+// Globals are already available without imports (via declare global above).
+// These re-exports let you use explicit `import type` when you want visible types
+// in function signatures, generics, or cross-file type sharing.
+//
+// @example
+// import type { PulseSignal, WidgetDef, LayoutConfig } from '@rb-pulse/core'
+
+export type { PulseSignal } from './types/signals'
+export type { HandlerOpts } from './types/events'
+export type {
+  ToggleDef,
+  SliderDef,
+  DropdownDef,
+  MultiDropdownDef,
+  ButtonDef,
+  KeybindDef,
+  LabelDef,
+  SeparatorDef,
+  WidgetDef,
+} from './types/widgets'
+export type {
+  ComponentRef,
+  GroupboxDef,
+  PageDef,
+  LayoutConfig,
+} from './types/components'

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@rb-pulse/core",
-  "version": "1.2.24",
-  "description": "Pulse framework — component, signal, and event TypeScript API",
-  "main": "./index.ts",
-  "types": "./index.ts",
+  "version": "1.3.1",
+  "description": "Pulse framework — TypeScript type declarations for components, signals, widgets, and the Roblox API",
+  "types": "./index.d.ts",
   "files": [
-    "index.ts",
-    "*.d.ts"
+    "index.d.ts",
+    "types/"
   ],
   "keywords": [
     "roblox",
     "pulse",
     "lua",
-    "typescript-to-lua"
+    "typescript-to-lua",
+    "types"
   ],
   "license": "MIT"
 }

package/types/components.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Component system, page layout, and window configuration.
+ *
+ * - `defineComponent` — SolidJS-style reactive component setup
+ * - `definePage`      — Next.js-style file-based page tabs
+ * - `groupbox`        — column layout declaration inside a page
+ * - `LayoutConfig`    — export default from `src/layout.ts`
+ */
+
+/// <reference path="./widgets.d.ts" />
+
+declare global {
+
+  // ── Component ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Opaque handle returned by `defineComponent`.
+   * Pass to `groupbox({ mount: 'ComponentName' })` to render its widgets.
+   */
+  interface ComponentRef {
+    readonly _name: string
+    readonly _ui:   WidgetDef[]
+  }
+
+  /**
+   * Register a reactive component.
+   *
+   * The `setup` function runs once on init. Declare signals, register `on.*`
+   * event handlers, then return an array of widget definitions. All event
+   * connections are auto-disconnected when the script re-executes or the
+   * component is destroyed (re-execution guard handles this automatically).
+   *
+   * Components mirror SolidJS function components: pure setup, reactive state,
+   * declarative UI return.
+   *
+   * @example
+   * defineComponent('SpeedHack', (): WidgetDef[] => {
+   *   const enabled = signal<boolean>(false)
+   *   const speed   = signal<number>(16)
+   *
+   *   on.heartbeat({ when: enabled }, (): void => {
+   *     const h = _PulseGetHumanoid() as any
+   *     if (h) h.WalkSpeed = speed()
+   *   })
+   *
+   *   return [
+   *     toggle('Speed Hack').bind(enabled),
+   *     slider('Walk Speed', { min: 16, max: 250 }).bind(speed),
+   *   ]
+   * })
+   */
+  function defineComponent(name: string, setup: () => WidgetDef[]): ComponentRef
+
+  // ── Page layout ────────────────────────────────────────────────────────────────
+
+  /**
+   * Groupbox column inside a page layout.
+   * Use `mount` to attach a named component's widgets, or `widgets` for inline widgets.
+   */
+  interface GroupboxDef {
+    readonly type:    'groupbox'
+    readonly side:    'left' | 'right'
+    readonly title:   string
+    readonly icon:    string
+    readonly mount?:  string
+  }
+
+  /** Page tab descriptor returned by `definePage`. */
+  interface PageDef {
+    readonly title:   string
+    readonly icon:    string
+    readonly layout:  GroupboxDef[]
+  }
+
+  /**
+   * Declare a groupbox column inside a `definePage` factory.
+   *
+   * @param side    Column position — `'left'` or `'right'`
+   * @param title   Header text of the groupbox
+   * @param opts    `icon` for a lucide icon name; `mount` to attach a component by name;
+   *                `widgets` for inline widget declarations without a component
+   *
+   * @example
+   * groupbox('left',  'Player',  { icon: 'person',  mount: 'SpeedHack' })
+   * groupbox('right', 'Visuals', { icon: 'eye',     mount: 'PlayerESP' })
+   */
+  function groupbox(side: 'left' | 'right', title: string, opts?: {
+    icon?:    string
+    mount?:   string
+    widgets?: WidgetDef[]
+  }): GroupboxDef
+
+  /**
+   * Declare a page tab. Place in `src/pages/N_Name.ts`.
+   *
+   * Tab order follows the numeric filename prefix: `1_Home.ts`, `2_Combat.ts`, …
+   * This mirrors the Next.js file-based routing convention.
+   *
+   * @example
+   * // src/pages/1_Home.ts
+   * definePage('Home', { icon: 'house' }, () => [
+   *   groupbox('left',  'Player',  { mount: 'SpeedHack' }),
+   *   groupbox('right', 'Visuals', { mount: 'PlayerESP' }),
+   * ])
+   */
+  function definePage(
+    title:   string,
+    opts:    { icon?: string },
+    factory: () => GroupboxDef[],
+  ): PageDef
+
+  // ── Layout configuration ───────────────────────────────────────────────────────
+
+  /**
+   * Window/layout configuration — export as `default` from `src/layout.ts`.
+   * Drives the UI window title, size, theme, and UI library selection.
+   *
+   * @example
+   * // src/layout.ts
+   * export default {
+   *   title:     'My Script',
+   *   author:    'YourName',
+   *   uiLibrary: 'windui',
+   *   size:      [850, 560],
+   *   theme:     'Indigo',
+   *   folder:    'MyHub',
+   * } satisfies LayoutConfig
+   */
+  interface LayoutConfig {
+    /** Window title displayed in the UI header. */
+    title:                 string
+    /** Author subtitle shown below the title. */
+    author?:               string
+    /** Key to toggle the UI open/closed. @default 'RightControl' */
+    toggleKey?:            string
+    /** Window dimensions `[width, height]` in pixels. @default [950, 600] */
+    size?:                 [number, number]
+    /** UI library to use. Currently only `'windui'` is supported. */
+    uiLibrary?:            'windui'
+    /** Theme name (library-specific, e.g. `'Indigo'`, `'Dark'`). */
+    theme?:                string
+    /** Lucide icon name or asset URL for the window icon. */
+    icon?:                 string
+    /** Config save folder name (inside executor workspace). */
+    folder?:               string
+    /** Enable acrylic/frosted glass background effect. */
+    acrylic?:              boolean
+    /** Background transparency `[0, 1]`. */
+    transparency?:         number
+    /** Show the open button only on mobile. */
+    openButtonMobileOnly?: boolean
+    /** Icon for the mobile open button. */
+    openButtonIcon?:       string
+    /** Custom theme overrides. */
+    themes?:               Array<{ name: string; values: Record<string, string> }>
+    /** File paths to exclude from the compat build. */
+    compatExclude?:        string[]
+  }
+
+}
+
+export type { ComponentRef, GroupboxDef, PageDef, LayoutConfig }

package/types/events.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Event subscription system — RunService, UserInputService, and signal watchers.
+ * All connections are automatically cleaned up when the enclosing component is destroyed.
+ * Must be called inside a `defineComponent` setup function.
+ */
+
+// Reference signal types so HandlerOpts can reference PulseSignal<T>
+/// <reference path="./signals.d.ts" />
+
+declare global {
+
+  /**
+   * Options for periodic event handlers.
+   * Both fields are optional — omit entirely to run every frame with no guard.
+   */
+  interface HandlerOpts {
+    /**
+     * Gate signal — while `false` the callback is skipped each frame.
+     * The connection stays alive; toggling to `true` resumes immediately.
+     *
+     * @example on.heartbeat({ when: enabled }, dt => doWork())
+     */
+    when?: PulseSignal<boolean>
+
+    /**
+     * Throttle — minimum seconds between callback invocations.
+     * Pass a `PulseSignal<number>` for live adjustment at runtime.
+     * @default 0  (every frame)
+     */
+    every?: number | PulseSignal<number>
+  }
+
+  /**
+   * Event subscription namespace.
+   *
+   * All connections registered via `on.*` are scoped to the current component
+   * and auto-disconnected when the script re-executes or the component is destroyed.
+   *
+   * @example
+   * defineComponent('SpeedHack', (): WidgetDef[] => {
+   *   const enabled = signal<boolean>(false)
+   *
+   *   on.heartbeat({ when: enabled }, dt => applySpeed())
+   *   on.respawn(() => resetSpeed())
+   *   on.signal(enabled, v => console.log('enabled:', v))
+   *
+   *   return [toggle('Speed Hack').bind(enabled)]
+   * })
+   */
+  const on: {
+    /**
+     * RunService.Heartbeat — fires every physics frame (~60 fps).
+     * Equivalent to SolidJS `createEffect` scoped to the RunService.Heartbeat event.
+     *
+     * @example
+     * on.heartbeat({ when: enabled, every: 0.1 }, dt => doWork())
+     * on.heartbeat(dt => updateDisplay(dt))
+     */
+    heartbeat(opts: HandlerOpts, fn: (dt: number) => void): void
+    heartbeat(fn: (dt: number) => void): void
+
+    /**
+     * RunService.RenderStepped — fires before every render frame (client-only).
+     * Use for camera/visual updates that must sync with rendering.
+     */
+    renderStepped(opts: HandlerOpts, fn: (dt: number) => void): void
+    renderStepped(fn: (dt: number) => void): void
+
+    /**
+     * RunService.Stepped — fires at the physics step rate.
+     * Provides both elapsed time and delta time.
+     */
+    stepped(opts: HandlerOpts, fn: (time: number, dt: number) => void): void
+    stepped(fn: (time: number, dt: number) => void): void
+
+    /** UserInputService.InputBegan — fires when any input starts. */
+    inputBegan(fn: (input: any, gameProcessed: boolean) => void): void
+
+    /** UserInputService.InputEnded — fires when any input ends. */
+    inputEnded(fn: (input: any, gameProcessed: boolean) => void): void
+
+    /** Fires each time the local player's character model is added to the world. */
+    respawn(fn: () => void): void
+
+    /** Player.CharacterAdded — fires when a new character model appears. */
+    characterAdded(fn: (character: any) => void): void
+
+    /** Player.CharacterRemoving — fires just before the character is removed. */
+    characterRemoving(fn: (character: any) => void): void
+
+    /**
+     * Subscribe to a `PulseSignal` inside a component.
+     * Fires immediately with the current value, then on every change.
+     * The subscription is auto-cleaned with the component.
+     *
+     * @example
+     * on.signal(speed, v => applySpeed(v))
+     */
+    signal<T>(sig: PulseSignal<T>, fn: (val: T) => void): void
+
+    /**
+     * One-shot callback after a delay in seconds.
+     * @example on.after(0.5, () => init())
+     */
+    after(seconds: number, fn: () => void): void
+  }
+
+}
+
+export type { HandlerOpts }

package/types/globals.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Roblox Lua globals not declared by @rbxts/types.
+ *
+ * roblox-ts accesses the workspace via `game.Workspace`, but in standard Roblox
+ * Lua (and executor environments) it is also available as the `workspace` global.
+ * We declare it here so TypeScript recognises it in Pulse scripts.
+ */
+
+declare global {
+
+  /**
+   * Alias for `game:GetService("Workspace")`.
+   * Provides access to the current place's Workspace service.
+   *
+   * @example
+   * const cam = workspace.CurrentCamera
+   * cam.FieldOfView = 90
+   */
+  const workspace: Workspace
+
+  /**
+   * The shared Lua global table.
+   * Used internally by the compiler to propagate runtime globals across
+   * sandboxed `loadstring` environments in executor contexts.
+   */
+  const _G: Record<string, unknown>
+
+  /**
+   * Print to the output console (Roblox Studio / executor output).
+   * Accepts any number of values, separated by tabs in the output.
+   */
+  function print(...args: unknown[]): void
+
+}
+
+export {}

package/types/runtime.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Pulse runtime globals — the `Pulse` namespace and character helper functions.
+ * These are set up automatically by the CDN bundle before your code runs.
+ */
+
+declare global {
+
+  // ── Pulse runtime namespace ────────────────────────────────────────────────────
+
+  /**
+   * The Pulse runtime namespace.
+   * Populated by the CDN bundle and extended by the adapter (Wind UI).
+   *
+   * `Pulse.UI` is available after the Wind UI adapter initialises the window.
+   * `Pulse.Log` and `Pulse.TestMode` are always available.
+   */
+  const Pulse: {
+    /**
+     * Dynamic element builder — populated by the Wind UI adapter.
+     * Use this for advanced manual UI construction beyond the standard widget set.
+     */
+    UI: {
+      /** Get the mounted groupbox container for a component reference. */
+      gb(component: ComponentRef): any
+      /** Add a rich paragraph (title + description) to a container. */
+      paragraph(
+        container: any,
+        title:     string,
+        desc:      string,
+      ): { set(title?: string, desc?: string): void }
+      /** Add a button to a container. */
+      button(container: any, label: string, desc: string, fn: () => void): any
+      /** Add a toggle to a container. */
+      toggle(
+        container:   any,
+        id:          string,
+        label:       string,
+        desc:        string,
+        defaultVal:  boolean,
+        fn:          (v: boolean) => void,
+      ): any
+      /** Add a slider to a container. */
+      slider(
+        container:   any,
+        id:          string,
+        label:       string,
+        min:         number,
+        max:         number,
+        defaultVal:  number,
+        fn:          (v: number) => void,
+      ): any
+      /** Add a dropdown to a container. */
+      dropdown(
+        container:   any,
+        id:          string,
+        label:       string,
+        options:     string[],
+        defaultVal:  string | undefined,
+        multi:       boolean,
+        fn:          (v: string | string[]) => void,
+      ): any
+      /** Add a collapsible section group to a container. */
+      section(container: any, title: string, icon?: string): any
+    }
+
+    /** Structured logging helpers. */
+    Log: {
+      info(tag: string, msg: string, data?: Record<string, unknown>): void
+      warn(tag: string, msg: string, data?: Record<string, unknown>): void
+      error(tag: string, msg: string, data?: Record<string, unknown>): void
+    }
+
+    /** Automated test-mode helpers (used by the test harness). */
+    TestMode: {
+      isActive(): boolean
+      isTarget(id: string): boolean
+      getTargets(): string[]
+    }
+  }
+
+  // ── Character helper functions ─────────────────────────────────────────────────
+  // Safe wrappers around LocalPlayer.Character — all return undefined if the
+  // character or the specific instance is not present.
+
+  /** Returns `LocalPlayer.Character` or `undefined`. */
+  function _PulseGetChar(): Instance | undefined
+
+  /** Returns `HumanoidRootPart` from the local character, or `undefined`. */
+  function _PulseGetHRP(): BasePart | undefined
+
+  /** Returns `Humanoid` from the local character, or `undefined`. */
+  function _PulseGetHumanoid(): Humanoid | undefined
+
+  /** Returns `true` while the local humanoid's health is above zero. */
+  function _PulseGetAlive(): boolean
+
+}
+
+export {}

package/types/signals.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Reactive signal primitives — SolidJS-style state atoms.
+ * No imports needed: these are Lua globals available in every Pulse script.
+ */
+
+declare global {
+
+  /**
+   * Reactive state cell returned by `signal<T>()`.
+   *
+   * Call it (no args) to read the current value. Calling `.set()` pushes a new
+   * value and propagates it to every bound UI widget, `on.*` guard, and watcher.
+   *
+   * Mirrors SolidJS `createSignal` but as a single callable object instead of a
+   * getter/setter tuple.
+   *
+   * @example
+   * const enabled = signal<boolean>(false)
+   * const speed   = signal<number>(16)
+   *
+   * enabled()             // → false   (read)
+   * enabled.set(true)     // write, triggers watchers
+   * enabled.toggle()      // flip boolean in-place
+   * speed.update(v => v + 1)
+   */
+  interface PulseSignal<T> {
+    /** Read the current value. */
+    (): T
+
+    /** Write a new value. No-op if the value hasn't changed. */
+    set(this: PulseSignal<T>, value: T): void
+
+    /**
+     * Toggle a boolean signal in-place (`sig.set(!sig())`).
+     * Type-constrained to `PulseSignal<boolean>`.
+     */
+    toggle(this: PulseSignal<boolean>): void
+
+    /**
+     * Subscribe to value changes.
+     * Fires immediately with the current value, then on every subsequent change.
+     * @returns Unsubscribe function — call to stop the subscription.
+     */
+    watch(this: PulseSignal<T>, fn: (value: T) => void): () => void
+
+    /**
+     * Apply a transform and write the result.
+     * @example speed.update(v => v + 10)
+     */
+    update(this: PulseSignal<T>, fn: (current: T) => T): void
+  }
+
+  /**
+   * Create a reactive state cell with an initial value.
+   * Always use an explicit generic so TypeScript infers the correct type.
+   *
+   * @example
+   * const enabled = signal<boolean>(false)
+   * const speed   = signal<number>(16)
+   * const mode    = signal<string>('Low')
+   * const targets = signal<string[]>([])
+   */
+  function signal<T>(initialValue: T): PulseSignal<T>
+
+  /**
+   * Create a read-only derived value that recomputes lazily when its dependencies
+   * change. The result is cached until invalidated.
+   *
+   * @example
+   * const displaySpeed = computed(() => `Speed: ${speed()}x`)
+   * label(displaySpeed())
+   */
+  function computed<T>(fn: () => T): () => T
+
+}
+
+export type { PulseSignal }

package/types/widgets.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Widget definitions and factory functions.
+ * Every factory returns a builder that you chain to configure and optionally bind to a signal.
+ * Return an array of widget defs from `defineComponent` to render them into the UI.
+ */
+
+/// <reference path="./signals.d.ts" />
+
+declare global {
+
+  // ── Widget interfaces ──────────────────────────────────────────────────────────
+
+  /**
+   * Toggle (checkbox) bound to a `PulseSignal<boolean>`.
+   * @example toggle('Speed Hack').bind(enabled)
+   */
+  interface ToggleDef {
+    /** Two-way bind to a boolean signal — UI changes update the signal, signal changes update UI. */
+    bind(this: ToggleDef, sig: PulseSignal<boolean>): ToggleDef
+    /** Tooltip text shown on hover. */
+    withTip(this: ToggleDef, text: string): ToggleDef
+    /** Persisted default value loaded from config on startup. */
+    withDefault(this: ToggleDef, v: boolean): ToggleDef
+  }
+
+  /**
+   * Slider (range input) bound to a `PulseSignal<number>`.
+   * @example slider('Walk Speed', { min: 16, max: 250 }).bind(speed)
+   */
+  interface SliderDef {
+    /** Two-way bind to a numeric signal. */
+    bind(this: SliderDef, sig: PulseSignal<number>): SliderDef
+    /** Tooltip text shown on hover. */
+    withTip(this: SliderDef, text: string): SliderDef
+    /** Persisted default value loaded from config on startup. */
+    withDefault(this: SliderDef, v: number): SliderDef
+  }
+
+  /**
+   * Dropdown (single-select) bound to a `PulseSignal<string>`.
+   * @example dropdown('Mode', { options: ['Low', 'High'] }).bind(mode)
+   */
+  interface DropdownDef {
+    /** Two-way bind to a string signal. */
+    bind(this: DropdownDef, sig: PulseSignal<string>): DropdownDef
+    /** Tooltip text shown on hover. */
+    withTip(this: DropdownDef, text: string): DropdownDef
+    /** Persisted default selected option. */
+    withDefault(this: DropdownDef, v: string): DropdownDef
+    /** Replace the option list at runtime (e.g. after fetching players). */
+    withOptions(this: DropdownDef, opts: string[]): DropdownDef
+  }
+
+  /**
+   * Multi-select dropdown bound to a `PulseSignal<string[]>`.
+   * @example multidropdown('Targets', { options: ['Player', 'NPC'] }).bind(targets)
+   */
+  interface MultiDropdownDef {
+    /** Two-way bind to a string-array signal. */
+    bind(this: MultiDropdownDef, sig: PulseSignal<string[]>): MultiDropdownDef
+    /** Tooltip text shown on hover. */
+    withTip(this: MultiDropdownDef, text: string): MultiDropdownDef
+    /** Persisted default selections. */
+    withDefault(this: MultiDropdownDef, v: string[]): MultiDropdownDef
+    /** Replace the option list at runtime. */
+    withOptions(this: MultiDropdownDef, opts: string[]): MultiDropdownDef
+  }
+
+  /**
+   * Button — triggers a callback when clicked.
+   * @example button('Reset', () => speed.set(16))
+   */
+  interface ButtonDef {
+    /** Register the click handler. Can be chained. */
+    onClick(this: ButtonDef, fn: () => void): ButtonDef
+    /** Satisfies `WidgetDef` — returns self. */
+    bind(this: ButtonDef): ButtonDef
+  }
+
+  /**
+   * Keybind — shows the current key and lets the user rebind it at runtime.
+   * @example keybind('Toggle UI', { key: 'RightControl' })
+   */
+  interface KeybindDef {
+    /** Two-way bind to a string signal tracking the current key name. */
+    bind(this: KeybindDef, sig: PulseSignal<string>): KeybindDef
+    /** Set the default key name (e.g. `'RightControl'`, `'F'`). */
+    withDefault(this: KeybindDef, key: string): KeybindDef
+  }
+
+  /**
+   * Static text label — non-interactive, just displays text.
+   * @example label('v1.3.1 — by YourName')
+   */
+  interface LabelDef {
+    /** Update the displayed text at runtime. */
+    setText(this: LabelDef, text: string): void
+  }
+
+  /** Horizontal divider line between widget groups. */
+  interface SeparatorDef {
+    readonly _type: 'separator'
+  }
+
+  /**
+   * Union of all renderable widget types.
+   * Use as the return type of the `defineComponent` setup function.
+   */
+  type WidgetDef =
+    | ToggleDef
+    | SliderDef
+    | DropdownDef
+    | MultiDropdownDef
+    | ButtonDef
+    | KeybindDef
+    | LabelDef
+    | SeparatorDef
+
+  // ── Widget factory functions ───────────────────────────────────────────────────
+
+  /**
+   * Create a toggle (checkbox) widget.
+   * Chain `.bind(signal)` to connect it to reactive state.
+   *
+   * @example
+   * toggle('Speed Hack').bind(enabled)
+   * toggle('Debug', { tip: 'Verbose logging', default: false }).bind(debug)
+   */
+  function toggle(label: string, opts?: { tip?: string; default?: boolean }): ToggleDef
+
+  /**
+   * Create a numeric slider widget.
+   *
+   * @example
+   * slider('Walk Speed', { min: 16, max: 250 }).bind(speed)
+   * slider('FOV', { min: 1, max: 120, suffix: '°', default: 70 }).bind(fov)
+   */
+  function slider(label: string, opts?: {
+    min?: number
+    max?: number
+    step?: number
+    default?: number
+    suffix?: string
+    tip?: string
+  }): SliderDef
+
+  /**
+   * Create a single-select dropdown widget.
+   *
+   * @example
+   * dropdown('Mode', { options: ['Silent', 'Normal', 'Loud'] }).bind(mode)
+   */
+  function dropdown(label: string, opts?: {
+    options?: string[]
+    default?: string
+    tip?: string
+  }): DropdownDef
+
+  /**
+   * Create a multi-select dropdown widget.
+   *
+   * @example
+   * multidropdown('Bypass', { options: ['AntiCheat', 'Logger'] }).bind(bypass)
+   */
+  function multidropdown(label: string, opts?: {
+    options?: string[]
+    default?: string[]
+    tip?: string
+  }): MultiDropdownDef
+
+  /**
+   * Create a button widget.
+   *
+   * @example
+   * button('Reset Speed', () => speed.set(16))
+   * button('Open Menu').onClick(() => openMenu())
+   */
+  function button(label: string, fn: () => void, opts?: { tip?: string }): ButtonDef
+  function button(label: string, opts?: { tip?: string }): ButtonDef
+
+  /**
+   * Create a user-rebindable keybind widget.
+   *
+   * @example
+   * keybind('Toggle', { key: 'RightControl' })
+   */
+  function keybind(label: string, opts?: { key?: string; tip?: string }): KeybindDef
+
+  /**
+   * Create a static text label widget.
+   *
+   * @example label('v1.3.1')
+   */
+  function label(text: string): LabelDef
+
+  /**
+   * Insert a horizontal separator line between widgets.
+   *
+   * @example separator()
+   */
+  function separator(): SeparatorDef
+
+}
+
+export type {
+  ToggleDef, SliderDef, DropdownDef, MultiDropdownDef,
+  ButtonDef, KeybindDef, LabelDef, SeparatorDef, WidgetDef,
+}

package/index.ts

@@ -1,399 +0,0 @@
-/**
- * @pulse/core — Component, signal, and event API for Pulse framework scripts.
- *
- * Write game scripts in TypeScript; compile to Lua via `rb build`.
- * Every API maps 1-to-1 to the Pulse Lua runtime.
- *
- * @example
- * ```typescript
- * import { defineComponent, signal, on } from '@pulse/core'
- * import { toggle, slider } from '@pulse/ui'
- *
- * export const KillAura = defineComponent(() => {
- *   const enabled = signal(false)
- *   const range   = signal(50)
- *
- *   on.heartbeat({ when: enabled, every: 0.1 }, dt => {
- *     // runs every 0.1 s while enabled === true
- *   })
- *
- *   return [
- *     toggle('Kill Aura').bind(enabled),
- *     slider('Range', { min: 1, max: 500 }).bind(range),
- *   ]
- * })
- * ```
- */
-
-// ── Signal ─────────────────────────────────────────────────────────────────────
-
-/**
- * Reactive state cell returned by `signal()`.
- *
- * Call it to read the current value; use `.set()` to write.
- * Changes automatically propagate to UI widgets, event guards, and watchers.
- *
- * Compiles to: `Signal(initialValue)` in Lua.
- */
-export interface Signal<T> {
-  /** Read the current value. Compiles to: `signalName()` */
-  (): T
-  /**
-   * Write a new value. Triggers UI, handler, and watcher updates.
-   * Compiles to: `signalName.set(value)`
-   */
-  set(value: T): void
-  /**
-   * Toggle the signal value (boolean signals only).
-   * Equivalent to `signal.set(!signal())`.
-   * Compiles to: `signalName.toggle()`
-   *
-   * @example
-   * const enabled = signal(false)
-   * button('Toggle').onClick(() => enabled.toggle())
-   */
-  toggle(this: Signal<boolean>): void
-  /**
-   * Subscribe to value changes. The callback fires immediately with the
-   * current value, then on every subsequent change.
-   * Returns an unsubscribe function.
-   * Compiles to: `signalName.watch(fn)`
-   *
-   * @example
-   * const unsubscribe = enabled.watch(v => {
-   *   print('enabled changed to', v)
-   * })
-   * // later: unsubscribe()
-   */
-  watch(fn: (value: T) => void): () => void
-  /**
-   * Mirror this signal's value into another signal on every change.
-   * Useful for propagating values across component boundaries.
-   * Compiles to: `signalName.mirror(target)`
-   */
-  mirror(target: Signal<T>): void
-}
-
-/**
- * Derived signal — recomputes when any signal read inside `fn` changes.
- * Read-only; no `.set()`.
- *
- * Compiles to: `Computed(fn)` in Lua.
- */
-export interface Computed<T> {
-  (): T
-}
-
-// ── Event options ──────────────────────────────────────────────────────────────
-
-/**
- * Options for periodic event handlers (`on.heartbeat`, `on.renderStepped`, `on.stepped`).
- * Both fields are optional — omit entirely to run every frame with no guard.
- */
-export interface HandlerOpts {
-  /**
-   * Gate: skip the callback while this signal is `false`.
-   * The event connection stays alive but the callback is skipped.
-   * Compiles to: `when = signalName` in the event binding.
-   */
-  when?: Signal<boolean>
-  /**
-   * Throttle: minimum seconds between callback invocations.
-   * Uses an internal accumulator — does not create extra connections.
-   * Accepts a number or a reactive `Signal<number>` for live adjustment.
-   * Compiles to: `every = value` in the event binding.
-   *
-   * @default 0  (every frame)
-   */
-  every?: number | Signal<number>
-}
-
-// ── Widget base ────────────────────────────────────────────────────────────────
-
-/** Base interface shared by all widget definitions returned from `defineComponent`. */
-export interface WidgetDef {
-  /**
-   * Bind this widget to a signal so their values stay in sync.
-   * The widget writes the signal on user interaction; the signal
-   * drives the widget when set programmatically.
-   */
-  bind(signal: Signal<any>): this
-}
-
-// ── Component ──────────────────────────────────────────────────────────────────
-
-/** Setup function type for `defineComponent`. */
-export type ComponentSetup = () => WidgetDef[]
-
-/**
- * Opaque component handle returned by `defineComponent`.
- * Pass it to `groupbox({ mount: MyComponent })` to embed its widgets.
- */
-export interface Component<S extends ComponentSetup> {
-  readonly _type:    'component'
-  readonly _widgets: ReturnType<S>
-}
-
-// ── Core API ───────────────────────────────────────────────────────────────────
-
-/**
- * Define a Pulse component — the primary building block.
- *
- * The setup function runs once on initialisation.
- * Declare signals, register event handlers with `on.*`, then return an array
- * of widget definitions to mount into the component's groupbox.
- * All `on.*` subscriptions are auto-disconnected when the component is destroyed.
- *
- * Compiles to a self-contained Lua IIFE with Signal/bind wiring.
- *
- * @param setup  Called once at init. Returns UI widget array.
- *
- * @example
- * export const SpeedHack = defineComponent(() => {
- *   const enabled = signal(false)
- *   const speed   = signal(16)
- *
- *   on.heartbeat({ when: enabled }, () => {
- *     // manipulate character walkspeed
- *   })
- *
- *   on.respawn(() => {
- *     if (enabled()) applySpeed(speed())
- *   })
- *
- *   return [
- *     toggle('Speed hack').bind(enabled),
- *     slider('Speed', { min: 1, max: 250, suffix: ' studs/s' }).bind(speed),
- *   ]
- * })
- */
-export declare function defineComponent<S extends ComponentSetup>(setup: S): Component<S>
-
-/**
- * Create a reactive state cell with an initial value.
- *
- * Compiles to: `Signal(initialValue)` in Lua.
- *
- * @param initialValue  The starting value.
- *
- * @example
- * const enabled = signal(false)   // Signal<boolean>
- * const range   = signal(50)      // Signal<number>
- * const mode    = signal('Auto')  // Signal<string>
- *
- * enabled()           // read → false
- * enabled.set(true)   // write
- * enabled.toggle()    // flip boolean
- * enabled.watch(v => print(v))  // subscribe
- */
-export declare function signal<T>(initialValue: T): Signal<T>
-
-/**
- * Create a derived signal that recomputes automatically when its dependencies change.
- *
- * Compiles to: `Computed(fn)` in Lua.
- *
- * @param fn  Pure function reading one or more signals. Must not have side effects.
- *
- * @example
- * const fov   = signal(90)
- * const label = computed(() => `FOV: ${fov()}`)
- *
- * // Use in a toggle tooltip or paragraph widget
- * paragraph('Current FOV', label())
- */
-export declare function computed<T>(fn: () => T): Computed<T>
-
-// ── Event namespace ────────────────────────────────────────────────────────────
-
-/**
- * Event subscription namespace.
- * All connections are automatically cleaned up when the component is destroyed.
- *
- * @example
- * on.heartbeat({ when: enabled, every: 0.1 }, dt => { ... })
- * on.heartbeat(dt => updateDisplay(dt))           // no opts overload
- * on.signal(range, v => applyRange(v))            // signal watcher
- * on.inputBegan(input => handleKey(input))
- * on.respawn(() => reapplyEffects())
- * on.after(0.5, () => init())                     // delayed one-shot
- */
-export declare const on: {
-  /**
-   * RunService.Heartbeat — fires every frame.
-   *
-   * Compiles to: `on Heartbeat { when = ..., every = ... }` in .rblua.
-   *
-   * @param opts     Optional `when` guard and `every` throttle.
-   * @param fn       Callback invoked each (throttled) tick. Receives delta-time.
-   *
-   * @example
-   * // Throttled, gated
-   * on.heartbeat({ when: enabled, every: 0.1 }, dt => {
-   *   doWork()
-   * })
-   *
-   * // Every frame, no guard
-   * on.heartbeat(dt => updateDisplay(dt))
-   */
-  heartbeat(opts: HandlerOpts, fn: (dt: number) => void): void
-  heartbeat(fn: (dt: number) => void): void
-
-  /**
-   * RunService.RenderStepped — fires before every frame render (client only).
-   * Prefer `heartbeat` for game logic; use this for camera / visual work.
-   *
-   * @example
-   * on.renderStepped({ when: espEnabled }, dt => drawBoxes(dt))
-   * on.renderStepped(dt => updateCamera(dt))
-   */
-  renderStepped(opts: HandlerOpts, fn: (dt: number) => void): void
-  renderStepped(fn: (dt: number) => void): void
-
-  /**
-   * RunService.Stepped — fires at the physics step rate.
-   *
-   * @example
-   * on.stepped({ when: enabled }, (t, dt) => applyVelocity(dt))
-   */
-  stepped(opts: HandlerOpts, fn: (time: number, dt: number) => void): void
-  stepped(fn: (time: number, dt: number) => void): void
-
-  /**
-   * UserInputService.InputBegan.
-   *
-   * @example
-   * on.inputBegan((input, gpe) => {
-   *   if (gpe) return
-   *   if (input.KeyCode === Enum.KeyCode.X) enabled.toggle()
-   * })
-   */
-  inputBegan(fn: (input: InputObject, gameProcessed: boolean) => void): void
-
-  /**
-   * UserInputService.InputEnded.
-   *
-   * @example
-   * on.inputEnded(input => {
-   *   if (input.UserInputType === Enum.UserInputType.MouseButton1) release()
-   * })
-   */
-  inputEnded(fn: (input: InputObject, gameProcessed: boolean) => void): void
-
-  /**
-   * Fires when the player's character respawns.
-   * Use this to re-apply effects that attach to the character.
-   *
-   * @example
-   * on.respawn(() => {
-   *   if (enabled()) applySpeed(speed())
-   * })
-   */
-  respawn(fn: () => void): void
-
-  /**
-   * Player.CharacterAdded — fires when a new character model is added.
-   *
-   * @example
-   * on.characterAdded(char => {
-   *   const hrp = char.WaitForChild('HumanoidRootPart') as BasePart
-   * })
-   */
-  characterAdded(fn: (character: Model) => void): void
-
-  /**
-   * Player.CharacterRemoving — fires just before the character is removed.
-   *
-   * @example
-   * on.characterRemoving(() => cleanup())
-   */
-  characterRemoving(fn: (character: Model) => void): void
-
-  /**
-   * Subscribe to changes on a signal — fires immediately with the current value,
-   * then on every subsequent change. Part of component lifecycle (auto-disconnected).
-   *
-   * Compiles to: `on signalName { }` signal handler in .rblua.
-   *
-   * @param sig  The signal to watch.
-   * @param fn   Called with the new value on every change.
-   *
-   * @example
-   * on.signal(enabled, v => {
-   *   if (v) activateESP() else deactivateESP()
-   * })
-   *
-   * on.signal(range, v => updateAimRadius(v))
-   */
-  signal<T>(sig: Signal<T>, fn: (val: T) => void): void
-
-  /**
-   * Run a one-shot callback after a delay.
-   * Runs inside the component's init phase — useful for deferred setup.
-   * Compiles to: `task.delay(seconds, fn)` wrapped in component lifecycle.
-   *
-   * @param seconds  Delay in seconds (0.5 is typical for post-mount init).
-   * @param fn       Callback to run once.
-   *
-   * @example
-   * on.after(0.5, () => {
-   *   // safe to read UI state here — everything is mounted
-   *   Pulse.UI.paragraph('Info', 'Loaded!')
-   * })
-   */
-  after(seconds: number, fn: () => void): void
-}
-
-// ── Roblox type stubs ──────────────────────────────────────────────────────────
-// Minimal stubs so editors don't error. Install @pulse/roblox for full types.
-
-/** @see @pulse/roblox */
-export interface InputObject {
-  KeyCode:       { Value: number; Name: string }
-  UserInputType: { Value: number; Name: string }
-  Position:      Vector3
-  Delta:         Vector3
-}
-
-/** @see @pulse/roblox */
-export interface Model {
-  WaitForChild(name: string, timeout?: number): Instance
-  FindFirstChild(name: string): Instance | undefined
-  FindFirstChildOfClass(className: string): Instance | undefined
-  GetChildren(): Instance[]
-}
-
-/** @see @pulse/roblox */
-export interface Instance {
-  Name:      string
-  Parent:    Instance | undefined
-  Destroy(): void
-}
-
-/** @see @pulse/roblox */
-export interface BasePart extends Instance {
-  Position:     Vector3
-  CFrame:       CFrame
-  Size:         Vector3
-  Anchored:     boolean
-  CanCollide:   boolean
-  Transparency: number
-}
-
-/** @see @pulse/roblox */
-export interface Vector3 {
-  X: number; Y: number; Z: number
-  Magnitude: number
-  Unit: Vector3
-  add(other: Vector3): Vector3
-  sub(other: Vector3): Vector3
-  mul(scalar: number): Vector3
-}
-
-/** @see @pulse/roblox */
-export interface CFrame {
-  Position:   Vector3
-  LookVector: Vector3
-  RightVector: Vector3
-  UpVector:   Vector3
-}