@garretapp/sdk 0.1.2 → 0.1.4

package/dist/{chunk-YBYF7JQS.js → chunk-AIGAFJFB.js}

@@ -187,9 +187,9 @@ function getGarret() {
     active: true,
     onActiveChange: () => () => {
     },
-    onOpenSettings: () => () => {
+    setCommands: () => {
     },
-    onRefresh: () => () => {
+    onCommand: () => () => {
     },
     setTitle: () => {
     },

package/dist/{platform-DjRN9xTv.d.cts → platform-Byqljdn8.d.cts}

@@ -43,6 +43,11 @@ interface SharedApi {
     storage: StorageApi;
     secrets: SecretsApi;
 }
+/** A frame ⋯-menu command a widget declares via `setCommands` (dispatched back through `onCommand`). */
+interface WidgetCommand {
+    id: string;
+    label: string;
+}
 /** Options for opening a floating sibling surface. All fields optional; sizes in px. */
 interface SurfaceOpenOptions {
     /** initial props delivered to the opened surface as `g.props`; structured-cloned, so each surface
@@ -106,7 +111,11 @@ interface GarretPlatform {
     /** Pack-shared store — present only when the pack declares `shared`; otherwise its calls reject. */
     shared: SharedApi;
     service<T extends ServiceClient = ServiceClient>(id: string): T;
-    notify(title: string, body?: string): void;
+    /** Show a system notification. `opts.url` makes it clickable → opens the link (requires the
+     *  `openExternal` capability; ignored otherwise). */
+    notify(title: string, body?: string, opts?: {
+        url?: string;
+    }): void;
     openExternal(url: string): Promise<boolean>;
     clipboard: {
         readText(): Promise<string>;
@@ -115,10 +124,10 @@ interface GarretPlatform {
     /** false when the board is ambient/idle — pause rAF/animations, throttle polling. */
     active: boolean;
     onActiveChange(cb: (active: boolean) => void): () => void;
-    /** The host (frame ⋯→Settings) asks this widget to open its own config UI. */
-    onOpenSettings(cb: () => void): () => void;
-    /** The host (frame ⋯→Refresh) asks this widget to reload its data. */
-    onRefresh(cb: () => void): () => void;
+    /** Declare the commands this widget wants in the frame's ⋯ menu. The host renders them and dispatches
+     *  the chosen one to `onCommand` — one generic mechanism (settings, refresh, or anything you invent). */
+    setCommands(commands: WidgetCommand[]): void;
+    onCommand(cb: (id: string) => void): () => void;
     /** Set this placement's title in the board frame header (persisted in the board config). */
     setTitle(title: string): void;
     /** Open sibling surfaces (same package) as floating windows. Requires the `windows` capability. */

package/dist/{platform-K2c4rKaG.d.ts → platform-CRkiyy2a.d.ts}

@@ -43,6 +43,11 @@ interface SharedApi {
     storage: StorageApi;
     secrets: SecretsApi;
 }
+/** A frame ⋯-menu command a widget declares via `setCommands` (dispatched back through `onCommand`). */
+interface WidgetCommand {
+    id: string;
+    label: string;
+}
 /** Options for opening a floating sibling surface. All fields optional; sizes in px. */
 interface SurfaceOpenOptions {
     /** initial props delivered to the opened surface as `g.props`; structured-cloned, so each surface
@@ -106,7 +111,11 @@ interface GarretPlatform {
     /** Pack-shared store — present only when the pack declares `shared`; otherwise its calls reject. */
     shared: SharedApi;
     service<T extends ServiceClient = ServiceClient>(id: string): T;
-    notify(title: string, body?: string): void;
+    /** Show a system notification. `opts.url` makes it clickable → opens the link (requires the
+     *  `openExternal` capability; ignored otherwise). */
+    notify(title: string, body?: string, opts?: {
+        url?: string;
+    }): void;
     openExternal(url: string): Promise<boolean>;
     clipboard: {
         readText(): Promise<string>;
@@ -115,10 +124,10 @@ interface GarretPlatform {
     /** false when the board is ambient/idle — pause rAF/animations, throttle polling. */
     active: boolean;
     onActiveChange(cb: (active: boolean) => void): () => void;
-    /** The host (frame ⋯→Settings) asks this widget to open its own config UI. */
-    onOpenSettings(cb: () => void): () => void;
-    /** The host (frame ⋯→Refresh) asks this widget to reload its data. */
-    onRefresh(cb: () => void): () => void;
+    /** Declare the commands this widget wants in the frame's ⋯ menu. The host renders them and dispatches
+     *  the chosen one to `onCommand` — one generic mechanism (settings, refresh, or anything you invent). */
+    setCommands(commands: WidgetCommand[]): void;
+    onCommand(cb: (id: string) => void): () => void;
     /** Set this placement's title in the board frame header (persisted in the board config). */
     setTitle(title: string): void;
     /** Open sibling surfaces (same package) as floating windows. Requires the `windows` capability. */

package/dist/react.cjs

@@ -220,9 +220,9 @@ function getGarret() {
     active: true,
     onActiveChange: () => () => {
     },
-    onOpenSettings: () => () => {
+    setCommands: () => {
     },
-    onRefresh: () => () => {
+    onCommand: () => () => {
     },
     setTitle: () => {
     },
@@ -426,17 +426,15 @@ function useActive() {
   react.useEffect(() => g.onActiveChange(setActive), [g]);
   return active;
 }
-function useOpenSettings(cb) {
+function useWidgetMenu(items) {
   const g = getGarret();
-  const ref = react.useRef(cb);
-  ref.current = cb;
-  react.useEffect(() => g.onOpenSettings(() => ref.current()), [g]);
-}
-function useRefresh(cb) {
-  const g = getGarret();
-  const ref = react.useRef(cb);
-  ref.current = cb;
-  react.useEffect(() => g.onRefresh(() => ref.current()), [g]);
+  const ref = react.useRef(items);
+  ref.current = items;
+  const key = items.map((i) => `${i.id}:${i.label}`).join("|");
+  react.useEffect(() => {
+    g.setCommands(ref.current.map((i) => ({ id: i.id, label: i.label })));
+    return g.onCommand((id) => ref.current.find((i) => i.id === id)?.run());
+  }, [g, key]);
 }
 function useInstanceConfig(defaults) {
   const g = getGarret();
@@ -501,7 +499,6 @@ exports.useGarret = useGarret;
 exports.useHost = useHost;
 exports.useHostEvent = useHostEvent;
 exports.useInstanceConfig = useInstanceConfig;
-exports.useOpenSettings = useOpenSettings;
 exports.useProps = useProps;
-exports.useRefresh = useRefresh;
 exports.useStream = useStream;
+exports.useWidgetMenu = useWidgetMenu;

package/dist/react.d.cts

@@ -1,6 +1,6 @@
 import { G as GarretError, E as EventMap, H as HostClient, f as StreamCall } from './types-BxSYAH_H.cjs';
-import { G as GarretPlatform } from './platform-DjRN9xTv.cjs';
-export { S as SurfaceApi, a as SurfaceHandle, b as SurfaceOpenOptions, W as WindowControls } from './platform-DjRN9xTv.cjs';
+import { G as GarretPlatform } from './platform-Byqljdn8.cjs';
+export { S as SurfaceApi, a as SurfaceHandle, b as SurfaceOpenOptions, W as WindowControls } from './platform-Byqljdn8.cjs';
 import { ReactNode } from 'react';
 import './protocol-Do0BJdeE.cjs';
 
@@ -110,10 +110,14 @@ declare function useStream<Chunk, Result = void>(factory: () => StreamCall<Chunk
 declare function useConfig<T>(): [T, (patch: Partial<T>) => void, (value: T) => void];
 /** Board activity — `false` when ambient/idle. Gate polling / rAF / animations on it. */
 declare function useActive(): boolean;
-/** Run `cb` when the host (frame ⋯→Settings) asks this widget to reveal its own config UI. */
-declare function useOpenSettings(cb: () => void): void;
-/** Run `cb` when the host (frame ⋯→Refresh) asks this widget to reload. */
-declare function useRefresh(cb: () => void): void;
+/** Declarative frame ⋯-menu: pass items with inline handlers. Registers them with the host (id +
+ *  label) and runs the matching `run` when the user picks one. One generic mechanism — no bespoke
+ *  per-action hooks. Example: `useWidgetMenu([{ id: 'refresh', label: 'Refresh', run: reload }])`. */
+declare function useWidgetMenu(items: {
+    id: string;
+    label: string;
+    run: () => void;
+}[]): void;
 /** Per-placement config backed by `g.instanceStorage` (isolated per widget instance). Loads once the
  *  runtime binds (calls before bind reject); `set` writes through to storage + state. `loaded` gates
  *  the first data fetch so you don't fetch with defaults before the saved config arrives. */
@@ -128,4 +132,4 @@ declare function useInstanceConfig<T extends Record<string, unknown>>(defaults:
  *  time), so this re-renders when the runtime binds. The `T` is an unchecked cast — validate it yourself. */
 declare function useProps<T = Record<string, unknown>>(): T;
 
-export { Accordion, Badge, Dot, EmptyState, ErrorState, Field, FieldGroup, GarretError, GarretPlatform, Item, NumberInput, Scroll, Select, SettingsPanel, type StreamStatus, Switch, TextInput, type Tone, type UseStreamResult, useActive, useConfig, useGarret, useHost, useHostEvent, useInstanceConfig, useOpenSettings, useProps, useRefresh, useStream };
+export { Accordion, Badge, Dot, EmptyState, ErrorState, Field, FieldGroup, GarretError, GarretPlatform, Item, NumberInput, Scroll, Select, SettingsPanel, type StreamStatus, Switch, TextInput, type Tone, type UseStreamResult, useActive, useConfig, useGarret, useHost, useHostEvent, useInstanceConfig, useProps, useStream, useWidgetMenu };

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import { G as GarretError, E as EventMap, H as HostClient, f as StreamCall } from './types-BxSYAH_H.js';
-import { G as GarretPlatform } from './platform-K2c4rKaG.js';
-export { S as SurfaceApi, a as SurfaceHandle, b as SurfaceOpenOptions, W as WindowControls } from './platform-K2c4rKaG.js';
+import { G as GarretPlatform } from './platform-CRkiyy2a.js';
+export { S as SurfaceApi, a as SurfaceHandle, b as SurfaceOpenOptions, W as WindowControls } from './platform-CRkiyy2a.js';
 import { ReactNode } from 'react';
 import './protocol-Do0BJdeE.js';
 
@@ -110,10 +110,14 @@ declare function useStream<Chunk, Result = void>(factory: () => StreamCall<Chunk
 declare function useConfig<T>(): [T, (patch: Partial<T>) => void, (value: T) => void];
 /** Board activity — `false` when ambient/idle. Gate polling / rAF / animations on it. */
 declare function useActive(): boolean;
-/** Run `cb` when the host (frame ⋯→Settings) asks this widget to reveal its own config UI. */
-declare function useOpenSettings(cb: () => void): void;
-/** Run `cb` when the host (frame ⋯→Refresh) asks this widget to reload. */
-declare function useRefresh(cb: () => void): void;
+/** Declarative frame ⋯-menu: pass items with inline handlers. Registers them with the host (id +
+ *  label) and runs the matching `run` when the user picks one. One generic mechanism — no bespoke
+ *  per-action hooks. Example: `useWidgetMenu([{ id: 'refresh', label: 'Refresh', run: reload }])`. */
+declare function useWidgetMenu(items: {
+    id: string;
+    label: string;
+    run: () => void;
+}[]): void;
 /** Per-placement config backed by `g.instanceStorage` (isolated per widget instance). Loads once the
  *  runtime binds (calls before bind reject); `set` writes through to storage + state. `loaded` gates
  *  the first data fetch so you don't fetch with defaults before the saved config arrives. */
@@ -128,4 +132,4 @@ declare function useInstanceConfig<T extends Record<string, unknown>>(defaults:
  *  time), so this re-renders when the runtime binds. The `T` is an unchecked cast — validate it yourself. */
 declare function useProps<T = Record<string, unknown>>(): T;
 
-export { Accordion, Badge, Dot, EmptyState, ErrorState, Field, FieldGroup, GarretError, GarretPlatform, Item, NumberInput, Scroll, Select, SettingsPanel, type StreamStatus, Switch, TextInput, type Tone, type UseStreamResult, useActive, useConfig, useGarret, useHost, useHostEvent, useInstanceConfig, useOpenSettings, useProps, useRefresh, useStream };
+export { Accordion, Badge, Dot, EmptyState, ErrorState, Field, FieldGroup, GarretError, GarretPlatform, Item, NumberInput, Scroll, Select, SettingsPanel, type StreamStatus, Switch, TextInput, type Tone, type UseStreamResult, useActive, useConfig, useGarret, useHost, useHostEvent, useInstanceConfig, useProps, useStream, useWidgetMenu };

package/dist/react.js

@@ -1,4 +1,4 @@
-import { getGarret, getRuntime, getHostTransport, createHostClient, getInstanceId } from './chunk-YBYF7JQS.js';
+import { getGarret, getRuntime, getHostTransport, createHostClient, getInstanceId } from './chunk-AIGAFJFB.js';
 import { GarretError } from './chunk-ENIDFSMM.js';
 export { GarretError } from './chunk-ENIDFSMM.js';
 import { useState, useMemo, useEffect, useRef, useCallback } from 'react';
@@ -191,17 +191,15 @@ function useActive() {
   useEffect(() => g.onActiveChange(setActive), [g]);
   return active;
 }
-function useOpenSettings(cb) {
+function useWidgetMenu(items) {
   const g = getGarret();
-  const ref = useRef(cb);
-  ref.current = cb;
-  useEffect(() => g.onOpenSettings(() => ref.current()), [g]);
-}
-function useRefresh(cb) {
-  const g = getGarret();
-  const ref = useRef(cb);
-  ref.current = cb;
-  useEffect(() => g.onRefresh(() => ref.current()), [g]);
+  const ref = useRef(items);
+  ref.current = items;
+  const key = items.map((i) => `${i.id}:${i.label}`).join("|");
+  useEffect(() => {
+    g.setCommands(ref.current.map((i) => ({ id: i.id, label: i.label })));
+    return g.onCommand((id) => ref.current.find((i) => i.id === id)?.run());
+  }, [g, key]);
 }
 function useInstanceConfig(defaults) {
   const g = getGarret();
@@ -245,4 +243,4 @@ function useProps() {
   return props;
 }
 
-export { Accordion, Badge, Dot, EmptyState, ErrorState, Field, FieldGroup, Item, NumberInput, Scroll, Select, SettingsPanel, Switch, TextInput, useActive, useConfig, useGarret, useHost, useHostEvent, useInstanceConfig, useOpenSettings, useProps, useRefresh, useStream };
+export { Accordion, Badge, Dot, EmptyState, ErrorState, Field, FieldGroup, Item, NumberInput, Scroll, Select, SettingsPanel, Switch, TextInput, useActive, useConfig, useGarret, useHost, useHostEvent, useInstanceConfig, useProps, useStream, useWidgetMenu };

package/dist/ui.cjs

@@ -215,9 +215,9 @@ function getGarret() {
     active: true,
     onActiveChange: () => () => {
     },
-    onOpenSettings: () => () => {
+    setCommands: () => {
     },
-    onRefresh: () => () => {
+    onCommand: () => () => {
     },
     setTitle: () => {
     },

package/dist/ui.d.cts

@@ -1,7 +1,7 @@
 import { T as Transport } from './protocol-Do0BJdeE.cjs';
 import { E as EventMap, H as HostClient } from './types-BxSYAH_H.cjs';
 export { C as Capability, G as GarretError, M as Manifest, S as Stream, f as StreamCall, g as defineConfig, h as defineManifest } from './types-BxSYAH_H.cjs';
-export { G as GarretPlatform, c as GarretRuntime, d as SecretsApi, e as ServiceClient, f as StorageApi, S as SurfaceApi, a as SurfaceHandle, b as SurfaceOpenOptions, W as WindowControls, g as getGarret, h as getHostTransport, i as getInstanceId, j as getRuntime } from './platform-DjRN9xTv.cjs';
+export { G as GarretPlatform, c as GarretRuntime, d as SecretsApi, e as ServiceClient, f as StorageApi, S as SurfaceApi, a as SurfaceHandle, b as SurfaceOpenOptions, W as WindowControls, g as getGarret, h as getHostTransport, i as getInstanceId, j as getRuntime } from './platform-Byqljdn8.cjs';
 
 /**
  * UI-side host client — a typed proxy over the wire (protocol.ts). Every call returns ONE handle

package/dist/ui.d.ts

@@ -1,7 +1,7 @@
 import { T as Transport } from './protocol-Do0BJdeE.js';
 import { E as EventMap, H as HostClient } from './types-BxSYAH_H.js';
 export { C as Capability, G as GarretError, M as Manifest, S as Stream, f as StreamCall, g as defineConfig, h as defineManifest } from './types-BxSYAH_H.js';
-export { G as GarretPlatform, c as GarretRuntime, d as SecretsApi, e as ServiceClient, f as StorageApi, S as SurfaceApi, a as SurfaceHandle, b as SurfaceOpenOptions, W as WindowControls, g as getGarret, h as getHostTransport, i as getInstanceId, j as getRuntime } from './platform-K2c4rKaG.js';
+export { G as GarretPlatform, c as GarretRuntime, d as SecretsApi, e as ServiceClient, f as StorageApi, S as SurfaceApi, a as SurfaceHandle, b as SurfaceOpenOptions, W as WindowControls, g as getGarret, h as getHostTransport, i as getInstanceId, j as getRuntime } from './platform-CRkiyy2a.js';
 
 /**
  * UI-side host client — a typed proxy over the wire (protocol.ts). Every call returns ONE handle

package/dist/ui.js

@@ -1,3 +1,3 @@
 export { defineConfig, defineManifest } from './chunk-RZJO3X6O.js';
-export { createHostClient, getGarret, getHostTransport, getInstanceId, getRuntime } from './chunk-YBYF7JQS.js';
+export { createHostClient, getGarret, getHostTransport, getInstanceId, getRuntime } from './chunk-AIGAFJFB.js';
 export { GarretError } from './chunk-ENIDFSMM.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@garretapp/sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Build extensions for Garret — one SDK for both web widgets and full-access native extensions. Host runtime (defineHost), UI client + React hooks. See docs/garret.html.",
   "license": "MIT",
   "author": "Sudharsan Selvaraj",