lumiverse-spindle-types 0.4.55 → 0.4.57

package/package.json

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

package/src/api.ts

@@ -1593,6 +1593,14 @@ export interface TokenCountResultDTO {
   approximate: boolean;
 }
 
+/** Context delivered to an on-request shared RPC endpoint handler. */
+export interface SharedRpcRequestContextDTO {
+  /** Fully-qualified endpoint name (for example `weather_ext.status.current`). */
+  endpoint: string;
+  /** Identifier of the extension requesting the value. */
+  requesterExtensionId: string;
+}
+
 // ─── Worker → Host messages ──────────────────────────────────────────────
 
 export type WorkerToHost =
@@ -1675,6 +1683,16 @@ export type WorkerToHost =
       reservationId: string;
     }
   | { type: "permissions_get_granted"; requestId: string }
+  | { type: "rpc_pool_sync"; endpoint: string; value: unknown }
+  | { type: "rpc_pool_register_handler"; endpoint: string }
+  | { type: "rpc_pool_unregister"; endpoint: string }
+  | { type: "rpc_pool_read"; requestId: string; endpoint: string }
+  | {
+      type: "rpc_pool_handler_result";
+      requestId: string;
+      result?: unknown;
+      error?: string;
+    }
   | { type: "connections_list"; requestId: string; userId?: string }
   | { type: "connections_get"; requestId: string; connectionId: string; userId?: string }
   | { type: "chat_get_messages"; requestId: string; chatId: string }
@@ -2010,6 +2028,12 @@ export type WorkerToHost =
 export type HostToWorker =
   | { type: "init"; manifest: SpindleManifest; storagePath: string }
   | { type: "event"; event: string; payload: unknown; userId?: string }
