@edgestation/sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChainList
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,209 @@
-# Temporary Holding Version
+# @edgestation/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Write widgets for [EdgeStation](https://github.com/chainlist/edgestation), in plain JavaScript, Svelte, React or Vue. EdgeStation is a widget dashboard for a secondary display: made first for the Corsair Xeneon Edge, it works on any other one. The docs call the display it runs on "the Edge", whichever it is.
+
+A widget is a folder with a `manifest.json` and an ES module that EdgeStation loads at runtime. The app hands each widget its `api` when it mounts, so nothing from this package runs inside the app: it gives you
+
+- the TypeScript types of the `api`, the manifest and the widget module,
+- `defineWidget()`, to get those types in plain JavaScript too,
+- adapters that mount a Svelte, React or Vue component as a widget,
+- a Vite plugin that builds the one self-contained `dist/main.js` EdgeStation loads,
+- a JSON Schema for `manifest.json`, for autocomplete and checks in your editor.
+
+What the `api` does, the manifest fields, settings, styling and theming are documented in [Writing a widget](https://github.com/chainlist/edgestation/blob/main/widgets/README.md).
+
+## Start a widget
+
+```bash
+npm install -D @edgestation/sdk vite
+```
+
+```
+my-widget/
+  manifest.json
+  package.json      ("type": "module")
+  vite.config.ts
+  src/main.ts       (or main.js, main.tsx, main.jsx)
+  dist/main.js      (built)
+```
+
+```json
+{
+	"$schema": "./node_modules/@edgestation/sdk/manifest.schema.json",
+	"name": "My widget",
+	"minAppVersion": "0.1.0",
+	"main": "dist/main.js",
+	"size": { "w": 2, "h": 1 }
+}
+```
+
+`minAppVersion` is the oldest EdgeStation that can run the widget: set it to the version of this package you build with (they are released together), and older apps show an error card instead of a broken widget.
+
+### Plain JavaScript or TypeScript
+
+```js
+// vite.config.js
+import { widget } from '@edgestation/sdk/vite';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [widget()] });
+```
+
+```js
+// src/main.js
+import { defineWidget } from '@edgestation/sdk';
+
+export default defineWidget({
+	mount(el, api) {
+		api.every(1000, async () => {
+			const { cpu } = await api.system();
+			el.textContent = `${Math.round(cpu.load)} %`;
+		});
+	}
+});
+```
+
+### Svelte 5
+
+```bash
+npm install -D svelte @sveltejs/vite-plugin-svelte
+```
+
+```ts
+// vite.config.ts
+import { widget } from '@edgestation/sdk/vite';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [svelte({ emitCss: false }), widget()] });
+```
+
+```ts
+// src/main.ts
+import { svelteWidget } from '@edgestation/sdk/svelte';
+import Cpu from './Cpu.svelte';
+
+export default svelteWidget(Cpu);
+```
+
+```svelte
+<!-- src/Cpu.svelte -->
+<script lang="ts">
+	import type { WidgetProps } from '@edgestation/sdk';
+
+	let props: WidgetProps = $props();
+	// svelte-ignore state_referenced_locally
+	const { api } = props;
+	let load = $state(0);
+	api.every(1000, async () => (load = (await api.system()).cpu.load));
+</script>
+
+<p>{Math.round(load)} %</p>
+```
+
+`emitCss: false` keeps each component's styles in its JavaScript, and Svelte adds them to the widget's shadow root when it mounts.
+
+Read `api` from the props once, at the top of the script. Svelte warns that this only captures the prop's first value (`state_referenced_locally`): that is what you want, since a setting change remounts the widget rather than changing the prop. Taking `api` out of `props` in one statement keeps the warning to that line, which the `svelte-ignore` comment silences. Destructured straight from `$props()`, `api` would raise it at every use.
+
+### React 19
+
+```bash
+npm install -D react react-dom @vitejs/plugin-react
+```
+
+```ts
+// vite.config.ts
+import { widget } from '@edgestation/sdk/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [react(), widget()] });
+```
+
+```tsx
+// src/main.tsx
+import { reactWidget } from '@edgestation/sdk/react';
+import type { WidgetProps } from '@edgestation/sdk';
+import { useEffect, useState } from 'react';
+
+function Cpu({ api }: WidgetProps) {
+	const [load, setLoad] = useState(0);
+	useEffect(() => api.every(1000, async () => setLoad((await api.system()).cpu.load)), []);
+	return <p>{Math.round(load)} %</p>;
+}
+
+export default reactWidget(Cpu);
+```
+
+An error thrown while rendering, that no error boundary of yours catches, shows the widget's error card.
+
+### Vue 3
+
+```bash
+npm install -D vue @vitejs/plugin-vue
+```
+
+```ts
+// vite.config.ts
+import { widget } from '@edgestation/sdk/vite';
+import vue from '@vitejs/plugin-vue';
+import { defineConfig } from 'vite';
+
+export default defineConfig({ plugins: [vue(), widget()] });
+```
+
+```ts
+// src/main.ts
+import { vueWidget } from '@edgestation/sdk/vue';
+import Cpu from './Cpu.vue';
+
+export default vueWidget(Cpu);
+```
+
+```vue
+<!-- src/Cpu.vue -->
+<script setup lang="ts">
+import { ref } from 'vue';
+import type { WidgetProps } from '@edgestation/sdk';
+
+const { api } = defineProps<WidgetProps>();
+const load = ref(0);
+api.every(1000, async () => (load.value = (await api.system()).cpu.load));
+</script>
+
+<template>
+	<p>{{ Math.round(load) }} %</p>
+</template>
+```
+
+Errors Vue catches (rendering, lifecycle hooks, watchers, template event handlers) show the widget's error card.
+
+## Build
+
+```bash
+npx vite build
+```
+
+`widget()` builds the entry into `dist/main.js`, one ES module with every dependency bundled in, your framework's runtime included. CSS your code imports (React, Vue `<style>` blocks) goes to `dist/main.css`: add `"styles": "dist/main.css"` to the manifest so EdgeStation loads it into the widget's shadow root. The build warns when the manifest doesn't point at what it wrote, and when your own code (not your dependencies) calls `setTimeout` or `setInterval`, which keep running while the widget's page is off screen: use `api.after` and `api.every` instead.
+
+Pass `widget({ entry: 'src/other.ts' })` for another entry. For TypeScript to accept CSS imports, add `"types": ["vite/client"]` to your `tsconfig.json`.
+
+## Try it in EdgeStation
+
+EdgeStation loads every folder of `%APPDATA%\com.edgestation.dashboard\widgets\` (Settings → Widgets → Open folder) that has a `manifest.json`; the folder name is the widget's id. Rather than copying your project there, link it, from a Command Prompt:
+
+```bat
+mklink /J "%APPDATA%\com.edgestation.dashboard\widgets\my-widget" C:\path\to\my-widget
+```
+
+Then rebuild on each change, and use Settings → Widgets → Reload Edge to load the new build:
+
+```bash
+npx vite build --watch
+```
+
+To share the widget, ship the folder with `manifest.json`, `dist/` and any files it reads with `api.asset()`.
+
+## Types
+
+Everything is exported from `@edgestation/sdk` as types: `WidgetApi`, `WidgetModule`, `WidgetManifest`, `WidgetProps`, the settings types and the results of `api.system()`, `api.media`, `api.apps` and `api.storage`.

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import type { WidgetModule } from './types.js';
+export type * from './types.js';
+/**
+ * Types a widget's default export, so editors know `el` and `api` without annotations, in
+ * plain JavaScript too:
+ *
+ * ```js
+ * export default defineWidget({
+ * 	mount(el, api) {
+ * 		el.textContent = api.manifest.name;
+ * 	}
+ * });
+ * ```
+ *
+ * Returns `widget` unchanged: the host only needs the object.
+ */
+export declare function defineWidget(widget: WidgetModule): WidgetModule;

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * Types a widget's default export, so editors know `el` and `api` without annotations, in
+ * plain JavaScript too:
+ *
+ * ```js
+ * export default defineWidget({
+ * 	mount(el, api) {
+ * 		el.textContent = api.manifest.name;
+ * 	}
+ * });
+ * ```
+ *
+ * Returns `widget` unchanged: the host only needs the object.
+ */
+export function defineWidget(widget) {
+    return widget;
+}

package/dist/react.d.ts

@@ -0,0 +1,11 @@
+import { type ComponentType } from 'react';
+import type { WidgetModule, WidgetProps } from './types.js';
+/**
+ * Makes a widget out of a React component: `export default reactWidget(Clock)`. The component
+ * is rendered in a React root on the widget's root with the `api` as its prop, and the root is
+ * unmounted with the widget.
+ *
+ * With React 19, an error thrown while rendering that no error boundary of yours catches shows
+ * the widget's error card.
+ */
+export declare function reactWidget(component: ComponentType<WidgetProps>): WidgetModule;

package/dist/react.js

@@ -0,0 +1,20 @@
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { report } from './report.js';
+/**
+ * Makes a widget out of a React component: `export default reactWidget(Clock)`. The component
+ * is rendered in a React root on the widget's root with the `api` as its prop, and the root is
+ * unmounted with the widget.
+ *
+ * With React 19, an error thrown while rendering that no error boundary of yours catches shows
+ * the widget's error card.
+ */
+export function reactWidget(component) {
+    return {
+        mount(el, api) {
+            const root = createRoot(el, { onUncaughtError: (error) => report(api, error) });
+            root.render(createElement(component, { api }));
+            return () => root.unmount();
+        }
+    };
+}

package/dist/report.d.ts

@@ -0,0 +1,3 @@
+import type { WidgetApi } from './types.js';
+/** Shows `error` on the widget's error card, as if a guarded callback had thrown it. */
+export declare function report(api: WidgetApi, error: unknown): void;

package/dist/report.js

@@ -0,0 +1,6 @@
+/** Shows `error` on the widget's error card, as if a guarded callback had thrown it. */
+export function report(api, error) {
+    api.guard(() => {
+        throw error;
+    })();
+}

package/dist/svelte.d.ts

@@ -0,0 +1,13 @@
+import { type Component } from 'svelte';
+import type { WidgetModule, WidgetProps } from './types.js';
+/**
+ * Makes a widget out of a Svelte 5 component: `export default svelteWidget(Clock)`. The
+ * component is mounted in the widget's root with the `api` as its prop, and unmounted with
+ * the widget.
+ *
+ * Its `<style>` blocks reach the widget's shadow root when the component is compiled with
+ * injected CSS (`svelte({ emitCss: false })` in the Vite config). Errors thrown while Svelte
+ * draws don't show the error card; errors in callbacks wrapped with `api.guard`,
+ * `api.every` or `api.after` do.
+ */
+export declare function svelteWidget(component: Component<WidgetProps>): WidgetModule;

package/dist/svelte.js

@@ -0,0 +1,21 @@
+import { mount, unmount } from 'svelte';
+/**
+ * Makes a widget out of a Svelte 5 component: `export default svelteWidget(Clock)`. The
+ * component is mounted in the widget's root with the `api` as its prop, and unmounted with
+ * the widget.
+ *
+ * Its `<style>` blocks reach the widget's shadow root when the component is compiled with
+ * injected CSS (`svelte({ emitCss: false })` in the Vite config). Errors thrown while Svelte
+ * draws don't show the error card; errors in callbacks wrapped with `api.guard`,
+ * `api.every` or `api.after` do.
+ */
+export function svelteWidget(component) {
+    return {
+        mount(el, api) {
+            const app = mount(component, { target: el, props: { api } });
+            return () => {
+                void unmount(app);
+            };
+        }
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,280 @@
+/**
+ * Contents of a widget's `manifest.json`, as the host hands it to the widget in `api.manifest`.
+ * `id` is not written in the file: the host sets it to the widget's folder name.
+ */
+export interface WidgetManifest {
+    id: string;
+    name: string;
+    version?: string;
+    description?: string;
+    author?: string;
+    /**
+     * Oldest EdgeStation version the widget runs on, such as `"0.1.0"`: the one whose `api` it
+     * uses. Older versions show the widget's error card instead of loading it.
+     */
+    minAppVersion?: string;
+    /** Entry module, relative to the widget folder. Defaults to `main.js`. */
+    main?: string;
+    /** Stylesheet loaded into the widget's shadow root. */
+    styles?: string;
+    /**
+     * Image shown next to the widget's name in settings, relative to the widget folder. Only its
+     * shape counts: it is drawn in the accent color.
+     */
+    icon?: string;
+    /** Default size in grid cells when added to a page. */
+    size?: {
+        w: number;
+        h: number;
+    };
+    /** Options the user can set per placement, in display order. */
+    settings?: WidgetSetting[];
+    /** Lets the widget call `api.webview`, and gives its settings a Profile choice. */
+    webview?: boolean;
+}
+/** One per-placement option, declared in the manifest. */
+export type WidgetSetting = SelectSetting | TextSetting;
+interface SettingBase {
+    key: string;
+    label: string;
+    /** Only shown (and only meaningful) while every listed setting has the given value. */
+    when?: Record<string, string>;
+}
+/** One value out of a list. */
+export interface SelectSetting extends SettingBase {
+    type: 'select';
+    options: {
+        value: string;
+        label: string;
+    }[];
+    /** Used until the user picks something. Defaults to the first option. */
+    default?: string;
+}
+/** Free text, such as a URL. */
+export interface TextSetting extends SettingBase {
+    type: 'text';
+    /** Used until the user types something. Defaults to empty. */
+    default?: string;
+    /** Hint shown while the field is empty. */
+    placeholder?: string;
+}
+/** Saved setting values of one placement, by key. */
+export type WidgetSettingValues = Record<string, string>;
+export type Cleanup = () => void;
+/**
+ * What a widget receives from the host. Deliberately small for now: the full API is still
+ * to be designed. Everything registered here is released when the widget unmounts.
+ */
+export interface WidgetApi {
+    /** Id of this placement; two copies of a widget get different ids. */
+    readonly instanceId: string;
+    readonly manifest: WidgetManifest;
+    /**
+     * This placement's settings: every key declared in the manifest, with its default when
+     * unset. The widget is remounted when the user changes one.
+     */
+    readonly settings: Readonly<WidgetSettingValues>;
+    /** The machine's performance, read when called; nothing is monitored in between. */
+    system(): Promise<SystemInfo>;
+    /**
+     * The programs that used the most CPU since the previous call (from any widget), busiest
+     * first: at most `count`, fewer when not that many used any. Read when called.
+     */
+    topPrograms(count: number): Promise<ProgramUsage[]>;
+    /** What is playing on the machine, read when called, and its playback controls. */
+    readonly media: MediaApi;
+    /** The apps of the Start menu: listed when called, started, and their icons. */
+    readonly apps: AppsApi;
+    /**
+     * The web's `fetch`, sent by the app rather than the Edge page, so CORS doesn't apply: any
+     * `http` or `https` URL answers as it would answer a server. Headers browsers forbid
+     * (`Cookie`, `Origin`, `Referer`, ...) can't be set. Cookies that sites set are kept across
+     * restarts and shared by every widget. A request still unanswered when the widget unmounts
+     * is cancelled.
+     */
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /**
+     * Data kept across remounts and restarts, shared by the widget's placements or owned by
+     * this one. Nothing in it is ever deleted automatically.
+     */
+    readonly storage: StorageApi;
+    /** URL of a file inside the widget folder (images, data, ...). */
+    asset(path: string): string;
+    /** Wraps a callback so an error thrown in it shows this widget's error card. */
+    guard<A extends unknown[]>(fn: (...args: A) => unknown): (...args: A) => void;
+    /**
+     * A guarded `setInterval`, cleared when the widget unmounts. It stops while the widget's
+     * page is off screen or the Edge is frozen (another app is full screen), and ticks right
+     * away when it resumes. Returns a function that stops it sooner.
+     */
+    every(ms: number, fn: () => unknown): Cleanup;
+    /**
+     * A guarded `setTimeout`, cleared if the widget unmounts first. It waits while the widget's
+     * page is off screen, and fires as soon as the page is back if it came due meanwhile.
+     * Unlike `every`, it still fires while the Edge is frozen. Returns a function that
+     * cancels it.
+     */
+    after(ms: number, fn: () => unknown): Cleanup;
+    /**
+     * Shows web page `url` in a native browser view laid over `target`, for sites that refuse
+     * to load in an iframe. It draws above the Edge, so it hides while pages slide and while
+     * `target` is not fully on screen: once it has shown, a picture of it lies over `target`
+     * in its place meanwhile (an `<img>` added to the widget's root). It takes the touches on
+     * its area. It opens in the
+     * browser profile picked in the placement's settings (Default unless the user picks
+     * another): sign-ins last across restarts. Needs `"webview": true` in the manifest, else
+     * it shows the error card. Closed when the widget unmounts; returns a function that closes
+     * it sooner.
+     */
+    webview(target: HTMLElement, url: string, options?: WebviewOptions): Cleanup;
+    /**
+     * Swaps the native scrollbars of `viewport`, an element of the widget that scrolls, for the
+     * app's overlay ones, which show while it scrolls. They are drawn in its parent, so wrap
+     * `viewport` in an element of its own: the parent takes the place `viewport` had in the
+     * layout, and `viewport` fills it. Removed when the widget unmounts; returns a function that
+     * removes them sooner.
+     */
+    scrollbars(viewport: HTMLElement): Cleanup;
+    /** Runs `fn` when the widget unmounts. */
+    onDispose(fn: Cleanup): void;
+}
+/** How `api.webview` opens its page. */
+export interface WebviewOptions {
+    /**
+     * Presents the view as Chrome on a phone (user agent and client hints), for every page it
+     * loads, so that sites which pick their layout from the browser serve their mobile one.
+     * Sites that only follow the width already fit the cell either way.
+     */
+    mobile?: boolean;
+    /**
+     * Shows a Home button in the view's top right corner while it is away from `url`, which
+     * takes it back there. The view leaves that corner to the button (an element added to the
+     * widget's root, like the picture). Where `url` redirects to as it loads counts as `url`.
+     */
+    homeButton?: boolean;
+}
+/** Where a widget saves data: pick the scope that fits each value. */
+export interface StorageApi {
+    /** Shared by every placement of this widget. */
+    readonly widget: WidgetStorage;
+    /** This placement's own; other copies of the widget don't see it. */
+    readonly instance: WidgetStorage;
+}
+/** Saved data: JSON values by key, written to disk shortly after each change. */
+export interface WidgetStorage {
+    /** The value saved under `key`; `undefined` when there is none. */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    /** Saves `value` (anything JSON can hold) under `key`, replacing the previous one. */
+    set(key: string, value: unknown): Promise<void>;
+    /** Removes `key`. Resolves `true` if it had a value. */
+    delete(key: string): Promise<boolean>;
+}
+/** Network throughput in bytes per second. */
+export interface NetRate {
+    down: number;
+    up: number;
+}
+/**
+ * The machine's performance at the time of the call. CPU load and network speeds are
+ * measured since the previous call (from any widget); calls less than 500 ms apart share
+ * one reading.
+ */
+export interface SystemInfo {
+    hostname: string;
+    /** Name of the connected Wi-Fi network (its Windows profile name); `null` when not connected. */
+    wifi: string | null;
+    /** Load of all CPU cores, in percent. */
+    cpu: {
+        load: number;
+    };
+    /** First NVIDIA GPU (load in percent, temperature in °C); `null` when there is none. */
+    gpu: {
+        load: number;
+        temperature: number;
+    } | null;
+    /**
+     * Since the previous call, plus averages over the calls of the last 1, 5 and 15 minutes:
+     * the full window while widgets keep asking, less right after they start or resume.
+     */
+    net: NetRate & {
+        avg1m: NetRate;
+        avg5m: NetRate;
+        avg15m: NetRate;
+    };
+}
+/** A program's CPU use: every process that shows the same name, added together. */
+export interface ProgramUsage {
+    /**
+     * What Task Manager calls it: its executable's description (`THE FINALS`, `Google Chrome`),
+     * else the executable file name (`crashpad_handler.exe`).
+     */
+    name: string;
+    /** Percent of all logical processors, like Task Manager. */
+    cpu: number;
+}
+export interface MediaApi {
+    /** The session Windows considers current (the one media keys control); `null` when none. */
+    current(): Promise<MediaInfo | null>;
+    /** Album art of the track from the latest `current()` call, as a data URL; `null` when none. */
+    art(): Promise<string | null>;
+    /** Asks the current session's app to play, pause or skip. Resolves `false` if it declined. */
+    control(action: MediaAction): Promise<boolean>;
+}
+export type MediaAction = 'play' | 'pause' | 'next' | 'previous';
+/** A media session as an app publishes it to Windows. Fields the app doesn't set are empty. */
+export interface MediaInfo {
+    /** App that owns the session, as Windows names it (`Spotify.exe`, `MSEdge`, ...). */
+    app: string;
+    title: string;
+    artist: string;
+    album: string;
+    playing: boolean;
+    /**
+     * Seconds into the track at the time of the call; `null` when the app reports no timeline.
+     * When the app blanks it out (Zen and Firefox do, about once a minute), it carries on from
+     * the last one reported, as long as calls come at least every 5 seconds.
+     */
+    position: number | null;
+    duration: number | null;
+    /** Changes whenever the album art does: call `art()` then. `null` when there is no art. */
+    art: number | null;
+    /** Which `control()` actions the app accepts right now. */
+    can: Record<MediaAction, boolean>;
+}
+/** The apps of the Start menu's All apps list (the shell's Apps folder). */
+export interface AppsApi {
+    /** Every app, by name, read when called. */
+    list(): Promise<AppInfo[]>;
+    /**
+     * Starts app `id` as the Start menu does, asking for its window on the main screen rather
+     * than the Edge (apps that remember their position may still open where they were).
+     * Rejects when the app is gone.
+     */
+    launch(id: string): Promise<void>;
+    /**
+     * URL of the icon of app `id`, for an `<img>`: a PNG `size` pixels square (16 to 256,
+     * default 64). Ask for the size it shows at in device pixels: icons drawn larger are sharper.
+     */
+    icon(id: string, size?: number): string;
+}
+/** An app as the Start menu lists it. */
+export interface AppInfo {
+    /**
+     * Launches it and draws its icon: its name in the shell's Apps folder, the app's
+     * AppUserModelID or, for a program without one, a path to it. Stays the same across
+     * restarts, so widgets can save it.
+     */
+    id: string;
+    /** What the Start menu calls it. */
+    name: string;
+}
+/** The default export of a widget's entry module. */
+export interface WidgetModule {
+    /** Render into `el`. May return (or resolve to) a cleanup function. */
+    mount(el: HTMLElement, api: WidgetApi): void | Cleanup | Promise<void | Cleanup>;
+}
+/** Props of a widget's root component in the Svelte, React and Vue adapters. */
+export interface WidgetProps {
+    api: WidgetApi;
+}
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/vite.d.ts

@@ -0,0 +1,22 @@
+import type { Plugin } from 'vite';
+export interface WidgetBuildOptions {
+    /**
+     * Entry module, relative to the project root. Defaults to the first of `src/main.ts`,
+     * `src/main.tsx`, `src/main.js` and `src/main.jsx` that exists.
+     */
+    entry?: string;
+}
+/**
+ * Builds the widget into what EdgeStation loads: one self-contained ES module,
+ * `dist/main.js`, with every dependency bundled in (frameworks included), plus `dist/main.css`
+ * when the code imports CSS. Add your framework's Vite plugin next to it:
+ *
+ * ```ts
+ * export default defineConfig({ plugins: [react(), widget()] });
+ * ```
+ *
+ * It also replaces `process.env.NODE_ENV`, which React and Vue read and a browser lacks, and
+ * warns when `manifest.json` doesn't point at the files it writes, or when the widget's own
+ * code (not its dependencies) calls `setTimeout` or `setInterval`, which don't pause with it.
+ */
+export declare function widget(options?: WidgetBuildOptions): Plugin;

package/dist/vite.js

@@ -0,0 +1,126 @@
+// Loaded by Node from the widget's Vite config: no relative imports, only erasable TypeScript.
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+const ENTRIES = ['src/main.ts', 'src/main.tsx', 'src/main.js', 'src/main.jsx'];
+/** Forward slashes and no leading `./`, as paths are written in `manifest.json`. */
+const normalize = (path) => path.replace(/\\/g, '/').replace(/^\.\//, '');
+/** What each global timer does that the `api` one doesn't. */
+const TIMERS = {
+    setInterval: "keeps running while the widget's page is off screen or the Edge is frozen, and after " +
+        'the widget unmounts: use api.every instead',
+    setTimeout: "fires even while the widget's page is off screen, and after the widget unmounts: use " +
+        'api.after instead'
+};
+const GLOBALS = new Set(['window', 'globalThis', 'self']);
+/** A file of the widget's own, by its module id: not a dependency, a virtual module or a query. */
+const OWN = /^[^\0?]+\.(?:[cm]?[jt]sx?|svelte|vue)$/;
+/** The global timer that `callee` names (`setTimeout`, `window.setInterval`, ...), if any. */
+function timerName(callee) {
+    const { object, property } = callee;
+    const global = callee.type === 'MemberExpression' &&
+        !callee.computed &&
+        object?.type === 'Identifier' &&
+        GLOBALS.has(object.name ?? '');
+    const name = global ? property?.name : callee.type === 'Identifier' ? callee.name : undefined;
+    return name !== undefined && Object.hasOwn(TIMERS, name) ? name : undefined;
+}
+/** The global timers called anywhere in `node`, an ESTree node or a list of them. */
+function timersCalled(node, found = new Set()) {
+    if (node && typeof node === 'object') {
+        const { type, callee } = node;
+        const name = type === 'CallExpression' && callee ? timerName(callee) : undefined;
+        if (name)
+            found.add(name);
+        for (const child of Object.values(node))
+            timersCalled(child, found);
+    }
+    return found;
+}
+/**
+ * Builds the widget into what EdgeStation loads: one self-contained ES module,
+ * `dist/main.js`, with every dependency bundled in (frameworks included), plus `dist/main.css`
+ * when the code imports CSS. Add your framework's Vite plugin next to it:
+ *
+ * ```ts
+ * export default defineConfig({ plugins: [react(), widget()] });
+ * ```
+ *
+ * It also replaces `process.env.NODE_ENV`, which React and Vue read and a browser lacks, and
+ * warns when `manifest.json` doesn't point at the files it writes, or when the widget's own
+ * code (not its dependencies) calls `setTimeout` or `setInterval`, which don't pause with it.
+ */
+export function widget(options = {}) {
+    let root = process.cwd();
+    let outDir = 'dist';
+    let manifest;
+    /** Path of a built file as `manifest.json` should name it. */
+    const built = (file) => normalize(relative(root, resolve(root, outDir, file)));
+    return {
+        name: 'edgestation-widget',
+        apply: 'build',
+        config(config, { mode }) {
+            const base = resolve(config.root ?? process.cwd());
+            const entry = options.entry ?? ENTRIES.find((file) => existsSync(join(base, file)));
+            if (!entry) {
+                throw new Error(`No widget entry: create one of ${ENTRIES.join(', ')}, or pass widget({ entry })`);
+            }
+            const nodeEnv = mode === 'production' ? 'production' : 'development';
+            return {
+                define: config.define?.['process.env.NODE_ENV'] === undefined
+                    ? { 'process.env.NODE_ENV': JSON.stringify(nodeEnv) }
+                    : {},
+                build: {
+                    lib: { entry, formats: ['es'], fileName: () => 'main.js', cssFileName: 'main' },
+                    outDir: config.build?.outDir ?? 'dist'
+                }
+            };
+        },
+        configResolved(config) {
+            root = config.root;
+            outDir = config.build.outDir;
+        },
+        buildStart() {
+            const file = join(root, 'manifest.json');
+            manifest = undefined;
+            if (!existsSync(file)) {
+                this.warn('No manifest.json in the project root: EdgeStation only lists folders with one.');
+                return;
+            }
+            try {
+                manifest = JSON.parse(readFileSync(file, 'utf8'));
+            }
+            catch (error) {
+                this.warn(`manifest.json is not valid JSON: ${error.message}`);
+                return;
+            }
+            const main = typeof manifest?.main === 'string' ? manifest.main : 'main.js';
+            if (normalize(main) !== built('main.js')) {
+                this.warn(`manifest.json has "main": "${main}" but the build writes ${built('main.js')}: ` +
+                    `set "main": "${built('main.js')}".`);
+            }
+        },
+        // Last, so TypeScript, Svelte and Vue files are plain JavaScript by then, whatever the
+        // plugin order. A dependency's timers are its own business.
+        transform: {
+            order: 'post',
+            handler(code, id) {
+                if (!OWN.test(id) || id.includes('/node_modules/'))
+                    return;
+                if (!/\bset(?:Timeout|Interval)\b/.test(code))
+                    return;
+                for (const name of timersCalled(this.parse(code))) {
+                    this.warn(`${normalize(relative(root, id))} calls ${name}, which ${TIMERS[name]}.`);
+                }
+            }
+        },
+        // Not `generateBundle`: Vite's CSS plugin adds main.css to the bundle after it.
+        writeBundle(_, bundle) {
+            const css = built('main.css');
+            const styles = typeof manifest?.styles === 'string' ? normalize(manifest.styles) : undefined;
+            if (manifest && bundle['main.css'] && styles !== css) {
+                this.warn(`The build writes ${css}: set "styles": "${css}" in manifest.json so EdgeStation ` +
+                    `loads it into the widget.`);
+            }
+        }
+    };
+}

package/dist/vue.d.ts

@@ -0,0 +1,11 @@
+import { type Component } from 'vue';
+import type { WidgetModule } from './types.js';
+/**
+ * Makes a widget out of a Vue 3 component: `export default vueWidget(Clock)`. The component is
+ * mounted as a Vue app on the widget's root with the `api` as its prop
+ * (`defineProps<WidgetProps>()`), and unmounted with the widget.
+ *
+ * Errors Vue catches (in rendering, lifecycle hooks, watchers and template event handlers)
+ * show the widget's error card.
+ */
+export declare function vueWidget(component: Component): WidgetModule;

package/dist/vue.js

@@ -0,0 +1,20 @@
+import { createApp } from 'vue';
+import { report } from './report.js';
+/**
+ * Makes a widget out of a Vue 3 component: `export default vueWidget(Clock)`. The component is
+ * mounted as a Vue app on the widget's root with the `api` as its prop
+ * (`defineProps<WidgetProps>()`), and unmounted with the widget.
+ *
+ * Errors Vue catches (in rendering, lifecycle hooks, watchers and template event handlers)
+ * show the widget's error card.
+ */
+export function vueWidget(component) {
+    return {
+        mount(el, api) {
+            const app = createApp(component, { api });
+            app.config.errorHandler = (error) => report(api, error);
+            app.mount(el);
+            return () => app.unmount();
+        }
+    };
+}

package/manifest.schema.json

@@ -0,0 +1,112 @@
+{
+	"$schema": "http://json-schema.org/draft-07/schema#",
+	"title": "EdgeStation widget manifest",
+	"description": "The manifest.json of an EdgeStation widget. The widget's id is its folder name.",
+	"type": "object",
+	"required": ["name"],
+	"additionalProperties": false,
+	"properties": {
+		"$schema": { "type": "string" },
+		"name": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Name shown in Settings."
+		},
+		"version": { "type": "string", "description": "The widget's own version." },
+		"description": { "type": "string", "description": "What the widget shows, for Settings." },
+		"author": { "type": "string" },
+		"minAppVersion": {
+			"type": "string",
+			"pattern": "^\\d+\\.\\d+\\.\\d+$",
+			"description": "Oldest EdgeStation version the widget runs on, such as \"0.1.0\": the one whose api it uses. Older versions show the error card instead."
+		},
+		"main": {
+			"type": "string",
+			"default": "main.js",
+			"description": "Entry ES module, relative to the widget folder. It default-exports { mount(el, api) }."
+		},
+		"styles": {
+			"type": "string",
+			"description": "Stylesheet loaded into the widget's shadow root, relative to the widget folder."
+		},
+		"icon": {
+			"type": "string",
+			"description": "Square SVG or PNG on a transparent background, shown in Settings. Only its shape counts: it is drawn in the accent color."
+		},
+		"size": {
+			"type": "object",
+			"description": "Default size in grid cells when the widget is added to a page.",
+			"required": ["w", "h"],
+			"additionalProperties": false,
+			"properties": {
+				"w": { "type": "integer", "minimum": 1 },
+				"h": { "type": "integer", "minimum": 1 }
+			}
+		},
+		"webview": {
+			"type": "boolean",
+			"description": "Lets the widget call api.webview, and gives its settings a Profile choice."
+		},
+		"settings": {
+			"type": "array",
+			"description": "Options the user sets per placement, in display order. The widget reads them from api.settings.",
+			"items": { "oneOf": [{ "$ref": "#/definitions/select" }, { "$ref": "#/definitions/text" }] }
+		}
+	},
+	"definitions": {
+		"key": {
+			"type": "string",
+			"minLength": 1,
+			"description": "Name of the value in api.settings."
+		},
+		"label": { "type": "string", "description": "Shown next to the field." },
+		"when": {
+			"type": "object",
+			"description": "Only show this setting while the named settings have these values.",
+			"additionalProperties": { "type": "string" }
+		},
+		"select": {
+			"type": "object",
+			"description": "One value out of a list.",
+			"required": ["key", "label", "type", "options"],
+			"additionalProperties": false,
+			"properties": {
+				"key": { "$ref": "#/definitions/key" },
+				"label": { "$ref": "#/definitions/label" },
+				"type": { "const": "select" },
+				"options": {
+					"type": "array",
+					"minItems": 1,
+					"items": {
+						"type": "object",
+						"required": ["value", "label"],
+						"additionalProperties": false,
+						"properties": {
+							"value": { "type": "string", "description": "Saved value." },
+							"label": { "type": "string", "description": "Shown label." }
+						}
+					}
+				},
+				"default": {
+					"type": "string",
+					"description": "Value until the user picks one. Defaults to the first option."
+				},
+				"when": { "$ref": "#/definitions/when" }
+			}
+		},
+		"text": {
+			"type": "object",
+			"description": "Free text, such as a URL.",
+			"required": ["key", "label", "type"],
+			"additionalProperties": false,
+			"properties": {
+				"key": { "$ref": "#/definitions/key" },
+				"label": { "$ref": "#/definitions/label" },
+				"type": { "const": "text" },
+				"default": { "type": "string", "description": "Value until the user types one." },
+				"placeholder": { "type": "string", "description": "Hint shown while the field is empty." },
+				"when": { "$ref": "#/definitions/when" }
+			}
+		}
+	}
+}

package/package.json

@@ -1,6 +1,94 @@
 {
   "name": "@edgestation/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Types and build helpers to write widgets for EdgeStation, the secondary display dashboard made for the Corsair Xeneon Edge, in plain JavaScript, Svelte, React or Vue.",
+  "keywords": [
+    "edgestation",
+    "widget",
+    "dashboard",
+    "secondary-display",
+    "xeneon-edge"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chainlist/edgestation.git",
+    "directory": "packages/sdk"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./svelte": {
+      "types": "./dist/svelte.d.ts",
+      "default": "./dist/svelte.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./vue": {
+      "types": "./dist/vue.d.ts",
+      "default": "./dist/vue.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "default": "./dist/vite.js"
+    },
+    "./manifest.schema.json": "./manifest.schema.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "manifest.schema.json"
+  ],
+  "peerDependencies": {
+    "react": ">=19",
+    "react-dom": ">=19",
+    "svelte": "^5",
+    "vite": ">=6",
+    "vue": "^3.3"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@sveltejs/vite-plugin-svelte": "^7.2.0",
+    "@types/node": "^26.6.6",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "ajv": "^8.20.0",
+    "happy-dom": "^21.0.4",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "svelte": "^5.57.2",
+    "typescript": "^6.0.3",
+    "vite": "^8.3.0",
+    "vitest": "^4.1.8",
+    "vue": "^3.5.45"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc -p tsconfig.json",
+    "test": "vitest --run"
+  }
 }