glimpse-sdk 0.3.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glimpse-sdk",
-  "version": "0.3.0",
+  "version": "0.7.0",
   "description": "Typed async framework for building Glimpse exec applets",
   "type": "module",
   "main": "dist/src/index.js",

package/src/app.ts

@@ -1,4 +1,5 @@
 import { createInterface } from "node:readline";
+import { spawn } from "node:child_process";
 
 import {
   type CallbackEvent,
@@ -13,7 +14,7 @@ import {
   parseInitEvent,
 } from "./events.js";
 import { StatusItem } from "./protocol.js";
-import { type TreeNode } from "./widgets.js";
+import { type TreeNode, InlineHandlerRegistry } from "./widgets.js";
 
 type Handler<EventT> = (event: EventT) => void | Promise<void>;
 
@@ -23,10 +24,25 @@ interface OutgoingMessage {
   line: string;
 }
 
+interface ShowNotificationOptions {
+  body?: string;
+}
+
+export interface CommandResult {
+  stdout: string;
+  stderr: string;
+  rc: number;
+}
+
+interface DismissNotificationArgs {
+  id: number;
+}
+
 export abstract class Applet<State extends object> {
   state: State;
 
   private readonly handlerMap = new Map<string, Handler<CallbackEvent>>();
+  private inlineHandlerMap = new Map<string, (event: CallbackEvent) => void | Promise<void>>();
   private readonly outgoing: OutgoingMessage[] = [];
   private flushPromise: Promise<void> | null = null;
   private renderQueued = false;
@@ -40,6 +56,10 @@ export abstract class Applet<State extends object> {
 
   protected abstract initialState(): State;
 
+  protected cssClass(): string | null {
+    return null;
+  }
+
   protected async onStart(): Promise<void> {}
 
   protected async onInit(_event: InitEvent): Promise<void> {}
@@ -79,10 +99,51 @@ export abstract class Applet<State extends object> {
     this.register("toggle", id, handler as Handler<CallbackEvent>);
   }
 
+  onPopover(handler: Handler<PopoverEvent>): void {
+    this.register("open", "popover", handler as Handler<CallbackEvent>);
+    this.register("close", "popover", handler as Handler<CallbackEvent>);
+  }
+
   isPopoverOpen(): boolean {
     return this.popoverOpen;
   }
 
+  log(...args: unknown[]): void {
+    process.stderr.write(args.map(String).join(" ") + "\n");
+  }
+
+  protected async showNotification(summary: string, options: ShowNotificationOptions = {}): Promise<void> {
+    const args = [summary];
+    if (options.body !== undefined) {
+      args.push(options.body);
+    }
+    await this.runDesktopCommand("notify-send", args);
+  }
+
+  protected async openUri(uri: string): Promise<void> {
+    await this.runDesktopCommand("xdg-open", [uri]);
+  }
+
+  protected async copyToClipboard(text: string): Promise<void> {
+    await this.runDesktopCommand("wl-copy", [], text);
+  }
+
+  protected async runCommand(command: string[]): Promise<CommandResult> {
+    return await runCommand(command);
+  }
+
+  protected dismissNotification(args: DismissNotificationArgs): void {
+    this.emitAction("dismiss_notification", args);
+  }
+
+  protected closePopover(): void {
+    this.emitAction("close_popover", {});
+  }
+
+  protected async runDesktopCommand(command: string, args: string[], input?: string): Promise<void> {
+    await runDesktopCommand([command, ...args], input);
+  }
+
   async run(): Promise<void> {
     process.stdout.on("error", (err: NodeJS.ErrnoException) => {
       if (err.code === "EPIPE") {
@@ -91,6 +152,10 @@ export abstract class Applet<State extends object> {
     });
 
     await this.onStart();
+    const cssClass = this.cssClass();
+    if (cssClass !== null) {
+      process.stdout.write(`class ${cssClass}\n`);
+    }
     await this.scheduleRender();
 
     const rl = createInterface({
@@ -133,7 +198,13 @@ export abstract class Applet<State extends object> {
   }
 
   private async dispatchCallback(event: CallbackEvent): Promise<void> {
-    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;
@@ -183,10 +254,15 @@ export abstract class Applet<State extends object> {
     }
 
     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);
     }
@@ -204,6 +280,10 @@ export abstract class Applet<State extends object> {
       }
     }
   }
+
+  private emitAction(type: string, args: object): void {
+    this.emit("action", { type, arguments: args });
+  }
 }
 
 function parseLine(line: string): { command: string; data: unknown } | null {
@@ -228,3 +308,40 @@ function deepEqual(left: unknown, right: unknown): boolean {
 function isPopoverEvent(event: CallbackEvent): event is PopoverEvent {
   return event.event === "open" || event.event === "close";
 }
+
+export async function runCommand(command: string[]): Promise<CommandResult> {
+  return await runCommandWithInput(command);
+}
+
+async function runDesktopCommand(command: string[], input?: string): Promise<void> {
+  const result = await runCommandWithInput(command, input);
+  if (result.rc !== 0) {
+    throw new Error(`${command[0]} exited with status ${result.rc}`);
+  }
+}
+
+async function runCommandWithInput(command: string[], input?: string): Promise<CommandResult> {
+  if (command.length === 0) {
+    throw new Error("command must not be empty");
+  }
+  return await new Promise<CommandResult>((resolve, reject) => {
+    const child = spawn(command[0], command.slice(1), { stdio: ["pipe", "pipe", "pipe"] });
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    child.on("error", reject);
+    child.stdout.on("data", (chunk: Buffer) => stdout.push(chunk));
+    child.stderr.on("data", (chunk: Buffer) => 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/src/events.ts

@@ -10,7 +10,7 @@ interface CallbackEventBase {
 
 export interface ClickEvent extends CallbackEventBase {
   event: "click";
-  button?: string;
+  button?: string | null;
 }
 
 export interface ScrollEvent extends CallbackEventBase {
@@ -57,7 +57,7 @@ export function parseCallbackEvent(payload: Record<string, unknown>): CallbackEv
   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/src/index.ts

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

package/src/ipc.ts

@@ -0,0 +1,233 @@
+// 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, type Socket } from "node:net";
+import { createInterface, type Interface } from "node:readline";
+import { join } from "node:path";
+
+/** 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 class IpcError extends Error {}
+
+interface Conn {
+  socket: Socket;
+  rl: Interface;
+  lines: AsyncIterator<string>;
+}
+
+/** A resolved IPC endpoint. Cheap to create; holds only the socket path. */
+export class Subscriber {
+  constructor(private readonly socketPath: string) {}
+
+  /** Subscribe to `channel` (an exact name, `prefix.*`, or `*`) and yield
+   * events until the server closes the connection. */
+  async *listen(channel: string): AsyncGenerator<Event> {
+    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: string,
+    params: Record<string, string> = {},
+  ): Promise<Record<string, string>> {
+    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);
+    }
+  }
+
+  private connect(): Promise<Conn> {
+    return new Promise<Conn>((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: Error) => {
+        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"): Subscriber {
+  return new Subscriber(socketPath(service));
+}
+
+function socketPath(service: string): string {
+  const override = process.env.GLIMPSE_IPC_DIR;
+  let dir: string;
+  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): void {
+  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: string, token: string, forbidEq: boolean): void {
+  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: string): string {
+  return s
+    .replaceAll("\\", "\\\\")
+    .replaceAll("\n", "\\n")
+    .replaceAll("\t", "\\t")
+    .replaceAll(" ", "\\s");
+}
+
+function unescape(s: string): string {
+  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: string): Event {
+  const tokens = line.split(/\s+/);
+  const name = tokens[0] ?? "";
+  let ts = 0;
+  const fields: Record<string, string> = {};
+  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: string): Record<string, string> {
+  const tokens = line.split(/\s+/);
+  if (tokens[0] !== "ack") {
+    throw new IpcError(`expected an ack, got: ${line}`);
+  }
+  let ok = false;
+  const fields: Record<string, string> = {};
+  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/src/protocol.ts

@@ -1,29 +1,8 @@
-export type IconKind = "name" | "path";
-
-export class Icon {
-  constructor(
-    public readonly kind: IconKind,
-    public readonly value: string,
-  ) {}
-
-  static name(value: string): Icon {
-    return new Icon("name", value);
-  }
-
-  static path(value: string): Icon {
-    return new Icon("path", value);
-  }
-
-  toProtocol(): { name: string } | { path: string } {
-    return this.kind === "name" ? { name: this.value } : { path: this.value };
-  }
-}
-
 export class StatusItem {
   constructor(
     public readonly options: {
       id?: string;
-      icon?: Icon;
+      icon?: string;
       label?: string;
       tooltip?: string;
     } = {},
@@ -35,7 +14,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;