lumiverse-spindle-types 0.5.8 → 0.5.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.5.8",
+  "version": "0.5.9",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/api.ts

@@ -1637,6 +1637,50 @@ export interface SpindleCommandContextDTO {
   isGroupChat?: boolean;
 }
 
+// ─── UI Automation DTOs ─────────────────────────────────────────────────
+
+/**
+ * Read-only snapshot of a drawer tab discoverable via
+ * {@link SpindleAPI.ui.getDrawerTabs}. Mirrors the metadata used by the
+ * built-in Command Palette to render the "Panels" group.
+ */
+export interface SpindleUIDrawerTabDTO {
+  /** Stable id used by `openDrawerTab(id)`. */
+  id: string;
+  /** Short label shown beneath the sidebar icon (max ~8 characters). */
+  shortName: string;
+  /** Full title shown in menus and the command palette. */
+  tabName: string;
+  /** One-line description shown in the command palette. */
+  tabDescription: string;
+  /** Keywords used for command-palette fuzzy search. */
+  keywords: string[];
+  /** Whether the tab is built into Lumiverse or contributed by another extension. */
+  source: "builtin" | "extension";
+  /** For extension-contributed tabs, the owning extension's identifier. */
+  extensionId?: string;
+}
+
+/**
+ * Read-only snapshot of a settings tab discoverable via
+ * {@link SpindleAPI.ui.getSettingsTabs}. Restricted entries (`role` set) are
+ * filtered out when the call resolves to a user that lacks the required role.
+ */
+export interface SpindleUISettingsTabDTO {
+  /** Stable id used by `openSettings(id)`. */
+  id: string;
+  /** Short label shown in the settings sidebar. */
+  shortName: string;
+  /** Full title shown in the settings header / command palette. */
+  tabName: string;
+  /** One-line description shown in the command palette. */
+  tabDescription: string;
+  /** Keywords used for command-palette fuzzy search. */
+  keywords: string[];
+  /** Set when the tab is only visible to certain roles. */
+  role?: "admin" | "owner";
+}
+
 // ─── Frontend Process Lifecycle DTOs ────────────────────────────────────
 
 /** High-level lifecycle state for a frontend process tracked by the backend host. */
@@ -2590,7 +2634,24 @@ export type WorkerToHost =
       scrape?: boolean;
       userId?: string;
     }
-  | { type: "web_search_get_settings"; requestId: string; userId?: string };
+  | { type: "web_search_get_settings"; requestId: string; userId?: string }
+  // ─── UI Automation (free tier) ────────────────────────────────────────
+  | { type: "ui_get_drawer_tabs"; requestId: string; userId?: string }
+  | { type: "ui_get_settings_tabs"; requestId: string; userId?: string }
+  | {
+      type: "ui_navigate";
+      requestId: string;
+      action:
+        | "open_drawer_tab"
+        | "close_drawer"
+        | "open_settings"
+        | "close_settings"
+        | "open_command_palette"
+        | "close_command_palette";
+      tabId?: string;
+      viewId?: string;
+      userId?: string;
+    };
 
 // ─── Host → Worker messages ──────────────────────────────────────────────
 

package/src/index.ts

@@ -121,6 +121,8 @@ export type {
   SpindleModalItemDTO,
    SpindleCommandDTO,
    SpindleCommandContextDTO,
+   SpindleUIDrawerTabDTO,
+   SpindleUISettingsTabDTO,
    FrontendProcessStateDTO,
    FrontendProcessExitReasonDTO,
    FrontendProcessSpawnOptionsDTO,

package/src/spindle-api.ts

@@ -72,6 +72,8 @@ import type {
   SpindleModalItemDTO,
   SpindleCommandDTO,
   SpindleCommandContextDTO,
+  SpindleUIDrawerTabDTO,
+  SpindleUISettingsTabDTO,
   FrontendProcessSpawnOptionsDTO,
   FrontendProcessListOptionsDTO,
   FrontendProcessInfoDTO,
@@ -1522,6 +1524,77 @@ export interface SpindleAPI {
     getRole(userId?: string): Promise<SpindleUserRoleDTO>;
   };
 
+  /**
+   * UI automation (free tier — no permission needed).
+   *
+   * Enumerate the built-in drawer / settings tabs and trigger navigation
+   * on the user's frontend. Same primitives the Command Palette uses, but
+   * exposed to extensions so agents and automations can guide the user to
+   * the right surface — for example, an onboarding flow that opens the
+   * Connections drawer, or a "fix it" prompt that jumps to the relevant
+   * settings tab.
+   *
+   * Listings include both built-in tabs (mirrored on the backend) and
+   * extension-contributed drawer tabs the user's frontend has registered.
+   * Navigation calls accept any tab id the frontend recognises — including
+   * extension-added ids — so an extension can deep-link into another
+   * extension's tab if it knows the id.
+   *
+   * @example
+   * ```ts
+   * // Enumerate every drawer tab the user can see and surface our own
+   * // command-palette-style picker.
+   * const tabs = await spindle.ui.getDrawerTabs({ userId })
+   * await spindle.modal.open({
+   *   title: "Jump to…",
+   *   items: tabs.map((t) => ({ type: "key_value", label: t.tabName, value: t.tabDescription })),
+   * })
+   *
+   * // Take the user straight to the Connections drawer.
+   * await spindle.ui.openDrawerTab("connections", { userId })
+   * ```
+   */
+  ui: {
+    /**
+     * Read the discoverable drawer tabs (built-in + extension-contributed)
+     * visible to the resolved user. Extension tabs are only included once
+     * the user's frontend has synced its registry over the WebSocket;
+     * during connection bootstrap the list may be limited to built-ins.
+     *
+     * For user-scoped extensions, `userId` defaults to the installer.
+     * Operator-scoped extensions should pass `userId` to scope the call.
+     */
+    getDrawerTabs(options?: { userId?: string }): Promise<SpindleUIDrawerTabDTO[]>;
+    /**
+     * Read the discoverable settings tabs visible to the resolved user.
+     * Restricted tabs (e.g. `role: "owner"`) are filtered out for users
+     * lacking the required role. When `userId` is omitted on operator-scoped
+     * extensions, role gating is skipped and every tab is returned.
+     */
+    getSettingsTabs(options?: { userId?: string }): Promise<SpindleUISettingsTabDTO[]>;
+    /**
+     * Open the drawer to a specific tab. The id is forwarded verbatim, so
+     * extension-contributed tabs are addressable too. The call resolves
+     * once the host has dispatched the navigation event — the frontend
+     * applies it asynchronously.
+     */
+    openDrawerTab(tabId: string, options?: { userId?: string }): Promise<void>;
+    /** Close the drawer if it is currently open. */
+    closeDrawer(options?: { userId?: string }): Promise<void>;
+    /**
+     * Open the settings modal. Pass a settings tab id (e.g. `"connections"`,
+     * `"display"`) to land on a specific view; omit to open the user's last
+     * settings view.
+     */
+    openSettings(viewId?: string, options?: { userId?: string }): Promise<void>;
+    /** Close the settings modal if it is currently open. */
+    closeSettings(options?: { userId?: string }): Promise<void>;
+    /** Open the command palette overlay. */
+    openCommandPalette(options?: { userId?: string }): Promise<void>;
+    /** Close the command palette overlay if it is currently open. */
+    closeCommandPalette(options?: { userId?: string }): Promise<void>;
+  };
+
   /** Show toast notifications in the frontend UI (free tier — no permission needed) */
   toast: {
     success(message: string, options?: { title?: string; duration?: number; /** For operator-scoped extensions only. */ userId?: string }): void;