glimpse-sdk

Write a glimpse panel applet in React. The applet is a Node program: the panel starts it, and the SDK speaks the panel's NDJSON protocol on the unix socket named by GLIMPSE_APPLET_SOCKET, which the panel sets (without it the applet exits with code 1).

import { Indicator, Popover, Row, run, Section } from "glimpse-sdk";

await run(
  <>
    <Indicator icon="face-smile-symbolic" tooltip="Hello">Hello</Indicator>
    <Popover icon="face-smile-symbolic" title="Hello">
      <Section title="Hello">
        <Row title="It works" />
      </Section>
    </Popover>
  </>,
);

Start

glimpsectl applet new
cd <dir> && npm install
glimpsectl applet run --dev .

applet new writes index.tsx, package.json, tsconfig.json, devconfig.toml, README.md and the desktop entry. The entry runs node --run start, which bundles everything into build/applet.mjs and starts it.

Set "jsxImportSource": "glimpse-sdk" in tsconfig.json.

API

See the SDK reference and elements.

usePersistentState(key, initial) works like useState: it loads key from state.json in that directory on the first render (a missing or corrupt file falls back to initial) and writes the whole JSON object back when the value changes, so several keys share one file. It persists nothing when the state dir is empty. The directory is the applet's private persistent directory, returned by useStateDir.

notify and copy run notify-send and wl-copy from the applet process.

An exec applet runs unconfined as a systemd user unit and has the user's full session.

The wire format is specified in PROTOCOL.md.

Testing

Call the in-memory host's close() before rendering another applet. The test host checks the shape of each commit, not the panel's nesting and size rules; glimpsectl applet run --dev enforces those. See the testing reference.