> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infilsense.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Application API

> Create the root library instance and control global UI behavior and theming.

The application object returned by `Library.new()` is the entry point for the entire library.

## `Library.new(config)`

Creates the root `ScreenGui`, loads configuration, initializes Quick Commands, applies the initial theme, and creates the built-in `Settings` tab.

```lua theme={null}
local app = Library.new({
	Name = "Universal Utility",
	SaveFolder = "Configs",
	SaveId = "settings",
	Theme = Library.Themes.Midnight,
})
```

**config** `table`

Application configuration. Omit the table to use the built-in defaults.

**config.Name** `string` (default: "Unnamed")

Library name used in internal state and console messages.

**config.SaveFolder** `string` (default: "")

Folder used for the JSON configuration file. When empty, the config is stored as `<SaveId>.json`.

**config.SaveId** `string` (default: "config")

Base name for the JSON configuration file. The `.json` extension is added automatically.

**config.Theme** `table`

Initial theme. Use a table of supported theme channels or one of the built-in presets such as `Library.Themes.Midnight`. Theme values must be Roblox `Color3` values.

**config.AccentColor** `Color3`

Backward-compatible top-level accent override. `Accent` is accepted as an alias.

**config.TabHeadingColor** `Color3`

Backward-compatible top-level tab heading color override. `TabHeading`, `HeaderText`, and the corresponding theme aliases are accepted.

**config.BackgroundColor** `Color3`

Backward-compatible top-level background override. `Background` is accepted as an alias.

**config.TextColor** `Color3`

Backward-compatible top-level text override. `Text` is accepted as an alias.

**config.InputColor** `Color3`

Backward-compatible top-level input background override. `InputBackground` is accepted as an alias.

**config.MutedColor** `Color3`

Backward-compatible top-level muted color override. `Muted` is accepted as an alias.

> [!NOTE]
>
> `Theme` is the preferred configuration surface for new code. Theme settings are applied at startup but are not written to the JSON persistence file.

> [!NOTE]
>
> `Library.new()` also creates a tab named `Settings`. Calling `CreateTab("Settings")` later returns that existing tab.

## `Library.Themes`

`Library.Themes` contains the built-in theme presets:

| Preset | Description |
| :- | :- |
| `InfilSense` | Purple InfilSense palette. This is the default theme. |
| `Midnight` | Blue-on-dark palette. |
| `Emerald` | Green-on-dark palette. |
| `Crimson` | Red-on-dark palette. |
| `Obsidian` | Monochrome black-and-white palette. |

Presets are ordinary Lua tables, so you can pass them directly to `Theme` or `SetTheme`, or copy one and modify individual channels.

```lua theme={null}
local app = Library.new({
	Theme = Library.Themes.Emerald,
})

app:SetTheme(Library.Themes.Obsidian)
```

## Theme channels

The theme system supports eight color channels. Keys are case-insensitive.

| Channel | Aliases | Used for |
| :- | :- | :- |
| `accent` | `accentcolor` | Accent fills, active states, gradients, and command highlighting. |
| `tabHeading` | `tabheadingcolor`, `headertext`, `tabtext` | Tab header text. |
| `background` | `backgroundcolor`, `dark` | Main component/tab backgrounds. Updating it also refreshes the derived hover color. |
| `hover` | `hovercolor`, `darkhover` | Hover/tooltip background channel. |
| `text` | `textcolor` | Primary component text. |
| `inputBackground` | `input`, `inputbg` | Text input and slider-track backgrounds. |
| `muted` | `mutedcolor`, `gray` | Inactive indicators and selection controls. |
| `placeholder` | `placeholdercolor`, `textplaceholder` | Placeholder and subdued prompt text. |

> [!NOTE]
>
> For custom themes, the canonical keys shown in the first column are recommended. A theme may be partial, so you only need to provide the channels you want to change.

## Methods

### `app:CreateTab(name, defaultPosition)`

