@fluxlay/react 0.1.6 → 1.1.0

package/README.md

@@ -18,19 +18,114 @@ import "@fluxlay/react/dist/sdk.css";
 
 ## API
 
-### `useBackendMouse()`
+### `useMousePosition()`
 
 Subscribes to the global mouse position streamed from the Fluxlay backend. The Y axis is inverted so that positive values point upward (standard mathematical coordinates).
 
 ```tsx
-import { useBackendMouse } from "@fluxlay/react";
+import { useMousePosition } from "@fluxlay/react";
 
 function Wallpaper() {
-  const { x, y } = useBackendMouse();
+  const { x, y } = useMousePosition();
   return <div style={{ transform: `translate(${x}px, ${y}px)` }} />;
 }
 ```
 
+### `useSystemMonitor()`
+
+Subscribes to real-time system and hardware metrics streamed from the Fluxlay backend. Returns CPU, memory, battery, network, disk, and other system information.
+
+```tsx
+import { useSystemMonitor } from "@fluxlay/react";
+
+function Wallpaper() {
+  const { cpuUsage, memoryUsage, batteryLevel } = useSystemMonitor();
+  return (
+    <div style={{ fontFamily: "monospace" }}>
+      <p>CPU: {cpuUsage.toFixed(1)}%</p>
+      <p>Memory: {memoryUsage.toFixed(1)}%</p>
+      <p>Battery: {batteryLevel ?? "N/A"}</p>
+    </div>
+  );
+}
+```
+
+Refresh intervals can be configured per-category in `fluxlay.yaml`:
+
+```yaml
+sdk:
+  system_monitor:
+    cpu_interval_ms: 500
+    memory_interval_ms: 1000
+    battery_interval_ms: 10000
+```
+
+### `useAudio()`
+
+Subscribes to real-time system audio information streamed from the Fluxlay backend. Returns RMS volume, peak level, and a 32-band frequency spectrum, useful for building audio visualizers.
+
+```tsx
+import { useAudio } from "@fluxlay/react";
+
+function Wallpaper() {
+  const { rms, peak, spectrum } = useAudio();
+  return (
+    <div>
+      <p>Volume: {(rms * 100).toFixed(0)}%</p>
+      <div style={{ display: "flex", gap: 2, alignItems: "flex-end", height: 100 }}>
+        {spectrum.map((v, i) => (
+          <div key={i} style={{ width: 4, height: `${v * 100}%`, background: "white" }} />
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `rms` | `number` | RMS (Root Mean Square) volume level (0.0 – 1.0). |
+| `peak` | `number` | Peak volume level (0.0 – 1.0). |
+| `spectrum` | `number[]` | Frequency spectrum split into 32 logarithmically-scaled bands (0.0 – 1.0 each). |
+
+### `useMediaMetadata()`
+
+Subscribes to media metadata for the currently playing track from system media players (e.g. Spotify, Apple Music). Returns title, artist, album artwork, playback progress, and playback state.
+
+```tsx
+import { useMediaMetadata } from "@fluxlay/react";
+
+function Wallpaper() {
+  const { title, artist, artwork, isPlaying, elapsedTime, duration } = useMediaMetadata();
+  return (
+    <div>
+      {artwork && <img src={artwork} alt="Album art" width={200} />}
+      <p>{title ?? "Not playing"}</p>
+      <p>{artist}</p>
+    </div>
+  );
+}
+```
+
+Polling interval can be configured in `fluxlay.yaml`:
+
+```yaml
+sdk:
+  media_metadata:
+    interval_ms: 1000
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string \| null` | Track title. |
+| `artist` | `string \| null` | Artist name. |
+| `album` | `string \| null` | Album name. |
+| `artwork` | `string \| null` | Artwork as a data URL (`data:image/...;base64,...`). |
+| `duration` | `number \| null` | Track duration in seconds. |
+| `elapsedTime` | `number \| null` | Elapsed playback time in seconds. |
+| `playbackRate` | `number \| null` | Playback rate (0.0 = paused, 1.0 = playing). |
+| `isPlaying` | `boolean` | Whether media is currently playing. |
+
 ### `useShell(commandId, options?)`
 
 Executes a shell command declared in `fluxlay.yaml` and optionally renders its output into a terminal.

package/dist/index.d.ts

@@ -3,6 +3,65 @@ import { ITheme } from '@xterm/xterm';
 import { RefObject } from 'react';
 import { Terminal } from '@xterm/xterm';
 
+/** System audio information streamed from the Fluxlay backend. */
+declare interface AudioInfo {
+    /** RMS (Root Mean Square) volume level (0.0 - 1.0). */
+    rms: number;
+    /** Peak volume level (0.0 - 1.0). */
+    peak: number;
+    /** Frequency spectrum split into logarithmically-scaled bands (0.0 - 1.0 each). The number of bands is configurable via `useAudio({ numBands })`. */
+    spectrum: number[];
+}
+
+/** Options for the audio stream. */
+export declare interface AudioOptions {
+    /** Number of frequency spectrum bands. Default is 32. */
+    numBands?: number;
+}
+
+/** Storage information for a single disk/volume. */
+declare interface DiskInfo {
+    /** Mount point path (e.g. "/", "/home"). */
+    mountPoint: string;
+    /** Disk/volume name. */
+    name: string;
+    /** Total capacity in bytes. */
+    totalBytes: number;
+    /** Available (free) space in bytes. */
+    availableBytes: number;
+    /** Usage percentage (0.0 - 100.0). */
+    usage: number;
+}
+
+/** Media metadata information for the currently playing track. */
+declare interface MediaMetadataInfo {
+    /** Track title, or `null` if unavailable. */
+    title: string | null;
+    /** Artist name, or `null` if unavailable. */
+    artist: string | null;
+    /** Album name, or `null` if unavailable. */
+    album: string | null;
+    /** Artwork as a data URL (e.g. "data:image/jpeg;base64,..."), or `null` if unavailable. */
+    artwork: string | null;
+    /** Track duration in seconds, or `null` if unavailable. */
+    duration: number | null;
+    /** Elapsed playback time in seconds, or `null` if unavailable. */
+    elapsedTime: number | null;
+    /** Playback rate (0.0 = paused, 1.0 = playing), or `null` if unavailable. */
+    playbackRate: number | null;
+    /** Whether media is currently playing. */
+    isPlaying: boolean;
+}
+
+/** Options for the media metadata stream. */
+export declare interface MediaMetadataOptions {
+    /** Polling interval in milliseconds. Default is 1000. */
+    intervalMs?: number;
+}
+
+/** Custom property values set by the end user via the Fluxlay settings UI. */
+declare type PropertyValues = Record<string, number | string | boolean>;
+
 /**
  * Runs a pre-declared shell command from fluxlay.yaml.
  *
@@ -35,6 +94,82 @@ export declare interface ShellResult {
     signal: number | null;
 }
 
+/** System hardware and performance information streamed from the Fluxlay backend. */
+declare interface SystemMonitorInfo {
+    /** Overall CPU usage percentage (0.0 - 100.0). */
+    cpuUsage: number;
+    /** Per-core CPU usage percentages (0.0 - 100.0 each). */
+    cpuPerCore: number[];
+    /** Per-core CPU frequency in MHz. */
+    cpuFrequencyMhz: number[];
+    /** Total physical memory in bytes. */
+    memoryTotal: number;
+    /** Used physical memory in bytes. */
+    memoryUsed: number;
+    /** Memory usage percentage (0.0 - 100.0). */
+    memoryUsage: number;
+    /** Total swap space in bytes. */
+    swapTotal: number;
+    /** Used swap space in bytes. */
+    swapUsed: number;
+    /** Swap usage percentage (0.0 - 100.0). */
+    swapUsage: number;
+    /** Battery charge level (0.0 - 100.0), or `null` if no battery is present. */
+    batteryLevel: number | null;
+    /** Whether the battery is currently charging, or `null` if no battery is present. */
+    batteryCharging: boolean | null;
+    /** Network receive speed in bytes per second. */
+    networkRxBytesPerSec: number;
+    /** Network transmit speed in bytes per second. */
+    networkTxBytesPerSec: number;
+    /** Disk read speed in bytes per second. */
+    diskReadBytesPerSec: number;
+    /** Disk write speed in bytes per second. */
+    diskWriteBytesPerSec: number;
+    /** Number of running processes. */
+    processCount: number;
+    /** System uptime in seconds. */
+    uptimeSecs: number;
+    /** Load average for the past 1, 5, and 15 minutes. */
+    loadAverage: [number, number, number];
+    /** Per-disk storage information. */
+    disks: DiskInfo[];
+    /** System hostname. */
+    hostname: string;
+    /** Operating system name and version. */
+    osName: string;
+    /** CPU model name (e.g. "Apple M2 Pro"). */
+    cpuBrand: string;
+    /** Number of physical CPU cores. */
+    physicalCoreCount: number;
+    /** Number of logical CPU cores (threads). */
+    logicalCoreCount: number;
+    /** CPU architecture (e.g. "aarch64", "x86_64"). */
+    cpuArch: string;
+    /** Kernel version string. */
+    kernelVersion: string;
+}
+
+/** Polling interval options for each system monitor category (in milliseconds). */
+export declare interface SystemMonitorOptions {
+    /** CPU usage polling interval in ms. */
+    cpuIntervalMs?: number;
+    /** Memory usage polling interval in ms. */
+    memoryIntervalMs?: number;
+    /** Network throughput polling interval in ms. */
+    networkIntervalMs?: number;
+    /** Disk I/O polling interval in ms. */
+    diskIoIntervalMs?: number;
+    /** Disk space polling interval in ms. */
+    diskSpaceIntervalMs?: number;
+    /** Battery status polling interval in ms. */
+    batteryIntervalMs?: number;
+    /** Process count polling interval in ms. */
+    processIntervalMs?: number;
+    /** Load average polling interval in ms. */
+    loadAverageIntervalMs?: number;
+}
+
 /** Holds the xterm {@link Terminal} and its associated {@link FitAddon}. */
 export declare interface TerminalInstance {
     /** The underlying xterm Terminal instance. */
@@ -116,6 +251,32 @@ export declare const TerminalThemes: {
     };
 };
 
+/**
+ * React hook that subscribes to system audio information streamed from
+ * the Fluxlay backend.
+ *
+ * Returns the current audio state including RMS volume, peak level,
+ * and frequency spectrum data, useful for building audio visualizers.
+ *
+ * @param options - Optional audio configuration.
+ * @returns The current audio info as `{ rms, peak, spectrum }`.
+ */
+export declare function useAudio(options?: AudioOptions): AudioInfo;
+
+/**
+ * React hook that subscribes to media metadata streamed from the
+ * Fluxlay backend.
+ *
+ * Returns information about the currently playing track from system
+ * media players (e.g. Spotify, Apple Music), including title, artist,
+ * album artwork, and playback state — useful for building
+ * music-reactive wallpapers.
+ *
+ * @param options - Optional media metadata configuration.
+ * @returns The current media metadata info.
+ */
+export declare function useMediaMetadata(options?: MediaMetadataOptions): MediaMetadataInfo;
+
 /**
  * React hook that subscribes to global mouse position events streamed from
  * the Fluxlay backend.
@@ -129,11 +290,23 @@ export declare const TerminalThemes: {
  *
  * @returns The current mouse position as `{ x, y }`.
  */
-export declare function useBackendMouse(): {
+export declare function useMousePosition(): {
     x: number;
     y: number;
 };
 
+/**
+ * React hook that provides the current custom property values defined
+ * in the wallpaper manifest and customized by the end user.
+ *
+ * Fetches initial values on mount and subscribes to real-time updates
+ * via the properties stream.
+ *
+ * @typeParam T - Shape of the property values object.
+ * @returns The current property values typed as `T`.
+ */
+export declare function useProperties<T extends PropertyValues = PropertyValues>(): T;
+
 /**
  * React hook that executes a pre-declared Fluxlay shell command and
  * optionally renders its output into an xterm terminal.
@@ -182,6 +355,19 @@ export declare interface UseShellOptions extends ShellOptions {
     terminal?: TerminalInstance | null;
 }
 
+/**
+ * React hook that subscribes to system hardware information streamed
+ * from the Fluxlay backend.
+ *
+ * Returns real-time system metrics including CPU usage, memory usage,
+ * battery status, and network throughput — useful for building
+ * system-reactive wallpapers (e.g. cyberpunk HUDs, hardware monitors).
+ *
+ * @param options - Optional polling interval configuration for each category.
+ * @returns The current system monitor info.
+ */
+export declare function useSystemMonitor(options?: SystemMonitorOptions): SystemMonitorInfo;
+
 /**
  * React hook that creates and manages a read-only xterm terminal rendered
  * inside a `<div>` element.