@garretapp/sdk 0.1.1 → 0.1.3

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

@@ -187,7 +187,11 @@ function getGarret() {
     active: true,
     onActiveChange: () => () => {
     },
-    onOpenSettings: () => () => {
+    setCommands: () => {
+    },
+    onCommand: () => () => {
+    },
+    setTitle: () => {
     },
     surfaces: { open: nope, onClosed: () => () => {
     } },

package/dist/{platform-CZHtdUK0.d.ts → platform-Bbj2Vh3W.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
@@ -115,8 +120,12 @@ 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;
+    /** 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. */
     surfaces: SurfaceApi;
     /** Controls for this UI's own surface window (no-op for a board-placed widget). */

package/dist/{platform-DnI7gJTx.d.cts → platform-qz2Ef0Rp.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
@@ -115,8 +120,12 @@ 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;
+    /** 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. */
     surfaces: SurfaceApi;
     /** Controls for this UI's own surface window (no-op for a board-placed widget). */

package/dist/react.cjs

@@ -220,7 +220,11 @@ function getGarret() {
     active: true,
     onActiveChange: () => () => {
     },
-    onOpenSettings: () => () => {
+    setCommands: () => {
+    },
+    onCommand: () => () => {
+    },
+    setTitle: () => {
     },
     surfaces: { open: nope, onClosed: () => () => {
     } },
@@ -422,11 +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]);
+  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();
@@ -491,6 +499,6 @@ exports.useGarret = useGarret;
 exports.useHost = useHost;
 exports.useHostEvent = useHostEvent;
 exports.useInstanceConfig = useInstanceConfig;
-exports.useOpenSettings = useOpenSettings;
 exports.useProps = useProps;
 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-DnI7gJTx.cjs';
-export { S as SurfaceApi, a as SurfaceHandle, b as SurfaceOpenOptions, W as WindowControls } from './platform-DnI7gJTx.cjs';
+import { G as GarretPlatform } from './platform-qz2Ef0Rp.cjs';
+export { S as SurfaceApi, a as SurfaceHandle, b as SurfaceOpenOptions, W as WindowControls } from './platform-qz2Ef0Rp.cjs';
 import { ReactNode } from 'react';
 import './protocol-Do0BJdeE.cjs';
 
@@ -110,8 +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;
+/** 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. */
@@ -126,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, 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-CZHtdUK0.js';
-export { S as SurfaceApi, a as SurfaceHandle, b as SurfaceOpenOptions, W as WindowControls } from './platform-CZHtdUK0.js';
+import { G as GarretPlatform } from './platform-Bbj2Vh3W.js';
+export { S as SurfaceApi, a as SurfaceHandle, b as SurfaceOpenOptions, W as WindowControls } from './platform-Bbj2Vh3W.js';
 import { ReactNode } from 'react';
 import './protocol-Do0BJdeE.js';
 
@@ -110,8 +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;
+/** 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. */
@@ -126,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, 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-ZJYHRC5C.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,11 +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]);
+  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();
@@ -239,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, 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,7 +215,11 @@ function getGarret() {
     active: true,
     onActiveChange: () => () => {
     },
-    onOpenSettings: () => () => {
+    setCommands: () => {
+    },
+    onCommand: () => () => {
+    },
+    setTitle: () => {
     },
     surfaces: { open: nope, onClosed: () => () => {
     } },

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-DnI7gJTx.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-qz2Ef0Rp.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-CZHtdUK0.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-Bbj2Vh3W.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-ZJYHRC5C.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.1",
+  "version": "0.1.3",
   "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",