@hmcs/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,2612 @@
+import { EventSource } from 'eventsource';
+
+/**
+ * Mathematical types and interfaces for 3D graphics and spatial calculations.
+ *
+ * This module provides type definitions for common mathematical concepts used
+ * throughout the Desktop Homunculus SDK, including transforms, vectors, and
+ * domain-specific request/response types.
+ * These types are designed to be compatible with Bevy's math system.
+ *
+ * @example
+ * ```typescript
+ * // Working with transforms
+ * const transform: TransformArgs = {
+ *   translation: [0, 100, 0],
+ *   rotation: [0, 0, 0, 1],
+ *   scale: [1, 1, 1]
+ * };
+ *
+ * // Working with vectors
+ * const position: Vec3 = [10, 20, 30];
+ * const screenPos: Vec2 = [1920, 1080];
+ * ```
+ */
+/**
+ * Represents a 3D transformation containing position, rotation, and scale.
+ *
+ * This is the core type for positioning objects in 3D space. All spatial
+ * operations in Desktop Homunculus use this transform representation,
+ * which is compatible with Bevy's Transform component.
+ *
+ * @example
+ * ```typescript
+ * const identity: Transform = {
+ *   translation: [0, 0, 0],
+ *   rotation: [0, 0, 0, 1],
+ *   scale: [1, 1, 1]
+ * };
+ * ```
+ */
+interface Transform {
+    /**
+     * The position of the entity in world space.
+     * Format: [x, y, z] where Y is typically up in Bevy's coordinate system.
+     */
+    translation: [number, number, number];
+    /**
+     * The rotation of the entity in world space, represented as a quaternion.
+     * Format: [x, y, z, w] where [0, 0, 0, 1] represents no rotation (identity).
+     */
+    rotation: [number, number, number, number];
+    /**
+     * The scale of the entity in world space.
+     * Format: [x, y, z] where [1, 1, 1] represents normal size.
+     */
+    scale: [number, number, number];
+}
+/**
+ * Represents a 2D vector as [x, y].
+ * Used for screen coordinates, UI positions, and 2D math operations.
+ * Compatible with Bevy's Vec2 serialization format.
+ */
+type Vec2 = [number, number];
+/**
+ * Represents a 3D vector as [x, y, z].
+ * Used for 3D positions, directions, and mathematical calculations.
+ * Compatible with Bevy's Vec3 serialization format.
+ */
+type Vec3 = [number, number, number];
+/**
+ * Represents a quaternion rotation as [x, y, z, w].
+ * Compatible with Bevy's Quat serialization format.
+ */
+type Quat = [number, number, number, number];
+/** Transform arguments for API requests. Partial version of Transform. */
+interface TransformArgs {
+    translation?: Vec3;
+    rotation?: Quat;
+    scale?: Vec3;
+}
+/** A 2D rectangle defined by minimum and maximum points. */
+interface Rect {
+    min: Vec2;
+    max: Vec2;
+}
+
+/**
+ * Coordinates API namespace provides coordinate system transformation utilities.
+ *
+ * Provides utilities for converting between different coordinate spaces used in the
+ * Desktop Homunculus 3D environment. This is essential for positioning UI elements,
+ * placing effects, and converting between screen coordinates and 3D world positions.
+ *
+ * Coordinate systems:
+ * - **Global Viewport**: Screen-space coordinates relative to the entire desktop
+ * - **World 2D**: 2D coordinates within the 3D world space
+ * - **World 3D**: Full 3D coordinates in world space
+ *
+ * @example
+ * ```typescript
+ * // Convert mouse position to 3D world coordinates
+ * const worldPos2D = await coordinates.toWorld({ x: 150, y: 200 });
+ *
+ * // Convert 3D object position to screen coordinates
+ * const screenPos = await coordinates.toViewport({ x: 0, y: 1.5, z: 0 });
+ * ```
+ */
+declare namespace coordinates {
+    /** 2D world coordinates within the 3D scene. */
+    type World2d = Vec2;
+    /** Full 3D world coordinates with x, y, and z components. */
+    type World3d = Vec3;
+    /**
+     * Converts global viewport coordinates to 2D world space coordinates.
+     *
+     * This transformation maps screen-space coordinates (like mouse positions or
+     * UI element positions) into the 2D coordinate system of the 3D world.
+     *
+     * @param viewport - Screen coordinates to convert (uses center if not provided)
+     * @returns A promise that resolves to the corresponding 2D world coordinates
+     *
+     * @example
+     * ```typescript
+     * const worldPos = await coordinates.toWorld({ x: 150, y: 200 });
+     * ```
+     */
+    function toWorld(viewport?: {
+        x?: number;
+        y?: number;
+    }): Promise<Vec2>;
+    /**
+     * Converts 3D world coordinates to global viewport (screen) coordinates.
+     *
+     * This transformation projects 3D positions in the world onto screen space,
+     * allowing you to position UI elements, effects, or webviews relative to
+     * 3D objects like VRM characters or scene elements.
+     *
+     * @param world - 3D world coordinates to convert (uses origin if not provided)
+     * @returns A promise that resolves to the corresponding screen coordinates
+     *
+     * @example
+     * ```typescript
+     * const screenPos = await coordinates.toViewport({ x: 0, y: 1.5, z: 0 });
+     * ```
+     */
+    function toViewport(world?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    }): Promise<GlobalViewport>;
+}
+/** Information about a connected display/monitor. */
+interface GlobalDisplay {
+    /** Unique display identifier. */
+    id: number;
+    /** Human-readable display name. */
+    title: string;
+    /** Display frame rectangle in screen coordinates. */
+    frame: Rect;
+}
+/** Global viewport coordinates (screen-space position) as [x, y]. */
+type GlobalViewport = [number, number];
+
+/**
+ * Displays API namespace for monitor and screen management.
+ *
+ * Provides functionality to query information about connected displays/monitors,
+ * including their dimensions, positions, and frame rectangles.
+ *
+ * @example
+ * ```typescript
+ * const allDisplays = await displays.findAll();
+ * console.log(`Found ${allDisplays.length} displays`);
+ * allDisplays.forEach((display) => {
+ *   console.log(`${display.title}: (${display.frame.min.x}, ${display.frame.min.y}) - (${display.frame.max.x}, ${display.frame.max.y})`);
+ * });
+ * ```
+ */
+declare namespace displays {
+    /**
+     * Retrieves information about all currently connected displays/monitors.
+     *
+     * @returns A promise that resolves to an array of display information
+     *
+     * @example
+     * ```typescript
+     * const allDisplays = await displays.findAll();
+     * console.log(`System has ${allDisplays.length} displays`);
+     * ```
+     */
+    function findAll(): Promise<GlobalDisplay[]>;
+}
+
+/**
+ * Audio API namespace for playing sound effects and background music.
+ *
+ * Provides functionality for one-shot sound effects ({@link audio.se}) and
+ * looping background music with transport controls ({@link audio.bgm}).
+ *
+ * @example
+ * ```typescript
+ * // Play a sound effect
+ * await audio.se.play("click");
+ *
+ * // Play background music with fade-in
+ * await audio.bgm.play("heme", {
+ *   volume: 0.8,
+ *   fadeIn: { durationSecs: 2.0 }
+ * });
+ *
+ * // Stop BGM with fade-out
+ * await audio.bgm.stop({ fadeOut: { durationSecs: 1.5 } });
+ * ```
+ */
+declare namespace audio {
+    /**
+     * Configuration options for sound effect playback.
+     */
+    interface SeOptions {
+        /** Volume level (0.0-1.0). Default: 1.0 */
+        volume?: number;
+        /** Playback speed. Default: 1.0 */
+        speed?: number;
+        /** Stereo panning (-1.0 left to 1.0 right). Default: 0.0 */
+        panning?: number;
+    }
+    /**
+     * Tween configuration for fade transitions.
+     */
+    interface FadeTween {
+        /** Duration in seconds */
+        durationSecs: number;
+        /** Easing function. Default: "linear" */
+        easing?: "linear" | "easeIn" | "easeOut" | "easeInOut";
+    }
+    /**
+     * Configuration options for starting BGM playback.
+     */
+    interface BgmPlayOptions {
+        /** Loop playback. Default: true */
+        loop?: boolean;
+        /** Volume level (0.0-1.0). Default: 1.0 */
+        volume?: number;
+        /** Playback speed. Default: 1.0 */
+        speed?: number;
+        /** Fade-in settings */
+        fadeIn?: FadeTween;
+    }
+    /**
+     * Configuration options for stopping BGM playback.
+     */
+    interface BgmStopOptions {
+        /** Fade-out settings. Omit for immediate stop */
+        fadeOut?: FadeTween;
+    }
+    /**
+     * Configuration options for updating BGM playback parameters.
+     */
+    interface BgmUpdateOptions {
+        /** New volume level */
+        volume?: number;
+        /** New playback speed */
+        speed?: number;
+        /** Transition settings */
+        tween?: FadeTween;
+    }
+    /**
+     * Current BGM playback status.
+     */
+    interface BgmStatus {
+        /** Current asset ID (null if stopped) */
+        asset: string | null;
+        /** Playback state */
+        state: "playing" | "paused" | "stopped";
+        /** Loop setting */
+        loop: boolean;
+        /** Current volume */
+        volume: number;
+        /** Current speed */
+        speed: number;
+    }
+    /**
+     * Sound effects (SE) sub-namespace for one-shot audio playback.
+     *
+     * @example
+     * ```typescript
+     * // Simple sound effect
+     * await audio.se.play("my-mod:notification");
+     *
+     * // With options
+     * await audio.se.play("my-mod:alert", {
+     *   volume: 0.5,
+     *   speed: 1.2,
+     *   panning: -0.5
+     * });
+     * ```
+     */
+    namespace se {
+        /**
+         * Plays a one-shot sound effect.
+         *
+         * @param asset - The asset ID of the sound effect (e.g., `"click"`)
+         * @param options - Optional playback configuration
+         *
+         * @example
+         * ```typescript
+         * await audio.se.play("click");
+         *
+         * await audio.se.play("coin", {
+         *   volume: 0.7,
+         *   speed: 1.5,
+         *   panning: 0.3
+         * });
+         * ```
+         */
+        function play(asset: string, options?: SeOptions): Promise<void>;
+    }
+    /**
+     * Background music (BGM) sub-namespace for continuous audio playback with transport controls.
+     *
+     * Only one BGM track plays at a time. Starting a new track replaces the current one.
+     *
+     * @example
+     * ```typescript
+     * // Play looping background music
+     * await audio.bgm.play("theme");
+     *
+     * // Pause and resume
+     * await audio.bgm.pause();
+     * await audio.bgm.resume();
+     *
+     * // Check current status
+     * const status = await audio.bgm.status();
+     * console.log(status.state); // "playing" | "paused" | "stopped"
+     * ```
+     */
+    namespace bgm {
+        /**
+         * Plays background music, replacing any currently playing BGM.
+         *
+         * @param asset - The asset ID of the music track (e.g., `"theme"`)
+         * @param options - Optional playback configuration
+         *
+         * @example
+         * ```typescript
+         * // Simple playback (loops by default)
+         * await audio.bgm.play("my-mod:battle");
+         *
+         * // With options
+         * await audio.bgm.play("my-mod:intro", {
+         *   loop: false,
+         *   volume: 0.6,
+         *   fadeIn: { durationSecs: 3.0, easing: "easeIn" }
+         * });
+         * ```
+         */
+        function play(asset: string, options?: BgmPlayOptions): Promise<void>;
+        /**
+         * Stops the currently playing BGM.
+         *
+         * @param options - Optional stop configuration (e.g., fade-out)
+         *
+         * @example
+         * ```typescript
+         * // Immediate stop
+         * await audio.bgm.stop();
+         *
+         * // Fade out over 2 seconds
+         * await audio.bgm.stop({
+         *   fadeOut: { durationSecs: 2.0, easing: "easeOut" }
+         * });
+         * ```
+         */
+        function stop(options?: BgmStopOptions): Promise<void>;
+        /**
+         * Pauses the currently playing BGM.
+         *
+         * @example
+         * ```typescript
+         * await audio.bgm.pause();
+         * ```
+         */
+        function pause(): Promise<void>;
+        /**
+         * Resumes paused BGM playback.
+         *
+         * @example
+         * ```typescript
+         * await audio.bgm.resume();
+         * ```
+         */
+        function resume(): Promise<void>;
+        /**
+         * Updates playback parameters of the currently playing BGM.
+         *
+         * @param options - The parameters to update
+         *
+         * @example
+         * ```typescript
+         * // Fade volume to 0.3 over 1 second
+         * await audio.bgm.update({
+         *   volume: 0.3,
+         *   tween: { durationSecs: 1.0, easing: "easeInOut" }
+         * });
+         *
+         * // Change speed immediately
+         * await audio.bgm.update({ speed: 0.8 });
+         * ```
+         */
+        function update(options: BgmUpdateOptions): Promise<void>;
+        /**
+         * Gets the current BGM playback status.
+         *
+         * @returns The current BGM status including asset, state, volume, and speed
+         *
+         * @example
+         * ```typescript
+         * const status = await audio.bgm.status();
+         * if (status.state === "playing") {
+         *   console.log(`Now playing: ${status.asset} at volume ${status.volume}`);
+         * }
+         * ```
+         */
+        function status(): Promise<BgmStatus>;
+    }
+}
+
+/** Request body for creating a stamp effect. */
+interface StampRequestBody {
+    asset: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    alpha?: number;
+    duration?: number;
+}
+/**
+ * Effects API namespace for visual effects.
+ *
+ * Provides functionality to trigger visual stamp effects that enhance the user experience.
+ *
+ * For audio playback, see the {@link audio} namespace.
+ *
+ * @example
+ * ```typescript
+ * // Show a stamp effect
+ * await effects.stamp("heart-reaction", {
+ *   width: 100,
+ *   height: 100,
+ *   duration: 2.0
+ * });
+ * ```
+ */
+declare namespace effects {
+    /**
+     * Configuration options for stamp visual effects.
+     */
+    interface StampOptions {
+        /** X position on screen. */
+        x?: number;
+        /** Y position on screen. */
+        y?: number;
+        /** Width in pixels. */
+        width?: number;
+        /** Height in pixels. */
+        height?: number;
+        /** Opacity (0-1). */
+        alpha?: number;
+        /** Duration in seconds. */
+        duration?: number;
+    }
+    /**
+     * Displays a visual stamp effect on the screen.
+     *
+     * @param asset - The asset ID of the stamp image.
+     * @param options - Optional configuration for the stamp appearance
+     *
+     * @example
+     * ```typescript
+     * await effects.stamp("thumbs-up");
+     *
+     * await effects.stamp("heart", {
+     *   x: 100,
+     *   y: 200,
+     *   width: 80,
+     *   height: 80,
+     *   duration: 1.5
+     * });
+     * ```
+     */
+    function stamp(asset: string, options?: StampOptions): Promise<void>;
+}
+
+/**
+ * Host API namespace for low-level HTTP communication with the Desktop Homunculus server.
+ *
+ * This module provides the foundational HTTP client functionality used internally
+ * by all other SDK modules. It handles the base URL configuration, URL construction,
+ * and HTTP methods with automatic error handling.
+ *
+ * **Note:** This module is primarily for internal SDK use. Most developers should
+ * use the higher-level namespaces like `vrm`, `signals`, etc.
+ *
+ * @example
+ * ```typescript
+ * // Internal SDK usage (you typically won't need this directly)
+ * const response = await host.get(host.createUrl("vrm"));
+ * const vrms = await response.json();
+ *
+ * // URL construction with parameters
+ * const url = host.createUrl("vrm", { name: "MyCharacter" });
+ * // Results in: http://localhost:3100/vrm?name=MyCharacter
+ *
+ * // Configure the base URL (e.g., from an MCP server)
+ * host.configure({ baseUrl: "http://localhost:4000" });
+ * ```
+ */
+/** Error thrown when the Homunculus HTTP API returns a non-OK response. */
+declare class HomunculusApiError extends Error {
+    /** HTTP status code (e.g. 404, 500) */
+    readonly statusCode: number;
+    /** The request endpoint URL */
+    readonly endpoint: string;
+    /** The response body text */
+    readonly body: string;
+    constructor(statusCode: number, endpoint: string, body: string);
+}
+/** Error thrown when an NDJSON stream contains malformed data. */
+declare class HomunculusStreamError extends Error {
+    /** The raw line that failed to parse */
+    readonly rawLine: string;
+    constructor(rawLine: string, cause?: unknown);
+}
+declare namespace host {
+    /**
+     * Configures the SDK's base URL for the Desktop Homunculus HTTP server.
+     *
+     * @param options - Configuration options
+     *
+     * @example
+     * ```typescript
+     * host.configure({ baseUrl: "http://localhost:4000" });
+     * ```
+     */
+    function configure(options: {
+        baseUrl: string;
+    }): void;
+    /** Returns the base URL for the Desktop Homunculus HTTP server. */
+    function base(): string;
+    /** Creates a new URL instance pointing to the base server. */
+    function baseUrl(): URL;
+    /**
+     * Creates a URL for the Desktop Homunculus API with optional query parameters.
+     *
+     * @param path - The API endpoint path (relative to base URL)
+     * @param params - Optional query parameters to append to the URL
+     * @returns A URL instance ready for use in HTTP requests
+     *
+     * @example
+     * ```typescript
+     * // Simple path
+     * const url = host.createUrl("vrm");
+     * // Result: http://localhost:3100/vrm
+     *
+     * // With query parameters
+     * const url = host.createUrl("entities", { name: "VRM", root: 123 });
+     * // Result: http://localhost:3100/entities?name=VRM&root=123
+     * ```
+     */
+    function createUrl(path: string, params?: object): URL;
+    /**
+     * Performs a GET request to the specified URL with automatic error handling.
+     *
+     * @param url - The URL to send the GET request to
+     * @returns The Response object if successful
+     * @throws {HomunculusApiError} If the response status is >= 400
+     *
+     * @example
+     * ```typescript
+     * const response = await host.get(host.createUrl("vrm"));
+     * const data = await response.json();
+     * ```
+     */
+    function get(url: URL): Promise<Response>;
+    /**
+     * Performs a POST request with JSON payload and automatic error handling.
+     *
+     * @param url - The URL to send the POST request to
+     * @param body - Optional request body that will be JSON-serialized
+     * @returns The Response object if successful
+     * @throws {HomunculusApiError} If the response status is >= 400
+     *
+     * @example
+     * ```typescript
+     * const response = await host.post(
+     *   host.createUrl("vrm"),
+     *   { asset: "my-mod::character.vrm" }
+     * );
+     * ```
+     */
+    function post<B>(url: URL, body?: B): Promise<Response>;
+    /**
+     * Performs a PUT request with JSON payload and automatic error handling.
+     *
+     * @param url - The URL to send the PUT request to
+     * @param body - Optional request body that will be JSON-serialized
+     * @returns The Response object if successful
+     * @throws {HomunculusApiError} If the response status is >= 400
+     *
+     * @example
+     * ```typescript
+     * await host.put(
+     *   host.createUrl("vrm/123/state"),
+     *   { state: "idle" }
+     * );
+     * ```
+     */
+    function put<B>(url: URL, body?: B): Promise<Response>;
+    /**
+     * Performs a PATCH request with JSON payload and automatic error handling.
+     *
+     * @param url - The URL to send the PATCH request to
+     * @param body - Optional request body that will be JSON-serialized
+     * @returns The Response object if successful
+     * @throws {HomunculusApiError} If the response status is >= 400
+     */
+    function patch<B>(url: URL, body?: B): Promise<Response>;
+    function deleteMethod(url: URL): Promise<Response>;
+    /**
+     * Performs a POST request and returns an async generator that yields
+     * parsed NDJSON objects from the streaming response.
+     *
+     * @param url - The URL to send the POST request to
+     * @param body - Optional request body that will be JSON-serialized
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns An async generator yielding parsed JSON objects of type T
+     * @throws {HomunculusApiError} If the response status is >= 400
+     * @throws {HomunculusStreamError} If an NDJSON line cannot be parsed
+     *
+     * @example
+     * ```typescript
+     * const stream = host.postStream<MyEvent>(
+     *   host.createUrl("mods/my-mod/commands/execute"),
+     *   { command: "build" }
+     * );
+     * for await (const event of stream) {
+     *   console.log(event);
+     * }
+     * ```
+     */
+    function postStream<T>(url: URL, body?: unknown, signal?: AbortSignal): AsyncGenerator<T>;
+}
+
+/**
+ * Preferences API namespace for persistent data storage and user settings.
+ *
+ * Provides a key-value store for saving and loading application data that persists
+ * across sessions.
+ *
+ * @example
+ * ```typescript
+ * await preferences.save('user-settings', { theme: 'dark', volume: 0.8 });
+ * const settings = await preferences.load<{ theme: string; volume: number }>('user-settings');
+ * ```
+ */
+declare namespace preferences {
+    /**
+     * List all saved preference keys.
+     *
+     * Returns an array of key names that have been stored.
+     * Use {@link preferences.load} to retrieve the value for a specific key.
+     *
+     * @returns Array of preference key names
+     *
+     * @example
+     * ```typescript
+     * const keys = await preferences.list();
+     * console.log(`${keys.length} preferences stored`);
+     *
+     * // Load all preferences
+     * for (const key of keys) {
+     *   const value = await preferences.load(key);
+     *   console.log(`${key}:`, value);
+     * }
+     * ```
+     */
+    function list(): Promise<string[]>;
+    /**
+     * Loads a value from the preference store with type safety.
+     *
+     * Returns `undefined` if the key does not exist.
+     *
+     * @template V - The expected type of the stored value
+     * @param key - The unique identifier for the stored data
+     * @returns A promise that resolves to the deserialized value, or `undefined` if the key does not exist
+     *
+     * @example
+     * ```typescript
+     * const username = await preferences.load<string>('username');
+     * if (username !== null) {
+     *   console.log(`Hello, ${username}`);
+     * }
+     * ```
+     */
+    function load<V>(key: string): Promise<V | undefined>;
+    /**
+     * Saves a value to the preference store with automatic serialization.
+     *
+     * @template V - The type of the value being saved
+     * @param key - The unique identifier for storing the data
+     * @param value - The data to save (must be JSON-serializable)
+     *
+     * @example
+     * ```typescript
+     * await preferences.save('username', 'Alice');
+     * ```
+     */
+    function save<V>(key: string, value: V): Promise<void>;
+}
+
+/** Request body for setting frame rate. */
+interface SetFpsBody {
+    fps: number;
+}
+/**
+ * Settings API namespace for controlling application-level configuration.
+ *
+ * @example
+ * ```typescript
+ * const currentFps = await settings.fps();
+ * await settings.setFps(30);
+ * ```
+ */
+declare namespace settings {
+    /**
+     * Gets the current frame rate (FPS).
+     *
+     * @returns A promise that resolves to the current FPS value
+     *
+     * @example
+     * ```typescript
+     * const fps = await settings.fps();
+     * console.log(`Current FPS: ${fps}`);
+     * ```
+     */
+    function fps(): Promise<number>;
+    /**
+     * Sets the frame rate (FPS). Persists and applies immediately.
+     *
+     * @param fps - The target frame rate in frames per second (1-120)
+     *
+     * @example
+     * ```typescript
+     * await settings.setFps(30);
+     * ```
+     */
+    function setFps(fps: number): Promise<void>;
+}
+
+/** Request body for setting shadow panel alpha. */
+interface ShadowPanelPutBody {
+    alpha: number;
+}
+/**
+ * Shadow Panel API namespace for controlling the application's shadow overlay.
+ *
+ * The shadow panel is a visual overlay that can be used to create atmospheric
+ * effects, focus attention, or provide visual feedback.
+ *
+ * @example
+ * ```typescript
+ * await shadowPanel.setAlpha(0.7);
+ * const currentAlpha = await shadowPanel.alpha();
+ * await shadowPanel.setAlpha(0);
+ * ```
+ */
+declare namespace shadowPanel {
+    /**
+     * Gets the current transparency level of the shadow panel.
+     *
+     * @returns A promise that resolves to the current alpha value (0-1)
+     */
+    function alpha(): Promise<number>;
+    /**
+     * Sets the transparency level of the shadow panel.
+     *
+     * @param alpha - The transparency value between 0 (invisible) and 1 (opaque)
+     *
+     * @example
+     * ```typescript
+     * await shadowPanel.setAlpha(0.7);
+     * ```
+     */
+    function setAlpha(alpha: number): Promise<void>;
+}
+
+/**
+ * Big Five personality traits (OCEAN model).
+ *
+ * @example
+ * ```typescript
+ * const ocean: Ocean = {
+ *   openness: 0.8,
+ *   conscientiousness: 0.6,
+ *   extraversion: 0.7,
+ * };
+ * ```
+ */
+interface Ocean {
+    /** Openness (0.0=conservative, 1.0=curious) */
+    openness?: number;
+    /** Conscientiousness (0.0=spontaneous, 1.0=organized) */
+    conscientiousness?: number;
+    /** Extraversion (0.0=introverted, 1.0=extroverted) */
+    extraversion?: number;
+    /** Agreeableness (0.0=independent, 1.0=cooperative) */
+    agreeableness?: number;
+    /** Neuroticism (0.0=stable, 1.0=sensitive) */
+    neuroticism?: number;
+}
+/**
+ * Persona data for a VRM character.
+ *
+ * @example
+ * ```typescript
+ * const persona: Persona = {
+ *   profile: "A cheerful virtual assistant",
+ *   personality: "Friendly and helpful",
+ *   ocean: { openness: 0.8, extraversion: 0.7 },
+ *   metadata: {},
+ * };
+ * ```
+ */
+interface Persona {
+    /** Character profile/background description. */
+    profile: string;
+    /** Personality description in natural language. */
+    personality?: string | null;
+    /** Big Five personality parameters. */
+    ocean: Ocean;
+    /** Extension metadata for MODs. */
+    metadata: Record<string, unknown>;
+}
+/** Response for VRM state queries. */
+interface VrmStateResponse {
+    state: string;
+}
+/** Request body for setting VRM state. */
+interface VrmStateRequest {
+    state: string;
+}
+/** Override type for expression override settings. */
+type OverrideType = "none" | "blend" | "block";
+/**
+ * Information about a single VRM expression.
+ *
+ * @example
+ * ```typescript
+ * const vrm = await Vrm.findByName("MyAvatar");
+ * const { expressions } = await vrm.expressions();
+ * for (const expr of expressions) {
+ *   console.log(`${expr.name}: weight=${expr.weight}, binary=${expr.isBinary}`);
+ * }
+ * ```
+ */
+interface ExpressionInfo {
+    /** Expression name (e.g. "happy", "aa", "blink"). */
+    name: string;
+    /** Current weight value (0.0-1.0). */
+    weight: number;
+    /** Whether this expression is binary (snaps to 0 or 1). */
+    isBinary: boolean;
+    /** Override type for blink expressions. */
+    overrideBlink: OverrideType;
+    /** Override type for lookAt expressions. */
+    overrideLookAt: OverrideType;
+    /** Override type for mouth expressions. */
+    overrideMouth: OverrideType;
+}
+/** Response for VRM expression queries. */
+interface ExpressionsResponse {
+    expressions: ExpressionInfo[];
+}
+/** Arguments for moving a VRM to a viewport position. */
+interface MoveToArgs {
+    globalViewport: GlobalViewport;
+}
+/** Spring bone physics properties. */
+interface SpringBoneProps {
+    stiffness: number;
+    dragForce: number;
+    gravityPower: number;
+    gravityDir: [number, number, number];
+    hitRadius: number;
+}
+/** A single spring bone chain. */
+interface SpringBoneChain {
+    entity: number;
+    joints: string[];
+    props: SpringBoneProps;
+}
+/** Response for spring bone chains query. */
+interface SpringBoneChainsResponse {
+    chains: SpringBoneChain[];
+}
+/** Repeat settings for VRMA playback. */
+interface VrmaRepeat {
+    type: "forever" | "never" | "count";
+    count?: number;
+}
+/**
+ * Helper functions for building {@link VrmaRepeat} values.
+ *
+ * @example
+ * ```typescript
+ * await vrm.playVrma({
+ *   asset: "vrma:idle-maid",
+ *   repeat: repeat.forever(),
+ * });
+ *
+ * await vrm.playVrma({
+ *   asset: "vrma:grabbed",
+ *   repeat: repeat.count(3),
+ * });
+ * ```
+ */
+declare namespace repeat {
+    /**
+     * Repeat the animation forever.
+     */
+    function forever(): VrmaRepeat;
+    /**
+     * Play the animation once (no repeat).
+     */
+    function never(): VrmaRepeat;
+    /**
+     * Repeat the animation a fixed number of times.
+     *
+     * @param n Positive integer repeat count.
+     * @throws {RangeError} If `n` is not a positive integer.
+     */
+    function count(n: number): VrmaRepeat;
+}
+/** Request body for playing a VRMA animation. */
+interface VrmaPlayRequest {
+    asset: string;
+    transitionSecs?: number;
+    repeat?: VrmaRepeat;
+    waitForCompletion?: boolean;
+    /** If true, resets SpringBone velocities to prevent bouncing during animation transitions. */
+    resetSpringBones?: boolean;
+}
+/** State of a VRMA animation. */
+interface VrmaState {
+    playing: boolean;
+    repeat: string;
+    speed: number;
+    elapsedSecs: number;
+}
+/** Info about a VRMA animation entity. */
+interface VrmaInfo {
+    entity: number;
+    name: string;
+    playing: boolean;
+}
+/** Current look-at state of a VRM. */
+type LookAtState = {
+    type: "cursor";
+} | {
+    type: "target";
+    entity: number;
+};
+/**
+ * Snapshot of a VRM instance with full runtime state.
+ *
+ * @example
+ * ```typescript
+ * const snapshots = await Vrm.findAllDetailed();
+ * for (const s of snapshots) {
+ *   console.log(`${s.name}: ${s.state} at (${s.globalViewport?.[0]}, ${s.globalViewport?.[1]})`);
+ * }
+ * ```
+ */
+interface VrmSnapshot {
+    entity: number;
+    name: string;
+    state: string;
+    transform: Transform;
+    globalViewport: GlobalViewport | null;
+    expressions: ExpressionsResponse;
+    animations: VrmaInfo[];
+    lookAt: LookAtState | null;
+    linkedWebviews: number[];
+    persona: Persona;
+}
+/**
+ * Response from the VRM position endpoint.
+ *
+ * @example
+ * ```ts
+ * const vrm = await Vrm.findByName("MyCharacter");
+ * const pos = await vrm.position();
+ * console.log(`Screen: (${pos.globalViewport?.[0]}, ${pos.globalViewport?.[1]})`);
+ * console.log(`World: (${pos.world[0]}, ${pos.world[1]}, ${pos.world[2]})`);
+ * ```
+ */
+interface PositionResponse {
+    /** Global screen coordinates (multi-monitor origin at leftmost screen). Null if not visible. */
+    globalViewport: GlobalViewport | null;
+    /** Bevy world coordinates. */
+    world: Vec3;
+}
+/** Request body for setting VRMA playback speed. */
+interface VrmaSpeedBody {
+    asset: string;
+    speed: number;
+}
+interface SpawnVrmOptions {
+    transform?: TransformArgs;
+    persona?: Persona;
+}
+/**
+ * A single keyframe in a speech timeline.
+ */
+interface TimelineKeyframe {
+    /**
+     * Duration of this keyframe in seconds.
+     */
+    duration: number;
+    /**
+     * Expression targets to set during this keyframe.
+     * Keys are expression names (e.g. "aa", "ih", "happy"), values are weights (0.0-1.0).
+     */
+    targets?: Record<string, number>;
+}
+/**
+ * Options for the timeline speech API.
+ */
+interface SpeakTimelineOptions {
+    /**
+     * If true, the method will wait for the speech to complete.
+     * Defaults to true.
+     */
+    waitForCompletion?: boolean;
+    /**
+     * Duration in seconds for smoothstep blending between adjacent keyframes.
+     * Defaults to 0.05 (50ms). Clamped to 40% of each keyframe's duration.
+     */
+    transitionDuration?: number;
+}
+interface VrmPointerEvent {
+    /**
+     * The cursor position in the global viewport.
+     */
+    globalViewport: [number, number];
+}
+interface VrmDragEvent extends VrmPointerEvent {
+    /**
+     * The change in cursor position since the last event.
+     */
+    delta: [number, number];
+}
+type Button = "Primary" | "Secondary" | "Middle";
+interface VrmMouseEvent extends VrmPointerEvent {
+    /**
+     * The button that was pressed or released.
+     */
+    button: Button;
+}
+interface VrmStateChangeEvent {
+    /**
+     * The new state of the VRM.
+     */
+    state: string;
+}
+interface PersonaChangeEvent {
+    /**
+     * The updated persona.
+     */
+    persona: Persona;
+}
+type EventMap = {
+    "drag-start": VrmPointerEvent;
+    "drag": VrmDragEvent;
+    "drag-end": VrmPointerEvent;
+    "pointer-press": VrmMouseEvent;
+    "pointer-click": VrmMouseEvent;
+    "pointer-release": VrmMouseEvent;
+    "pointer-over": VrmPointerEvent;
+    "pointer-out": VrmPointerEvent;
+    "pointer-cancel": VrmPointerEvent;
+    "pointer-move": VrmPointerEvent;
+    "state-change": VrmStateChangeEvent;
+    "expression-change": VrmStateChangeEvent;
+    "vrma-play": VrmStateChangeEvent;
+    "vrma-finish": VrmStateChangeEvent;
+    "persona-change": PersonaChangeEvent;
+};
+interface VrmMetadata {
+    name: string;
+    entity: number;
+}
+type Bones = "hips" | "spine" | "chest" | "neck" | "head" | "leftShoulder" | "leftArm" | "leftForeArm" | "leftHand" | "rightShoulder" | "rightArm" | "rightForeArm" | "rightHand" | "leftUpLeg" | "leftLeg" | "leftFoot" | "rightUpLeg" | "rightLeg" | "rightFoot";
+declare class VrmEventSource implements Disposable {
+    readonly eventSource: EventSource;
+    constructor(eventSource: EventSource);
+    /**
+     * Registers an event listener for the specified event type.
+     */
+    on<K extends keyof EventMap>(event: K, callback: (event: EventMap[K]) => (void | Promise<void>)): void;
+    /**
+     * Closes the EventSource connection.
+     */
+    close(): void;
+    [Symbol.dispose](): void;
+}
+declare class Vrm {
+    readonly entity: number;
+    constructor(entity: number);
+    /**
+     * Returns an EventSource for receiving events related to this VRM entity.
+     */
+    events(): VrmEventSource;
+    /**
+     * Returns the current state of the VRM.
+     */
+    state(): Promise<string>;
+    /**
+     * Sets the state of the VRM.
+     *
+     * @param state The new state to set.
+     */
+    setState(state: string): Promise<void>;
+    /**
+     * Returns the persona of the VRM.
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * const persona = await vrm.persona();
+     * console.log(persona.profile);
+     * ```
+     */
+    persona(): Promise<Persona>;
+    /**
+     * Sets the persona of the VRM.
+     *
+     * @param persona The persona data to set.
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * await vrm.setPersona({
+     *   profile: "A cheerful assistant",
+     *   ocean: { openness: 0.8, extraversion: 0.7 },
+     *   metadata: {},
+     * });
+     * ```
+     */
+    setPersona(persona: Persona): Promise<void>;
+    /**
+     * Returns the name of the VRM avatar.
+     */
+    name(): Promise<string>;
+    /**
+     * Finds the entity ID of a bone by its name.
+     */
+    findBoneEntity(bone: Bones): Promise<number>;
+    /**
+     * Despawns this VRM entity.
+     */
+    despawn(): Promise<void>;
+    /**
+     * Gets the current position of this VRM in both screen and world coordinates.
+     *
+     * @example
+     * ```ts
+     * const vrm = await Vrm.findByName("MyCharacter");
+     * const pos = await vrm.position();
+     * console.log(`Screen: (${pos.globalViewport?.[0]}, ${pos.globalViewport?.[1]})`);
+     * console.log(`World: (${pos.world[0]}, ${pos.world[1]}, ${pos.world[2]})`);
+     * ```
+     */
+    position(): Promise<PositionResponse>;
+    /**
+     * Gets all expressions and their current weights, including metadata
+     * such as binary status and override settings.
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * const { expressions } = await vrm.expressions();
+     * for (const expr of expressions) {
+     *   console.log(`${expr.name}: ${expr.weight}`);
+     * }
+     * ```
+     */
+    expressions(): Promise<ExpressionsResponse>;
+    /**
+     * Sets expression weights, replacing all previous overrides.
+     * Expressions not included will return to VRMA animation control.
+     *
+     * @param weights A record of expression names to weight values (0.0-1.0).
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * await vrm.setExpressions({ happy: 1.0, blink: 0.5 });
+     * ```
+     */
+    setExpressions(weights: Record<string, number>): Promise<void>;
+    /**
+     * Modifies specific expression weights without affecting others (partial update).
+     * Existing overrides not mentioned remain unchanged.
+     *
+     * @param weights A record of expression names to weight values (0.0-1.0).
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * // Only modifies "happy", leaves other overrides intact
+     * await vrm.modifyExpressions({ happy: 1.0 });
+     * ```
+     */
+    modifyExpressions(weights: Record<string, number>): Promise<void>;
+    /**
+     * Clears all expression overrides, returning control to VRMA animation.
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * await vrm.clearExpressions();
+     * ```
+     */
+    clearExpressions(): Promise<void>;
+    /**
+     * Modifies mouth expression weights for lip-sync.
+     * Unspecified mouth expressions are reset to 0.0.
+     * Non-mouth expression overrides are preserved.
+     *
+     * @param weights A record of mouth expression names to weight values (0.0-1.0).
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * await vrm.modifyMouth({ aa: 0.8, oh: 0.2 });
+     * ```
+     */
+    modifyMouth(weights: Record<string, number>): Promise<void>;
+    /**
+     * Gets all spring bone chains.
+     */
+    springBones(): Promise<SpringBoneChainsResponse>;
+    /**
+     * Gets a single spring bone chain by entity ID.
+     *
+     * @param chainId The chain entity ID.
+     */
+    springBone(chainId: number): Promise<SpringBoneChain>;
+    /**
+     * Updates spring bone properties for a chain.
+     *
+     * @param chainId The chain entity ID.
+     * @param props Partial properties to update.
+     */
+    setSpringBone(chainId: number, props: Partial<SpringBoneProps>): Promise<void>;
+    /**
+     * Gets all VRMA animations for this VRM.
+     */
+    listVrma(): Promise<VrmaInfo[]>;
+    /**
+     * Plays a VRMA animation.
+     *
+     * @param options Play request options including asset, repeat, transition.
+     */
+    playVrma(options: VrmaPlayRequest): Promise<void>;
+    /**
+     * Stops a VRMA animation.
+     *
+     * @param asset The asset ID of the VRMA animation to stop.
+     */
+    stopVrma(asset: string): Promise<void>;
+    /**
+     * Gets the state of a VRMA animation.
+     *
+     * @param asset The asset ID of the VRMA animation to query.
+     */
+    vrmaState(asset: string): Promise<VrmaState>;
+    /**
+     * Sets the playback speed of a VRMA animation.
+     *
+     * @param asset The asset ID of the VRMA animation.
+     * @param speed The playback speed.
+     */
+    setVrmaSpeed(asset: string, speed: number): Promise<void>;
+    /**
+     * Speaks using pre-generated audio with a timeline of expression keyframes.
+     * This allows any TTS engine to be used — the engine receives WAV audio and
+     * frame-synchronized lip-sync data.
+     *
+     * @param audio - WAV audio data as ArrayBuffer or Uint8Array.
+     * @param keyframes - Timeline keyframes specifying expression targets and durations.
+     * @param options - Optional settings (e.g. waitForCompletion).
+     *
+     * @example
+     * ```typescript
+     * const vrm = await Vrm.findByName("MyAvatar");
+     * const wavData = await fetchWavFromTTS("Hello world");
+     * await vrm.speakWithTimeline(wavData, [
+     *   { duration: 0.1, targets: { aa: 1.0 } },
+     *   { duration: 0.05 },
+     *   { duration: 0.12, targets: { oh: 1.0, happy: 0.5 } },
+     * ]);
+     * ```
+     */
+    speakWithTimeline(audio: ArrayBuffer | Uint8Array, keyframes: TimelineKeyframe[], options?: SpeakTimelineOptions): Promise<void>;
+    /**
+     * Looks at the mouse cursor.
+     */
+    lookAtCursor(): Promise<void>;
+    /**
+     * Sets the VRM's look-at target to a specific entity.
+     *
+     * @param target The entity ID to look at.
+     */
+    lookAtTarget(target: number): Promise<void>;
+    /**
+     * Disables the VRM's look-at functionality.
+     */
+    unlook(): Promise<void>;
+    /**
+     * Spawns a new VRM instance from the given mod asset ID.
+     */
+    static spawn(asset: string, options?: SpawnVrmOptions): Promise<Vrm>;
+    /**
+     * Finds a VRM instance by its name.
+     *
+     * @param vrmName VRM avatar name
+     */
+    static findByName(vrmName: string): Promise<Vrm>;
+    /**
+     * Waits for a VRM instance to be spawned and initialized by its name.
+     *
+     * @param vrmName VRM avatar name
+     */
+    static waitLoadByName(vrmName: string): Promise<Vrm>;
+    /**
+     * Returns entity IDs of all currently loaded VRM instances.
+     *
+     * @example
+     * ```typescript
+     * const entities = await Vrm.findAllEntities();
+     * console.log(`Found ${entities.length} VRM entities`);
+     * ```
+     */
+    static findAllEntities(): Promise<number[]>;
+    /**
+     * Returns detailed snapshot of all VRM instances.
+     *
+     * @example
+     * ```typescript
+     * const snapshots = await Vrm.findAllDetailed();
+     * for (const s of snapshots) {
+     *   console.log(`${s.name}: ${s.state} at (${s.globalViewport?.[0]}, ${s.globalViewport?.[1]})`);
+     * }
+     * ```
+     */
+    static findAllDetailed(): Promise<VrmSnapshot[]>;
+    static streamMetadata(f: (vrm: VrmMetadata) => (void | Promise<void>)): EventSource;
+    /**
+     * Streams all currently existing VRM instances and any VRM instances that will be created in the future.
+     * @param f
+     */
+    static stream(f: (vrm: Vrm) => (void | Promise<void>)): EventSource;
+    /**
+     * Returns all VRM instances that are currently loaded.
+     */
+    static findAll(): Promise<Vrm[]>;
+    private fetch;
+    private post;
+    private put;
+    private patch;
+    private delete;
+}
+
+/**
+ * Speech utilities for converting phoneme data to Timeline keyframes.
+ *
+ * @example
+ * ```typescript
+ * import { speech, Vrm } from "@hmcs/sdk";
+ *
+ * const keyframes = speech.fromPhonemes([
+ *   ["aa", 0.1],
+ *   [null, 0.05],
+ *   ["oh", 0.12],
+ * ]);
+ * const vrm = await Vrm.findByName("MyAvatar");
+ * await vrm.speakWithTimeline(wavData, keyframes);
+ * ```
+ */
+declare namespace speech {
+    /**
+     * Creates timeline keyframes from a simple phoneme list.
+     *
+     * Each entry is a tuple of [expression_name | null, duration_seconds].
+     * A null expression name creates a silent keyframe.
+     *
+     * @param phonemes - Array of [expression_name, duration] tuples.
+     * @returns An array of timeline keyframes.
+     *
+     * @example
+     * ```typescript
+     * const keyframes = speech.fromPhonemes([
+     *   ["aa", 0.1],
+     *   [null, 0.05],
+     *   ["oh", 0.12],
+     * ]);
+     * ```
+     */
+    function fromPhonemes(phonemes: Array<[string | null, number]>): TimelineKeyframe[];
+}
+
+/**
+ * Represets a local webview source.
+ */
+interface WebviewSourceLocal {
+    type: "local";
+    id: string;
+}
+/**
+ * Represents a inline-html webview source.
+ */
+interface WebviewSourceHtml {
+    type: "html";
+    content: string;
+}
+/**
+ * Represents a remott webview source.
+ */
+interface WebviewSourceUrl {
+    type: "url";
+    url: string;
+}
+/**
+ * Webview source specification (request): URL/path, inline HTML, or local asset ID.
+ *
+ * @example
+ * ```typescript
+ * // URL or mod asset path
+ * const urlSource: WebviewSource = webviewSource.url("my-mod::ui.html");
+ * // Inline HTML content
+ * const htmlSource: WebviewSource = webviewSource.html("<h1>Hello</h1>");
+ * // Local asset by ID
+ * const localSource: WebviewSource = webviewSource.local("my-mod::panel.html");
+ * ```
+ */
+type WebviewSource = WebviewSourceUrl | WebviewSourceHtml | WebviewSourceLocal;
+/**
+ * Returns whether webview source is local.
+ */
+declare function isWebviewSourceLocal(source: WebviewSource): source is WebviewSourceLocal;
+/**
+ * Returns whether webview source is url.
+ */
+declare function isWebviewSourceUrl(source: WebviewSource): source is WebviewSourceUrl;
+/**
+ * Returns whether webview source is inline-html.
+ */
+declare function isWebviewSourceHtml(source: WebviewSource): source is WebviewSourceHtml;
+/**
+ * Factory functions for creating {@link WebviewSource} objects.
+ *
+ * @example
+ * ```typescript
+ * import { Webview, webviewSource } from "@hmcs/sdk";
+ *
+ * await Webview.open({ source: webviewSource.local("menu:ui") });
+ * await Webview.open({ source: webviewSource.url("https://example.com") });
+ * await wv.navigate(webviewSource.html("<h1>Hello</h1>"));
+ * ```
+ */
+declare namespace webviewSource {
+    /**
+     * Create a local asset source.
+     *
+     * @param id - Asset ID (e.g., `"menu:ui"`, `"settings:ui"`)
+     *
+     * @example
+     * ```typescript
+     * const source = webviewSource.local("menu:ui");
+     * // { type: "local", id: "menu:ui" }
+     * ```
+     */
+    function local(id: string): WebviewSourceLocal;
+    /**
+     * Create a URL source.
+     *
+     * @param url - URL string
+     *
+     * @example
+     * ```typescript
+     * const source = webviewSource.url("https://example.com");
+     * // { type: "url", url: "https://example.com" }
+     * ```
+     */
+    function url(url: string): WebviewSourceUrl;
+    /**
+     * Create an inline HTML source.
+     *
+     * @param content - HTML string
+     *
+     * @example
+     * ```typescript
+     * const source = webviewSource.html("<h1>Hello</h1>");
+     * // { type: "html", content: "<h1>Hello</h1>" }
+     * ```
+     */
+    function html(content: string): WebviewSourceHtml;
+}
+/**
+ * Represents a url webview source info
+ */
+interface WebviewSourceInfoUrl {
+    type: "url";
+    url: string;
+}
+/**
+ * Represents a local webview source info.
+ */
+interface WebviewSourceInfoLocal {
+    type: "local";
+    id: string;
+}
+/**
+ * Repsents a inline-html source info.
+ */
+interface WebviewSourceInfoHtml {
+    type: "html";
+    content?: string;
+}
+/**
+ * Webview source information (response).
+ * In list responses, Html content is omitted.
+ * In detail responses, Html content is included.
+ */
+type WebviewSourceInfo = WebviewSourceInfoHtml | WebviewSourceInfoLocal | WebviewSourceInfoUrl;
+declare function isWebviewSourceInfoLocal(source: WebviewSourceInfo): source is WebviewSourceInfoLocal;
+declare function isWebviewSourceInfoUrl(source: WebviewSourceInfo): source is WebviewSourceInfoUrl;
+declare function isWebviewSourceInfoHtml(source: WebviewSourceInfoHtml): source is WebviewSourceInfoHtml;
+/** Information about a webview instance. */
+interface WebviewInfo {
+    entity: number;
+    source: WebviewSourceInfo;
+    size: Vec2;
+    viewportSize: Vec2;
+    offset: Vec2;
+    linkedVrm?: number | null;
+}
+/**
+ * Options for opening a webview.
+ *
+ * @example
+ * ```typescript
+ * const options: WebviewOpenOptions = {
+ *   source: webviewSource.url("my-mod::ui.html"),
+ *   size: [0.7, 0.7],
+ *   viewportSize: [800, 600],
+ *   offset: [0, 0.5],
+ * };
+ * ```
+ */
+interface WebviewOpenOptions {
+    source: WebviewSource;
+    size?: Vec2;
+    viewportSize?: Vec2;
+    offset?: Vec2;
+    linkedVrm?: number;
+}
+/** Request body for patching webview properties. */
+interface WebviewPatchRequest {
+    offset?: Vec2;
+    size?: Vec2;
+    viewportSize?: Vec2;
+}
+/** Request body for navigating a webview to a new source. */
+interface WebviewNavigateRequest {
+    source: WebviewSource;
+}
+/** Request body for setting a webview's linked VRM. */
+interface SetLinkedVrmRequest {
+    vrm: number;
+}
+/**
+ * Webview management for creating and controlling embedded web interfaces.
+ *
+ * Desktop Homunculus uses webviews to provide rich UI experiences that can be
+ * positioned anywhere in 3D space or attached to VRM characters.
+ *
+ * @example
+ * ```typescript
+ * const webview = await Webview.open({
+ *   source: webviewSource.url("my-mod::ui.html"),
+ *   size: [0.7, 0.7],
+ *   viewportSize: [800, 600],
+ *   offset: [0, 0.5],
+ * });
+ *
+ * if (!(await webview.isClosed())) {
+ *   await webview.close();
+ * }
+ * ```
+ */
+/**
+ * Represents a webview instance that can display HTML content in 3D space.
+ */
+declare class Webview {
+    readonly entity: number;
+    constructor(entity: number);
+    /**
+     * Closes the webview.
+     */
+    close(): Promise<void>;
+    /**
+     * Checks whether this webview has been closed.
+     *
+     * @returns A promise that resolves to true if the webview is closed
+     */
+    isClosed(): Promise<boolean>;
+    /**
+     * Gets information about this webview.
+     *
+     * @returns A promise that resolves to the webview info
+     */
+    info(): Promise<WebviewInfo>;
+    /**
+     * Patches webview properties (offset, size, viewportSize).
+     *
+     * @param options - The properties to update
+     */
+    patch(options: WebviewPatchRequest): Promise<void>;
+    /**
+     * Sets the offset of the webview.
+     *
+     * @param offset - The new offset
+     */
+    setOffset(offset: Vec2): Promise<void>;
+    /**
+     * Sets the size of the webview.
+     *
+     * @param size - The new size
+     */
+    setSize(size: Vec2): Promise<void>;
+    /**
+     * Sets the viewport size of the webview.
+     *
+     * @param size - The new viewport size
+     */
+    setViewportSize(size: Vec2): Promise<void>;
+    /**
+     * Navigates the webview to a new source.
+     *
+     * @param source - The new source (URL/path, inline HTML, or local asset ID)
+     *
+     * @example
+     * ```typescript
+     * const wv = new Webview(entity);
+     * // Navigate to a mod asset
+     * await wv.navigate(webviewSource.url("my-mod::page.html"));
+     * // Navigate to inline HTML
+     * await wv.navigate(webviewSource.html("<h1>Hello</h1>"));
+     * // Navigate to a local asset by ID
+     * await wv.navigate(webviewSource.local("my-mod::panel.html"));
+     * ```
+     */
+    navigate(source: WebviewSource): Promise<void>;
+    /**
+     * Reloads the webview content.
+     */
+    reload(): Promise<void>;
+    /**
+     * Navigates the webview back in history.
+     *
+     * @example
+     * ```typescript
+     * const wv = (await Webview.list())[0];
+     * await new Webview(wv.entity).navigateBack();
+     * ```
+     */
+    navigateBack(): Promise<void>;
+    /**
+     * Navigates the webview forward in history.
+     *
+     * @example
+     * ```typescript
+     * const wv = (await Webview.list())[0];
+     * await new Webview(wv.entity).navigateForward();
+     * ```
+     */
+    navigateForward(): Promise<void>;
+    /**
+     * Gets the VRM linked to this webview.
+     *
+     * @returns The linked VRM instance, or undefined if no VRM is linked
+     */
+    linkedVrm(): Promise<Vrm | undefined>;
+    /**
+     * Links this webview to a VRM entity.
+     *
+     * @param vrm - The VRM to link to this webview
+     */
+    setLinkedVrm(vrm: Vrm): Promise<void>;
+    /**
+     * Removes the VRM link from this webview.
+     */
+    unlinkVrm(): Promise<void>;
+    /**
+     * Gets all open webviews.
+     *
+     * @returns A promise that resolves to an array of webview info
+     */
+    static list(): Promise<WebviewInfo[]>;
+    /**
+     * Creates and opens a webview positioned in world space.
+     *
+     * @param options - Configuration for the webview
+     * @returns A promise that resolves to a new Webview instance
+     *
+     * @example
+     * ```typescript
+     * // Open with a mod asset URL
+     * const panel = await Webview.open({
+     *   source: webviewSource.url("my-mod::settings.html"),
+     *   size: [0.7, 0.5],
+     *   viewportSize: [800, 600],
+     *   offset: [0, 1.0],
+     * });
+     *
+     * // Open with inline HTML
+     * const inline = await Webview.open({
+     *   source: webviewSource.html("<h1>Hello World</h1>"),
+     * });
+     *
+     * // Open with a local asset
+     * const local = await Webview.open({
+     *   source: webviewSource.local("my-mod::panel.html"),
+     *   offset: [0.5, 0],
+     * });
+     * ```
+     */
+    static open(options: WebviewOpenOptions): Promise<Webview>;
+    /**
+     * Gets the current webview instance if called from within a webview context.
+     *
+     * @returns The current Webview instance, or undefined if not in a webview context
+     */
+    static current(): Webview | undefined;
+}
+
+/**
+ * Signals API namespace for cross-process communication.
+ *
+ * Provides a pub/sub mechanism that allows external processes to communicate
+ * with the Desktop Homunculus application and its mods through event streaming.
+ *
+ * Key features:
+ * - Real-time event streaming via Server-Sent Events (SSE)
+ * - Signal broadcasting to multiple subscribers
+ * - Type-safe payload handling
+ *
+ * @example
+ * ```typescript
+ * // Listen for custom events from external processes
+ * const eventSource = signals.stream<{action: string, data: any}>(
+ *   "my-custom-signal",
+ *   (payload) => {
+ *     console.log("Received signal:", payload.action, payload.data);
+ *   }
+ * );
+ *
+ * // Send signals to all listeners
+ * await signals.send("my-custom-signal", {
+ *   action: "update",
+ *   data: { message: "Hello from external app!" }
+ * });
+ *
+ * // Clean up when done
+ * eventSource.close();
+ * ```
+ */
+declare namespace signals {
+    /**
+     * Information about an active signal channel.
+     */
+    interface SignalChannelInfo {
+        /** The signal channel name. */
+        signal: string;
+        /** The number of active subscribers. */
+        subscribers: number;
+    }
+    /**
+     * Lists all active signal channels and their subscriber counts.
+     *
+     * Returns information about every signal channel that has been created.
+     * Useful for debugging, monitoring, and discovering available channels.
+     *
+     * @returns Array of active signal channel information
+     *
+     * @example
+     * ```typescript
+     * // List all active signal channels
+     * const channels = await signals.list();
+     * for (const ch of channels) {
+     *   console.log(`${ch.signal}: ${ch.subscribers} subscribers`);
+     * }
+     *
+     * // Check if a specific signal has listeners before sending
+     * const channels = await signals.list();
+     * const target = channels.find(ch => ch.signal === "my-signal");
+     * if (target && target.subscribers > 0) {
+     *   await signals.send("my-signal", { data: "hello" });
+     * }
+     * ```
+     */
+    function list(): Promise<SignalChannelInfo[]>;
+    /**
+     * Creates a persistent connection to stream signal events of a specific type.
+     *
+     * This establishes a Server-Sent Events (SSE) connection that will receive
+     * all signals sent to the specified signal channel. The connection remains
+     * open until explicitly closed.
+     *
+     * @template V - The type of the payload that will be received
+     * @param signal - The signal channel name to subscribe to
+     * @param f - Callback function to handle received payloads
+     * @returns EventSource instance for managing the connection
+     *
+     * @example
+     * ```typescript
+     * // Listen for user interaction events
+     * interface UserAction {
+     *   type: 'click' | 'hover' | 'scroll';
+     *   position: [number, number];
+     *   timestamp: number;
+     * }
+     *
+     * const userEventStream = signals.stream<UserAction>(
+     *   "user-interactions",
+     *   async (action) => {
+     *     console.log(`User ${action.type} at`, action.position);
+     *     // Process the user action...
+     *   }
+     * );
+     *
+     * // Later, close the stream
+     * userEventStream.close();
+     * ```
+     */
+    function stream<V>(signal: string, f: (payload: V) => (void | Promise<void>)): EventSource;
+    /**
+     * Sends a signal payload to all subscribers listening to the specified signal channel.
+     *
+     * This broadcasts the payload to all active EventSource connections that are
+     * streaming the same signal type. The operation is asynchronous and will
+     * complete once the signal has been distributed to all subscribers.
+     *
+     * @template V - The type of the payload being sent
+     * @param signal - The signal channel name to broadcast to
+     * @param payload - The data to send to all subscribers
+     *
+     * @throws Will throw an error if the signal broadcast fails
+     *
+     * @example
+     * ```typescript
+     * // Send a notification to all mod windows
+     * await signals.send("notifications", {
+     *   type: "info",
+     *   title: "Update Available",
+     *   message: "A new version of the character is available",
+     *   timestamp: Date.now()
+     * });
+     *
+     * // Send real-time data updates
+     * await signals.send("data-update", {
+     *   source: "weather-api",
+     *   temperature: 72,
+     *   conditions: "sunny"
+     * });
+     *
+     * // Trigger actions in mods
+     * await signals.send("vrm-action", {
+     *   action: "wave",
+     *   target: vrmEntity,
+     *   duration: 2000
+     * });
+     * ```
+     */
+    function send<V>(signal: string, payload: V): Promise<void>;
+}
+
+/**
+ * Entities API namespace for managing ECS (Entity Component System) entities.
+ *
+ * In Desktop Homunculus, everything is represented as entities in Bevy's ECS system.
+ * This includes VRM models, bones, UI elements, and other game objects. This namespace
+ * provides core functionality for finding entities by name and manipulating their
+ * transforms (position, rotation, scale).
+ *
+ * Key concepts:
+ * - **Entity**: A unique identifier in the ECS system
+ * - **Name**: Human-readable identifier for entities
+ * - **Transform**: Position, rotation, and scale data
+ * - **Hierarchy**: Entities can have parent-child relationships
+ *
+ * @example
+ * ```typescript
+ * // Find a VRM entity by name
+ * const vrmEntity = await entities.findByName("MyCharacter");
+ *
+ * // Get the current transform (position, rotation, scale)
+ * const transform = await entities.transform(vrmEntity);
+ * console.log("Position:", transform.translation);
+ *
+ * // Move the VRM to a new position
+ * await entities.setTransform(vrmEntity, {
+ *   translation: [100, 0, 50]
+ * });
+ *
+ * // Find a bone within a specific VRM
+ * const headBone = await entities.findByName("head", { root: vrmEntity });
+ * ```
+ */
+declare namespace entities {
+    /**
+     * Options for entity search operations.
+     */
+    interface FindOptions {
+        /**
+         * Optional root entity to search within.
+         * If specified, the search will be limited to children of this entity.
+         * If not specified, the search will be global across all entities.
+         */
+        root?: number;
+    }
+    /**
+     * Gets the current transform (position, rotation, scale) of an entity.
+     *
+     * The transform defines where the entity is positioned in 3D space,
+     * how it's rotated, and its scale factor.
+     *
+     * @param entity - The entity ID to get the transform for
+     * @returns A promise that resolves to the entity's transform data
+     *
+     * @example
+     * ```typescript
+     * const vrmEntity = await entities.findByName("MyCharacter");
+     * const transform = await entities.transform(vrmEntity);
+     *
+     * console.log("Position:", transform.translation);
+     * console.log("Rotation:", transform.rotation);
+     * console.log("Scale:", transform.scale);
+     * ```
+     */
+    function transform(entity: number): Promise<Transform>;
+    /**
+     * Updates the transform (position, rotation, scale) of an entity.
+     *
+     * You can provide a partial transform to update only specific components.
+     * For example, you can change just the position while leaving rotation
+     * and scale unchanged.
+     *
+     * @param entity - The entity ID to update
+     * @param transform - Partial transform data with the values to update
+     *
+     * @example
+     * ```typescript
+     * // Move entity to a new position
+     * await entities.setTransform(vrmEntity, {
+     *   translation: [0, 100, 0]  // Move up 100 units
+     * });
+     *
+     * // Rotate and scale the entity
+     * await entities.setTransform(vrmEntity, {
+     *   rotation: [0, 0, 0, 1],   // Reset rotation to identity
+     *   scale: [2, 2, 2]          // Double the size
+     * });
+     *
+     * // Update all transform components at once
+     * await entities.setTransform(vrmEntity, {
+     *   translation: [50, 0, -25],
+     *   rotation: [0, 0.707, 0, 0.707],  // 90 degree Y rotation
+     *   scale: [1.5, 1.5, 1.5]
+     * });
+     * ```
+     */
+    function setTransform(entity: number, transform: Partial<Transform>): Promise<void>;
+    /**
+     * Gets the human-readable name of an entity.
+     *
+     * Most entities in Desktop Homunculus have names that make them easier
+     * to identify and work with. VRM models use their character names,
+     * bones use standard bone names like "head", "leftHand", etc.
+     *
+     * @param entity - The entity ID to get the name for
+     * @returns A promise that resolves to the entity's name
+     *
+     * @example
+     * ```typescript
+     * const vrmEntity = await entities.findByName("MyCharacter");
+     * const name = await entities.name(vrmEntity);
+     * console.log("Entity name:", name); // "MyCharacter"
+     *
+     * // Get bone names
+     * const headBone = await entities.findByName("head", { root: vrmEntity });
+     * const boneName = await entities.name(headBone);
+     * console.log("Bone name:", boneName); // "head"
+     * ```
+     */
+    function name(entity: number): Promise<string>;
+    /**
+     * Finds an entity by its name, optionally within a specific parent entity.
+     *
+     * This is the primary method for locating entities in the ECS system.
+     * Names are unique within their scope (global or under a specific parent).
+     *
+     * @param name - The name of the entity to find
+     * @param options - Optional search parameters
+     * @returns A promise that resolves to the entity ID
+     * @throws Will throw an error if no entity with the given name is found
+     *
+     * @example
+     * ```typescript
+     * // Find a VRM character globally
+     * const vrmEntity = await entities.findByName("MyCharacter");
+     *
+     * // Find a bone within a specific VRM
+     * const headBone = await entities.findByName("head", {
+     *   root: vrmEntity
+     * });
+     *
+     * // Find UI elements or other named entities
+     * const settingsPanel = await entities.findByName("SettingsPanel");
+     * const chatWindow = await entities.findByName("ChatWindow");
+     * ```
+     */
+    function findByName(name: string, options?: FindOptions): Promise<number>;
+    interface MoveTargetWorld {
+        type: "world";
+        position: Vec2;
+        z?: number;
+    }
+    interface MoveTargetViewport {
+        type: "viewport";
+        position: Vec2;
+    }
+    /**
+     * Target position for entity movement.
+     *
+     * Use `type: "world"` for direct world-space coordinates (position as [x, y], z optional).
+     * Use `type: "viewport"` for screen-space coordinates that are automatically converted to world space.
+     */
+    type MoveTarget = MoveTargetWorld | MoveTargetViewport;
+    /**
+     * Moves an entity to the specified position.
+     *
+     * Supports two coordinate types:
+     * - **World coordinates**: Sets the entity's position directly in 3D world space.
+     *   `z` is optional — if omitted, the entity keeps its current z position.
+     * - **Viewport coordinates**: Screen-space position that is automatically converted
+     *   to world coordinates internally.
+     *
+     * @param entity - The entity ID to move
+     * @param target - The target position (world or viewport coordinates)
+     *
+     * @example
+     * ```typescript
+     * // Move to world coordinates
+     * await entities.move(vrmEntity, { type: "world", position: [0, 1.5], z: -2 });
+     *
+     * // Move to world coordinates (keep current z)
+     * await entities.move(vrmEntity, { type: "world", position: [0, 1.5] });
+     *
+     * // Move to a screen position
+     * await entities.move(vrmEntity, { type: "viewport", position: [500, 300] });
+     * ```
+     */
+    function move(entity: number, target: MoveTarget): Promise<void>;
+    /**
+     * Easing functions for tween animations.
+     * Controls the acceleration curve of the animation.
+     */
+    type EasingFunction = "linear" | "quadraticIn" | "quadraticOut" | "quadraticInOut" | "cubicIn" | "cubicOut" | "cubicInOut" | "quarticIn" | "quarticOut" | "quarticInOut" | "quinticIn" | "quinticOut" | "quinticInOut" | "sineIn" | "sineOut" | "sineInOut" | "circularIn" | "circularOut" | "circularInOut" | "exponentialIn" | "exponentialOut" | "exponentialInOut" | "elasticIn" | "elasticOut" | "elasticInOut" | "backIn" | "backOut" | "backInOut" | "bounceIn" | "bounceOut" | "bounceInOut" | "smoothStepIn" | "smoothStepOut" | "smoothStep" | "smootherStepIn" | "smootherStepOut" | "smootherStep";
+    /**
+     * Request parameters for tweening an entity's position.
+     */
+    interface TweenPositionRequest {
+        /** Target position as [x, y, z] */
+        target: [number, number, number];
+        /** Duration in milliseconds */
+        durationMs: number;
+        /** Easing function (default: "linear") */
+        easing?: EasingFunction;
+        /** Whether to wait for the tween to complete before returning (default: false) */
+        wait?: boolean;
+    }
+    /**
+     * Request parameters for tweening an entity's rotation.
+     */
+    interface TweenRotationRequest {
+        /** Target rotation as quaternion [x, y, z, w] */
+        target: [number, number, number, number];
+        /** Duration in milliseconds */
+        durationMs: number;
+        /** Easing function (default: "linear") */
+        easing?: EasingFunction;
+        /** Whether to wait for the tween to complete before returning (default: false) */
+        wait?: boolean;
+    }
+    /**
+     * Request parameters for tweening an entity's scale.
+     */
+    interface TweenScaleRequest {
+        /** Target scale as [x, y, z] */
+        target: [number, number, number];
+        /** Duration in milliseconds */
+        durationMs: number;
+        /** Easing function (default: "linear") */
+        easing?: EasingFunction;
+        /** Whether to wait for the tween to complete before returning (default: false) */
+        wait?: boolean;
+    }
+    /**
+     * Smoothly animate an entity's position to a target value.
+     *
+     * @param entityId - The entity ID to tween
+     * @param request - Tween parameters
+     * @returns Promise that resolves when the request completes (or when animation finishes if wait=true)
+     *
+     * @example
+     * ```typescript
+     * await entities.tweenPosition(myEntity, {
+     *   target: [100, 50, 0],
+     *   durationMs: 1000,
+     *   easing: "quadraticInOut",
+     *   wait: true,
+     * });
+     * ```
+     */
+    function tweenPosition(entityId: number, request: TweenPositionRequest): Promise<void>;
+    /**
+     * Smoothly animate an entity's rotation to a target value.
+     *
+     * @param entityId - The entity ID to tween
+     * @param request - Tween parameters
+     * @returns Promise that resolves when the request completes (or when animation finishes if wait=true)
+     *
+     * @example
+     * ```typescript
+     * await entities.tweenRotation(myEntity, {
+     *   target: [0, 0, 0.7071, 0.7071], // 90 degrees around Z axis
+     *   durationMs: 500,
+     *   easing: "elasticOut",
+     * });
+     * ```
+     */
+    function tweenRotation(entityId: number, request: TweenRotationRequest): Promise<void>;
+    /**
+     * Smoothly animate an entity's scale to a target value.
+     *
+     * @param entityId - The entity ID to tween
+     * @param request - Tween parameters
+     * @returns Promise that resolves when the request completes (or when animation finishes if wait=true)
+     *
+     * @example
+     * ```typescript
+     * await entities.tweenScale(myEntity, {
+     *   target: [2, 2, 2],
+     *   durationMs: 800,
+     *   easing: "bounceOut",
+     *   wait: false,
+     * });
+     * ```
+     */
+    function tweenScale(entityId: number, request: TweenScaleRequest): Promise<void>;
+}
+
+/**
+ * Provides access to the application API.
+ */
+declare namespace app {
+    /**
+     * Exits the application without any problems.
+     */
+    function exit(): Promise<void>;
+    /**
+     * Checks if the Desktop Homunculus server is running and healthy.
+     *
+     * Returns `true` if the server responds with a successful health check,
+     * `false` if the server is unreachable or unhealthy.
+     *
+     * @example
+     * ```typescript
+     * const alive = await app.health();
+     * if (!alive) {
+     *   console.error("Homunculus server is not running");
+     * }
+     * ```
+     */
+    function health(): Promise<boolean>;
+    /**
+     * Platform information about the running system.
+     */
+    interface PlatformInfo {
+        /** Operating system name (e.g., "macos", "windows", "linux"). */
+        os: string;
+        /** CPU architecture (e.g., "aarch64", "x86_64"). */
+        arch: string;
+    }
+    /**
+     * Summary of a loaded mod as returned by the info endpoint.
+     */
+    interface InfoMod {
+        /** The mod package name. */
+        name: string;
+        /** The mod package version. */
+        version: string;
+        /** Human-readable description. */
+        description: string | null;
+        /** The mod author. */
+        author: string | null;
+        /** The mod license. */
+        license: string | null;
+        /** Whether the mod has a running main process. */
+        hasMain: boolean;
+        /** Available bin command names. */
+        binCommands: string[];
+        /** Registered asset IDs. */
+        assetIds: string[];
+    }
+    /**
+     * Application metadata returned by the info endpoint.
+     */
+    interface AppInfo {
+        /** The engine version string (e.g., "0.1.0-alpha.3.2"). */
+        version: string;
+        /** Platform information. */
+        platform: PlatformInfo;
+        /** Engine-level features available in this build. */
+        features: string[];
+        /** All loaded mods with metadata. */
+        mods: InfoMod[];
+    }
+    /**
+     * Returns metadata about the running Desktop Homunculus instance.
+     *
+     * Provides the engine version, platform info, compiled features,
+     * and loaded mods in a single request. Useful for startup checks,
+     * feature detection, and status displays.
+     *
+     * @returns Application info including version, platform, features, and mods
+     *
+     * @example
+     * ```typescript
+     * const info = await app.info();
+     * console.log(`Engine v${info.version} on ${info.platform.os}/${info.platform.arch}`);
+     * console.log(`Features: ${info.features.join(", ")}`);
+     * console.log(`${info.mods.length} mods loaded`);
+     * ```
+     */
+    function info(): Promise<AppInfo>;
+}
+
+/**
+ * Mod management namespace for executing commands defined in mod packages.
+ *
+ * Provides functions to run on-demand scripts from installed mods,
+ * with support for passing arguments, stdin data, configuring timeouts,
+ * and real-time NDJSON streaming of command output.
+ *
+ * @example
+ * ```typescript
+ * // Execute a command and collect the result
+ * const result = await mods.executeCommand({ command: "greet" });
+ * console.log(result.stdout);
+ *
+ * // Stream command output in real-time
+ * for await (const event of mods.streamCommand({ command: "build" })) {
+ *   if (event.type === "stdout") console.log(event.data);
+ *   if (event.type === "stderr") console.error(event.data);
+ *   if (event.type === "exit") console.log("Exit code:", event.exitCode);
+ * }
+ * ```
+ */
+declare namespace mods {
+    /**
+     * Summary information about a loaded mod.
+     *
+     * @example
+     * ```typescript
+     * const allMods = await mods.list();
+     * for (const mod of allMods) {
+     *   console.log(`${mod.name}@${mod.version} (${mod.commands.length} commands)`);
+     * }
+     * ```
+     */
+    interface ModInfo {
+        /** The mod package name. */
+        name: string;
+        /** The mod package version. */
+        version: string;
+        /** Optional description from package.json. */
+        description?: string;
+        /** Optional author from package.json. */
+        author?: string;
+        /** Optional license from package.json. */
+        license?: string;
+        /** Service script path (auto-launched at startup), or null if no service. */
+        serviceScriptPath?: string;
+        /** Available bin command names. */
+        commands: string[];
+        /** Asset declarations keyed by asset ID. */
+        assets: Record<string, {
+            path: string;
+            type: string;
+            description: string;
+        }>;
+        /** Menu entries registered by this mod. */
+        menus: Array<{
+            id: string;
+            text: string;
+            command: string;
+        }>;
+        /** Absolute path to the mod's root directory. */
+        modDir: string;
+    }
+    /**
+     * List all loaded mods and their metadata.
+     *
+     * Returns summary information for every mod discovered at startup,
+     * including available bin commands and registered asset IDs.
+     *
+     * @returns Array of mod information objects
+     *
+     * @example
+     * ```typescript
+     * // List all installed mods
+     * const allMods = await mods.list();
+     * console.log(`${allMods.length} mods installed`);
+     *
+     * // Find mods with bin commands
+     * const withCommands = allMods.filter(m => m.commands.length > 0);
+     *
+     * // Get assets from a specific mod
+     * const elmer = allMods.find(m => m.name === "elmer");
+     * if (elmer) {
+     *   console.log("Elmer assets:", Object.keys(elmer.assets));
+     * }
+     * ```
+     */
+    function list(): Promise<ModInfo[]>;
+    /**
+     * Get detailed information about a specific mod by name.
+     *
+     * @param modName - The mod package name
+     * @returns Mod information
+     *
+     * @example
+     * ```typescript
+     * const elmer = await mods.get("elmer");
+     * console.log(`${elmer.name}@${elmer.version}`);
+     * console.log("Commands:", elmer.commands);
+     * ```
+     */
+    function get(modName: string): Promise<ModInfo>;
+    /**
+     * Request parameters for executing a mod command.
+     *
+     * @example
+     * ```typescript
+     * const request: mods.ExecuteCommandRequest = {
+     *   command: "build",
+     *   args: ["--verbose"],
+     *   stdin: "input data",
+     *   timeoutMs: 5000,
+     * };
+     * ```
+     */
+    interface ExecuteCommandRequest {
+        /** The command name to execute (resolved via npx from installed mod packages). */
+        command: string;
+        /** Arguments to pass to the script (after the script path). Max 64 args, each max 4096 chars. */
+        args?: string[];
+        /** Data to write to the process stdin. Stdin is closed after writing. Max 1 MiB. */
+        stdin?: string;
+        /** Timeout in milliseconds (1–300000). Defaults to 30000 (30s). */
+        timeoutMs?: number;
+    }
+    /** A stdout line event from a streaming command execution. */
+    interface CommandStdoutEvent {
+        type: "stdout";
+        data: string;
+    }
+    /** A stderr line event from a streaming command execution. */
+    interface CommandStderrEvent {
+        type: "stderr";
+        data: string;
+    }
+    /** The exit event from a streaming command execution. Always the last event. */
+    interface CommandExitEvent {
+        type: "exit";
+        /** Process exit code, or null if the process was killed by a signal. */
+        exitCode: number | null;
+        /** Whether the process was killed due to timeout. */
+        timedOut: boolean;
+        /** Unix signal name if the process was killed by a signal. */
+        signal?: string;
+    }
+    /** Union of all command event types emitted during streaming execution. */
+    type CommandEvent = CommandStdoutEvent | CommandStderrEvent | CommandExitEvent;
+    /**
+     * Buffered result of a command execution.
+     *
+     * @example
+     * ```typescript
+     * const result = await mods.executeCommand({ command: "hello" });
+     * if (result.exitCode === 0) {
+     *   console.log("Output:", result.stdout);
+     * } else {
+     *   console.error("Error:", result.stderr);
+     * }
+     * ```
+     */
+    interface CommandResult {
+        /** Process exit code, or null if the process was killed by a signal. */
+        exitCode: number | null;
+        /** Whether the process was killed due to timeout. */
+        timedOut: boolean;
+        /** Unix signal name if the process was killed by a signal. */
+        signal?: string;
+        /** All stdout output joined by newlines. */
+        stdout: string;
+        /** All stderr output joined by newlines. */
+        stderr: string;
+    }
+    /**
+     * Execute a mod command with real-time NDJSON streaming output.
+     *
+     * Returns an async generator that yields {@link CommandEvent} objects
+     * as the command produces output. The last event is always an `exit` event.
+     *
+     * @param request - Command execution parameters
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns An async generator yielding command events
+     *
+     * @example
+     * ```typescript
+     * // Stream output from a long-running build
+     * for await (const event of mods.streamCommand({ command: "build" })) {
+     *   switch (event.type) {
+     *     case "stdout": console.log(event.data); break;
+     *     case "stderr": console.error(event.data); break;
+     *     case "exit": console.log("Done, exit code:", event.exitCode); break;
+     *   }
+     * }
+     * ```
+     */
+    function streamCommand(request: ExecuteCommandRequest, signal?: AbortSignal): AsyncGenerator<CommandEvent>;
+    /**
+     * Execute a mod command and collect the full result.
+     *
+     * This is a convenience wrapper around {@link streamCommand} that buffers
+     * all output and returns a single {@link CommandResult}.
+     *
+     * @param request - Command execution parameters
+     * @param signal - Optional AbortSignal for cancellation
+     * @returns The collected command result with exit code, stdout, and stderr
+     *
+     * @example
+     * ```typescript
+     * // Simple execution
+     * const result = await mods.executeCommand({ command: "build" });
+     *
+     * // With arguments
+     * const result = await mods.executeCommand({
+     *   command: "compile",
+     *   args: ["--target", "es2020"],
+     * });
+     *
+     * // With stdin data and custom timeout
+     * const result = await mods.executeCommand({
+     *   command: "transform",
+     *   stdin: JSON.stringify({ input: "data" }),
+     *   timeoutMs: 60000,
+     * });
+     * ```
+     */
+    function executeCommand(request: ExecuteCommandRequest, signal?: AbortSignal): Promise<CommandResult>;
+    /**
+     * Metadata for a mod-registered context menu item.
+     *
+     * @example
+     * ```typescript
+     * const items = await mods.menus();
+     * for (const item of items) {
+     *   console.log(`${item.modName}: ${item.text}`);
+     * }
+     * ```
+     */
+    interface ModMenuMetadata {
+        /** Unique identifier for the menu item. */
+        id: string;
+        /** The mod package name that registered this menu item. */
+        modName: string;
+        /** Display text shown in the context menu. */
+        text: string;
+        /** Bin command to execute when the menu item is selected. */
+        command: string;
+    }
+    /**
+     * Returns all registered mod menu items.
+     *
+     * Menu items are declared in each mod's `package.json` under the
+     * `homunculus.menus` field and collected at startup.
+     *
+     * @example
+     * ```typescript
+     * import { mods } from "@hmcs/sdk";
+     *
+     * const menuItems = await mods.menus();
+     * for (const item of menuItems) {
+     *   console.log(`${item.modName}: ${item.text}`);
+     * }
+     * ```
+     */
+    function menus(): Promise<ModMenuMetadata[]>;
+}
+
+/**
+ * Assets API namespace for querying available mod assets.
+ *
+ * Provides access to the asset registry, which contains all assets declared
+ * by installed mods. Assets are referenced by their globally unique ID using
+ * the format `"mod-name:asset-name"` (e.g., `"elmer:idle"`, `"my-mod:click"`).
+ *
+ * @example
+ * ```typescript
+ * // List all available assets
+ * const all = await assets.list();
+ *
+ * // Filter by type
+ * const vrms = await assets.list({ type: "vrm" });
+ *
+ * // Filter by mod
+ * const elmerAssets = await assets.list({ mod: "elmer" });
+ * ```
+ */
+declare namespace assets {
+    /** The type of an asset. */
+    type AssetType = "vrm" | "vrma" | "sound" | "image" | "html";
+    /** Information about a registered asset. */
+    interface AssetInfo {
+        /** Globally unique asset ID. */
+        id: string;
+        /** The asset type. */
+        type: AssetType;
+        /** The mod that provides this asset. */
+        mod: string;
+        /** Optional description of the asset. */
+        description?: string;
+    }
+    /** Filter options for listing assets. */
+    interface AssetFilter {
+        /** Filter by asset type. */
+        type?: AssetType;
+        /** Filter by mod name. */
+        mod?: string;
+    }
+    /**
+     * Lists available assets, optionally filtered by type and/or mod.
+     *
+     * @param filter - Optional filter criteria
+     * @returns Array of matching asset info objects
+     *
+     * @example
+     * ```typescript
+     * // Get all assets
+     * const all = await assets.list();
+     *
+     * // Get only VRM models
+     * const vrms = await assets.list({ type: "vrm" });
+     *
+     * // Get assets from a specific mod
+     * const modAssets = await assets.list({ mod: "elmer" });
+     *
+     * // Combine filters
+     * const sounds = await assets.list({ type: "sound", mod: "my-mod" });
+     * ```
+     */
+    function list(filter?: AssetFilter): Promise<AssetInfo[]>;
+}
+
+/**
+ * Resolves after `ms` milliseconds (non-blocking delay).
+ *
+ * @example
+ *
+ */
+declare function sleep(ms: number): Promise<unknown>;
+
+export { HomunculusApiError, HomunculusStreamError, Vrm, VrmEventSource, Webview, app, assets, audio, coordinates, displays, effects, entities, host, isWebviewSourceHtml, isWebviewSourceInfoHtml, isWebviewSourceInfoLocal, isWebviewSourceInfoUrl, isWebviewSourceLocal, isWebviewSourceUrl, mods, preferences, repeat, settings, shadowPanel, signals, sleep, speech, webviewSource };
+export type { Bones, Button, EventMap, ExpressionInfo, ExpressionsResponse, GlobalDisplay, GlobalViewport, LookAtState, MoveToArgs, Ocean, OverrideType, Persona, PersonaChangeEvent, PositionResponse, Quat, Rect, SetFpsBody, SetLinkedVrmRequest, ShadowPanelPutBody, SpawnVrmOptions, SpeakTimelineOptions, SpringBoneChain, SpringBoneChainsResponse, SpringBoneProps, StampRequestBody, TimelineKeyframe, Transform, TransformArgs, Vec2, Vec3, VrmDragEvent, VrmMetadata, VrmMouseEvent, VrmPointerEvent, VrmSnapshot, VrmStateChangeEvent, VrmStateRequest, VrmStateResponse, VrmaInfo, VrmaPlayRequest, VrmaRepeat, VrmaSpeedBody, VrmaState, WebviewInfo, WebviewNavigateRequest, WebviewOpenOptions, WebviewPatchRequest, WebviewSource, WebviewSourceHtml, WebviewSourceInfo, WebviewSourceInfoHtml, WebviewSourceInfoLocal, WebviewSourceInfoUrl, WebviewSourceLocal, WebviewSourceUrl };