glimpse-sdk 0.5.0 → 0.8.0

package/README.md

@@ -15,19 +15,19 @@ npm install glimpse-sdk
 Create and live-run a TypeScript applet project with the Glimpse tooling:
 
 ```sh
-glimpse-applet new counter --lang typescript
+glimpse-shell applets new counter --lang typescript
 cd counter
-glimpse-applet dev
+glimpse-shell applets dev
 ```
 
-Read `docs/custom-applets/tooling.md` for project layout, `applet.toml`, dev applets, linking, and diagnostics.
+Read `docs/custom-applets/tooling.md` for project layout, `applet.toml`, dev applets, local linking, distribution, and diagnostics.
 
 ## Goals
 
 - typed protocol models
 - typed widget builders
 - async runtime
-- explicit typed handler registration
+- widget-local callbacks, with explicit typed handler registration available when needed
 - separate `status(state)` and `popover(state)` methods; state mutation via `await this.setState(...)`
 
 ## Example
@@ -35,12 +35,11 @@ Read `docs/custom-applets/tooling.md` for project layout, `applet.toml`, dev app
 ```ts
 import {
   Applet,
-  Box,
-  Button,
+  Column,
   Hero,
-  Icon,
   Label,
   StatusItem,
+  Tile,
   type TreeNode,
 } from "glimpse-sdk";
 
@@ -50,42 +49,43 @@ interface DeployState {
 }
 
 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 initialState(): DeployState {
+    return { version: "2026.04.07", status: "Ready" };
   }
 
   protected async status(state: DeployState): Promise<StatusItem[]> {
     return [
       new StatusItem({
         id: "deploy",
-        icon: Icon.name("software-update-available-symbolic"),
+        icon: "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: state.version,
-      }),
-      new Label("Version"),
-      new Button({
-        id: "deploy_now",
-        label: "Deploy now",
-        icon: "media-playback-start-symbolic",
-        variant: "primary",
-      }),
-    ]);
+    return new Column({
+      children: [
+        new Hero({
+          icon: "software-update-available-symbolic",
+          title: "Deploy",
+          subtitle: state.version,
+        }),
+        new Label("Version"),
+        new Tile({
+          id: "deploy_now",
+          primary: "Deploy now",
+          left_icon: "media-playback-start-symbolic",
+          on_click: async () => {
+            await this.setState({ status: "Deploying" });
+          },
+        }),
+      ],
+    });
   }
 }
 
@@ -94,7 +94,9 @@ await new DeployApplet().run();
 
 ## Handler Registration
 
-Use explicit registration helpers instead of decorators:
+Prefer widget-local callbacks for controls rendered in `popover(state)`.
+Explicit registration helpers are still available when the handler should live
+outside the widget tree:
 
 - `this.onClick(id, handler)`
 - `this.onScroll(id, handler)`

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,16 +7,13 @@ interface OutgoingMessage {
     data: unknown;
     line: string;
 }
-interface ShowNotificationArgs {
-    summary: string;
+interface ShowNotificationOptions {
     body?: string;
-    urgency?: string;
 }
-interface OpenUriArgs {
-    uri: string;
-}
-interface CopyToClipboardArgs {
-    text: string;
+export interface CommandResult {
+    stdout: string;
+    stderr: string;
+    rc: number;
 }
 interface DismissNotificationArgs {
     id: number;
@@ -24,6 +21,7 @@ interface DismissNotificationArgs {
 export declare abstract class Applet<State extends object> {
     state: State;
     private readonly handlerMap;
+    private inlineHandlerMap;
     private readonly outgoing;
     private flushPromise;
     private renderQueued;
@@ -32,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>;
@@ -43,12 +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;
-    protected showNotification(args: ShowNotificationArgs): void;
-    protected openUri(args: OpenUriArgs): void;
-    protected copyToClipboard(args: CopyToClipboardArgs): void;
+    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;
@@ -59,4 +62,5 @@ export declare abstract class Applet<State extends object> {
     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,17 +46,31 @@ 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;
     }
-    showNotification(args) {
-        this.emitAction("show_notification", args);
+    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]);
     }
-    openUri(args) {
-        this.emitAction("open_uri", args);
+    async copyToClipboard(text) {
+        await this.runDesktopCommand("wl-copy", [], text);
     }
-    copyToClipboard(args) {
-        this.emitAction("copy_to_clipboard", args);
+    async runCommand(command) {
+        return await runCommand(command);
     }
     dismissNotification(args) {
         this.emitAction("dismiss_notification", args);
@@ -58,6 +78,9 @@ export class Applet {
     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") {
@@ -65,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,
@@ -104,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;
@@ -151,6 +184,14 @@ 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 };
         if (!deepEqual(tree, this.lastTree)) {
             this.lastTree = tree;
@@ -194,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,5 +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 { 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";
+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 +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 { 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";
+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/protocol.d.ts

@@ -1,28 +1,23 @@
-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;
+        cssClasses?: string[];
     };
     constructor(options?: {
         id?: string;
-        icon?: Icon;
+        icon?: string;
         label?: string;
         tooltip?: string;
+        cssClasses?: string[];
     });
+    /**
+     * Return a copy with `cssClass` appended to `cssClasses`. Immutable-update
+     * form that mirrors the Rust SDK's `css_class()` builder so SDK-hopping
+     * users see equivalent ergonomics across languages.
+     */
+    withCssClass(cssClass: string): StatusItem;
     toProtocol(): Record<string, unknown>;
 }

package/dist/src/protocol.js

@@ -1,32 +1,26 @@
-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;
     }
+    /**
+     * Return a copy with `cssClass` appended to `cssClasses`. Immutable-update
+     * form that mirrors the Rust SDK's `css_class()` builder so SDK-hopping
+     * users see equivalent ergonomics across languages.
+     */
+    withCssClass(cssClass) {
+        return new StatusItem({
+            ...this.options,
+            cssClasses: [...(this.options.cssClasses ?? []), cssClass],
+        });
+    }
     toProtocol() {
         const payload = {};
         if (this.options.id !== undefined) {
             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;
@@ -34,6 +28,9 @@ export class StatusItem {
         if (this.options.tooltip !== undefined) {
             payload.tooltip = this.options.tooltip;
         }
+        if (this.options.cssClasses && this.options.cssClasses.length > 0) {
+            payload.css_classes = [...this.options.cssClasses];
+        }
         return payload;
     }
 }