glimpse-sdk 0.8.0 → 0.9.0

package/README.md

@@ -1,128 +1,51 @@
-# Glimpse Applet TypeScript SDK
-
-Small async framework for building Glimpse `exec` applets without touching stdio or raw JSON.
-
-Requires Node.js 20+.
-
-## Install
-
-```sh
-npm install glimpse-sdk
+# glimpse-sdk
+
+Write a [glimpse](https://github.com/alex-oleshkevich/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
+stdin and stdout.
+
+```tsx
+import { Hero, Indicator, Popover, Row, run, Section } from "glimpse-sdk";
+
+await run(
+  <>
+    <Indicator icon="face-smile-symbolic" tooltip="Hello">Hello</Indicator>
+    <Popover>
+      <Hero icon="face-smile-symbolic" title="Hello" />
+      <Section title="Hello">
+        <Row title="It works" />
+      </Section>
+    </Popover>
+  </>,
+);
 ```
 
-## Develop
-
-Create and live-run a TypeScript applet project with the Glimpse tooling:
+## Start
 
-```sh
-glimpse-shell applets new counter --lang typescript
-cd counter
-glimpse-shell applets dev
 ```
-
-Read `docs/custom-applets/tooling.md` for project layout, `applet.toml`, dev applets, local linking, distribution, and diagnostics.
-
-## Goals
-
-- typed protocol models
-- typed widget builders
-- async runtime
-- widget-local callbacks, with explicit typed handler registration available when needed
-- separate `status(state)` and `popover(state)` methods; state mutation via `await this.setState(...)`
-
-## Example
-
-```ts
-import {
-  Applet,
-  Column,
-  Hero,
-  Label,
-  StatusItem,
-  Tile,
-  type TreeNode,
-} from "glimpse-sdk";
-
-interface DeployState {
-  version: string;
-  status: string;
-}
-
-class DeployApplet extends Applet<DeployState> {
-  constructor() {
-    super();
-  }
-
-  protected initialState(): DeployState {
-    return { version: "2026.04.07", status: "Ready" };
-  }
-
-  protected async status(state: DeployState): Promise<StatusItem[]> {
-    return [
-      new StatusItem({
-        id: "deploy",
-        icon: "software-update-available-symbolic",
-        label: state.status,
-      }),
-    ];
-  }
-
-  protected async popover(state: DeployState): Promise<TreeNode | null> {
-    return new Column({
-      children: [
-        new Hero({
-          icon: "software-update-available-symbolic",
-          title: "Deploy",
-          subtitle: state.version,
-        }),
-        new Label("Version"),
-        new Tile({
-          id: "deploy_now",
-          primary: "Deploy now",
-          left_icon: "media-playback-start-symbolic",
-          on_click: async () => {
-            await this.setState({ status: "Deploying" });
-          },
-        }),
-      ],
-    });
-  }
-}
-
-await new DeployApplet().run();
+glimpsectl applets new
+cd <dir> && npm install && npm run build
+glimpsectl applets dev .
 ```
 
-## Handler Registration
+`applets new` writes `index.tsx`, `package.json`, `tsconfig.json`, `README.md` and the desktop
+entry. `npm run build` bundles everything into `build/applet.mjs` with a `#!/usr/bin/env node`
+shebang.
 
-Prefer widget-local callbacks for controls rendered in `popover(state)`.
-Explicit registration helpers are still available when the handler should live
-outside the widget tree:
+Set `"jsxImportSource": "glimpse-sdk"` in `tsconfig.json`.
 
-- `this.onClick(id, handler)`
-- `this.onScroll(id, handler)`
-- `this.onInput(id, handler)`
-- `this.onChange(id, handler)`
-- `this.onToggle(id, handler)`
+## API
 
