glimpse-sdk 0.3.0 → 0.7.0

package/README.md

@@ -10,6 +10,18 @@ Requires Node.js 20+.
 npm install glimpse-sdk
 ```
 
+## Develop
+
+Create and live-run a TypeScript applet project with the Glimpse tooling:
+
+```sh
+glimpse-applet new counter --lang typescript
+cd counter
+glimpse-applet dev
+```
+
+Read `docs/custom-applets/tooling.md` for project layout, `applet.toml`, dev applets, linking, and diagnostics.
+
 ## Goals
 
 - typed protocol models
@@ -27,8 +39,8 @@ import {
   Button,
   Hero,
   Icon,
-  Label,
   StatusItem,
+  Label,
   type TreeNode,
 } from "glimpse-sdk";
 
@@ -92,3 +104,23 @@ Use explicit registration helpers instead of decorators:
 
 The SDK owns the line transport. `status(state)` produces the panel items;
 `popover(state)` produces the popover tree; both are pure functions of state.
+
+## IPC client
+
+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);
+}
+```

package/dist/src/app.d.ts

@@ -1,4 +1,4 @@
-import { type CallbackEvent, type ChangeEvent, type ClickEvent, type InitEvent, type InputEvent, type ScrollEvent, type ToggleEvent } from "./events.js";
+import { type CallbackEvent, type ChangeEvent, type ClickEvent, type InitEvent, type InputEvent, type PopoverEvent, type ScrollEvent, type ToggleEvent } from "./events.js";
 import { StatusItem } from "./protocol.js";
 import { type TreeNode } from "./widgets.js";
 type Handler<EventT> = (event: EventT) => void | Promise<void>;
@@ -7,9 +7,21 @@ interface OutgoingMessage {
     data: unknown;
     line: string;
 }
