@rb-pulse/core 1.3.0 → 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.3.0",
-  "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,350 +0,0 @@
-/**
- * @pulse/core — Global ambient declarations for Pulse framework TypeScript scripts.
- *
- * Mental model:
- *   - SolidJS-style reactive signals: `signal(default)` returns a PulseSignal<T>.
- *     Call it to read, `.set()` to write, `.watch()` to subscribe — just like
- *     SolidJS `createSignal` but without the getter/setter tuple split.
- *   - Next.js-style file-based pages: place `src/pages/1_Home.ts`, `2_Combat.ts`…
- *     Each file calls `definePage(...)` at the top level — tab order is determined
- *     by the numeric filename prefix, just like Next.js routes.
- *   - Components are SolidJS-style setup functions: call `defineComponent(name, setup)`
- *     where `setup` declares signals, registers `on.*` handlers, and returns widgets.
- *   - All APIs are Lua globals — no imports needed. TypeScript sees them via this
- *     `declare global {}` block. TSTL will NOT emit any `require()` calls.
- *
- * Compiled to Lua via typescript-to-lua (TSTL): `rb build` handles this for you.
- *
- * @example
- * // src/combat/SpeedHack.ts
- * defineComponent('SpeedHack', () => {
- *   const enabled = signal(false)
- *   const speed   = signal(16)
- *   on.heartbeat({ when: enabled }, () => {
- *     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),
- *   ]
- * })
- */
-
-declare global {
-
-  // ── Signal ────────────────────────────────────────────────────────────────────
-
-  /**
-   * Reactive state cell returned by `signal()`.
-   *
-   * Call it to read the current value. Changes propagate to UI widgets,
-   * event guards, and watchers automatically.
-   *
-   * Like SolidJS `createSignal` but without the getter/setter tuple split.
-   */
-  interface PulseSignal<T> {
-    /** Read the current value. */
-    (): T
-    /** Write a new value. Triggers UI, handler, and watcher updates. */
-    set(this: PulseSignal<T>, value: T): void
-    /**
-     * Toggle the signal value (boolean signals only).
-     * Equivalent to `signal.set(!signal())`.
-     */
-    toggle(this: PulseSignal<boolean>): void
-    /**
-     * Subscribe to value changes. Returns an unsubscribe function.
-     * Fires immediately with the current value, then on every change.
-     */
-    watch(this: PulseSignal<T>, fn: (value: T) => void): () => void
-    /**
-     * Apply a function to the current value and set the result.
-     * @example speed.update(v => v + 10)
-     */
-    update(this: PulseSignal<T>, fn: (current: T) => T): void
-  }
-
-  // ── 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.
-   */
-  interface HandlerOpts {
-    /**
-     * Gate: skip the callback while this signal is `false`.
-     * The event connection stays alive but the callback is skipped.
-     */
-    when?: PulseSignal<boolean>
-    /**
-     * Throttle: minimum seconds between callback invocations.
-     * Accepts a number or a reactive `PulseSignal<number>` for live adjustment.
-     * @default 0  (every frame)
-     */
-    every?: number | PulseSignal<number>
-  }
-
-  // ── Widget definitions ────────────────────────────────────────────────────────
-
-  interface ToggleDef {
-    bind(this: ToggleDef, sig: PulseSignal<boolean>): ToggleDef
-    withTip(this: ToggleDef, text: string): ToggleDef
-    withDefault(this: ToggleDef, v: boolean): ToggleDef
-  }
-
-  interface SliderDef {
-    bind(this: SliderDef, sig: PulseSignal<number>): SliderDef
-    withTip(this: SliderDef, text: string): SliderDef
-    withDefault(this: SliderDef, v: number): SliderDef
-  }
-
-  interface DropdownDef {
-    bind(this: DropdownDef, sig: PulseSignal<string>): DropdownDef
-    withTip(this: DropdownDef, text: string): DropdownDef
-    withDefault(this: DropdownDef, v: string): DropdownDef
-  }
-
-  interface ButtonDef {
-    onClick(this: ButtonDef, fn: () => void): ButtonDef
-    bind(this: ButtonDef): ButtonDef
-  }
-
-  type WidgetDef = ToggleDef | SliderDef | DropdownDef | ButtonDef | {
-    bind(this: any): any
-  }
-
-  // ── Component / Page / Layout ────────────────────────────────────────────────
-
-  /** Opaque handle returned by `defineComponent`. */
-  interface ComponentRef {
-    readonly _name: string
-    readonly _ui:   WidgetDef[]
-  }
-
-  interface GroupboxDef {
-    readonly type:  'groupbox'
-    readonly side:  'left' | 'right'
-    readonly title: string
-    readonly icon:  string
-    readonly mount?: string
-  }
-
-  interface PageDef {
-    readonly title:  string
-    readonly icon:   string
-    readonly layout: GroupboxDef[]
-  }
-
-  interface LayoutConfig {
-    title:               string
-    author?:             string
-    toggleKey?:          string
-    size?:               [number, number]
-    uiLibrary?:          'windui' | 'linoria'
-    theme?:              string
-    icon?:               string
-    folder?:             string
-    acrylic?:            boolean
-    transparency?:       number
-    openButtonMobileOnly?: boolean
-    openButtonIcon?:     string
-    themes?:             Array<{ name: string; values: Record<string, string> }>
-    compatExclude?:      string[]
-  }
-
-  // ── Core API — all are Lua globals, no require() ──────────────────────────────
-
-  /**
-   * SolidJS-style reactive state — see createSignal.
-   *
-   * Creates a reactive state cell with an initial value.
-   * Compiles to `Signal(initialValue)` in Lua.
-   *
-   * @example
-   * const enabled = signal(false)   // PulseSignal<boolean>
-   * const speed   = signal(16)      // PulseSignal<number>
-   * enabled()           // read
-   * enabled.set(true)   // write
-   * enabled.toggle()    // flip boolean
-   */
-  function signal<T>(initialValue: T): PulseSignal<T>
-
-  /**
-   * Create a derived value that recomputes when its dependencies change.
-   * Compiles to `Computed(fn)` in Lua.
-   */
-  function computed<T>(fn: () => T): () => T
-
-  /**
-   * SolidJS-style component setup function.
-   *
-   * The setup function runs once on init. Declare signals, register `on.*`
-   * handlers, then return an array of widget definitions. All connections are
-   * auto-disconnected when the component is destroyed.
-   *
-   * @example
-   * defineComponent('SpeedHack', () => {
-   *   const enabled = signal(false)
-   *   on.heartbeat({ when: enabled }, () => { ... })
-   *   return [toggle('Speed Hack').bind(enabled)]
-   * })
-   */
-  function defineComponent(name: string, setup: () => WidgetDef[]): ComponentRef
-
-  /**
-   * Event subscription namespace.
-   * All connections are automatically cleaned up when the component is destroyed.
-   * Must be called inside a `defineComponent` setup function.
-   */
-  const on: {
-    /**
-     * RunService.Heartbeat — fires every frame.
-     * Like SolidJS createEffect scoped to RunService.Heartbeat.
-     *
-     * @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 frame render (client only). */
-    renderStepped(opts: HandlerOpts, fn: (dt: number) => void): void
-    renderStepped(fn: (dt: number) => void): void
-
-    /** RunService.Stepped — fires at the physics step rate. */
-    stepped(opts: HandlerOpts, fn: (time: number, dt: number) => void): void
-    stepped(fn: (time: number, dt: number) => void): void
-
-    /** UserInputService.InputBegan. */
-    inputBegan(fn: (input: any, gameProcessed: boolean) => void): void
-
-    /** UserInputService.InputEnded. */
-    inputEnded(fn: (input: any, gameProcessed: boolean) => void): void
-
-    /** Fires when the player's character respawns. */
-    respawn(fn: () => void): void
-
-    /** Player.CharacterAdded — fires when a new character model is added. */
-    characterAdded(fn: (character: any) => void): void
-
-    /** Player.CharacterRemoving — fires just before the character is removed. */
-    characterRemoving(fn: (character: any) => void): void
-
-    /**
-     * Subscribe to changes on a signal.
-     * Fires immediately with the current value, then on every change.
-     */
-    signal<T>(sig: PulseSignal<T>, fn: (val: T) => void): void
-
-    /**
-     * Run a one-shot callback after a delay (seconds).
-     * @example on.after(0.5, () => init())
-     */
-    after(seconds: number, fn: () => void): void
-  }
-
-  // ── Widget factory globals ─────────────────────────────────────────────────────
-
-  /** Toggle widget — checkbox bound to a `PulseSignal<boolean>`. */
-  function toggle(label: string, opts?: { tip?: string; default?: boolean }): ToggleDef
-
-  /** Slider widget — numeric range input. */
-  function slider(label: string, opts?: {
-    min?: number; max?: number; step?: number; default?: number;
-    suffix?: string; tip?: string
-  }): SliderDef
-
-  /** Dropdown widget — selectable list of string options. */
-  function dropdown(label: string, opts?: {
-    options?: string[]; default?: string; tip?: string
-  }): DropdownDef
-
-  /** Multi-select dropdown widget. */
-  function multidropdown(label: string, opts?: {
-    options?: string[]; default?: string[]; tip?: string
-  }): DropdownDef
-
-  /** Button widget — triggers a callback when clicked. */
-  function button(label: string, fn: () => void, opts?: { tip?: string }): ButtonDef
-  function button(label: string, opts?: { tip?: string }): ButtonDef
-
-  /** Keybind widget — lets the user rebind a hotkey. */
-  function keybind(label: string, opts?: { key?: string; tip?: string }): WidgetDef
-
-  /** Label widget — static non-interactive text. */
-  function label(text: string): WidgetDef
-
-  /** Separator widget — horizontal divider line. */
-  function separator(): WidgetDef
-
-  /**
-   * Declare a groupbox column in a page.
-   * @param side  'left' or 'right' column
-   * @param title Groupbox header text
-   * @param opts  icon, mount (component name string), widgets
-   */
-  function groupbox(side: 'left' | 'right', title: string, opts?: {
-    icon?: string; mount?: string; widgets?: WidgetDef[]
-  }): GroupboxDef
-
-  /**
-   * Next.js-style file-based page tab — place in src/pages/N_Name.ts.
-   *
-   * Each file calls `definePage` at the top level. Tab order is determined
-   * by the numeric prefix of the filename (1_Home.ts, 2_Combat.ts, …).
-   *
-   * @example
-   * // src/pages/1_Home.ts
-   * definePage('Home', { icon: 'house' }, () => [
-   *   groupbox('left', 'Player', { icon: 'person', mount: 'SpeedHack' }),
-   * ])
-   */
-  function definePage(
-    title:    string,
-    opts:     { icon?: string },
-    factory:  () => GroupboxDef[],
-  ): PageDef
-
-  // ── Roblox globals (minimal stubs) ────────────────────────────────────────────
-
-  const game: {
-    GetService(name: string): any
-    HttpGet(url: string): string
-  }
-
-  const workspace: {
-    CurrentCamera: any
-    [key: string]: any
-  }
-
-  const Enum: Record<string, Record<string, any>>
-
-  const Color3: {
-    new(r: number, g: number, b: number): any
-    fromRGB(r: number, g: number, b: number): any
-  }
-
-  const Vector3: {
-    new(x: number, y: number, z: number): any
-  }
-
-  const CFrame: {
-    new(x: number, y: number, z: number): any
-  }
-
-  // ── Pulse character helpers ───────────────────────────────────────────────────
-
-  /** Returns `LocalPlayer.Character` or nil. */
-  function _PulseGetChar(): any
-  /** Returns `HumanoidRootPart` from the character, or nil. */
-  function _PulseGetHRP(): any
-  /** Returns `Humanoid` from the character, or nil. */
-  function _PulseGetHumanoid(): any
-  /** Returns true if the local player's humanoid is alive. */
-  function _PulseGetAlive(): boolean
-
-}
-
-export {}