-The SDK owns the line transport. `status(state)` produces the panel items;
-`popover(state)` produces the popover tree; both are pure functions of state.
+- Components: `Indicator`, `Popover`, `Hero`, `Section`, `Row`, `SwitchRow`, `Fader`, `Entry`,
+  `Placeholder`, `Footer`, `Box`, `Label`, `Image`, `Button`, `Switch`, `Scale`, `Spinner`,
+  `Progress` and `Separator`.
+- Hooks: `useState`, `useEffect`, `useOptions`, `usePlacement`, `usePopoverOpen`,
+  `useAppletName` and `useStateDir`. `useStateDir` returns the applet's private, persistent
+  directory.
+- Host requests: `notify`, `copy`, `openUri`, `sessionAction` and `closePopover`.
 
-## IPC client
+The applet runs in a sandbox. Beyond its state directory, it reaches only the paths the user
+grants under `[applets."<id>"] sandbox` in the glimpse config, and it has no network unless
+`network = true`.
 
-Talk to a running Glimpse daemon: subscribe to event channels and dispatch
-actions. `ipc(service)` only resolves the socket path — the connection is
-opened lazily.
-
-```ts
-import { ipc } from "glimpse-sdk";
-
-const sub = ipc("shell"); // "shell" | "wallpaper" | "idle" | "lock"
-
-// Fire an action; awaits the ack, throws IpcError if the server rejects it.
-const ack = await sub.dispatch("open_uri", { uri: "https://example.com" });
-
-// Stream events until the socket closes.
-for await (const ev of sub.listen("audio.*")) {
-  console.log(ev.name, ev.fields);
-}
-```
+The wire format is specified in [PROTOCOL.md](PROTOCOL.md).

package/dist/index.d.ts

