glimpse-sdk 0.2.0 → 0.5.0

package/README.md

@@ -10,14 +10,25 @@ 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
 - typed widget builders
 - async runtime
 - explicit typed handler registration
-- state-driven rendering via `await this.setState(...)`
-- single `render()` method that returns all panel state
+- separate `status(state)` and `popover(state)` methods; state mutation via `await this.setState(...)`
 
 ## Example
 
@@ -29,9 +40,9 @@ import {
   Hero,
   Icon,
   Label,
-  RenderResult,
   StatusItem,
-} from "./src/index.js";
+  type TreeNode,
+} from "glimpse-sdk";
 
 interface DeployState {
   version: string;
@@ -50,25 +61,31 @@ class DeployApplet extends Applet<DeployState> {
     });
   }
 
-  protected async render(): Promise<RenderResult> {
-    return new RenderResult({
-      status: [
-        new StatusItem({
-          id: "deploy",
-          icon: Icon.name("software-update-available-symbolic"),
-          label: this.state.status,
-        }),
-      ],
-      hero: new Hero({
+  protected async status(state: DeployState): Promise<StatusItem[]> {
+    return [
+      new StatusItem({
+        id: "deploy",
+        icon: Icon.name("software-update-available-symbolic"),
+        label: state.status,
+      }),
+    ];
+  }
+
+  protected async popover(state: DeployState): Promise<TreeNode | null> {
+    return Box.vertical([
+      new Hero({
         icon: Icon.name("software-update-available-symbolic"),
         title: "Deploy",
-        subtitle: this.state.version,
+        subtitle: state.version,
       }),
-      tree: Box.vertical([
-        new Label("Version"),
-        new Button({ id: "deploy_now", label: "Deploy now" }),
-      ]),
-    });
+      new Label("Version"),
+      new Button({
+        id: "deploy_now",
+        label: "Deploy now",
+        icon: "media-playback-start-symbolic",
+        variant: "primary",
+      }),
+    ]);
   }
 }
 
@@ -85,4 +102,25 @@ Use explicit registration helpers instead of decorators:
 - `this.onChange(id, handler)`
 - `this.onToggle(id, handler)`
 
-The SDK owns the line transport and writes `status {json}` and `popover {json}` messages derived from `render()`.
+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

@@ -7,17 +7,19 @@ interface OutgoingMessage {
     data: unknown;
     line: string;
 }
-export declare class RenderResult {
-    readonly options: {
-        status?: StatusItem[];
-        tree?: TreeNode | null;
-    };
-    constructor(options?: {
-        status?: StatusItem[];
-        tree?: TreeNode | null;
-    });
-    get status(): StatusItem[];
-    get tree(): TreeNode | null;
+interface ShowNotificationArgs {
+    summary: string;
+    body?: string;
+    urgency?: string;
+}
+interface OpenUriArgs {
+    uri: string;
+}
+interface CopyToClipboardArgs {
+    text: string;
+}
+interface DismissNotificationArgs {
+    id: number;
 }
 export declare abstract class Applet<State extends object> {
     state: State;
@@ -33,7 +35,8 @@ export declare abstract class Applet<State extends object> {
     protected onStart(): Promise<void>;
     protected onInit(_event: InitEvent): Promise<void>;
     protected onCallback(_event: CallbackEvent): Promise<void>;
-    protected render(): Promise<RenderResult>;
+    protected status(_state: State): Promise<StatusItem[]>;
+    protected popover(_state: State): Promise<TreeNode | null>;
     setState(patch: Partial<State>): Promise<void>;
     onClick(id: string, handler: Handler<ClickEvent>): void;
     onScroll(id: string, handler: Handler<ScrollEvent>): void;
@@ -41,6 +44,11 @@ export declare abstract class Applet<State extends object> {
     onChange(id: string, handler: Handler<ChangeEvent>): void;
     onToggle(id: string, handler: Handler<ToggleEvent>): void;
     isPopoverOpen(): boolean;
+    protected showNotification(args: ShowNotificationArgs): void;
+    protected openUri(args: OpenUriArgs): void;
+    protected copyToClipboard(args: CopyToClipboardArgs): void;
+    protected dismissNotification(args: DismissNotificationArgs): void;
+    protected closePopover(): void;
     run(): Promise<void>;
     protected drainOutgoingForTest(): Promise<OutgoingMessage[]>;
     private register;
@@ -49,5 +57,6 @@ export declare abstract class Applet<State extends object> {
     private scheduleRender;
     private flushRender;
     private emit;
+    private emitAction;
 }
 export {};

package/dist/src/app.js

@@ -1,17 +1,5 @@
 import { createInterface } from "node:readline";
 import { parseCallbackEvent, parseInitEvent, } from "./events.js";
-export class RenderResult {
-    options;
-    constructor(options = {}) {
-        this.options = options;
-    }
-    get status() {
-        return this.options.status ?? [];
-    }
-    get tree() {
-        return this.options.tree ?? null;
-    }
-}
 export class Applet {
     state;
     handlerMap = new Map();
@@ -27,8 +15,11 @@ export class Applet {
     async onStart() { }
     async onInit(_event) { }
     async onCallback(_event) { }
-    async render() {
-        return new RenderResult();
+    async status(_state) {
+        return [];
+    }
+    async popover(_state) {
+        return null;
     }
     async setState(patch) {
         this.state = { ...this.state, ...patch };
@@ -52,6 +43,21 @@ export class Applet {
     isPopoverOpen() {
         return this.popoverOpen;
     }
+    showNotification(args) {
+        this.emitAction("show_notification", args);
+    }
+    openUri(args) {
+        this.emitAction("open_uri", args);
+    }
+    copyToClipboard(args) {
+        this.emitAction("copy_to_clipboard", args);
+    }
+    dismissNotification(args) {
+        this.emitAction("dismiss_notification", args);
+    }
+    closePopover() {
+        this.emitAction("close_popover", {});
+    }
     async run() {
         process.stdout.on("error", (err) => {
             if (err.code === "EPIPE") {
@@ -138,15 +144,15 @@ export class Applet {
         await this.flushPromise;
     }
     async flushRender() {
-        const rendered = await this.render();
-        const status = rendered.status.map((item) => item.toProtocol());
-        const tree = { root: rendered.tree?.toProtocol() ?? null };
+        const statusItems = await this.status(this.state);
+        const status = statusItems.map((item) => item.toProtocol());
         if (!deepEqual(status, this.lastStatus)) {
             this.lastStatus = status;
             this.emit("status", { items: status });
         }
-        const publishPopover = this.popoverOpen || this.lastTree === null || tree.root === null;
-        if (publishPopover && !deepEqual(tree, this.lastTree)) {
+        const widget = await this.popover(this.state);
+        const tree = { root: widget?.toProtocol() ?? null };
+        if (!deepEqual(tree, this.lastTree)) {
             this.lastTree = tree;
             this.emit("popover", tree);
         }
@@ -164,6 +170,9 @@ export class Applet {
             }
         }
     }
+    emitAction(type, args) {
+        this.emit("action", { type, arguments: args });
+    }
 }
 function parseLine(line) {
     const trimmed = line.trim();

package/dist/src/index.d.ts

@@ -1,4 +1,5 @@
-export { Applet, RenderResult } from "./app.js";
+export { Applet } 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, MenuItem, StatusItem } from "./protocol.js";
-export { ActionMenu, ActionMenuItem, ActionRow, type Align, Badge, Box, Button, Card, Checkbox, Collapsible, CollapsibleItem, Column, Copyable, DetailGrid, DetailGridItem, Dropdown, DropdownItem, EmptyState, Grid, GridChild, Header, Hero, IconWidget, Image, Item, Label, Meter, type Orientation, Progress, Row, Scale, Scroll, Section, Separator, Spinner, StatusDot, Switch, Toast, ToastAction, type TreeNode, type Variant, } from "./widgets.js";
+export { Icon, StatusItem } from "./protocol.js";
+export { type Event, IpcError, Subscriber, ipc } from "./ipc.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";

package/dist/src/index.js

@@ -1,4 +1,5 @@
-export { Applet, RenderResult } from "./app.js";
+export { Applet } from "./app.js";
 export { parseCallbackEvent, parseInitEvent, } from "./events.js";
-export { Icon, MenuItem, StatusItem } from "./protocol.js";
-export { ActionMenu, ActionMenuItem, ActionRow, Badge, Box, Button, Card, Checkbox, Collapsible, CollapsibleItem, Column, Copyable, DetailGrid, DetailGridItem, Dropdown, DropdownItem, EmptyState, Grid, GridChild, Header, Hero, IconWidget, Image, Item, Label, Meter, Progress, Row, Scale, Scroll, Section, Separator, Spinner, StatusDot, Switch, Toast, ToastAction, } from "./widgets.js";
+export { Icon, StatusItem } from "./protocol.js";
+export { IpcError, Subscriber, ipc } from "./ipc.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";

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

@@ -26,18 +26,3 @@ export declare class StatusItem {
     });
     toProtocol(): Record<string, unknown>;
 }
-export declare class MenuItem {
-    readonly options: {
-        id: string;
-        label: string;
-        visible?: boolean;
-        enabled?: boolean;
-    };
-    constructor(options: {
-        id: string;
-        label: string;
-        visible?: boolean;
-        enabled?: boolean;
-    });
-    toProtocol(): Record<string, unknown>;
-}

package/dist/src/protocol.js

@@ -37,22 +37,3 @@ export class StatusItem {
         return payload;
     }
 }
-export class MenuItem {
-    options;
-    constructor(options) {
-        this.options = options;
-    }
-    toProtocol() {
-        const payload = {
-            id: this.options.id,
-            label: this.options.label,
-        };
-        if (this.options.visible !== undefined) {
-            payload.visible = this.options.visible;
-        }
-        if (this.options.enabled !== undefined) {
-            payload.enabled = this.options.enabled;
-        }
-        return payload;
-    }
-}