lumiverse-spindle-types 0.4.47 → 0.4.49

package/package.json

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

package/src/dom.ts

@@ -1,28 +1,21 @@
-/** DOM helper API provided to frontend extension modules */
+/** DOM helper API provided inside isolated frontend extension modules. */
 export interface SpindleDOMHelper {
-  /** Inject sanitized HTML into a target area */
-  inject(
-    target: string | Element,
-    html: string,
-    position?: InsertPosition
-  ): Element;
-
-  /** Create a scoped style element. Returns a removal function. */
+  /** Create a style element inside the extension sandbox document. Returns a removal function. */
   addStyle(css: string): () => void;
 
-  /** Create an element safely with optional attributes */
+  /** Create an element inside the extension sandbox document with optional attributes. */
   createElement<K extends keyof HTMLElementTagNameMap>(
     tag: K,
     attrs?: Record<string, string>
   ): HTMLElementTagNameMap[K];
 
-  /** Query within this extension's own injected elements only */
+  /** Query inside the extension sandbox document. */
   query(selector: string): Element | null;
 
-  /** Query all within this extension's own injected elements only */
+  /** Query all matches inside the extension sandbox document. */
   queryAll(selector: string): Element[];
 
-  /** Remove all DOM injections by this extension */
+  /** Remove all DOM created inside the extension sandbox document. */
   cleanup(): void;
 }
 
@@ -161,6 +154,34 @@ export interface SpindleInputBarActionHandle {
   destroy(): void;
 }
 
+// ── Sandboxed Frame ──
+
+export interface SpindleSandboxFrameOptions {
+  /** HTML document or fragment rendered inside the sandboxed iframe. */
+  html: string;
+  /** Automatically resize the host iframe to fit the child content. Default: `true`. */
+  autoResize?: boolean;
+  /** Initial host iframe height in CSS pixels. Default: `minHeight` or `40`. */
+  initialHeight?: number;
+  /** Minimum host iframe height in CSS pixels. Default: `40`. */
+  minHeight?: number;
+  /** Maximum host iframe height in CSS pixels. Default: `4000`. */
+  maxHeight?: number;
+}
+
+export interface SpindleSandboxFrameHandle {
+  /** The sandboxed iframe element. Extensions may place and style it like any other element. */
+  element: HTMLIFrameElement;
+  /** Replace the child document contents. */
+  setContent(html: string): void;
+  /** Send a message payload into the child sandbox runtime. */
+  postMessage(payload: unknown): void;
+  /** Receive payloads sent from the child sandbox runtime. */
+  onMessage(handler: (payload: unknown) => void): () => void;
+  /** Destroy the sandbox and remove the iframe from the DOM. */
+  destroy(): void;
+}
+
 export interface SpindleUploadFile {
   name: string;
   mimeType: string;
@@ -186,6 +207,19 @@ export interface SpindleMessageTagInterceptorOptions {
   removeFromMessage?: boolean;
 }
 
+export interface SpindleMessageWidgetOptions {
+  /** Message ID that should host the widget. */
+  messageId: string;
+  /** Stable extension-defined widget ID, unique within the target message. */
+  widgetId: string;
+  /** HTML document or fragment rendered inside a host-managed opaque-origin iframe. */
+  html: string;
+  /** Minimum iframe height in CSS pixels. Default: 40. */
+  minHeight?: number;
+  /** Maximum iframe height in CSS pixels. Default: 4000. */
+  maxHeight?: number;
+}
+
 /** Options for `permissions.request()` — displayed in the system confirmation modal. */
 export interface PermissionRequestOptions {
   /** Human-readable explanation of why the extension needs these permissions.
@@ -470,6 +504,21 @@ export interface SpindleFrontendContext {
       options: SpindleMessageTagInterceptorOptions,
       handler: (payload: SpindleMessageTagIntercept) => void
     ): () => void;
+    /** Render or replace a sandboxed widget below a message. Returns a cleanup function. */
+    renderWidget(
+      options: SpindleMessageWidgetOptions,
+      handler?: (payload: unknown) => void,
+    ): () => void;
+    /** Remove a previously rendered message widget. */
+    removeWidget(messageId: string, widgetId: string): void;
+  };
+  characters: {
+    /** Read a character through the host app's authenticated API. */
+    get(characterId: string): Promise<unknown>;
+  };
+  chats: {
+    /** Update a message through the host app's authenticated API. */
+    updateMessage(chatId: string, messageId: string, input: { content?: string }): Promise<unknown>;
   };
   manifest: import("./manifest").SpindleManifest;
 }

package/src/index.ts

@@ -123,9 +123,10 @@ export type {
   SpindleDOMHelper,
   SpindleMountPoint,
   SpindleUploadFile,
-  SpindleMessageTagIntercept,
-  SpindleMessageTagInterceptorOptions,
-  PermissionRequestOptions,
+    SpindleMessageTagIntercept,
+    SpindleMessageTagInterceptorOptions,
+    SpindleMessageWidgetOptions,
+    PermissionRequestOptions,
   SpindleFrontendContext,
   SpindleFrontendModule,
   SpindleDrawerTabOptions,
@@ -137,11 +138,13 @@ export type {
   SpindleDockPanelHandle,
   SpindleAppMountOptions,
   SpindleAppMountHandle,
-  SpindleInputBarActionOptions,
-  SpindleInputBarActionHandle,
-  SpindleContextMenuOptions,
-  SpindleContextMenuItemDef,
-  SpindleContextMenuResult,
+   SpindleInputBarActionOptions,
+   SpindleInputBarActionHandle,
+   SpindleSandboxFrameOptions,
+   SpindleSandboxFrameHandle,
+   SpindleContextMenuOptions,
+   SpindleContextMenuItemDef,
+   SpindleContextMenuResult,
   SpindleModalOptions,
   SpindleModalHandle,
    SpindleConfirmVariant,