Creates a draggable floating tab. Reusing an existing tab name returns the existing tab object.

```lua theme={null}
local combat = app:CreateTab("Combat")
local movement = app:CreateTab(
	"Movement",
	UDim2.new(0, 260, 0, 80)
)
```

**name** `string` *required*

Tab title and the key used for saved tab position/state.

**defaultPosition** `UDim2`

Initial pixel position used only when the tab has no saved position.

> [!NOTE]
>
> New tabs start minimized. Without a saved position or explicit position, the library stacks them vertically. Dragging is viewport-clamped and can use grid snapping.

### `app:GetTab(name)`

Returns an existing tab object or `nil` if the name is not registered.

```lua theme={null}
local settings = app:GetTab("Settings")
if settings then
	settings:AddLabel("Additional settings")
end
```

### `app:ToggleGui(forcedState)`

Shows or hides every floating tab. The Quick Commands overlay remains available.

```lua theme={null}
app:ToggleGui()      -- Toggle
app:ToggleGui(true)  -- Show
app:ToggleGui(false) -- Hide
```

**forcedState** `boolean`

When supplied, visibility is set directly instead of toggled.

The same action is bound to **Right Shift** by default. The key can be changed from the built-in `Settings` tab.

### `app:SetTheme(themeTable)`

Applies every recognized `Color3` channel in a theme table to the running UI. Existing components that listen to the affected channel update immediately.

```lua theme={null}
app:SetTheme({
	accent = Color3.fromRGB(170, 0, 255),
	background = Color3.fromRGB(16, 16, 22),
	text = Color3.fromRGB(240, 240, 240),
})
```

The same alias rules used by `config.Theme` are accepted. Unknown keys and non-`Color3` values are ignored.

### Individual theme setters

Each setter changes one theme channel at runtime:

| Method | Channel |
| :- | :- |
| `app:SetAccentColor(color)` | `accent` |
| `app:SetTabHeadingColor(color)` | `tabHeading` |
| `app:SetBackgroundColor(color)` | `background` |
| `app:SetHoverColor(color)` | `hover` |
| `app:SetTextColor(color)` | `text` |
| `app:SetInputBackgroundColor(color)` | `inputBackground` |
| `app:SetMutedColor(color)` | `muted` |
| `app:SetPlaceholderColor(color)` | `placeholder` |

```lua theme={null}
app:SetAccentColor(Color3.fromRGB(0, 200, 255))
app:SetBackgroundColor(Color3.fromRGB(18, 18, 24))
app:SetPlaceholderColor(Color3.fromRGB(150, 150, 160))
```

### `app:ExportQuickCommandsList()`

Prints every registered Quick Command, returns the same entries as a Lua array, and writes a text file when the environment exposes `writefile`.

```lua theme={null}
local commands = app:ExportQuickCommandsList()
for _, line in ipairs(commands) do
	print(line)
end
```

The file path is:

```text theme={null}
<SaveFolder>/commandIds/<SaveId>.txt
```

When `SaveFolder` is empty, that becomes:

```text theme={null}
commandIds/<SaveId>.txt
```

Each line contains the command title, command ID, aliases, and usage when applicable.

## Complete application surface

The user-facing application API is:

```text theme={null}
Library.Themes
Library.new(config)
app:CreateTab(name, defaultPosition)
app:GetTab(name)
app:ToggleGui(forcedState)
app:SetTheme(themeTable)
app:SetAccentColor(color)
app:SetTabHeadingColor(color)
app:SetBackgroundColor(color)
app:SetHoverColor(color)
app:SetTextColor(color)
app:SetInputBackgroundColor(color)
app:SetMutedColor(color)
app:SetPlaceholderColor(color)
app:ExportQuickCommandsList()
```

`ConfigManager`, `KeybindManager`, `State`, and component `.create()` functions are bundled implementation modules, not part of the stable application contract.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.