+interface ShowNotificationOptions {
+    body?: string;
+}
+export interface CommandResult {
+    stdout: string;
+    stderr: string;
+    rc: number;
+}
+interface DismissNotificationArgs {
+    id: number;
+}
 export declare abstract class Applet<State extends object> {
     state: State;
     private readonly handlerMap;
+    private inlineHandlerMap;
     private readonly outgoing;
     private flushPromise;
     private renderQueued;
@@ -18,6 +30,7 @@ export declare abstract class Applet<State extends object> {
     private popoverOpen;
     protected constructor();
     protected abstract initialState(): State;
+    protected cssClass(): string | null;
     protected onStart(): Promise<void>;
     protected onInit(_event: InitEvent): Promise<void>;
     protected onCallback(_event: CallbackEvent): Promise<void>;
@@ -29,7 +42,16 @@ export declare abstract class Applet<State extends object> {
     onInput(id: string, handler: Handler<InputEvent>): void;
     onChange(id: string, handler: Handler<ChangeEvent>): void;
     onToggle(id: string, handler: Handler<ToggleEvent>): void;
+    onPopover(handler: Handler<PopoverEvent>): void;
     isPopoverOpen(): boolean;
+    log(...args: unknown[]): void;
+    protected showNotification(summary: string, options?: ShowNotificationOptions): Promise<void>;
+    protected openUri(uri: string): Promise<void>;
+    protected copyToClipboard(text: string): Promise<void>;
+    protected runCommand(command: string[]): Promise<CommandResult>;
+    protected dismissNotification(args: DismissNotificationArgs): void;
+    protected closePopover(): void;
+    protected runDesktopCommand(command: string, args: string[], input?: string): Promise<void>;
     run(): Promise<void>;
     protected drainOutgoingForTest(): Promise<OutgoingMessage[]>;
     private register;
@@ -38,5 +60,7 @@ export declare abstract class Applet<State extends object> {
     private scheduleRender;
     private flushRender;
     private emit;
+    private emitAction;
 }
+export declare function runCommand(command: string[]): Promise<CommandResult>;
 export {};

package/dist/src/app.js

@@ -1,8 +1,11 @@
 import { createInterface } from "node:readline";
+import { spawn } from "node:child_process";
 import { parseCallbackEvent, parseInitEvent, } from "./events.js";
+import { InlineHandlerRegistry } from "./widgets.js";
 export class Applet {
     state;
     handlerMap = new Map();
+    inlineHandlerMap = new Map();
     outgoing = [];
     flushPromise = null;
     renderQueued = false;
@@ -12,6 +15,9 @@ export class Applet {
     constructor() {
         this.state = this.initialState();
     }
+    cssClass() {
+        return null;
+    }
     async onStart() { }
     async onInit(_event) { }
     async onCallback(_event) { }
@@ -40,9 +46,41 @@ export class Applet {
     onToggle(id, handler) {
         this.register("toggle", id, handler);
     }
+    onPopover(handler) {
+        this.register("open", "popover", handler);
+        this.register("close", "popover", handler);
+    }
     isPopoverOpen() {
         return this.popoverOpen;
     }
+    log(...args) {
+        process.stderr.write(args.map(String).join(" ") + "\n");
+    }
+    async showNotification(summary, options = {}) {
+        const args = [summary];
+        if (options.body !== undefined) {
+            args.push(options.body);
+        }
+        await this.runDesktopCommand("notify-send", args);
+    }
+    async openUri(uri) {
+        await this.runDesktopCommand("xdg-open", [uri]);
+    }
+    async copyToClipboard(text) {
+        await this.runDesktopCommand("wl-copy", [], text);
+    }
+    async runCommand(command) {
+        return await runCommand(command);
+    }
+    dismissNotification(args) {
+        this.emitAction("dismiss_notification", args);
+    }
+    closePopover() {
+        this.emitAction("close_popover", {});
+    }
+    async runDesktopCommand(command, args, input) {
+        await runDesktopCommand([command, ...args], input);
+    }
     async run() {
         process.stdout.on("error", (err) => {
             if (err.code === "EPIPE") {
@@ -50,6 +88,10 @@ export class Applet {
             }
         });
         await this.onStart();
+        const cssClass = this.cssClass();
+        if (cssClass !== null) {
+            process.stdout.write(`class ${cssClass}\n`);
+        }
         await this.scheduleRender();
         const rl = createInterface({
             input: process.stdin,
@@ -89,7 +131,13 @@ export class Applet {
         this.handlerMap.set(`${event}:${id}`, handler);
     }
     async dispatchCallback(event) {
-        const handler = this.handlerMap.get(`${event.event}:${event.id}`);
+        const key = `${event.event}:${event.id}`;
+        const inlineHandler = this.inlineHandlerMap.get(key);
+        if (inlineHandler !== undefined) {
+            await inlineHandler(event);
+            return;
+        }
+        const handler = this.handlerMap.get(key);
         if (handler !== undefined) {
             await handler(event);
             return;
@@ -136,10 +184,16 @@ export class Applet {
             this.emit("status", { items: status });
         }
         const widget = await this.popover(this.state);
+        if (widget !== null) {
+            const registry = new InlineHandlerRegistry();
+            widget.bindHandlers?.(registry, []);
+            this.inlineHandlerMap = registry.handlers;
+        }
+        else {
+            this.inlineHandlerMap = new Map();
+        }
         const tree = { root: widget?.toProtocol() ?? null };
-        // Emit only when popover open, or first render, or clearing.
-        const shouldEmit = this.popoverOpen || this.lastTree === null || tree.root === null;
-        if (shouldEmit && !deepEqual(tree, this.lastTree)) {
+        if (!deepEqual(tree, this.lastTree)) {
             this.lastTree = tree;
             this.emit("popover", tree);
         }
@@ -157,6 +211,9 @@ export class Applet {
             }
         }
     }
+    emitAction(type, args) {
+        this.emit("action", { type, arguments: args });
+    }
 }
 function parseLine(line) {
     const trimmed = line.trim();
@@ -178,3 +235,38 @@ function deepEqual(left, right) {
 function isPopoverEvent(event) {
     return event.event === "open" || event.event === "close";
 }
+export async function runCommand(command) {
+    return await runCommandWithInput(command);
+}
+async function runDesktopCommand(command, input) {
+    const result = await runCommandWithInput(command, input);
+    if (result.rc !== 0) {
+        throw new Error(`${command[0]} exited with status ${result.rc}`);
+    }
+}
+async function runCommandWithInput(command, input) {
+    if (command.length === 0) {
+        throw new Error("command must not be empty");
+    }
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command[0], command.slice(1), { stdio: ["pipe", "pipe", "pipe"] });
+        const stdout = [];
+        const stderr = [];
+        child.on("error", reject);
+        child.stdout.on("data", (chunk) => stdout.push(chunk));
+        child.stderr.on("data", (chunk) => stderr.push(chunk));
+        child.on("close", (code) => {
+            resolve({
+                stdout: Buffer.concat(stdout).toString("utf8"),
+                stderr: Buffer.concat(stderr).toString("utf8"),
+                rc: code ?? -1,
+            });
+        });
+        if (input !== undefined) {
+            child.stdin.end(input);
+        }
+        else {
+            child.stdin.end();
+        }
+    });
+}

package/dist/src/events.d.ts

@@ -8,7 +8,7 @@ interface CallbackEventBase {
 }
 export interface ClickEvent extends CallbackEventBase {
     event: "click";
-    button?: string;
+    button?: string | null;
 }
 export interface ScrollEvent extends CallbackEventBase {
     event: "scroll";

package/dist/src/events.js

@@ -8,7 +8,7 @@ export function parseCallbackEvent(payload) {
     const event = String(payload.type ?? payload.event ?? "");
     const id = String(payload.id ?? "");
     if (event === "click") {
-        return { id, event, button: payload.button === undefined ? undefined : String(payload.button) };
+        return { id, event, button: payload.button === undefined ? null : String(payload.button) };
     }
     if (event === "scroll") {
         return {

package/dist/src/index.d.ts

@@ -1,4 +1,5 @@
-export { Applet } from "./app.js";
+export { Applet, runCommand } from "./app.js";
 export { type CallbackEvent, type ChangeEvent, type ClickEvent, type InitEvent, type InputEvent, type PopoverEvent, type ScrollEvent, type ToggleEvent, parseCallbackEvent, parseInitEvent, } from "./events.js";
-export { Icon, StatusItem } from "./protocol.js";
-export { ActionItem, type Align, Badge, Box, Button, type ButtonVariant, Card, Checkbox, Column, type ContentFit, Copyable, EmptyState, Expander, Grid, GridChild, Hero, Image, Item, Label, LevelBar, type LevelBarMode, LinkButton, ListBox, MenuButton, Meter, Overlay, type Orientation, type PagerAppearance, PagerItem, PagerStrip, Picture, Progress, type Properties, PropertyList, Row, Scroll, Section, Select, SelectOption, Separator, Slider, Spinner, StatusDot, Switch, ToggleButton, TreeExpander, type TreeNode, type Variant, } from "./widgets.js";
+export { ipc, IpcError, Subscriber } from "./ipc.js";
+export { StatusItem } from "./protocol.js";
+export { Badge, type BadgeKind, BatteryHero, BoxedList, ButtonRow, Calendar, CameraIndicator, Choice, ChoiceList, ChoiceTile, CircleBox, Column, Container, DateHero, EmptyState, EventItem, Events, ExpanderTile, Header, Hero, KeyValueGrid, Label, LocationIndicator, Meter, MicIndicator, MutedIndicator, type PagerAppearance, PagerItem, PagerStrip, PanelIndicator, PopoverShell, type PopoverSize, Row, ScreenCastIndicator, Scroll, SegmentedTile, Separator, SliderTile, Spinner, StatusDot, type StatusDotStatus, SwitchTile, Tile, type TreeNode, WeatherForecastItem, WeatherForecastList, WeatherHourlyItem, WeatherHourlyStrip, WidgetBase, WorldClock, WorldClockRow, } from "./widgets.js";

package/dist/src/index.js

@@ -1,4 +1,5 @@
-export { Applet } from "./app.js";
+export { Applet, runCommand } from "./app.js";
 export { parseCallbackEvent, parseInitEvent, } from "./events.js";
-export { Icon, StatusItem } from "./protocol.js";
-export { ActionItem, Badge, Box, Button, Card, Checkbox, Column, Copyable, EmptyState, Expander, Grid, GridChild, Hero, Image, Item, Label, LevelBar, LinkButton, ListBox, MenuButton, Meter, Overlay, PagerItem, PagerStrip, Picture, Progress, PropertyList, Row, Scroll, Section, Select, SelectOption, Separator, Slider, Spinner, StatusDot, Switch, ToggleButton, TreeExpander, } from "./widgets.js";
+export { ipc, IpcError, Subscriber } from "./ipc.js";
+export { StatusItem } from "./protocol.js";
+export { Badge, BatteryHero, BoxedList, ButtonRow, Calendar, CameraIndicator, Choice, ChoiceList, ChoiceTile, CircleBox, Column, Container, DateHero, EmptyState, EventItem, Events, ExpanderTile, Header, Hero, KeyValueGrid, Label, LocationIndicator, Meter, MicIndicator, MutedIndicator, PagerItem, PagerStrip, PanelIndicator, PopoverShell, Row, ScreenCastIndicator, Scroll, SegmentedTile, Separator, SliderTile, Spinner, StatusDot, SwitchTile, Tile, WeatherForecastItem, WeatherForecastList, WeatherHourlyItem, WeatherHourlyStrip, WidgetBase, WorldClock, WorldClockRow, } from "./widgets.js";

package/dist/src/ipc.d.ts

@@ -0,0 +1,28 @@
+/** One decoded event line; `fields` values are unescaped. */
+export interface Event {
+    name: string;
+    ts: number;
+    fields: Record<string, string>;
+}
+/** Thrown on connection failure or a rejected dispatch (`ok=false`). */
+export declare class IpcError extends Error {
+}
+/** A resolved IPC endpoint. Cheap to create; holds only the socket path. */
+export declare class Subscriber {
+    private readonly socketPath;
+    constructor(socketPath: string);
+    /** Subscribe to `channel` (an exact name, `prefix.*`, or `*`) and yield
+     * events until the server closes the connection. */
+    listen(channel: string): AsyncGenerator<Event>;
+    /** Dispatch `action` with `params` on a fresh connection and await the
+     * ack. Resolves with the extra ack fields; rejects with `IpcError` if the
+     * server replies `ok=false`. */
+    dispatch(action: string, params?: Record<string, string>): Promise<Record<string, string>>;
+    private connect;
+}
+/** Resolve the {@link Subscriber} for `service` (`"shell"` for the panel).
+ *
+ * The socket is `<dir>/<service>.sock` (`shell` maps to `ipc.sock`) where
+ * `<dir>` is `$GLIMPSE_IPC_DIR`, else `$XDG_RUNTIME_DIR/glimpse`. No
+ * connection is made here. */
+export declare function ipc(service?: string): Subscriber;

package/dist/src/ipc.js

@@ -0,0 +1,214 @@
+// Minimal client for the Glimpse IPC socket.
+//
+// `ipc(service)` resolves a `Subscriber` (no I/O — the connection is opened
+// lazily). `Subscriber.listen` subscribes to an event channel and yields
+// decoded `Event`s; `Subscriber.dispatch` sends an action and awaits the
+// server ack on a one-shot connection. The wire protocol matches the
+// `glimpse-shell watch` / `dispatch` CLIs.
+import { createConnection } from "node:net";
+import { createInterface } from "node:readline";
+import { join } from "node:path";
+/** Thrown on connection failure or a rejected dispatch (`ok=false`). */
+export class IpcError extends Error {
+}
+/** A resolved IPC endpoint. Cheap to create; holds only the socket path. */
+export class Subscriber {
+    socketPath;
+    constructor(socketPath) {
+        this.socketPath = socketPath;
+    }
+    /** Subscribe to `channel` (an exact name, `prefix.*`, or `*`) and yield
+     * events until the server closes the connection. */
+    async *listen(channel) {
+        const conn = await this.connect();
+        try {
+            conn.socket.write(`subscribe ${channel}\n`);
+            for (;;) {
+                const next = await conn.lines.next();
+                if (next.done)
+                    return;
+                const line = next.value.trim();
+                if (line)
+                    yield parseEvent(line);
+            }
+        }
+        finally {
+            close(conn);
+        }
+    }
+    /** Dispatch `action` with `params` on a fresh connection and await the
+     * ack. Resolves with the extra ack fields; rejects with `IpcError` if the
+     * server replies `ok=false`. */
+    async dispatch(action, params = {}) {
+        validateToken("action", action, false);
+        const entries = Object.entries(params);
+        for (const [k] of entries)
+            validateToken("param key", k, true);
+        const conn = await this.connect();
+        try {
+            let line = action;
+            for (const [k, v] of entries) {
+                line += ` ${k}=${escape(v)}`;
+            }
+            conn.socket.write(line + "\n");
+            const next = await conn.lines.next();
+            if (next.done) {
+                throw new IpcError("IPC server closed connection without ack");
+            }
+            return parseAck(next.value.trim());
+        }
+        finally {
+            close(conn);
+        }
+    }
+    connect() {
+        return new Promise((resolve, reject) => {
+            const socket = createConnection({ path: this.socketPath });
+            let connected = false;
+            // This handler stays attached for the socket's whole lifetime. Never
+            // remove it: an unhandled 'error' event on a Socket throws and crashes
+            // the process. `close()` only destroys the socket, it does not detach.
+            socket.on("error", (err) => {
+                if (connected) {
+                    // Post-connect transport error: end the stream cleanly so the
+                    // line iterator completes instead of crashing the process.
+                    socket.destroy();
+                }
+                else {
+                    reject(new IpcError(`cannot connect to IPC socket at ${this.socketPath}: ${err.message}`));
+                }
+            });
+            socket.once("connect", () => {
+                connected = true;
+                const rl = createInterface({ input: socket, crlfDelay: Infinity });
+                const lines = rl[Symbol.asyncIterator]();
+                void (async () => {
+                    const hello = await lines.next();
+                    if (hello.done || !hello.value.startsWith("hello")) {
+                        rl.close();
+                        socket.destroy();
+                        reject(new IpcError(hello.done
+                            ? "IPC server closed connection before hello"
+                            : `unexpected IPC greeting: ${hello.value}`));
+                        return;
+                    }
+                    resolve({ socket, rl, lines });
+                })();
+            });
+        });
+    }
+}
+/** Resolve the {@link Subscriber} for `service` (`"shell"` for the panel).
+ *
+ * The socket is `<dir>/<service>.sock` (`shell` maps to `ipc.sock`) where
+ * `<dir>` is `$GLIMPSE_IPC_DIR`, else `$XDG_RUNTIME_DIR/glimpse`. No
+ * connection is made here. */
+export function ipc(service = "shell") {
+    return new Subscriber(socketPath(service));
+}
+function socketPath(service) {
+    const override = process.env.GLIMPSE_IPC_DIR;
+    let dir;
+    if (override) {
+        dir = override;
+    }
+    else {
+        const runtime = process.env.XDG_RUNTIME_DIR;
+        if (!runtime) {
+            throw new IpcError("neither GLIMPSE_IPC_DIR nor XDG_RUNTIME_DIR is set; " +
+                "cannot locate the Glimpse IPC socket");
+        }
+        dir = join(runtime, "glimpse");
+    }
+    return join(dir, service === "shell" ? "ipc.sock" : `${service}.sock`);
+}
+function close(conn) {
+    conn.rl.close();
+    conn.socket.destroy();
+}
+// The wire protocol splits client lines on whitespace and never unescapes
+// the command name or a field key, so an `action`/key with whitespace would
+// forge extra tokens or whole client lines. Values are safe (escaped).
+function validateToken(label, token, forbidEq) {
+    if (token.length === 0) {
+        throw new IpcError(`IPC ${label} must not be empty`);
+    }
+    if (/\s/.test(token)) {
+        throw new IpcError(`IPC ${label} "${token}" must not contain whitespace`);
+    }
+    if (forbidEq && token.includes("=")) {
+        throw new IpcError(`IPC param key "${token}" must not contain '='`);
+    }
+}
+function escape(s) {
+    return s
+        .replaceAll("\\", "\\\\")
+        .replaceAll("\n", "\\n")
+        .replaceAll("\t", "\\t")
+        .replaceAll(" ", "\\s");
+}
+function unescape(s) {
+    let out = "";
+    for (let i = 0; i < s.length; i++) {
+        if (s[i] !== "\\") {
+            out += s[i];
+            continue;
+        }
+        const next = s[++i];
+        if (next === "s")
+            out += " ";
+        else if (next === "n")
+            out += "\n";
+        else if (next === "t")
+            out += "\t";
+        else if (next === "\\")
+            out += "\\";
+        else if (next === undefined)
+            out += "\\";
+        else
+            out += "\\" + next;
+    }
+    return out;
+}
+function parseEvent(line) {
+    const tokens = line.split(/\s+/);
+    const name = tokens[0] ?? "";
+    let ts = 0;
+    const fields = {};
+    for (const token of tokens.slice(1)) {
+        const eq = token.indexOf("=");
+        if (eq < 0)
+            continue;
+        const key = token.slice(0, eq);
+        const value = unescape(token.slice(eq + 1));
+        if (key === "ts" && /^\d+$/.test(value)) {
+            ts = Number(value);
+            continue;
+        }
+        fields[key] = value;
+    }
+    return { name, ts, fields };
+}
+function parseAck(line) {
+    const tokens = line.split(/\s+/);
+    if (tokens[0] !== "ack") {
+        throw new IpcError(`expected an ack, got: ${line}`);
+    }
+    let ok = false;
+    const fields = {};
+    for (const token of tokens.slice(1)) {
+        const eq = token.indexOf("=");
+        if (eq < 0)
+            continue;
+        const key = token.slice(0, eq);
+        const value = unescape(token.slice(eq + 1));
+        if (key === "ok")
+            ok = value === "true";
+        else
+            fields[key] = value;
+    }
+    if (!ok) {
+        throw new IpcError(fields.error ?? "command failed");
+    }
+    return fields;
+}

package/dist/src/protocol.d.ts

@@ -1,26 +1,13 @@
-export type IconKind = "name" | "path";
-export declare class Icon {
-    readonly kind: IconKind;
-    readonly value: string;
-    constructor(kind: IconKind, value: string);
-    static name(value: string): Icon;
-    static path(value: string): Icon;
-    toProtocol(): {
-        name: string;
-    } | {
-        path: string;
-    };
-}
 export declare class StatusItem {
     readonly options: {
         id?: string;
-        icon?: Icon;
+        icon?: string;
         label?: string;
         tooltip?: string;
     };
     constructor(options?: {
         id?: string;
-        icon?: Icon;
+        icon?: string;
         label?: string;
         tooltip?: string;
     });

package/dist/src/protocol.js

@@ -1,20 +1,3 @@
-export class Icon {
-    kind;
-    value;
-    constructor(kind, value) {
-        this.kind = kind;
-        this.value = value;
-    }
-    static name(value) {
-        return new Icon("name", value);
-    }
-    static path(value) {
-        return new Icon("path", value);
-    }
-    toProtocol() {
-        return this.kind === "name" ? { name: this.value } : { path: this.value };
-    }
-}
 export class StatusItem {
     options;
     constructor(options = {}) {
@@ -26,7 +9,7 @@ export class StatusItem {
             payload.id = this.options.id;
         }
         if (this.options.icon !== undefined) {
-            payload.icon = this.options.icon.toProtocol();
+            payload.icon = this.options.icon;
         }
         if (this.options.label !== undefined) {
             payload.label = this.options.label;