@@ -0,0 +1,174 @@
+import { type Io, type Placement } from "./reconciler.ts";
+export { Fragment, jsx, jsxDEV, jsxs } from "./jsx-runtime.ts";
+export type Node = string | number | boolean | null | undefined | Node[] | {
+    type: unknown;
+    props: unknown;
+    key: unknown;
+};
+export type FC<P = object> = (props: P & {
+    key?: string | number;
+}) => Node;
+export type ClassName = "dim-label" | "caption" | "heading" | "title-1" | "title-2" | "title-3" | "title-4" | "numeric" | "accent" | "success" | "warning" | "error" | "flat" | "pill" | "circular";
+type Align = "fill" | "start" | "end" | "center" | "baseline";
+export declare const Indicator: FC<{
+    icon?: string;
+    tooltip?: string;
+    text?: string;
+    badge?: string;
+    overlay?: string;
+    dot?: string;
+    severity?: "info" | "warning" | "error";
+    attention?: boolean;
+    notice?: boolean;
+    className?: ClassName;
+    onPress?: (button: number) => void;
+    onScroll?: (dx: number, dy: number) => void;
+    children?: Node;
+}>;
+export declare const Popover: FC<{
+    className?: ClassName;
+    children?: Node;
+}>;
+export declare const Hero: FC<{
+    icon?: string;
+    title?: string;
+    subtitle?: string;
+    className?: ClassName;
+}>;
+export declare const Section: FC<{
+    title?: string;
+    count?: string;
+    className?: ClassName;
+    children?: Node;
+}>;
+export declare const Row: FC<{
+    icon?: string;
+    title?: string;
+    subtitle?: string;
+    value?: string;
+    selected?: boolean;
+    busy?: boolean;
+    className?: ClassName;
+    onActivate?: () => void;
+}>;
+export declare const SwitchRow: FC<{
+    icon?: string;
+    title?: string;
+    subtitle?: string;
+    active?: boolean;
+    busy?: boolean;
+    className?: ClassName;
+    onToggle?: (active: boolean) => void;
+}>;
+export declare const Fader: FC<{
+    icon?: string;
+    value?: number;
+    maximum?: number;
+    floor?: number;
+    muted?: boolean;
+    className?: ClassName;
+    onChange?: (value: number) => void;
+    onMute?: () => void;
+}>;
+export declare const Entry: FC<{
+    placeholder?: string;
+    value?: string;
+    className?: ClassName;
+    onChange?: (value: string) => void;
+    onSubmit?: (value: string) => void;
+}>;
+export declare const Placeholder: FC<{
+    icon?: string;
+    title?: string;
+    description?: string;
+    className?: ClassName;
+}>;
+export declare const Footer: FC<{
+    className?: ClassName;
+    children?: Node;
+}>;
+export declare const Box: FC<{
+    orientation?: "horizontal" | "vertical";
+    spacing?: number;
+    homogeneous?: boolean;
+    halign?: Align;
+    valign?: Align;
+    hexpand?: boolean;
+    vexpand?: boolean;
+    className?: ClassName;
+    children?: Node;
+}>;
+export declare const Label: FC<{
+    text?: string;
+    wrap?: boolean;
+    xalign?: number;
+    ellipsize?: "none" | "start" | "middle" | "end";
+    lines?: number;
+    className?: ClassName;
+    children?: Node;
+}>;
+export declare const Image: FC<{
+    icon?: string;
+    tooltip?: string;
+    pixelSize?: number;
+    className?: ClassName;
+}>;
+export declare const Button: FC<{
+    text?: string;
+    icon?: string;
+    tooltip?: string;
+    sensitive?: boolean;
+    className?: ClassName;
+    onClick?: () => void;
+    children?: Node;
+}>;
+export declare const Switch: FC<{
+    active?: boolean;
+    sensitive?: boolean;
+    className?: ClassName;
+    onToggle?: (active: boolean) => void;
+}>;
+export declare const Scale: FC<{
+    value?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    sensitive?: boolean;
+    className?: ClassName;
+    onChange?: (value: number) => void;
+}>;
+export declare const Spinner: FC<{
+    className?: ClassName;
+}>;
+export declare const Progress: FC<{
+    text?: string;
+    fraction?: number;
+    className?: ClassName;
+    children?: Node;
+}>;
+export declare const Separator: FC<{
+    orientation?: "horizontal" | "vertical";
+    className?: ClassName;
+}>;
+export type { Io, Placement };
+export declare function useState<T>(initial: T | (() => T)): [T, (action: T | ((prev: T) => T)) => void];
+export declare function useEffect(effect: () => void | (() => void), deps?: readonly unknown[]): void;
+export declare function useOptions<T extends Record<string, unknown> = Record<string, unknown>>(): T;
+export declare function usePlacement(): Placement | null;
+export declare function usePopoverOpen(): boolean;
+export declare function useAppletName(): string;
+export declare function useStateDir(): string;
+export declare function createElement(type: unknown, props?: Record<string, unknown> | null, ...children: unknown[]): unknown;
+export declare function notify(message: {
+    summary: string;
+    body?: string;
+    icon?: string;
+    urgency?: "low" | "normal" | "critical";
+}): void;
+export declare function copy(text: string): void;
+export declare function openUri(uri: string): void;
+export type SessionAction = "lock" | "suspend" | "hibernate" | "log-out" | "reboot" | "power-off";
+export declare function sessionAction(action: SessionAction): void;
+export { sessionAction as session };
+export declare function closePopover(): void;
+export declare function run(element: unknown, io?: Io): Promise<void>;

package/dist/index.js

