Initial commitHEADmain

1 files changed, 796 insertions, 0 deletions

diff --git a/noctalia.d.luau b/noctalia.d.luau
new file mode 100644
index 0000000..5ec34a0
--- /dev/null
+++ b/noctalia.d.luau
@@ -0,0 +1,796 @@
+--!strict
+-- Type definitions for the Noctalia plugin API (plugin_api 32).
+--
+-- luau-lsp *definition file*: it declares the host-injected globals (noctalia.*,
+-- barWidget.*, shortcut.*, launcher.*, desktopWidget.*, panel.*, ui.*) so authors
+-- get autocomplete and typo diagnostics. Annotations are a runtime no-op.
+-- See README.md ("Editor setup") for pointing luau-lsp at this file.
+--
+-- Prop tables are exhaustive: the host logs and skips any prop not listed here.
+-- "API n" marks the plugin_api level a member requires.
+
+-- ── Shared value shapes ──────────────────────────────────────────────────────
+
+export type CommandResult = {
+  exitCode: number,
+  stdout: string,
+  stderr: string,
+  timedOut: boolean,
+  stdoutTruncated: boolean,
+  stderrTruncated: boolean,
+}
+
+export type HttpRequest = {
+  url: string,
+  method: string?, -- defaults to "GET"
+  headers: { string }?, -- each entry is a full "Header: value" line
+  body: string?,
+  basic_username: string?,
+  basic_password: string?,
+  follow_redirects: boolean?,
+  -- Disables origin certificate and hostname verification; trusted endpoints only. API 7.
+  allow_insecure_tls: boolean?,
+}
+
+export type HttpResponse = {
+  ok: boolean, -- transport success (not the HTTP status)
+  status: number,
+  body: string,
+}
+
+export type HttpStreamResult = {
+  ok: boolean, -- transport success (not the HTTP status)
+  status: number, -- HTTP status code (0 when ok is false)
+}
+
+export type HttpStreamHandle = {
+  stop: () -> (), -- cancel the stream; idempotent, suppresses onClose
+}
+
+export type Output = {
+  name: string,
+  description: string,
+  width: number,
+  height: number,
+  x: number,
+  y: number,
+  scale: number,
+  focused: boolean,
+}
+
+export type WallpaperMask = {
+  path: string,
+  wallpaperPath: string,
+}
+
+export type PanelContextMenuAction = {
+  kind: "item"?, -- may be omitted for action rows
+  id: string,
+  label: string,
+  enabled: boolean?, -- defaults to true
+}
+
+export type PanelContextMenuHeader = {
+  kind: "header",
+  label: string,
+}
+
+export type PanelContextMenuSeparator = {
+  kind: "separator",
+}
+
+export type PanelContextMenuItem = PanelContextMenuAction | PanelContextMenuHeader | PanelContextMenuSeparator
+
+export type PanelContextMenuRequest = {
+  items: { PanelContextMenuItem },
+  onActivate: string,
+  context: (string | number | boolean)?,
+  maxVisible: number?, -- defaults to 12, valid range 1..30
+}
+
+-- A tooltip row: { key, value } or the positional array form { key, value }.
+export type TooltipRow = { key: string?, value: string? }
+
+export type LauncherResult = {
+  id: string?,
+  title: string?,
+  subtitle: string?,
+  glyph: string?,
+  icon: string?,
+  badge: string?,
+  category: string?, -- must match a [[launcher_provider.category]] label
+  presentation: string?,
+  query: string?, -- on activate, set this provider's query to this sub-query (host adds the prefix)
+  score: number?,
+}
+
+export type SystemStats = {
+  sampledAtMs: number?, -- epoch ms of the latest aggregate sample (API 16)
+  -- Absent sensors are nil rather than 0, so "no probe" is distinguishable from "idle".
+  cpu: { usagePercent: number, tempC: number?, freqMhz: number?, maxFreqMhz: number? },
+  ram: { usagePercent: number, usedMb: number, totalMb: number },
+  swap: { usedMb: number, totalMb: number },
+  gpu: { tempC: number?, usagePercent: number?, vramUsedBytes: number?, vramTotalBytes: number? },
+  net: {
+    rxBytesPerSec: number,
+    txBytesPerSec: number,
+    interfaces: { [string]: { rxBytesPerSec: number, txBytesPerSec: number } },
+  },
+  loadAvg: { number }, -- 1, 5 and 15 minute averages
+}
+
+export type DiskMount = {
+  path: string,
+  source: string,
+  filesystem: string,
+}
+
+export type DiskStats = {
+  usagePercent: number,
+  totalBytes: number,
+  freeBytes: number,
+  availableBytes: number,
+}
+
+-- Noctalia provides Luau's built-in `require(path: string): any` for explicit relative `.luau` modules (API 22).
+
+-- ── noctalia.* - shared across every entry type ──────────────────────────────
+
+export type NoctaliaState = {
+  set: (key: string, value: any) -> (),
+  get: (key: string) -> any,
+  watch: (key: string, callback: (value: any) -> ()) -> (),
+}
+
+export type NoctaliaJson = {
+  decode: (str: string) -> (any, string?), -- value, or (nil, err)
+  encode: (value: any, pretty: boolean?) -> (string?, string?),
+}
+
+export type NoctaliaString = {
+  trim: (s: string) -> string,
+  urlEncode: (s: string) -> string,
+  urlDecode: (s: string) -> string,
+}
+
+-- API 20. Paths resolve like the filesystem APIs. `load` returning true means the
+-- request was accepted, not that decoding succeeded; at most eight loads may be
+-- pending. Names and pending callbacks are released when this runtime reloads.
+export type NoctaliaSound = {
+  load: (name: string, path: string, onLoaded: (ok: boolean, error: string?) -> ()) -> boolean,
+  play: (name: string) -> (),
+}
+
+export type Noctalia = {
+  log: (msg: string) -> (),
+
+  -- Subprocess. A string runs through /bin/sh -c; an argv table (API 24) executes
+  -- the program directly. With no callback, runAsync is a detached fire-and-forget
+  -- launch; timeoutMs is clamped to [50, 60000].
+  runAsync: (cmdOrArgv: string | { string }, onResult: ((result: CommandResult) -> ())?, timeoutMs: number?) -> boolean,
+  runStream: (cmd: string, onLine: (line: string) -> ()) -> boolean,
+  runInTerminal: (cmd: string) -> boolean,
+  commandExists: (name: string) -> boolean,
+  -- onResult(true) iff a running process command line matches all needles.
+  processMatches: (onResult: (matched: boolean) -> (), ...string) -> boolean,
+  flatpakAppInstalled: (appId: string) -> boolean,
+  portalAvailable: () -> boolean,
+
+  -- Outputs / display.
+  focusedOutputName: () -> string?,
+  outputs: () -> { Output },
+  isDarkMode: () -> boolean,
+  -- Active theme palette color for a role ("primary", "surface", "on_surface", ...) as
+  -- "#RRGGBB"; nil for unknown role names. API 31.
+  getColor: (role: string) -> string?,
+  -- Effective shell config by dotted path ("bar.main.position", "shell.offline_mode").
+  -- Array indices are zero-based ("bar.order[0]"); nil when the path matches nothing. API 26.
+  getSetting: (path: string) -> any,
+
+  -- Resolves an app id (desktop-entry id / StartupWMClass), or a raw icon name when no
+  -- entry matches, to an icon path for ui.image. nil when nothing resolves.
+  appIconPath: (appIdOrIconName: string, sizePx: number?) -> string?,
+
+  -- Wallpaper. setWallpaper(path) targets all outputs; setWallpaper(connector, path) targets one.
+  setWallpaperEnabled: (connector: string, enabled: boolean) -> (),
+  setWallpaper: (connectorOrPath: string, path: string?) -> (),
+  wallpaperDirectory: () -> string?,
+  -- Source-aligned output mask: 0 keeps desktop widgets visible, 255 erases them to
+  -- reveal the wallpaper. API 25.
+  wallpaperPath: (connector: string) -> string?,
+  setWallpaperMask: (connector: string, mask: WallpaperMask?) -> (),
+
+  togglePanel: (panelId: string) -> (), -- "author/plugin:panel"
+  -- Opens the settings window at this plugin's settings; no-op without settings. API 15.
+  openSettings: () -> (),
+  -- The callback receives the canonical #RRGGBB color, or nil when cancelled.
+  openColorPicker: (initialColor: string, onClose: (color: string?) -> ()) -> boolean,
+
+  notify: (title: string, body: string?) -> (),
+  notifyError: (title: string, body: string?) -> (),
+
+  copyToClipboard: (text: string, mimeType: string) -> boolean,
+  clipboardText: () -> string?, -- nil when empty or non-text
+  getenv: (name: string) -> string?,
+  expandPath: (path: string) -> string,
+  formatTime: (pattern: string, unixSeconds: number?, timezone: string?) -> string,
+  timeFormat: () -> string, -- [shell].time_format, e.g. "{:%H:%M}" (API 19)
+  dateFormat: () -> string, -- [shell].date_format, e.g. "%A, %x" (API 19)
+  -- True when `name` is empty (system local) or names a zone in the active database. API 19.
+  isValidTimezone: (name: string) -> boolean,
+  nowMs: () -> number, -- the only sub-second clock; formatTime and os.time are whole-second (API 12)
+
+  -- System monitor. nil when [system.monitor] is disabled. The first systemStats call
+  -- opts this plugin into its optional CPU/GPU probes. API 12.
+  systemStats: () -> SystemStats?,
+  -- Per-core usage in /proc/stat order; nil until the first delta lands. Offline cores are
+  -- absent, so length can change and an index is not a core id.
+  cpuCores: () -> { number }?,
+  -- Physical block-device filesystems, deduped by source, sorted by mount path. API 16.
+  diskMounts: () -> { DiskMount },
+  -- statvfs snapshot for an absolute or ~/ path; the path is retained for sampling. API 16.
+  diskStats: (path: string) -> DiskStats?,
+
+  setUpdateInterval: (ms: number) -> (), -- update() tick rate, clamped to >= 16ms
+
+  -- Filesystem (paths resolve ~ -> $HOME, absolute verbatim, else plugin-relative).
+  readFile: (path: string) -> (string?, string?), -- contents, or (nil, err)
+  readFileAsync: (path: string, onResult: (contents: string?, err: string?) -> ()) -> boolean, -- API 23
+  writeFile: (path: string, contents: string) -> (boolean, string?),
+  mkdirAll: (path: string) -> (boolean, string?), -- like mkdir -p; existing dir is success
+  removeFile: (path: string) -> (boolean, string?), -- files only, refuses directories
+  renameFile: (from: string, to: string) -> (boolean, string?),
+  fileExists: (path: string) -> boolean,
+  fileInfo: (path: string) -> ({ size: number, mtime: number, isDir: boolean }?, string?),
+  listDir: (path: string) -> ({ string }?, string?),
+  pluginDir: () -> string?,
+  -- Per-plugin persistent data dir, created on demand; survives updates, honors
+  -- NOCTALIA_STATE_HOME. Use for durable data (state is in-memory only).
+  pluginDataDir: () -> (string?, string?),
+
+  -- Registers a font file so its family works in setFont / a label's fontFamily.
+  -- Returns the family name, or (nil, err); visible to every surface once loaded.
+  loadFont: (path: string) -> (string?, string?),
+
+  -- Translation against the plugin's own translations/<lang>.json.
+  tr: (key: string, subst: { [string]: string | number | boolean }?) -> string,
+  trp: (key: string, count: number, subst: { [string]: string | number | boolean }?) -> string,
+
+  -- HTTP (honors shell.offline_mode; download dest resolves like readFile).
+  http: (req: HttpRequest, onResponse: (response: HttpResponse) -> ()) -> boolean,
+  -- Long-lived stream (e.g. SSE). onLine fires per line (CR trimmed); onClose fires once
+  -- unless stopped through the handle. Non-2xx bodies stream to onLine and the status
+  -- arrives in onClose. Cancelled on script reload; nil when it could not start. API 4.
+  httpStream: (
+    req: HttpRequest,
+    onLine: (line: string) -> (),
+    onClose: (result: HttpStreamResult) -> ()
+  ) -> HttpStreamHandle?,
+  download: (url: string, destPath: string, onDone: (success: boolean) -> ()) -> boolean,
+
+  fuzzyScore: (pattern: string, text: string) -> number?, -- nil if no match
+
+  getConfig: (key: string) -> any, -- string | number | boolean | {string} | {[string]: string} | nil
+
+  state: NoctaliaState,
+  sound: NoctaliaSound,
+  json: NoctaliaJson,
+  string: NoctaliaString,
+}
+
+declare noctalia: Noctalia
+
+-- ── ui.* - declarative control tree (bar widgets, desktop widgets, panels) ───
+
+-- One node of a ui.* tree.
+export type UiNode = {
+  type: string,
+  props: { [string]: any },
+  children: { UiNode },
+}
+
+-- A palette role ("primary", "on_surface"), a role with alpha ("primary/0.6",
+-- resolved live against the palette), or a hex value ("#rrggbb" / "#rrggbbaa").
+export type UiColor = string
+
+-- A callback prop takes the name of a plugin global, or a function (API 9) that is
+-- render-scoped: re-rendering replaces it, and an event on a node the current tree no
+-- longer contains does nothing. An empty name counts as unset. Every argument arrives
+-- as a string, for named handlers and closures alike.
+export type UiClickHandler = string | (() -> ())
+-- state is "true" on enter and "false" on leave; key is the node's `key` ("" when unset).
+-- Only the innermost hovered node reports, and every "true" is matched by a "false".
+export type UiHoverHandler = string | ((state: string, key: string) -> ())
+export type UiChangeHandler = string | ((value: string) -> ())
+export type UiSelectHandler = string | ((index: string, text: string) -> ())
+export type UiScrollHandler = string | ((offset: string, maxOffset: string) -> ())
+-- Pointer position normalized to the graph's own box, "0.0000".."1.0000", 0,0 top-left.
+export type UiPointerHandler = string | ((normX: string, normY: string) -> ())
+export type UiDropHandler = string | ((payload: string, value: string) -> ())
+
+-- Common to every node. `opacity` is a group opacity: it fades children too, so use a
+-- translucent `fill` for a translucent background. `key` gives a child stable identity
+-- across renders (keeps input text, hover state, and closures aligned with their row).
+export type UiCommonProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+}
+
+-- ui.column / ui.row. Children stretch across the cross axis unless `align` says otherwise.
+-- onClick makes the whole container a click target and joins the tab order (Enter/Space);
+-- a container with only onHover passes clicks through to an enclosing target.
+export type UiFlexProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  gap: number?,
+  padding: number?,
+  paddingH: number?,
+  paddingV: number?,
+  align: ("start" | "center" | "end" | "stretch")?,
+  justify: ("start" | "center" | "end" | "space_between")?,
+  fill: UiColor?,
+  radius: number?,
+  border: UiColor?,
+  borderWidth: number?,
+  minWidth: number?,
+  minHeight: number?,
+  onClick: UiClickHandler?,
+  onHover: UiHoverHandler?,
+  tooltip: string?, -- shown on hover (API 32); wraps the container in a hover target; cleared when dropped
+}
+
+-- ui.box. Leaf node: it takes no children (use a column/row for content).
+export type UiBoxProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  fill: UiColor?,
+  radius: number?,
+  border: UiColor?,
+  borderWidth: number?,
+  softness: number?,
+  onClick: UiClickHandler?,
+  onHover: UiHoverHandler?,
+  tooltip: string?, -- shown on hover (API 32); wraps the box in a hover target; cleared when dropped
+}
+
+-- ui.label. Unset text props inherit the host defaults (in a bar, the bar's or widget's
+-- font_family/font_weight and scale). fontFamily needs noctalia.loadFont first.
+-- baseline "pictographic" centers art/icon fonts anchored at the ink top.
+export type UiLabelProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  text: string?,
+  fontSize: number?,
+  color: UiColor?,
+  fontWeight: ("thin" | "light" | "normal" | "medium" | "semibold" | "bold" | "heavy")?,
+  fontFamily: string?,
+  baseline: ("text" | "textFixedHeight" | "inkCentered" | "pictographic")?,
+  maxWidth: number?,
+  maxLines: number?,
+  textAlign: ("start" | "center" | "end")?,
+}
+
+-- ui.markdown. Read-only block; re-parsed only when text or the surface scale changes. API 21.
+export type UiMarkdownProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  text: string?,
+}
+
+-- ui.glyph. `name` is a Tabler/Nerd-Font glyph; `size` is a glyph size in px.
+export type UiGlyphProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  name: string?,
+  size: number?,
+  color: UiColor?,
+}
+
+-- ui.image. Local files only: download remote previews first, then pass the saved path.
+export type UiImageProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  path: string?, -- plugin-relative, ~, or absolute
+  radius: number?,
+  fit: ("contain" | "cover" | "stretch")?,
+  border: UiColor?,
+  borderWidth: number?,
+  onClick: UiClickHandler?,
+  onHover: UiHoverHandler?,
+  tooltip: string?, -- shown on hover (API 32); wraps the image in a hover target; cleared when dropped
+}
+
+export type UiSeparatorProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  thickness: number?,
+  color: UiColor?,
+  spacing: number?,
+  orientation: ("auto" | "horizontal" | "vertical")?,
+}
+
+-- ui.spacer: flexible filler, sized with flexGrow.
+export type UiSpacerProps = UiCommonProps
+
+export type UiProgressProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  progress: number?, -- 0..1
+  fill: UiColor?,
+  track: UiColor?,
+  radius: number?,
+}
+
+-- ui.button. Setting only `glyph` clears a retained button's previous text. `tooltip`
+-- shows in bar widgets and panels, never on desktop widgets; dropping it clears it.
+-- In bar widgets a button hugs its content unless sized with width/height/controlSize.
+export type UiButtonProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  text: string?,
+  glyph: string?,
+  fontSize: number?,
+  glyphSize: number?,
+  variant: ("default" | "primary" | "secondary" | "destructive" | "outline" | "ghost")?,
+  contentAlign: ("start" | "center" | "end")?,
+  controlSize: ("sm" | "md" | "lg")?, -- 32 / 38 / 44px tiers; `height` wins when both are set
+  tooltip: string?,
+  enabled: boolean?,
+  selected: boolean?,
+  onClick: UiClickHandler?,
+  onRightClick: UiClickHandler?, -- the only place panel.openContextMenu may be called
+  onHover: UiHoverHandler?,
+}
+
+-- ui.graph. Takes no clicks. The pointer callbacks (API 29) are coalesced on one shared
+-- stream, so the newest event wins and a leave never arrives ahead of a position it
+-- followed. Every entered graph reports its leave, including when the graph is dropped or
+-- rewired - but that teardown leave only reaches a *named* handler, since a closure from
+-- the render that dropped the graph is already superseded.
+export type UiGraphProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  values: { number }?, -- 0..1, clamped
+  values2: { number }?,
+  color: UiColor?,
+  color2: UiColor?,
+  lineWidth: number?,
+  fillOpacity: number?,
+  onPointerMove: UiPointerHandler?,
+  onPointerLeave: UiClickHandler?,
+}
+
+-- ui.input (panels only; skipped with a warning in the bar). Uncontrolled: `value` seeds
+-- the field once, then the host owns the text - keep a stable `key` so edits survive a
+-- re-render, and read them through onChange/onSubmit. `focus` grabs the keyboard when the
+-- control is *created*, never on a later render; a fresh `key` focuses again.
+-- multiline and password are mutually exclusive; multiline submits on Ctrl+Enter, or on
+-- Enter with submitOnEnter (Shift+Enter then inserts the newline).
+export type UiInputProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  value: string?,
+  placeholder: string?,
+  fontSize: number?,
+  controlSize: ("sm" | "md" | "lg")?,
+  password: boolean?,
+  multiline: boolean?,
+  submitOnEnter: boolean?, -- API 21
+  frameVisible: boolean?, -- false hides the native background/border, keeps editing (API 27)
+  focus: boolean?,
+  enabled: boolean?,
+  onChange: UiChangeHandler?,
+  onSubmit: UiChangeHandler?,
+}
+
+-- ui.select (panels only; no dropdowns inside a persistent panel). Value-driven:
+-- pass selectedIndex on every render and update it from onChange, which receives the
+-- selected index and its text.
+export type UiSelectProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  options: { string }?,
+  selectedIndex: number?,
+  placeholder: string?,
+  controlSize: ("sm" | "md" | "lg")?,
+  enabled: boolean?,
+  onChange: UiSelectHandler?,
+}
+
+-- ui.slider. Value-driven, but `value` is re-applied only while not dragging, so
+-- re-rendering mid-drag with a draft value is safe. onChange reports every change
+-- (coalesced); onDragEnd fires with no arguments when the interaction ends - pointer
+-- release and keyboard adjustment. The wheel does not adjust plugin sliders.
+export type UiSliderProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  min: number?,
+  max: number?,
+  step: number?,
+  value: number?,
+  controlSize: ("sm" | "md" | "lg")?,
+  enabled: boolean?,
+  onChange: UiChangeHandler?,
+  onDragEnd: UiClickHandler?,
+}
+
+-- ui.toggle. Value-driven; onChange receives "true" / "false".
+export type UiToggleProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  checked: boolean?,
+  enabled: boolean?,
+  onChange: UiChangeHandler?,
+}
+
+-- ui.scroll (panels only; skipped with a warning in the bar). Vertical scrolling
+-- container with a column's layout props. stickToBottom, onScroll and
+-- scrollToBottomRev are API 21.
+export type UiScrollProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  gap: number?,
+  padding: number?,
+  paddingH: number?,
+  paddingV: number?,
+  align: ("start" | "center" | "end" | "stretch")?,
+  justify: ("start" | "center" | "end" | "space_between")?,
+  fill: UiColor?,
+  radius: number?,
+  border: UiColor?,
+  borderWidth: number?,
+  stickToBottom: boolean?, -- stay pinned to the bottom until the user scrolls away
+  scrollToBottomRev: number?, -- jumps to the bottom on first sight and on every change
+  onScroll: UiScrollHandler?,
+}
+
+-- ui.dragSource (panels only, API 5). Marks a subtree draggable: a grip glyph, or a whole
+-- row through previewAncestor. dragType and payload are required - a missing, mistyped,
+-- empty or over-limit value disables the control for that render. Limits: payload 16 KiB,
+-- dragType 256 bytes.
+export type UiDragSourceProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  gap: number?,
+  padding: number?,
+  paddingH: number?,
+  paddingV: number?,
+  align: ("start" | "center" | "end" | "stretch")?,
+  justify: ("start" | "center" | "end" | "space_between")?,
+  fill: UiColor?,
+  radius: number?,
+  border: UiColor?,
+  borderWidth: number?,
+  minWidth: number?,
+  minHeight: number?,
+  dragType: string, -- matched against a dropZone's `accepts`
+  payload: string, -- opaque; first onDrop argument
+  enabled: boolean?,
+  tooltip: string?,
+  previewAncestor: number?, -- integer 0..8 parent levels the ghost shows; 1 previews the row around a grip
+  liftFromLayout: boolean?, -- remove the previewed row from layout while dragging
+}
+
+-- ui.dropZone (panels only, API 5). Flex container that accepts drops; accepts, value and
+-- onDrop are required (`accepts = {}` accepts nothing). Nested zones resolve to the
+-- deepest accepting zone, hitSlop zones first, closest wins. The host moves nothing: the
+-- callback mutates the plugin's model and re-renders. Limits: value/onDrop/each accepts
+-- entry 256 bytes, at most 16 accepts entries.
+export type UiDropZoneProps = {
+  key: string?,
+  width: number?,
+  height: number?,
+  flexGrow: number?,
+  opacity: number?,
+  visible: boolean?,
+  gap: number?,
+  padding: number?,
+  paddingH: number?,
+  paddingV: number?,
+  align: ("start" | "center" | "end" | "stretch")?,
+  justify: ("start" | "center" | "end" | "space_between")?,
+  fill: UiColor?,
+  radius: number?,
+  border: UiColor?,
+  borderWidth: number?,
+  minWidth: number?,
+  minHeight: number?,
+  accepts: { string }, -- drag types
+  value: string, -- opaque; second onDrop argument
+  onDrop: UiDropHandler,
+  direction: ("column" | "row")?,
+  enabled: boolean?,
+  expandOnDrag: boolean?, -- a fixed-height zone animates to the dragged row's height
+  hitSlop: number?, -- extra drag-only hit distance, without changing layout or clicks
+}
+
+-- Only column, row, scroll, dragSource and dropZone host children; the rest are leaves.
+declare ui: {
+  column: (props: UiFlexProps?, children: { UiNode }?) -> UiNode,
+  row: (props: UiFlexProps?, children: { UiNode }?) -> UiNode,
+  scroll: (props: UiScrollProps?, children: { UiNode }?) -> UiNode,
+  dragSource: (props: UiDragSourceProps, children: { UiNode }?) -> UiNode,
+  dropZone: (props: UiDropZoneProps, children: { UiNode }?) -> UiNode,
+  box: (props: UiBoxProps?) -> UiNode,
+  label: (props: UiLabelProps?) -> UiNode,
+  markdown: (props: UiMarkdownProps?) -> UiNode,
+  glyph: (props: UiGlyphProps?) -> UiNode,
+  image: (props: UiImageProps?) -> UiNode,
+  separator: (props: UiSeparatorProps?) -> UiNode,
+  spacer: (props: UiSpacerProps?) -> UiNode,
+  progress: (props: UiProgressProps?) -> UiNode,
+  button: (props: UiButtonProps?) -> UiNode,
+  graph: (props: UiGraphProps?) -> UiNode,
+  input: (props: UiInputProps?) -> UiNode,
+  select: (props: UiSelectProps?) -> UiNode,
+  slider: (props: UiSliderProps?) -> UiNode,
+  toggle: (props: UiToggleProps?) -> UiNode,
+}
+
+-- ── barWidget.* - [[widget]] presentation ────────────────────────────────────
+
+declare barWidget: {
+  setText: (text: string) -> (),
+  setGlyph: (name: string) -> (),
+  setImage: (path: string, watch: boolean?, width: number?, height: number?) -> (),
+  setTooltip: (tooltip: (string | TooltipRow | { TooltipRow })?) -> (),
+  clearTooltip: () -> (),
+  -- family: a font family name (load a file with noctalia.loadFont first).
+  -- baseline: "text" (default) | "textFixedHeight" | "inkCentered" | "pictographic".
+  setFont: (family: string, baseline: string?) -> (),
+  setColor: (role: string, mode: string?) -> (),
+  setGlyphColor: (role: string, mode: string?) -> (),
+  isVertical: () -> boolean,
+  -- Connector of the output this widget instance's bar is on; per-instance, unlike
+  -- noctalia.focusedOutputName(). nil when unknown.
+  outputName: () -> string?,
+  setVisible: (visible: boolean) -> (),
+  -- Declarative alternative to setText/setGlyph: the tree replaces the built-in
+  -- glyph/text row. ui.input/ui.select/ui.scroll are not supported in the bar.
+  render: (tree: UiNode) -> (),
+}
+
+-- Gestures are configuration, not code: the user binds them per widget instance in
+-- [widget.<id>.actions] (left, right, middle, back, forward, scroll_up, scroll_down,
+-- scroll_left, scroll_right), and a binding wins over the matching callback. An action is
+-- an IPC command ("media toggle"), `exec <command line>`, or `none`. Manifests declare
+-- their own defaults in [widget.actions] (API 14).
+--
+-- Middle click is the one to know about: every widget defaults to
+-- `middle = "settings-open-widget"`, so onMiddleClick does not fire until the manifest or
+-- the user binds `middle = "none"`. Scroll has one extra gate: `enable_scroll = false`
+-- turns onScroll off regardless of bindings.
+
+-- ── shortcut.* - [[shortcut]] quick-toggle tile ──────────────────────────────
+
+declare shortcut: {
+  setLabel: (label: string) -> (),
+  setIcon: (on: string, off: string?) -> (),
+  setActive: (active: boolean) -> (),
+  setEnabled: (enabled: boolean) -> (),
+}
+
+-- ── launcher.* - [[launcher_provider]] results ───────────────────────────────
+
+declare launcher: {
+  setResults: (query: string, results: { LauncherResult }) -> (),
+  setQuery: (text: string) -> (), -- prefix + text (stays in provider); "" resets to root
+}
+
+-- ── desktopWidget.* - [[desktop_widget]] declarative UI ──────────────────────
+
+declare desktopWidget: {
+  render: (tree: UiNode) -> (),
+  setWantsSecondTicks: (wants: boolean) -> (), -- run update() on second boundaries
+  setNeedsFrameTick: (needs: boolean) -> (), -- deliver onFrameTick(deltaMs) every frame
+}
+
+-- ── panel.* - [[panel]] declarative UI ───────────────────────────────────────
+
+declare panel: {
+  render: (tree: UiNode) -> (),
+  close: () -> (),
+  -- Opens a native menu at the originating direct pointer callback; false outside a live
+  -- one. onActivate receives (actionId, context) in the panel script. API 28.
+  openContextMenu: (request: PanelContextMenuRequest) -> boolean,
+  setWantsSecondTicks: (wants: boolean) -> (),
+  setNeedsFrameTick: (needs: boolean) -> (), -- onFrameTick(deltaMs) while open (API 18)
+}
+
+-- ── Entry-point callbacks ────────────────────────────────────────────────────
+--
+-- Your entry defines the globals the host calls, as plain global functions - the
+-- host only calls a callback if the entry defines it:
+--
+--   function update() end                       -- bar/desktop widget, service tick
+--   function onIpc(event, payload) end          -- any entry (payload: string?)
+--   function onClick() / onRightClick() end     -- shortcut, bar widget
+--   function onMiddleClick() end                -- bar widget (see "Gestures" above)
+--   function onHover(entered) end               -- bar widget pointer enter / leave
+--   function onScroll(axis, steps, startsGesture) end -- bar widget scroll; axis is "vertical" | "horizontal",
+--                                               -- steps is whole wheel detents (negative = up / left),
+--                                               -- startsGesture is true only on the first step of a flick
+--   function onQuery(text) / onActivate(id) end -- launcher provider
+--   function onFrameTick(deltaMs) end           -- desktop widget, or open panel (API 18); after
+--                                               -- setNeedsFrameTick(true), frames coalesced
+--   function onAudioSpectrum(valuesCsv, stateCsv) end -- audio-reactive bar widget
+--   function onOpen(context) / onClose() end    -- panel lifecycle
+--   function onKey(chord, pressed) end          -- panel: a capture_keys chord, verbatim from the
+--                                               -- manifest (API 13)
+--   function onConfigChanged() end              -- service: settings changed; getConfig() is now new
+--   function onEnable() end                     -- service: plugin explicitly enabled (API 17)
+--   function onOutputsChanged() end             -- service: output set or geometry changed
+--   function onExit(signal, reason) end         -- any entry teardown; signal is 0 normally, 2 SIGINT,
+--                                               -- 15 SIGTERM; reason is "reload" | "disable" |
+--                                               -- "uninstall" | "shutdown" (API 17)
+--
+-- These are intentionally NOT declared here: declaring them as globals makes
+-- luau-lsp treat your definition as overwriting a built-in.