lumiverse-spindle-types 0.4.61 → 0.4.64

package/package.json

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

package/src/api.ts

@@ -44,6 +44,8 @@ export interface MacroDefinitionDTO {
   returnType?: "string" | "integer" | "number" | "boolean";
   args?: { name: string; description?: string; required?: boolean }[];
   handler: string; // serialized function body (executed in worker context)
+  /** Set true when the macro returns different output across calls with the same args (time, randomness, idle duration). The display-regex cache will not store resolutions that include this macro. */
+  volatile?: boolean;
 }
 
 /** Minimal shape exposed to extension macro handlers. Additional fields may be present. */
@@ -288,6 +290,8 @@ export interface RequestInitDTO {
   /** When `"arraybuffer"`, the response body is returned as a base64-encoded string
    *  with `encoding: "base64"`. Used by the sandboxed-widget transparent proxy. */
   responseType?: "text" | "arraybuffer";
+  /** Restricts transparent binary proxy responses to a browser-renderable media class. */
+  mediaType?: "image" | "audio";
 }
 
 /**
@@ -570,6 +574,14 @@ export interface ChatSwitchedPayloadDTO {
   chatId: string | null;
 }
 
+/** Payload for `CHAT_CHANGED` events. */
+export interface ChatChangedPayloadDTO {
+  /** The chat after the change. */
+  chat: { id: string; [key: string]: unknown };
+  /** Optional. Dot-paths of fields that differed between the prior and new chat (e.g. `metadata.macro_variables.local.foo`, `name`, `metadata.last_message_id`). Absent on events emitted by sources that don't compute the diff. */
+  changedFields?: string[];
+}
+
 // ─── World Book DTOs ─────────────────────────────────────────────────────
 
 /**
@@ -679,7 +691,7 @@ export type WorldBookEntryUpdateDTO = WorldBookEntryCreateDTO;
 export type RegexPlacementDTO = "user_input" | "ai_output" | "world_info" | "reasoning";
 export type RegexScopeDTO = "global" | "character" | "chat";
 export type RegexTargetDTO = "prompt" | "response" | "display";
-export type RegexMacroModeDTO = "none" | "raw" | "escaped";
+export type RegexMacroModeDTO = "none" | "raw" | "escaped" | "after";
 
 export interface RegexScriptDTO {
   id: string;

package/src/dom.ts

@@ -190,6 +190,37 @@ export interface SpindleSandboxFrameHandle {
   destroy(): void;
 }
 
+export interface SpindleSandboxMediaResource {
+  /** Object URL that can be assigned to sandbox-local media elements. */
+  url: string;
+  /** Response media type without parameters, e.g. `audio/mpeg`. */
+  contentType: string;
+  /** Downloaded media size in bytes. */
+  sizeBytes: number;
+  /** Revoke the object URL when it is no longer needed. */
+  revoke(): void;
+}
+
+export interface SpindleSandboxAudioOptions {
+  /** Request options passed to the permission-gated CORS proxy. */
+  request?: RequestInitDTO;
+  controls?: boolean;
+  loop?: boolean;
+  muted?: boolean;
+  preload?: "none" | "metadata" | "auto";
+  /** Clamped to the browser audio range `[0, 1]`. */
+  volume?: number;
+}
+
+export interface SpindleSandboxAudioHandle extends SpindleSandboxMediaResource {
+  /** Sandbox-local audio element backed by the fetched blob URL. */
+  element: HTMLAudioElement;
+  play(): Promise<void>;
+  pause(): void;
+  /** Pause playback, detach the element, and revoke the object URL. */
+  destroy(): void;
+}
+
 /** API exposed inside the sandboxed iframe as `window.spindleSandbox`. */
 export interface SpindleSandboxAPI {
   postMessage(payload: unknown): void;
@@ -197,6 +228,10 @@ export interface SpindleSandboxAPI {
   requestResize(height?: number): void;
   /** Fetch a URL through the extension's CORS proxy. Requires the `cors_proxy` permission. */
   corsProxy(url: string, options?: RequestInitDTO): Promise<unknown>;
+  /** Fetch remote audio through the permission-gated proxy and expose it as a blob URL. */
+  fetchAudio(url: string, options?: RequestInitDTO): Promise<SpindleSandboxMediaResource>;
+  /** Fetch remote audio through the proxy and create a sandbox-local audio element. */
+  createAudio(url: string, options?: SpindleSandboxAudioOptions): Promise<SpindleSandboxAudioHandle>;
 }
 
 export interface SpindleUploadFile {

package/src/index.ts

@@ -36,6 +36,7 @@ export type {
    ChatDTO,
    ChatUpdateDTO,
    ChatSwitchedPayloadDTO,
+   ChatChangedPayloadDTO,
    WorldBookDTO,
   WorldBookCreateDTO,
   WorldBookUpdateDTO,
@@ -161,9 +162,12 @@ export type {
   SpindleAppMountHandle,
    SpindleInputBarActionOptions,
    SpindleInputBarActionHandle,
-   SpindleSandboxFrameOptions,
-   SpindleSandboxFrameHandle,
-   SpindleSandboxAPI,
+    SpindleSandboxFrameOptions,
+    SpindleSandboxFrameHandle,
+    SpindleSandboxMediaResource,
+    SpindleSandboxAudioOptions,
+    SpindleSandboxAudioHandle,
+    SpindleSandboxAPI,
    SpindleContextMenuOptions,
    SpindleContextMenuItemDef,
    SpindleContextMenuResult,

package/src/spindle-api.ts

@@ -73,6 +73,7 @@ import type {
   BackendProcessInfoDTO,
   BackendProcessLifecycleEventDTO,
   BackendProcessStopOptionsDTO,
+  ChatChangedPayloadDTO,
   GenerationStartedPayloadDTO,
   StreamTokenPayloadDTO,
   GenerationEndedPayloadDTO,
@@ -176,6 +177,8 @@ export interface SpindleAPI {
   on(event: "GENERATION_ENDED", handler: (payload: GenerationEndedPayloadDTO, userId?: string) => void): () => void;
   /** Subscribe to generation-stopped events (requires `generation` permission). The optional `userId` identifies which user triggered the event. */
   on(event: "GENERATION_STOPPED", handler: (payload: GenerationStoppedPayloadDTO, userId?: string) => void): () => void;
+  /** Subscribe to `CHAT_CHANGED` events. `changedFields` lists the dot-paths that differed when emitted by the standard `updateChat` path; absent on emits from other sources. */
+  on(event: "CHAT_CHANGED", handler: (payload: ChatChangedPayloadDTO, userId?: string) => void): () => void;
   /**
    * Subscribe to swipe lifecycle events. The payload's `action` discriminator
    * tells you whether a swipe was added, updated, deleted, or navigated, and