@@ -0,0 +1,78 @@
+import { nameStore, openStore, optionsStore, placementStore, redirectConsole, send, session, stateStore, standardIo, } from "./reconciler.js";
+import * as react from "react";
+redirectConsole();
+export { Fragment, jsx, jsxDEV, jsxs } from "./jsx-runtime.js";
+export const Indicator = "indicator";
+export const Popover = "popover";
+export const Hero = "hero";
+export const Section = "section";
+export const Row = "row";
+export const SwitchRow = "switchrow";
+export const Fader = "fader";
+export const Entry = "entry";
+export const Placeholder = "placeholder";
+export const Footer = "footer";
+export const Box = "box";
+export const Label = "label";
+export const Image = "image";
+export const Button = "button";
+export const Switch = "switch";
+export const Scale = "scale";
+export const Spinner = "spinner";
+export const Progress = "progress";
+export const Separator = "separator";
+export function useState(initial) {
+    return react.useState(initial);
+}
+export function useEffect(effect, deps) {
+    react.useEffect(effect, deps);
+}
+export function useOptions() {
+    return react.useSyncExternalStore(optionsStore.subscribe, optionsStore.get);
+}
+export function usePlacement() {
+    return react.useSyncExternalStore(placementStore.subscribe, placementStore.get);
+}
+export function usePopoverOpen() {
+    return react.useSyncExternalStore(openStore.subscribe, openStore.get);
+}
+export function useAppletName() {
+    return react.useSyncExternalStore(nameStore.subscribe, nameStore.get);
+}
+export function useStateDir() {
+    return react.useSyncExternalStore(stateStore.subscribe, stateStore.get);
+}
+export function createElement(type, props, ...children) {
+    return react.createElement(type, props ?? null, ...children);
+}
+export function notify(message) {
+    const wire = {
+        t: "notify",
+        summary: message.summary,
+    };
+    if (message.body !== undefined)
+        wire.body = message.body;
+    if (message.icon !== undefined)
+        wire.icon = message.icon;
+    if (message.urgency !== undefined)
+        wire.urgency = message.urgency;
+    send(wire);
+}
+export function copy(text) {
+    send({ t: "copy", text });
+}
+export function openUri(uri) {
+    send({ t: "open-uri", uri });
+}
+export function sessionAction(action) {
+    send({ t: "session", action });
+}
+export { sessionAction as session };
+export function closePopover() {
+    send({ t: "close-popover" });
+}
+export async function run(element, io) {
+    redirectConsole();
+    await session(element, io ?? standardIo());
+    process.exit(0);
+}

package/dist/jsx-runtime.d.ts

@@ -0,0 +1,16 @@
+import { Fragment } from "react/jsx-runtime";
+import type { Node } from "./index.ts";
+type JsxFn = (type: unknown, props: unknown, key?: unknown) => unknown;
+export declare const jsx: JsxFn;
+export declare const jsxs: JsxFn;
+export { Fragment };
+export declare function jsxDEV(type: unknown, props: unknown, key?: unknown): unknown;
+export declare namespace JSX {
+    type Element = Node;
+    interface ElementChildrenAttribute {
+        children: unknown;
+    }
+    interface IntrinsicElements {
+        [elemName: string]: Record<string, unknown>;
+    }
+}

package/dist/jsx-runtime.js

@@ -0,0 +1,7 @@
+import { Fragment, jsx as reactJsx, jsxs as reactJsxs } from "react/jsx-runtime";
+export const jsx = reactJsx;
+export const jsxs = reactJsxs;
+export { Fragment };
+export function jsxDEV(type, props, key) {
+    return jsx(type, props, key);
+}

package/dist/reconciler.d.ts

@@ -0,0 +1,30 @@
+import type { Readable } from "node:stream";
+export type Placement = {
+    output: string | null;
+    position: string;
+    orientation: string;
+    zone: string;
+    size: number;
+};
+export type Io = {
+    writeLine: (line: string) => void;
+    lines: AsyncIterable<string | string[]>;
+};
+type Store<T> = {
+    get: () => T;
+    set: (value: T) => void;
+    subscribe: (listener: () => void) => () => void;
+};
+export declare const optionsStore: Store<Record<string, unknown>>;
+export declare const placementStore: Store<Placement | null>;
+export declare const nameStore: Store<string>;
+export declare const stateStore: Store<string>;
+export declare const openStore: Store<boolean>;
+export declare function setEmit(write: (message: unknown) => void): void;
+export declare function send(message: unknown): void;
+export declare function redirectConsole(): void;
+export declare function restoreConsole(): void;
+export declare function session(element: unknown, io: Io): Promise<void>;
+export declare function stdinLines(input?: Readable): AsyncIterable<string[]>;
+export declare function standardIo(): Io;
+export {};