@fluxlay/react 1.2.0 → 1.3.0

package/dist/index.d.mts

@@ -1,7 +1,259 @@
 import * as _$react from "react";
+import { RefObject } from "react";
 import { FitAddon } from "@xterm/addon-fit";
 import * as _$_xterm_xterm0 from "@xterm/xterm";
 import { ITheme, Terminal } from "@xterm/xterm";
+//#region ../sdk-core/dist/index.d.mts
+//#region src/caret-position.d.ts
+/**
+ * Compute the viewport-relative pixel rect of the text caret in a focused
+ * `<input>` or `<textarea>` element. Used by the IME pipeline to (a) draw a
+ * fake blinking caret while the field has lost OS focus to the IME proxy
+ * window, and (b) reposition the IME candidate panel so it tracks the caret
+ * as the user types.
+ *
+ * Implementation: the standard "mirror div" technique. We construct a hidden
+ * `<div>` styled identically to the field, set its text content to the value
+ * up to the caret, append a zero-width marker `<span>`, and read the marker's
+ * `getBoundingClientRect` to get the caret pixel position. The mirror div is
+ * removed immediately after measurement, so there is no persistent DOM
+ * footprint.
+ */
+/** A caret rect in viewport-relative CSS pixels (top-left origin). */
+interface CaretRect {
+  x: number;
+  y: number;
+  height: number;
+}
+/** A selection rect in viewport-relative CSS pixels (top-left origin). */
+interface SelectionRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+declare function measureCaretRect(el: HTMLInputElement | HTMLTextAreaElement, position?: number): CaretRect | null;
+/**
+ * Reverse mapping: given a viewport-relative point, find the character
+ * index in `el.value` whose caret rect lies closest to it. Used to
+ * implement mouse-driven selection in environments where the browser's
+ * native drag-selection is broken (e.g. wallpaper webviews on macOS,
+ * which can't become the OS key window so AppKit drops mouseDragged
+ * events from the field).
+ *
+ * Strategy:
+ * 1. Binary-search a position whose caret y matches `clientY` (within
+ *    one line height tolerance). For `<input>` (single-line) this step
+ *    is skipped — every position shares the same y.
+ * 2. Within that row, binary-search by x for the position whose caret
+ *    rect is closest to `clientX`.
+ *
+ * Cost: O(log² n) calls to {@link measureCaretRect}, each of which
+ * builds a one-shot mirror div. Acceptable for pointer-event-driven
+ * code (one call per pointermove tick, coalesced via rAF by the caller
+ * if needed).
+ */
+declare function caretIndexFromClientPoint(el: HTMLInputElement | HTMLTextAreaElement, clientX: number, clientY: number): number;
+/**
+ * Compute viewport-relative pixel rects covering the selected range
+ * `[start, end)` within a focused field. Returns an empty array if the
+ * range is collapsed.
+ *
+ * Approach: measure caret rects at start and end via the same mirror-div
+ * technique. If both fall on the same visual line (same y), emit a single
+ * rect spanning x_start → x_end. Otherwise (multi-line in `<textarea>`),
+ * emit three rects approximating the selection band:
+ *   1. start-line tail: x_start → field right edge
+ *   2. middle band: full field width × (end_y - start_y - lineHeight)
+ *   3. end-line head: field left → x_end
+ *
+ * The middle band over-approximates wrapped lines (it covers the entire
+ * width regardless of where each line actually ended), which matches the
+ * intent of a continuous "block selection" highlight. Padding/border
+ * insets are not respected — the band uses the field's bounding rect for
+ * left/right, so the highlight may bleed slightly into the border on
+ * fields with thick borders. This is intentional to keep the
+ * implementation cheap; visual fidelity is acceptable.
+ */
+declare function measureSelectionRects(el: HTMLInputElement | HTMLTextAreaElement, start: number, end: number): SelectionRect[]; //#endregion
+//#region src/coords.d.ts
+/**
+ * Coordinate conversions between fluxlay's normalized OS space and CSS pixels.
+ *
+ * fluxlay reports pointer coordinates in the range `[-1, 1]` with the Y axis
+ * flipped (positive Y points upward, mirroring a mathematical coordinate
+ * system). The DOM, in contrast, uses CSS pixels with Y growing downward and
+ * the origin at the top-left of the viewport.
+ *
+ * Wallpaper windows always cover the entire screen, so `window.innerWidth` /
+ * `innerHeight` is the right reference frame for both directions.
+ */
+/**
+ * Convert a normalized fluxlay coordinate (`[-1, 1]`, Y-up) to CSS pixels
+ * (Y-down) within the current window.
+ */
+declare function normalizedToPixel(nx: number, ny: number): {
+  x: number;
+  y: number;
+};
+/**
+ * Convert a CSS pixel coordinate (Y-down) within the current window to the
+ * normalized fluxlay coordinate space (`[-1, 1]`, Y-up).
+ */
+declare function pixelToNormalized(x: number, y: number): {
+  x: number;
+  y: number;
+}; //#endregion
+//#region src/file-url.d.ts
+/**
+ * Build a URL the wallpaper webview can use to load a local file referenced
+ * by an `image` or `file` property value.
+ *
+ * The file is served by the Fluxlay desktop app via `GET /v1/file` and is
+ * restricted to paths currently assigned to an `image` / `file` property of
+ * the active wallpaper. Returns `null` when the path is missing.
+ */
+declare function getPropertyFileUrl(path: string | null | undefined): string | null; //#endregion
+//#region src/ime-inline.d.ts
+/**
+ * Predicate: is `el` an element on which we want to auto-handle IME?
+ *
+ * Matches text-input `<input>`, `<textarea>`, and `[contenteditable]` nodes.
+ * Numeric / range / date / etc. inputs are excluded since they have no IME
+ * use case.
+ */
+declare function isImeAutoTarget(el: EventTarget | null): el is HTMLElement;
+/** Options for {@link ImeInlineController}. */
+interface ImeInlineControllerOptions {
+  /**
+   * Render a thin blinking caret overlay at the focused field's caret
+   * position. Required for the auto-IME path because the IME proxy window
+   * steals OS focus from the wallpaper webview, which makes the native
+   * caret disappear. Default: `false`.
+   */
+  showCaret?: boolean;
+  /**
+   * Notified whenever the caret position changes (or `null` when the
+   * controller detaches). Used by the auto-IME path to forward caret
+   * coordinates to the backend so the IME candidate panel tracks the
+   * caret. Coordinates are viewport-relative CSS pixels.
+   */
+  onCaretChange?: (rect: CaretRect | null) => void;
+}
+/**
+ * Stateful controller that mirrors an IME composition into a focused
+ * input / textarea so it appears inline (matching native browser IME UX).
+ *
+ * Usage:
+ * 1. Call {@link setTarget} with the focused element when focus changes
+ *    (and `null` on blur).
+ * 2. Call {@link updateComposition} on every composition stream update.
+ * 3. Call {@link commit} when an IME commit event arrives.
+ *
+ * The controller mutates `target.value` directly via the platform-native
+ * value setter and dispatches an `input` event so React controlled-input
+ * change tracking still fires.
+ *
+ * `[contenteditable]` targets only support {@link commit} (text is inserted
+ * via `document.execCommand("insertText", ...)`); inline composition for
+ * arbitrary DOM nodes would require positional text-range manipulation
+ * that is out of scope for this helper.
+ */
+declare class ImeInlineController {
+  private target;
+  /**
+   * The range within `target.value` currently occupied by the in-progress
+   * composition. `null` while no composition is active.
+   */
+  private tracked;
+  private readonly showCaret;
+  private readonly onCaretChange?;
+  private overlay;
+  private selectionOverlay;
+  /**
+   * The "sticky" visual x coordinate for vertical caret motion. When the
+   * user presses Up/Down repeatedly, native textareas remember the
+   * column they started from so traversing through a short line and
+   * back to a long line returns the caret to the original column. We
+   * track the same here, resetting whenever any non-vertical motion or
+   * text mutation occurs.
+   */
+  private desiredVerticalX;
+  private caretListenersAttached;
+  private rafHandle;
+  private readonly onSelectionChange;
+  private readonly onTargetScroll;
+  private readonly onWindowResize;
+  /**
+   * Mouse-drag selection state. Browsers normally handle drag-select
+   * natively, but in environments where the host window can't become
+   * the OS key window (e.g. macOS wallpaper webviews) AppKit drops
+   * mouseDragged events from the field, so the browser never sees them
+   * and selection doesn't extend. We re-implement drag selection in JS
+   * by listening to pointermove on the target while a primary pointer
+   * is pressed, computing the caret index from the pointer coordinates,
+   * and calling `setSelectionRange` ourselves. Anchor is captured from
+   * the field's `selectionStart` after the browser handles the initial
+   * pointerdown (so single-click positioning still flows through the
+   * browser unchanged).
+   */
+  private dragState;
+  private readonly onTargetPointerDown;
+  private readonly onTargetPointerMove;
+  private readonly onTargetPointerUp;
+  private readonly onTargetPointerCancel;
+  constructor(options?: ImeInlineControllerOptions);
+  /** Returns the element this controller is currently tracking, if any. */
+  getTarget(): HTMLElement | null;
+  /**
+   * Switch the controller to a new target (or detach with `null`). If a
+   * composition was in progress on the previous target, the inline text is
+   * removed before switching so we don't leave half-typed glyphs behind.
+   */
+  setTarget(el: HTMLElement | null): void;
+  /**
+   * Apply a composition stream update. `composition` is the current marked
+   * text (or `null` when composition has ended). `cursor` is the caret
+   * position within the marked text in code units.
+   *
+   * On the first non-null update the controller captures the element's
+   * current `selectionStart` as the composition's anchor and inserts the
+   * text there. Subsequent updates replace the anchored range with the new
+   * composition text. A `null` update removes the inline range entirely
+   * (cancellation path; a commit handler should null-out the tracked
+   * range before this fires).
+   */
+  updateComposition(composition: string | null, cursor: number): void;
+  /**
+   * Apply a non-character key command (Backspace, arrow keys, Enter, Tab,
+   * etc.) that arrived from the macOS IME proxy because the proxy panel was
+   * the key window when the user pressed the key. `kind` is the Cocoa
+   * selector name forwarded by `doCommandBySelector:`
+   * (e.g. `deleteBackward:`, `moveLeft:`, `insertNewline:`).
+   *
+   * No-op for `[contenteditable]` targets — implementing arrow / delete
+   * semantics for arbitrary DOM is out of scope; wallpaper authors who need
+   * that should manage focus/composition manually.
+   */
+  applyCommand(kind: string): void;
+  private applyCommandInner;
+  /**
+   * Apply a commit. If a composition is currently inlined, its range is
+   * replaced with `text`; otherwise `text` is inserted at the current
+   * caret position (this branch covers direct insertion paths such as
+   * typing in English mode, where the OS IME never enters composition).
+   */
+  commit(text: string): void;
+  private attachCaretListeners;
+  private detachCaretListeners;
+  private scheduleCaretRefresh;
+  private refreshCaret;
+  private clearCaret;
+  private ensureOverlay;
+  private ensureSelectionOverlay;
+  private resolveCaretColor;
+  private resolveSelectionColor;
+} //#endregion
 //#region src/transport/index.d.ts
 /** The result returned after executing a shell command. */
 interface ShellResult {
@@ -16,6 +268,77 @@ interface ShellResult {
   /** Signal number that terminated the process, or `null` if it exited normally. */
   signal: number | null;
 }
+/** Mouse cursor position reported by the Fluxlay backend. */
+interface MousePosition {
+  /** Horizontal position of the cursor in screen coordinates. */
+  x: number;
+  /** Vertical position of the cursor in screen coordinates. */
+  y: number;
+  /** Label of the window that received the mouse event. */
+  windowLabel: string;
+}
+/** Mouse button identifier. */
+type MouseButton = "left" | "right" | "middle" | "other";
+/** Mouse button press / release event in window-normalized coordinates ([-1, 1]). */
+interface MouseButtonEvent {
+  type: "button";
+  /** Which button was pressed/released. */
+  button: MouseButton;
+  /** True for press, false for release. */
+  pressed: boolean;
+  /** Horizontal position in normalized window coordinates. */
+  x: number;
+  /** Vertical position in normalized window coordinates. */
+  y: number;
+  /** Label of the window the event was normalized against. */
+  windowLabel: string;
+}
+/** Mouse wheel / trackpad scroll event in window-normalized coordinates ([-1, 1]). */
+interface MouseWheelEvent {
+  type: "wheel";
+  /** Horizontal scroll delta (OS-defined units). */
+  deltaX: number;
+  /** Vertical scroll delta (OS-defined units). */
+  deltaY: number;
+  /** Cursor X at scroll time, in normalized window coordinates. */
+  x: number;
+  /** Cursor Y at scroll time, in normalized window coordinates. */
+  y: number;
+  /** Label of the window the event was normalized against. */
+  windowLabel: string;
+}
+/** Aggregate of mouse interaction events streamed from the Fluxlay backend. */
+type MouseInputEvent = MouseButtonEvent | MouseWheelEvent;
+/** Modifier key state at the time of a keyboard event. */
+interface KeyModifiers {
+  shift: boolean;
+  control: boolean;
+  alt: boolean;
+  /** macOS Command key / Windows logo key. */
+  meta: boolean;
+}
+/**
+ * Keyboard key press / release event.
+ *
+ * `code` follows the Web `KeyboardEvent.code` convention identifying a physical
+ * key independent of layout (e.g. `"KeyA"`, `"Space"`, `"Digit1"`,
+ * `"ArrowLeft"`, `"ShiftLeft"`). Unmapped keys come through as
+ * `"Unidentified"`.
+ */
+interface KeyEvent {
+  /** Physical key identifier (Web `KeyboardEvent.code` style). */
+  code: string;
+  /** True for key down, false for key up. */
+  pressed: boolean;
+  /**
+   * True when the OS reports this event as an auto-repeat. On Windows the
+   * low-level hook does not surface a repeat flag, so this is derived by
+   * tracking the pressed-key set.
+   */
+  repeat: boolean;
+  /** Modifier key state at the time of the event. */
+  modifiers: KeyModifiers;
+}
 /** System audio information streamed from the Fluxlay backend. */
 interface AudioInfo {
   /** RMS (Root Mean Square) volume level (0.0 - 1.0). */
@@ -125,6 +448,237 @@ interface MediaMetadataInfo {
 type PropertyValue = number | string | boolean | string[] | null;
 /** Custom property values set by the end user via the Fluxlay settings UI. */
 type PropertyValues = Record<string, PropertyValue>;
+/** Wallpaper manifest information visible to the SDK. */
+interface ManifestInfo {
+  /** Permission strings declared in `fluxlay.yaml` (kebab-case). */
+  permissions: string[];
+}
+/** IME composition update (text being composed but not yet committed). */
+interface ImeCompositionPayload {
+  /** Current composition text. Empty string means no active composition. */
+  text: string;
+  /** Caret position within `text`, in code points. */
+  cursor: number;
+  /** Selection range within `text`, in code points, or null when no selection. */
+  selection: [number, number] | null;
+}
+/**
+ * Event emitted by the `ime-commit-stream`. Multiplexes two distinct event
+ * kinds into one stream so we stay below WKWebView's 6-connections-per-host
+ * cap:
+ *
+ * - `commit`: text the IME finalized (Enter etc.)
+ * - `command`: a non-character key (Backspace, arrow keys, Enter, Tab, etc.)
+ *   that was pressed while the macOS IME proxy panel was the key window. The
+ *   proxy can't apply these to the wallpaper's `<input>` directly, so it
+ *   forwards the Cocoa selector name (e.g. `deleteBackward:`, `moveLeft:`)
+ *   here for the SDK to apply.
+ */
+type ImeCommitPayload = {
+  type: "commit";
+  text: string;
+} | {
+  type: "command";
+  kind: string;
+};
+/**
+ * Map of backend `invoke` method names to the deserialized response type.
+ *
+ * Adding a new backend endpoint? Append it here so `Transport.invoke` infers
+ * the return type from the method name.
+ */
+interface InvokeMethodMap {
+  "run-script": ShellResult;
+  properties: PropertyValues;
+  manifest: ManifestInfo;
+  "ime-activate": Record<string, never>;
+  "ime-deactivate": Record<string, never>;
+  "ime-update-caret": Record<string, never>;
+}
+/**
+ * Map of backend stream names to the per-payload type emitted by
+ * `Transport.subscribe`.
+ *
+ * Adding a new stream? Append it here so the callback's payload is inferred
+ * from the event name.
+ */
+interface SubscribeEventMap {
+  "audio-stream": AudioInfo;
+  "ime-commit-stream": ImeCommitPayload;
+  "ime-composition-stream": ImeCompositionPayload;
+  "keyboard-stream": KeyEvent;
+  "media-metadata-stream": MediaMetadataInfo;
+  "mouse-event-stream": MouseInputEvent;
+  "mouse-stream": MousePosition;
+  "properties-stream": PropertyValues;
+  "system-monitor-stream": SystemMonitorInfo;
+}
+/** Abstract interface for communicating with the Fluxlay backend. */
+interface Transport {
+  /**
+   * Sends a request to the backend and returns the deserialized response.
+   * The return type is inferred from the method name via {@link InvokeMethodMap}.
+   *
+   * @param method The backend endpoint name (must be a key of `InvokeMethodMap`).
+   * @param params Request payload serialized as JSON.
+   */
+  invoke<M extends keyof InvokeMethodMap>(method: M, params: Record<string, any>): Promise<InvokeMethodMap[M]>;
+  /**
+   * Opens a streaming subscription to a backend event and invokes `callback`
+   * for each received payload. The payload type is inferred from the event
+   * name via {@link SubscribeEventMap}.
+   *
+   * @param event The backend event / endpoint name (must be a key of `SubscribeEventMap`).
+   * @param callback Function called with each deserialized payload.
+   * @param params Optional query parameters appended to the request URL.
+   * @returns A cleanup function that cancels the subscription when called.
+   */
+  subscribe<E extends keyof SubscribeEventMap>(event: E, callback: (payload: SubscribeEventMap[E]) => void, params?: Record<string, any>): () => void;
+} //#endregion
+//#region src/shell.d.ts
+/** Options that control how a shell command is executed. */
+interface ShellOptions {
+  /** Number of columns (character width) of the pseudo-terminal. */
+  columns?: number;
+  /** Number of rows (line height) of the pseudo-terminal. */
+  lines?: number;
+}
+/**
+ * Runs a pre-declared shell command from fluxlay.yaml.
+ *
+ * @param commandId The ID of the command declared in the manifest's `shell` section.
+ * @param options Options for command execution.
+ * @returns The standard output and error of the command.
+ * @throws An error if the command fails or the ID is invalid.
+ */
+declare function runShell(commandId: string, options?: ShellOptions): Promise<ShellResult>; //#endregion
+//#region src/transport/http.d.ts
+/**
+ * HTTP-based implementation of the {@link Transport} interface.
+ *
+ * Communicates with the Fluxlay backend over `http://127.0.0.1:<port>/v1`.
+ * The port is read from the `fluxlay_port` query parameter of the current URL,
+ * defaulting to `1421` when the parameter is absent.
+ */
+declare class HttpTransport implements Transport {
+  /** Resolves the base URL of the Fluxlay backend API from the current page URL. */
+  private get baseUrl();
+  /**
+   * In-flight invoke promises keyed by a cache key composed of the method name,
+   * window label, and serialized parameters.
+   * Prevents duplicate requests when the same call is made concurrently.
+   */
+  private pendingInvokes;
+  /**
+   * Active SSE/NDJSON subscriptions keyed by event + params, with reference
+   * counting. Multiple `subscribe()` calls for the same event share a single
+   * physical fetch stream; the underlying request is aborted only after every
+   * caller has unsubscribed.
+   *
+   * This keeps wallpapers below WKWebView's 6-connections-per-host limit,
+   * which would otherwise queue subsequent `invoke()` POSTs forever once 6
+   * long-lived streams are open.
+   */
+  private subscriptions;
+  /**
+   * Sends a POST request to the backend endpoint identified by `method` and
+   * returns the deserialized JSON response.
+   *
+   * If an identical request (same method, window label, and parameters) is
+   * already in flight, the existing promise is returned instead of sending a
+   * duplicate request.
+   *
+   * @param method The backend endpoint name.
+   * @param params Request payload serialized as JSON.
+   * @returns A promise that resolves to the response value of type `T`.
+   * @throws An error if the HTTP response status is not OK.
+   */
+  invoke<M extends keyof InvokeMethodMap>(method: M, params: Record<string, any>): Promise<InvokeMethodMap[M]>;
+  /**
+   * Opens a streaming GET request to the backend event endpoint and invokes
+   * `callback` for each newline-delimited JSON (NDJSON) payload received.
+   *
+   * The stream is cancelled when the returned cleanup function is called.
+   *
+   * @param event The backend event / endpoint name.
+   * @param callback Function called with each deserialized NDJSON payload.
+   * @param params Optional query parameters appended to the request URL.
+   * @returns A cleanup function that aborts the stream when called.
+   */
+  subscribe<E extends keyof SubscribeEventMap>(event: E, callback: (payload: SubscribeEventMap[E]) => void, params?: Record<string, any>): () => void;
+} //#endregion
+//#region src/transport/default.d.ts
+/**
+ * Process-wide singleton {@link HttpTransport}. All SDK code paths that need
+ * to talk to the fluxlay backend should reuse this instance instead of
+ * instantiating their own — `HttpTransport.subscribe` ref-counts physical
+ * fetch streams per URL, so sharing the transport keeps the wallpaper below
+ * WKWebView's 6-connections-per-host limit even when multiple hooks /
+ * Providers / auto-handlers subscribe to overlapping events.
+ */
+declare const defaultTransport: HttpTransport; //#endregion
+//#region src/themes/index.d.ts
+/**
+ * Collection of pre-built xterm color themes.
+ *
+ * Pass any of these values to the `theme` option of {@link useTerminal}.
+ *
+ * @example
+ * ```tsx
+ * const { terminalRef, instance } = useTerminal({
+ *   theme: TerminalThemes.dracula,
+ * });
+ * ```
+ */
+declare const TerminalThemes: {
+  /** Dark themes with a transparent background. */readonly dark: {
+    /** Default dark theme using Tailwind color palette. */readonly default: _$_xterm_xterm0.ITheme; /** Modern dark theme using Slate/Rose color palette. */
+    readonly modern: _$_xterm_xterm0.ITheme;
+  }; /** Light themes. */
+  readonly light: {
+    /** Default light theme. */readonly default: _$_xterm_xterm0.ITheme; /** Modern light theme. */
+    readonly modern: _$_xterm_xterm0.ITheme;
+  }; /** Nord theme — an arctic, north-bluish color palette. */
+  readonly nord: _$_xterm_xterm0.ITheme; /** Dracula theme — a dark theme with vivid accent colors. */
+  readonly dracula: _$_xterm_xterm0.ITheme; /** Gruvbox themes — a retro groove color scheme. */
+  readonly gruvbox: {
+    /** Gruvbox dark variant. */readonly dark: _$_xterm_xterm0.ITheme; /** Gruvbox light variant. */
+    readonly light: _$_xterm_xterm0.ITheme;
+  }; /** Solarized themes — a precision color scheme with reduced brightness. */
+  readonly solarized: {
+    /** Solarized dark variant. */readonly dark: _$_xterm_xterm0.ITheme; /** Solarized light variant. */
+    readonly light: _$_xterm_xterm0.ITheme;
+  }; /** One Dark theme — based on Atom's One Dark syntax theme. */
+  readonly oneDark: _$_xterm_xterm0.ITheme; /** Catppuccin themes — a soothing pastel color scheme. */
+  readonly catppuccin: {
+    /** Catppuccin Latte — the light variant. */readonly latte: _$_xterm_xterm0.ITheme; /** Catppuccin Frappé — a cool medium-dark variant. */
+    readonly frappe: _$_xterm_xterm0.ITheme; /** Catppuccin Macchiato — a warm medium-dark variant. */
+    readonly macchiato: _$_xterm_xterm0.ITheme; /** Catppuccin Mocha — the darkest variant. */
+    readonly mocha: _$_xterm_xterm0.ITheme;
+  }; /** Monokai Pro theme — a refined dark theme inspired by Monokai. */
+  readonly monokaiPro: _$_xterm_xterm0.ITheme; /** Tokyo Night theme — a dark theme inspired by Tokyo city lights. */
+  readonly tokyoNight: _$_xterm_xterm0.ITheme; /** Night Owl theme — optimized for late-night coding with low brightness. */
+  readonly nightOwl: _$_xterm_xterm0.ITheme; /** Everforest themes — a green-tinted theme inspired by forests. */
+  readonly everforest: {
+    /** Everforest dark variant. */readonly dark: _$_xterm_xterm0.ITheme; /** Everforest light variant. */
+    readonly light: _$_xterm_xterm0.ITheme;
+  };
+}; //#endregion
+//#endregion
+//#region src/hooks/use-active-element.d.ts
+/**
+ * Reactively track `document.activeElement`.
+ *
+ * Returns the currently focused element, or `null` when nothing is focused
+ * (i.e. focus is on `<body>` or the document itself). Subscribes to
+ * `focusin` / `focusout` so the value updates whenever focus moves anywhere
+ * in the document.
+ *
+ * Useful on wallpapers for debugging / visualizing which element synthetic
+ * keyboard input is being routed to, since WebKit doesn't paint a focus ring
+ * on non-key windows.
+ */
+declare function useActiveElement(): Element | null;
 //#endregion
 //#region src/hooks/use-audio.d.ts
 /** Options for the audio stream. */
@@ -144,16 +698,100 @@ interface AudioOptions {
  */
 declare function useAudio(options?: AudioOptions): AudioInfo;
 //#endregion
-//#region src/lib/file-url.d.ts
+//#region src/hooks/use-ime-input.d.ts
 /**
- * Build a URL the wallpaper webview can use to load a local file referenced
- * by an `image` or `file` property value.
+ * Callback fired when the IME commits text (the user finalized their input,
+ * e.g. by pressing Enter to confirm a Japanese conversion).
+ */
+type ImeCommitHandler = (text: string) => void;
+/**
+ * Return value of {@link useImeInput}.
  *
- * The file is served by the Fluxlay desktop app via `GET /v1/file` and is
- * restricted to paths currently assigned to an `image` / `file` property of
- * the active wallpaper. Returns `null` when the path is missing.
+ * The wallpaper must call `activate()` to start receiving IME input — typically
+ * in response to the user clicking an in-wallpaper "input field". Until
+ * activated, the proxy window stays in the background and does not steal focus
+ * from other applications.
+ */
+interface ImeInputApi {
+  /** Current composition text, or null when no composition is active. */
+  composition: string | null;
+  /** Caret position within `composition`, in code points. */
+  cursor: number;
+  /**
+   * Request the IME proxy window to take focus and start delivering input.
+   *
+   * Pass an `HTMLElement` (typically your `<input>` ref) or an explicit
+   * `{ x, y, height }` rect in screen-relative CSS pixels to position the
+   * IME candidate window near the caret. Without an argument the candidate
+   * appears in the middle of the active screen.
+   */
+  activate: (anchor?: HTMLElement | {
+    x: number;
+    y: number;
+    height: number;
+  }) => void;
+  /** Release the IME proxy window's focus and stop delivering input. */
+  deactivate: () => void;
+  /**
+   * Register a handler that fires every time the IME commits text.
+   * Returns a cleanup function that removes the handler.
+   */
+  onCommit: (handler: ImeCommitHandler) => () => void;
+}
+/**
+ * React hook that exposes IME (Input Method Editor) text input for wallpapers
+ * that need to accept Japanese / Chinese / Korean / etc. text.
+ *
+ * Wallpapers MUST declare `permissions: [ime-input]` in their `fluxlay.yaml`.
+ * The backend rejects every IME request from wallpapers without the permission
+ * with HTTP 403, in which case this hook stays a quiet no-op (no streams flow,
+ * activate / deactivate are accepted by the SDK but produce nothing).
+ *
+ * The hook is independent of `useKeyboard`: while the IME proxy is active
+ * (between `activate()` and `deactivate()`), `useKeyboard` events are
+ * suppressed by the backend so IME candidate operations (arrows, Enter, Esc)
+ * do not double-fire as raw key events.
  */
-declare function getPropertyFileUrl(path: string | null | undefined): string | null;
+declare function useImeInput(): ImeInputApi;
+//#endregion
+//#region src/hooks/use-is-focused.d.ts
+/**
+ * Track whether the element pointed to by `ref` currently has DOM focus.
+ *
+ * Why this exists: wallpaper windows are not the OS key window, so WebKit
+ * suppresses the visual `:focus` / `:focus-visible` styling that authors
+ * normally rely on. To render a focus ring on a wallpaper you have to mirror
+ * focus state into React and toggle a class manually. This hook encapsulates
+ * that pattern — subscribe to `focus`/`blur` and expose a boolean.
+ *
+ * The hook also seeds the initial value from `document.activeElement` so the
+ * state is correct even if focus was already on the element at mount time.
+ */
+declare function useIsFocused(ref: RefObject<HTMLElement | null>): boolean;
+//#endregion
+//#region src/hooks/use-keyboard.d.ts
+/**
+ * Callbacks for global keyboard events streamed from the Fluxlay backend.
+ *
+ * Keyboard events are not tied to a specific wallpaper window — every
+ * subscriber on every window receives every key press/release while the user
+ * is anywhere on the desktop.
+ */
+interface KeyboardHandlers {
+  onKeyDown?: (event: KeyEvent) => void;
+  onKeyUp?: (event: KeyEvent) => void;
+}
+/**
+ * React hook that subscribes to global keyboard events from the Fluxlay
+ * backend. Convenient for wallpapers that implement game-like interactions.
+ *
+ * Platform notes:
+ * - macOS: requires the user to grant Fluxlay "Input Monitoring" permission.
+ * - Windows: the global hook may be flagged by antivirus software; key events
+ *   that target a process running at a higher integrity level (e.g. an app
+ *   launched as Administrator) are not delivered, due to UIPI.
+ */
+declare function useKeyboard(handlers: KeyboardHandlers): void;
 //#endregion
 //#region src/hooks/use-media-metadata.d.ts
 /** Options for the media metadata stream. */
@@ -194,6 +832,34 @@ declare function useMousePosition(): {
   y: number;
 };
 //#endregion
+//#region src/hooks/use-mouse-events.d.ts
+/**
+ * Callbacks invoked when the Fluxlay backend reports mouse interaction events
+ * (clicks, button releases, wheel/trackpad scrolls) inside the current
+ * wallpaper window. Coordinates are normalized to `[-1, 1]` with the Y axis
+ * inverted to match a standard math coordinate system.
+ *
+ * Pass only the callbacks you need; missing ones are simply ignored.
+ */
+interface MouseEventHandlers {
+  onButton?: (event: MouseButtonEvent) => void;
+  onWheel?: (event: MouseWheelEvent) => void;
+}
+/**
+ * React hook that subscribes to mouse click and wheel events streamed from the
+ * Fluxlay backend. The Y axis is inverted so positive Y points upward, just
+ * like {@link useMousePosition}.
+ *
+ * The subscription is scoped to the window identified by the `window_label`
+ * query parameter of the current URL, defaulting to `"main"`.
+ *
+ * On macOS, mouse click events require the user to grant the Fluxlay app
+ * "Input Monitoring" permission in System Settings. On Windows the global
+ * mouse hook may be flagged by some antivirus software; events from windows
+ * running with elevated privileges are also not delivered (UIPI).
+ */
+declare function useMouseEvents(handlers: MouseEventHandlers): void;
+//#endregion
 //#region src/hooks/use-properties.d.ts
 /**
  * React hook that provides the current custom property values defined
@@ -207,24 +873,6 @@ declare function useMousePosition(): {
  */
 declare function useProperties<T extends PropertyValues = PropertyValues>(): T;
 //#endregion
-//#region src/shell.d.ts
-/** Options that control how a shell command is executed. */
-interface ShellOptions {
-  /** Number of columns (character width) of the pseudo-terminal. */
-  columns?: number;
-  /** Number of rows (line height) of the pseudo-terminal. */
-  lines?: number;
-}
-/**
- * Runs a pre-declared shell command from fluxlay.yaml.
- *
- * @param commandId The ID of the command declared in the manifest's `shell` section.
- * @param options Options for command execution.
- * @returns The standard output and error of the command.
- * @throws An error if the command fails or the ID is invalid.
- */
-declare function runShell(commandId: string, options?: ShellOptions): Promise<ShellResult>;
-//#endregion
 //#region src/hooks/use-terminal.d.ts
 /** Options for the {@link useTerminal} hook. */
 interface UseTerminalOptions {
@@ -354,52 +1002,4 @@ interface SystemMonitorOptions {
  */
 declare function useSystemMonitor(options?: SystemMonitorOptions): SystemMonitorInfo;
 //#endregion
-//#region src/themes/index.d.ts
-/**
- * Collection of pre-built xterm color themes.
- *
- * Pass any of these values to the `theme` option of {@link useTerminal}.
- *
- * @example
- * ```tsx
- * const { terminalRef, instance } = useTerminal({
- *   theme: TerminalThemes.dracula,
- * });
- * ```
- */
-declare const TerminalThemes: {
-  /** Dark themes with a transparent background. */readonly dark: {
-    /** Default dark theme using Tailwind color palette. */readonly default: _$_xterm_xterm0.ITheme; /** Modern dark theme using Slate/Rose color palette. */
-    readonly modern: _$_xterm_xterm0.ITheme;
-  }; /** Light themes. */
-  readonly light: {
-    /** Default light theme. */readonly default: _$_xterm_xterm0.ITheme; /** Modern light theme. */
-    readonly modern: _$_xterm_xterm0.ITheme;
-  }; /** Nord theme — an arctic, north-bluish color palette. */
-  readonly nord: _$_xterm_xterm0.ITheme; /** Dracula theme — a dark theme with vivid accent colors. */
-  readonly dracula: _$_xterm_xterm0.ITheme; /** Gruvbox themes — a retro groove color scheme. */
-  readonly gruvbox: {
-    /** Gruvbox dark variant. */readonly dark: _$_xterm_xterm0.ITheme; /** Gruvbox light variant. */
-    readonly light: _$_xterm_xterm0.ITheme;
-  }; /** Solarized themes — a precision color scheme with reduced brightness. */
-  readonly solarized: {
-    /** Solarized dark variant. */readonly dark: _$_xterm_xterm0.ITheme; /** Solarized light variant. */
-    readonly light: _$_xterm_xterm0.ITheme;
-  }; /** One Dark theme — based on Atom's One Dark syntax theme. */
-  readonly oneDark: _$_xterm_xterm0.ITheme; /** Catppuccin themes — a soothing pastel color scheme. */
-  readonly catppuccin: {
-    /** Catppuccin Latte — the light variant. */readonly latte: _$_xterm_xterm0.ITheme; /** Catppuccin Frappé — a cool medium-dark variant. */
-    readonly frappe: _$_xterm_xterm0.ITheme; /** Catppuccin Macchiato — a warm medium-dark variant. */
-    readonly macchiato: _$_xterm_xterm0.ITheme; /** Catppuccin Mocha — the darkest variant. */
-    readonly mocha: _$_xterm_xterm0.ITheme;
-  }; /** Monokai Pro theme — a refined dark theme inspired by Monokai. */
-  readonly monokaiPro: _$_xterm_xterm0.ITheme; /** Tokyo Night theme — a dark theme inspired by Tokyo city lights. */
-  readonly tokyoNight: _$_xterm_xterm0.ITheme; /** Night Owl theme — optimized for late-night coding with low brightness. */
-  readonly nightOwl: _$_xterm_xterm0.ITheme; /** Everforest themes — a green-tinted theme inspired by forests. */
-  readonly everforest: {
-    /** Everforest dark variant. */readonly dark: _$_xterm_xterm0.ITheme; /** Everforest light variant. */
-    readonly light: _$_xterm_xterm0.ITheme;
-  };
-};
-//#endregion
-export { AudioOptions, MediaMetadataOptions, ShellOptions, type ShellResult, SystemMonitorOptions, TerminalInstance, TerminalThemes, UseShellOptions, UseTerminalOptions, getPropertyFileUrl, runShell, useAudio, useMediaMetadata, useMousePosition, useProperties, useShell, useSystemMonitor, useTerminal };
+export { AudioInfo, AudioOptions, CaretRect, DiskInfo, HttpTransport, ImeCommitHandler, type ImeCommitPayload, type ImeCompositionPayload, ImeInlineController, ImeInlineControllerOptions, ImeInputApi, InvokeMethodMap, type KeyEvent, type KeyModifiers, KeyboardHandlers, ManifestInfo, MediaMetadataInfo, MediaMetadataOptions, type MouseButton, type MouseButtonEvent, MouseEventHandlers, type MouseInputEvent, MousePosition, type MouseWheelEvent, PropertyValue, PropertyValues, SelectionRect, ShellOptions, type ShellResult, SubscribeEventMap, SystemMonitorInfo, SystemMonitorOptions, TerminalInstance, TerminalThemes, Transport, UseShellOptions, UseTerminalOptions, caretIndexFromClientPoint, defaultTransport, getPropertyFileUrl, isImeAutoTarget, measureCaretRect, measureSelectionRects, normalizedToPixel, pixelToNormalized, runShell, useActiveElement, useAudio, useImeInput, useIsFocused, useKeyboard, useMediaMetadata, useMouseEvents, useMousePosition, useProperties, useShell, useSystemMonitor, useTerminal };