glimpse-custom-applet-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Oleshkevich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# Glimpse Applet TypeScript SDK
+
+Small async framework for building Glimpse `exec` applets without touching stdio or raw JSON.
+
+## 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
+
+## Example
+
+```ts
+import {
+  Applet,
+  Box,
+  Button,
+  Hero,
+  Icon,
+  Label,
+  RenderResult,
+  StatusItem,
+} from "./src/index.js";
+
+interface DeployState {
+  version: string;
+  status: string;
+}
+
+class DeployApplet extends Applet<DeployState> {
+  protected initialState(): DeployState {
+    return { version: "2026.04.07", status: "Ready" };
+  }
+
+  constructor() {
+    super();
+    this.onClick("deploy_now", async () => {
+      await this.setState({ status: "Deploying" });
+    });
+  }
+
+  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({
+        icon: Icon.name("software-update-available-symbolic"),
+        title: "Deploy",
+        subtitle: this.state.version,
+      }),
+      tree: Box.vertical([
+        new Label("Version"),
+        new Button({ id: "deploy_now", label: "Deploy now" }),
+      ]),
+    });
+  }
+}
+
+await new DeployApplet().run();
+```
+
+## Handler Registration
+
+Use explicit registration helpers instead of decorators:
+
+- `this.onClick(id, handler)`
+- `this.onScroll(id, handler)`
+- `this.onInput(id, handler)`
+- `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()`.

package/dist/src/app.d.ts

@@ -0,0 +1,53 @@
+import { type CallbackEvent, type ChangeEvent, type ClickEvent, type InitEvent, type InputEvent, 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;
+}
+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;
+}
+export declare abstract class Applet<State extends object> {
+    state: State;
+    private readonly handlerMap;
+    private readonly outgoing;
+    private flushPromise;
+    private renderQueued;
+    private lastStatus;
+    private lastTree;
+    private popoverOpen;
+    protected constructor();
+    protected abstract initialState(): State;
+    protected onStart(): Promise<void>;
+    protected onInit(_event: InitEvent): Promise<void>;
+    protected onCallback(_event: CallbackEvent): Promise<void>;
+    protected render(): Promise<RenderResult>;
+    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;
+    isPopoverOpen(): boolean;
+    run(): Promise<void>;
+    protected drainOutgoingForTest(): Promise<OutgoingMessage[]>;
+    private register;
+    private dispatchCallback;
+    private handleIncoming;
+    private scheduleRender;
+    private flushRender;
+    private emit;
+}
+export {};

package/dist/src/app.js

@@ -0,0 +1,187 @@
+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();
+    outgoing = [];
+    flushPromise = null;
+    renderQueued = false;
+    lastStatus = null;
+    lastTree = null;
+    popoverOpen = false;
+    constructor() {
+        this.state = this.initialState();
+    }
+    async onStart() { }
+    async onInit(_event) { }
+    async onCallback(_event) { }
+    async render() {
+        return new RenderResult();
+    }
+    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);
+    }
+    isPopoverOpen() {
+        return this.popoverOpen;
+    }
+    async run() {
+        process.stdout.on("error", (err) => {
+            if (err.code === "EPIPE") {
+                process.exit(0);
+            }
+        });
+        await this.onStart();
+        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-applet: 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-applet: 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 handler = this.handlerMap.get(`${event.event}:${event.id}`);
+        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 rendered = await this.render();
+        const status = rendered.status.map((item) => item.toProtocol());
+        const tree = { root: rendered.tree?.toProtocol() ?? null };
+        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)) {
+            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;
+            }
+        }
+    }
+}
+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";
+}

package/dist/src/events.d.ts

@@ -0,0 +1,36 @@
+export interface InitEvent {
+    instance: string;
+    options: Record<string, unknown>;
+}
+interface CallbackEventBase {
+    id: string;
+    event: string;
+}
+export interface ClickEvent extends CallbackEventBase {
+    event: "click";
+    button?: string;
+}
+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

@@ -0,0 +1,37 @@
+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 ? undefined : 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

@@ -0,0 +1,4 @@
+export { Applet, RenderResult } 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";

package/dist/src/index.js

@@ -0,0 +1,4 @@
+export { Applet, RenderResult } 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";

package/dist/src/protocol.d.ts

@@ -0,0 +1,43 @@
+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;
+        label?: string;
+        tooltip?: string;
+    };
+    constructor(options?: {
+        id?: string;
+        icon?: Icon;
+        label?: string;
+        tooltip?: string;
+    });
+    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

@@ -0,0 +1,58 @@
+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 = {}) {
+        this.options = options;
+    }
+    toProtocol() {
+        const payload = {};
+        if (this.options.id !== undefined) {
+            payload.id = this.options.id;
+        }
+        if (this.options.icon !== undefined) {
+            payload.icon = this.options.icon.toProtocol();
+        }
+        if (this.options.label !== undefined) {
+            payload.label = this.options.label;
+        }
+        if (this.options.tooltip !== undefined) {
+            payload.tooltip = this.options.tooltip;
+        }
+        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;
+    }
+}