lumiverse-spindle-types 0.3.8 → 0.3.9

package/package.json

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

package/src/api.ts

@@ -640,6 +640,53 @@ export type SpindleModalItemDTO =
   /** A themed card/container that groups child items. */
   | { type: "card"; items: SpindleModalItemDTO[] };
 
+// ─── Command Palette DTOs ──────────────────────────────────────────────
+
+/**
+ * Command registration payload sent by extensions to add entries
+ * to the Lumiverse command palette (Cmd/Ctrl+K).
+ *
+ * Commands are contextual — extensions can register different sets
+ * based on the current chat, page, or app state by calling
+ * `spindle.commands.register()` with an updated list at any time.
+ * Each call replaces all previously registered commands from that extension.
+ */
+export interface SpindleCommandDTO {
+  /** Unique identifier for this command within the extension (e.g. `"summarize-chat"`). */
+  id: string;
+  /** Display label shown in the command palette. Max 80 characters. */
+  label: string;
+  /** Description shown below the label. Max 200 characters. */
+  description: string;
+  /** Optional search keywords for fuzzy matching. Max 10 keywords, 30 chars each. */
+  keywords?: string[];
+  /**
+   * Scope restriction controlling when the command appears.
+   * - `'global'` — always visible (default)
+   * - `'chat'` — only when viewing a chat
+   * - `'chat-idle'` — only when in a chat and not streaming
+   * - `'landing'` — only on the home page
+   * - `'character'` — only on character pages
+   */
+  scope?: "global" | "chat" | "chat-idle" | "landing" | "character";
+}
+
+/**
+ * Context snapshot sent to the extension when a command is invoked
+ * from the command palette. Contains the frontend's current UI state
+ * so the extension can act on the right chat/character/page.
+ */
+export interface SpindleCommandContextDTO {
+  /** Current route path (e.g. `"/chat/abc-123"`, `"/"`, `"/characters/xyz"`). */
+  route: string;
+  /** Active chat ID, if the user is in a chat view. */
+  chatId?: string;
+  /** Active character ID, if available. */
+  characterId?: string;
+  /** Whether the active chat is a group chat. */
+  isGroupChat?: boolean;
+}
+
 // ─── Worker → Host messages ──────────────────────────────────────────────
 
 export type WorkerToHost =
@@ -883,7 +930,10 @@ export type WorkerToHost =
   | { type: "theme_clear"; requestId: string; userId?: string }
   | { type: "theme_get_current"; requestId: string; userId?: string }
   // ─── Color Extraction (gated: "app_manipulation") ─────────────────────
-  | { type: "color_extract"; requestId: string; imageId: string; userId?: string };
+  | { type: "color_extract"; requestId: string; imageId: string; userId?: string }
+  // ─── Commands (free tier) ──────────────────────────────────────────────
+  | { type: "commands_register"; commands: SpindleCommandDTO[] }
+  | { type: "commands_unregister"; commandIds: string[] };
 
 // ─── Host → Worker messages ──────────────────────────────────────────────
 
@@ -930,4 +980,10 @@ export type HostToWorker =
       type: "oauth_callback";
       requestId: string;
       params: Record<string, string>;
+    }
+  | {
+      type: "command_invoked";
+      commandId: string;
+      context: SpindleCommandContextDTO;
+      userId: string;
     };

package/src/index.ts

@@ -57,6 +57,8 @@ export type {
   ColorRGB,
   ColorHSL,
   SpindleModalItemDTO,
+  SpindleCommandDTO,
+  SpindleCommandContextDTO,
   WorkerToHost,
   HostToWorker,
 } from "./api";

package/src/spindle-api.ts

@@ -34,6 +34,8 @@ import type {
   ThemeInfoDTO,
   ColorExtractionResult,
   SpindleModalItemDTO,
+  SpindleCommandDTO,
+  SpindleCommandContextDTO,
 } from "./api";
 
 /** The global `spindle` object available in backend extension workers */
@@ -728,6 +730,71 @@ export interface SpindleAPI {
     }>;
   };
 
+  /**
+   * Command palette integration (free tier — no permission needed).
+   * Register commands that appear in the Lumiverse command palette
+   * (Cmd/Ctrl+K). Commands are contextual — call `register()` with
+   * an updated list whenever the available commands should change
+   * (e.g. based on active chat, character, or extension state).
+   *
+   * Each `register()` call **replaces** all previously registered
+   * commands from this extension. To add commands incrementally,
+   * maintain your own list and pass the full set each time.
+   *
+   * @example
+   * ```ts
+   * // Register commands
+   * spindle.commands.register([
+   *   {
+   *     id: 'summarize-chat',
+   *     label: 'Summarize Chat',
+   *     description: 'Generate a summary of the current conversation',
+   *     keywords: ['summary', 'recap', 'tldr'],
+   *     scope: 'chat',
+   *   },
+   * ])
+   *
+   * // Handle invocations
+   * spindle.commands.onInvoked((commandId, context) => {
+   *   if (commandId === 'summarize-chat') {
+   *     // context.chatId, context.characterId, etc.
+   *   }
+   * })
+   *
+   * // Update commands based on context
+   * spindle.on('CHAT_CHANGED', () => {
+   *   spindle.commands.register(getCommandsForCurrentState())
+   * })
+   *
+   * // Remove all commands
+   * spindle.commands.unregister()
+   * ```
+   */
+  commands: {
+    /**
+     * Register (or replace) the extension's command palette entries.
+     * Each call replaces the full set — pass the complete list of
+     * commands you want visible. Max 20 commands per extension.
+     */
+    register(commands: SpindleCommandDTO[]): void;
+    /**
+     * Remove specific commands by ID, or all commands if no IDs given.
+     */
+    unregister(commandIds?: string[]): void;
+    /**
+     * Register a handler called when the user selects one of this
+     * extension's commands from the palette. The handler receives
+     * the command ID and a snapshot of the frontend's current state.
+     * Returns an unsubscribe function.
+     */
+    onInvoked(
+      handler: (
+        commandId: string,
+        context: SpindleCommandContextDTO,
+      ) => void | Promise<void>,
+    ): () => void;
+  };
+
   /** This extension's manifest */
   manifest: SpindleManifest;
 }