glimpse-sdk 0.7.0 → 0.9.0

package/dist/src/app.d.ts

@@ -1,66 +0,0 @@
-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>;
-interface OutgoingMessage {
-    command: string;
-    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;
-    private lastStatus;
-    private lastTree;
-    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>;
-    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;
-    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;
-    private dispatchCallback;
-    private handleIncoming;
-    private scheduleRender;
-    private flushRender;
-    private emit;
-    private emitAction;
-}
-export declare function runCommand(command: string[]): Promise<CommandResult>;
-export {};

package/dist/src/app.js

@@ -1,272 +0,0 @@
-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;
-    lastStatus = null;
-    lastTree = null;
-    popoverOpen = false;
-    constructor() {
-        this.state = this.initialState();
-    }
-    cssClass() {
-        return null;
-    }
-    async onStart() { }
-    async onInit(_event) { }
-    async onCallback(_event) { }
-    async status(_state) {
-        return [];
-    }
-    async popover(_state) {
-        return null;
-    }
-    async setState(patch) {
-        this.state = { ...this.state, ...patch };
-        await this.scheduleRender();
-    }
-    onClick(id, handler) {
-        this.register("click", id, handler);
-    }
-    onScroll(id, handler) {
-        this.register("scroll", id, handler);
-    }
-    onInput(id, handler) {
-        this.register("input", id, handler);
-    }
-    onChange(id, handler) {
-        this.register("change", id, handler);
-    }
-    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") {
-                process.exit(0);
-            }
-        });
-        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,
-            crlfDelay: Infinity,
-        });
-        for await (const line of rl) {
-            if (!line) {
-                continue;
-            }
-            let raw;
-            try {
-                raw = parseLine(line);
-            }
-            catch (err) {
-                process.stderr.write(`glimpse-sdk: ignoring malformed input: ${err}\n`);
-                continue;
-            }
-            if (raw === null) {
-                continue;
-            }
-            const data = raw.data;
-            try {
-                await this.handleIncoming(raw.command, data);
-            }
-            catch (err) {
-                process.stderr.write(`glimpse-sdk: error handling input: ${err}\n`);
-            }
-        }
-    }
-    async drainOutgoingForTest() {
-        await this.scheduleRender();
-        const drained = [...this.outgoing];
-        this.outgoing.length = 0;
-        return drained;
-    }
-    register(event, id, handler) {
-        this.handlerMap.set(`${event}:${id}`, handler);
-    }
-    async dispatchCallback(event) {
-        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;
-        }
-        await this.onCallback(event);
-    }
-    async handleIncoming(type, data) {
-        if (type === "init") {
-            await this.onInit(parseInitEvent(data));
-            await this.scheduleRender();
-            return;
-        }
-        if (type === "event") {
-            const event = parseCallbackEvent(data);
-            if (isPopoverEvent(event)) {
-                this.popoverOpen = event.open;
-            }
-            await this.dispatchCallback(event);
-            await this.scheduleRender();
-        }
-    }
-    async scheduleRender() {
-        this.renderQueued = true;
-        if (this.flushPromise === null) {
-            this.flushPromise = Promise.resolve().then(async () => {
-                try {
-                    while (this.renderQueued) {
-                        this.renderQueued = false;
-                        await this.flushRender();
-                    }
-                }
-                finally {
-                    this.flushPromise = null;
-                }
-            });
-        }
-        await this.flushPromise;
-    }
-    async flushRender() {
-        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 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 };
-        if (!deepEqual(tree, this.lastTree)) {
-            this.lastTree = tree;
-            this.emit("popover", tree);
-        }
-    }
-    emit(command, data) {
-        const line = `${command} ${JSON.stringify(data)}`;
-        this.outgoing.push({ command, data, line });
-        try {
-            process.stdout.write(`${line}\n`);
-        }
-        catch (err) {
-            const code = err?.code;
-            if (code !== "EPIPE") {
-                throw err;
-            }
-        }
-    }
-    emitAction(type, args) {
-        this.emit("action", { type, arguments: args });
-    }
-}
-function parseLine(line) {
-    const trimmed = line.trim();
-    if (trimmed === "") {
-        return null;
-    }
-    const split = trimmed.search(/\s/);
-    if (split < 0) {
-        throw new Error("missing command payload");
-    }
-    return {
-        command: trimmed.slice(0, split),
-        data: JSON.parse(trimmed.slice(split).trimStart()),
-    };
-}
-function deepEqual(left, right) {
-    return JSON.stringify(left) === JSON.stringify(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

@@ -1,36 +0,0 @@
-export interface InitEvent {
-    instance: string;
-    options: Record<string, unknown>;
-}
-interface CallbackEventBase {
-    id: string;
-    event: string;
-}
-export interface ClickEvent extends CallbackEventBase {
-    event: "click";
-    button?: string | null;
-}
-export interface ScrollEvent extends CallbackEventBase {
-    event: "scroll";
-    delta_y?: number;
-}
-export interface InputEvent extends CallbackEventBase {
-    event: "input";
-    text: string;
-}
-export interface ChangeEvent extends CallbackEventBase {
-    event: "change";
-    value: unknown;
-}
-export interface ToggleEvent extends CallbackEventBase {
-    event: "toggle";
-    value: boolean;
-}
-export interface PopoverEvent extends CallbackEventBase {
-    event: "open" | "close";
-    open: boolean;
-}
-export type CallbackEvent = ClickEvent | ScrollEvent | InputEvent | ChangeEvent | ToggleEvent | PopoverEvent;
-export declare function parseInitEvent(payload: Record<string, unknown>): InitEvent;
-export declare function parseCallbackEvent(payload: Record<string, unknown>): CallbackEvent;
-export {};

package/dist/src/events.js

@@ -1,37 +0,0 @@
-export function parseInitEvent(payload) {
-    return {
-        instance: String(payload.instance ?? ""),
-        options: (payload.options ?? {}),
-    };
-}
-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 ? null : String(payload.button) };
-    }
-    if (event === "scroll") {
-        return {
-            id,
-            event,
-            delta_y: typeof payload.delta_y === "number" ? payload.delta_y : undefined,
-        };
-    }
-    if (event === "input") {
-        return { id, event, text: String(payload.text ?? "") };
-    }
-    if (event === "toggle") {
-        let value = false;
-        if (typeof payload.active === "boolean") {
-            value = payload.active;
-        }
-        else if (typeof payload.value === "boolean") {
-            value = payload.value;
-        }
-        return { id, event, value };
-    }
-    if (event === "open" || event === "close") {
-        return { id, event, open: event === "open" };
-    }
-    return { id, event: "change", value: payload.value };
-}

package/dist/src/index.d.ts

@@ -1,5 +0,0 @@
-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 { 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,5 +0,0 @@
-export { Applet, runCommand } from "./app.js";
-export { parseCallbackEvent, parseInitEvent, } from "./events.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

@@ -1,28 +0,0 @@
-/** 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

@@ -1,214 +0,0 @@
-// 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,15 +0,0 @@
-export declare class StatusItem {
-    readonly options: {
-        id?: string;
-        icon?: string;
-        label?: string;
-        tooltip?: string;
-    };
-    constructor(options?: {
-        id?: string;
-        icon?: string;
-        label?: string;
-        tooltip?: string;
-    });
-    toProtocol(): Record<string, unknown>;
-}