+  | {
+      type: "rpc_pool_request";
+      requestId: string;
+      endpoint: string;
+      requesterExtensionId: string;
+    }
   | {
       type: "intercept_request";
       requestId: string;

package/src/dom.ts

@@ -377,6 +377,83 @@ export interface SpindleConfirmResult {
   confirmed: boolean;
 }
 
+// ── UI Event Helpers ──
+
+export type SpindleUIDomActionEventType = "click" | "pointerdown" | "pointerup";
+
+export interface SpindleUIKeyboardState {
+  /** True when the host believes a virtual keyboard is currently visible. */
+  visible: boolean;
+  /** Safe bottom inset in CSS pixels that keeps content above the keyboard. */
+  insetBottom: number;
+  /** Current visual viewport width in CSS pixels. */
+  viewportWidth: number;
+  /** Current visual viewport height in CSS pixels. */
+  viewportHeight: number;
+}
+
+export interface SpindleUIDrawerState {
+  /** Whether the side drawer is currently visible. */
+  open: boolean;
+  /** Active drawer tab, if any. */
+  tabId: string | null;
+}
+
+export interface SpindleUISettingsState {
+  /** Whether the settings modal is currently visible. */
+  open: boolean;
+  /** Active settings view identifier. */
+  view: string;
+}
+
+export interface SpindleUIDomActionDetail {
+  /** Matched action identifier read from the target element. */
+  actionId: string;
+  /** DOM event type that triggered the callback. */
+  eventType: SpindleUIDomActionEventType;
+  /** Matched descendant element that carried the action identifier. */
+  element: HTMLElement;
+  /** Bound extension-owned root used for delegation. */
+  root: Element;
+  /** Native DOM event from the host document. */
+  originalEvent: Event;
+}
+
+export interface SpindleUIDomActionBindingOptions {
+  /** Attribute used to resolve action IDs. Default: `id`. */
+  attribute?: string;
+  /** Event types to listen for. Default: `["click"]`. */
+  events?: SpindleUIDomActionEventType[];
+}
+
+export interface SpindleUIEventsHelper {
+  /** Read the current virtual keyboard snapshot. */
+  getKeyboardState(): SpindleUIKeyboardState;
+  /** Subscribe to keyboard visibility / safe-area changes. */
+  onKeyboardChange(handler: (state: SpindleUIKeyboardState) => void): () => void;
+  /** Read the current side drawer snapshot. */
+  getDrawerState(): SpindleUIDrawerState;
+  /** Subscribe to side drawer open/close and tab changes. */
+  onDrawerChange(handler: (state: SpindleUIDrawerState) => void): () => void;
+  /** Read the current settings modal snapshot. */
+  getSettingsState(): SpindleUISettingsState;
+  /** Subscribe to settings modal open/close and active-view changes. */
+  onSettingsChange(handler: (state: SpindleUISettingsState) => void): () => void;
+  /**
+   * Delegate action handlers from extension-owned DOM.
+   *
+   * This is intended for non-sandbox UI where the extension injects or mounts
+   * host DOM directly and wants to react to user interaction without wiring
+   * global document listeners. By default the helper matches descendant
+   * elements by `id`, but `options.attribute` can be used instead.
+   */
+  bindActionHandlers(
+    target: string | Element,
+    handlers: Record<string, (detail: SpindleUIDomActionDetail) => void>,
+    options?: SpindleUIDomActionBindingOptions,
+  ): () => void;
+}
+
 // ── Frontend Process Lifecycle ──
 
 /** Controller passed to a frontend process instance spawned by the backend runtime. */
@@ -432,6 +509,7 @@ export interface SpindleFrontendContext {
     emit(event: string, payload: unknown): void;
   };
   ui: {
+    events: SpindleUIEventsHelper;
     mount(point: SpindleMountPoint): Element;
     registerDrawerTab(options: SpindleDrawerTabOptions): SpindleDrawerTabHandle;
     createFloatWidget(options?: SpindleFloatWidgetOptions): SpindleFloatWidgetHandle;

package/src/index.ts

@@ -111,6 +111,7 @@ export type {
   TokenModelSourceDTO,
   TokenCountOptionsDTO,
   TokenCountResultDTO,
+  SharedRpcRequestContextDTO,
   MacroInterceptorPhase,
   MacroInterceptorEnvDTO,
   MacroInterceptorCtxDTO,
@@ -155,11 +156,18 @@ export type {
   SpindleModalOptions,
   SpindleModalHandle,
    SpindleConfirmVariant,
-   SpindleConfirmOptions,
-   SpindleConfirmResult,
-   SpindleFrontendProcessContext,
-   SpindleFrontendProcessRegistry,
-} from "./dom";
+    SpindleConfirmOptions,
+    SpindleConfirmResult,
+    SpindleUIDomActionEventType,
+    SpindleUIKeyboardState,
+    SpindleUIDrawerState,
+    SpindleUISettingsState,
+    SpindleUIDomActionDetail,
+    SpindleUIDomActionBindingOptions,
+    SpindleUIEventsHelper,
+    SpindleFrontendProcessContext,
+    SpindleFrontendProcessRegistry,
+ } from "./dom";
 
 export type { ExtensionInfo } from "./extension-info";
 

package/src/spindle-api.ts

@@ -83,6 +83,7 @@ import type {
   MacroInterceptorResultDTO,
   MessageContentProcessorCtxDTO,
   MessageContentProcessorResultDTO,
+  SharedRpcRequestContextDTO,
 } from "./api";
 
 export interface FrontendProcessHandle {
@@ -816,6 +817,37 @@ export interface SpindleAPI {
     onChanged(handler: (detail: PermissionChangedDetail) => void): () => void;
   };
 
+  /**
+   * Shared RPC pool (free tier).
+   *
+   * Use this to expose lightweight cross-extension state behind a stable
+   * `<extension_id>.<channel>` endpoint. Owner methods accept either the bare
+   * channel suffix (`status.current`) or the fully-qualified endpoint.
+   */
+  rpcPool: {
+    /**
+     * Publish the latest value for an endpoint. Replaces any previous on-demand
+     * handler for the same endpoint.
+     *
+     * Returns the fully-qualified endpoint name.
+     */
+    sync(endpoint: string, value: unknown): string;
+    /**
+     * Register an on-demand endpoint handler. Replaces any previously synced
+     * value or handler for the same endpoint.
+     *
+     * Returns the fully-qualified endpoint name.
+     */
+    handle(
+      endpoint: string,
+      handler: (ctx: SharedRpcRequestContextDTO) => unknown | Promise<unknown>
+    ): string;
+    /** Read the latest value from another extension's fully-qualified endpoint. */
+    read<T = unknown>(endpoint: string): Promise<T>;
+    /** Remove an endpoint owned by this extension. */
+    unregister(endpoint: string): void;
+  };
+
   /** Make a CORS-proxied HTTP request */
   cors(url: string, options?: RequestInitDTO): Promise<unknown>;