lumiverse-spindle-types 0.6.42 → 0.6.44

package/dist/dom.d.ts

@@ -1,4 +1,5 @@
 import type { SpindleSTTAPI } from "./speech-to-text.js";
+import type { SpindleSystemAudioAPI } from "./system-audio.js";
 import type { SpindleFileDownloadAPI } from "./file-transfers.js";
 import type { ChatDTO, ChatMessageDTO, ChatUpdateDTO, ConnectionProfileDTO, LlmMessageDTO, PromptBlockDTO, PromptVariableValuesDTO, RequestInitDTO, TokenCountOptionsDTO, TokenCountResultDTO, WorldBookCreateDTO, WorldBookDTO, WorldBookEntryCreateDTO, WorldBookEntryDTO, WorldBookEntryUpdateDTO, WorldBookUpdateDTO } from "./api.js";
 import type { SpindleComponentsHelper } from "./components.js";
@@ -1047,6 +1048,8 @@ export interface SpindleFrontendContext {
     readonly files: SpindleFileDownloadAPI;
     /** Host-managed STT. Feature-detect speech-to-text-v1; unavailable on older hosts. */
     readonly stt?: SpindleSTTAPI;
+    /** Host-managed system-audio analysis (spectrum only). Feature-detect system-audio-v1; desktop client only. */
+    readonly systemAudio?: SpindleSystemAudioAPI;
     /** Per-document routing identity, available with frontend-session-origin-v1. */
     readonly frontendSessionId?: string;
     /** Immutable host compatibility descriptor for this extension runtime. */

package/dist/index.d.ts

@@ -27,3 +27,5 @@ export type { CouncilMember, CouncilMemberContext, SidecarConfig, CouncilSidecar
 export { SIDECAR_DEFAULTS, COUNCIL_SIDECAR_DEFAULTS, COUNCIL_TOOLS_DEFAULTS, COUNCIL_SETTINGS_DEFAULTS, } from "./council.js";
 export type { SpindleSTTProvider, SpindleSTTProviderOption, SpindleSTTStatus, SpindleSTTResult, SpindleSTTAudioFrame, SpindleSTTTranscript, SpindleSTTPcmAudio, SpindleSTTOptions, SpindleSTTStartOptions, SpindleSTTSession, SpindleSTTAPI, } from "./speech-to-text.js";
 export { SPINDLE_STT_HOST_CAPABILITIES } from "./speech-to-text.js";
+export type { SpindleSystemAudioUnavailableReason, SpindleSystemAudioAvailability, SpindleSystemAudioFrame, SpindleSystemAudioEndReason, SpindleSystemAudioStartOptions, SpindleSystemAudioSession, SpindleSystemAudioAPI, } from "./system-audio.js";
+export { SPINDLE_SYSTEM_AUDIO_HOST_CAPABILITIES } from "./system-audio.js";

package/dist/index.js

@@ -9,3 +9,4 @@ export { ALL_FRONTEND_RUNTIME_CAPABILITIES, isValidFrontendRuntimeCapability, }
 export { PERMISSION_DENIED_PREFIX } from "./api.js";
 export { SIDECAR_DEFAULTS, COUNCIL_SIDECAR_DEFAULTS, COUNCIL_TOOLS_DEFAULTS, COUNCIL_SETTINGS_DEFAULTS, } from "./council.js";
 export { SPINDLE_STT_HOST_CAPABILITIES } from "./speech-to-text.js";
+export { SPINDLE_SYSTEM_AUDIO_HOST_CAPABILITIES } from "./system-audio.js";

package/dist/permissions.d.ts

@@ -37,7 +37,10 @@
  * - "providers.sidecar.register"   — register a sidecar HTTP endpoint
  * - "mcp_servers"                  — inspect/connect user MCP servers and invoke advertised tools
  * - "mcp_servers.create"           — add MCP server profiles for a user
+ * - "system_audio"                — frontend ctx.systemAudio: a spectrum and levels of the audio the
+ *                            device is playing (never samples), desktop client only. Privileged;
+ *                            the host asks the user on every start.
  */
-export type SpindlePermission = "screen_capture" | "screen_recording" | "generation" | "interceptor" | "tools" | "cors_proxy" | "context_handler" | "ephemeral_storage" | "chat_mutation" | "event_tracking" | "ui_panels" | "app_manipulation" | "oauth" | "characters" | "chats" | "presets" | "world_books" | "regex_scripts" | "regex_scripts_unrestricted" | "databanks" | "memories" | "media" | "personas" | "push_notification" | "image_gen" | "images" | "generation_parameters" | "macro_interceptor" | "web_search" | "unsafe_eval" | "final_response" | "providers.embedding.register" | "providers.tts.register" | "providers.stt.register" | "providers.sidecar.register" | "mcp_servers" | "mcp_servers.create";
+export type SpindlePermission = "screen_capture" | "screen_recording" | "system_audio" | "generation" | "interceptor" | "tools" | "cors_proxy" | "context_handler" | "ephemeral_storage" | "chat_mutation" | "event_tracking" | "ui_panels" | "app_manipulation" | "oauth" | "characters" | "chats" | "presets" | "world_books" | "regex_scripts" | "regex_scripts_unrestricted" | "databanks" | "memories" | "media" | "personas" | "push_notification" | "image_gen" | "images" | "generation_parameters" | "macro_interceptor" | "web_search" | "unsafe_eval" | "final_response" | "providers.embedding.register" | "providers.tts.register" | "providers.stt.register" | "providers.sidecar.register" | "mcp_servers" | "mcp_servers.create";
 export declare const ALL_PERMISSIONS: readonly SpindlePermission[];
 export declare function isValidPermission(p: string): p is SpindlePermission;

package/dist/permissions.js

@@ -1,6 +1,7 @@
 export const ALL_PERMISSIONS = [
     "screen_capture",
     "screen_recording",
+    "system_audio",
     "generation",
     "interceptor",
     "tools",

package/dist/spindle-api.d.ts

@@ -760,7 +760,7 @@ export interface SpindleAPI {
      * For operator-scoped extensions, pass userId to scope to a specific user.
      */
     images: {
-        /** Read original stored bytes, up to 25 MiB. Rejects missing, inaccessible, or oversized assets. */
+        /** Read original stored bytes, up to 100 MiB. Rejects missing, inaccessible, or oversized assets. */
         readBinary(imageId: string, userId?: string): Promise<Uint8Array>;
         list(options?: ImageListOptionsDTO): Promise<{
             data: ImageDTO[];

package/dist/system-audio.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Host-managed analysis of the audio the device is playing, for frontend Spindle extensions.
+ *
+ * Extensions receive a spectrum and levels only (the same shape as `SpindleSTTAudioFrame`): never samples, a
+ * `MediaStream`, or anything else from which what was played could be reconstructed. Available only where the host
+ * has a native adapter (the desktop client); feature-detect `system-audio-v1` and call `isAvailable()`.
+ */
+/** Why system audio cannot be started right now. */
+export type SpindleSystemAudioUnavailableReason = 
+/** This host or device has no system-audio adapter (every browser, and desktop platforms without one). */
+'unsupported'
+/** The user has not enabled system-audio analysis for this client. */
+ | 'disabled';
+export interface SpindleSystemAudioAvailability {
+    available: boolean;
+    unavailableReason?: SpindleSystemAudioUnavailableReason;
+}
+/** One analysis frame. Every number is normalised to 0 – 1. */
+export interface SpindleSystemAudioFrame {
+    /** Overall level (RMS). */
+    amplitude: number;
+    /** Loudest recent level. */
+    peak: number;
+    /** `bands` log-spaced magnitudes from about 40 Hz up to about 14 kHz, lowest first. */
+    frequencies: number[];
+}
+/** Why a session ended without the extension calling `stop()`. */
+export type SpindleSystemAudioEndReason = 'revoked' | 'user-stopped' | 'source-lost' | 'host-disabled';
+export interface SpindleSystemAudioStartOptions {
+    /** Number of bands in each frame, 8 – 64 (default 32). The host clamps out-of-range values. */
+    bands?: number;
+    /** Most frames per second, 1 – 30 (default 30). The host clamps out-of-range values. */
+    maxFps?: number;
+    signal?: AbortSignal;
+    onFrame(frame: SpindleSystemAudioFrame): void;
+    /** Called once if the host ends the session (permission revoked, the user pressed Stop on the host's indicator, the device went away). */
+    onEnd?(reason: SpindleSystemAudioEndReason): void;
+}
+export interface SpindleSystemAudioSession {
+    /**
+     * Resolves when the user has approved the host's prompt and analysis has begun. Rejects with a `NotAllowedError`
+     * `DOMException` if the user declines, `NotSupportedError` if unavailable, and `AbortError` if cancelled first.
+     */
+    readonly ready: Promise<void>;
+    /** Stops analysis immediately; safe to call repeatedly. */
+    stop(): void;
+}
+/** Host-managed system-audio analysis, available with `system-audio-v1`. */
+export interface SpindleSystemAudioAPI {
+    /** Free. Never prompts, and never opens anything. */
+    isAvailable(): SpindleSystemAudioAvailability;
+    /**
+     * Requires `system_audio`. Call directly from a user gesture. The host asks the user for approval on every
+     * start and shows an indicator for as long as analysis runs. One session per extension at a time.
+     */
+    start(options: SpindleSystemAudioStartOptions): SpindleSystemAudioSession;
+}
+export declare const SPINDLE_SYSTEM_AUDIO_HOST_CAPABILITIES: Readonly<{
+    'system-audio-v1': 1;
+}>;

package/dist/system-audio.js

@@ -0,0 +1,8 @@
+/**
+ * Host-managed analysis of the audio the device is playing, for frontend Spindle extensions.
+ *
+ * Extensions receive a spectrum and levels only (the same shape as `SpindleSTTAudioFrame`): never samples, a
+ * `MediaStream`, or anything else from which what was played could be reconstructed. Available only where the host
+ * has a native adapter (the desktop client); feature-detect `system-audio-v1` and call `isAvailable()`.
+ */
+export const SPINDLE_SYSTEM_AUDIO_HOST_CAPABILITIES = Object.freeze({ 'system-audio-v1': 1 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.6.42",
+  "version": "0.6.44",
   "type": "module",
   "types": "./dist/index.d.ts",
   "keywords": [