@hmcs/sdk 1.0.0

package/dist/index.js

@@ -0,0 +1,17 @@
+export { coordinates } from './coordinates.js';
+export { displays } from './displays.js';
+export { audio } from './audio.js';
+export { effects } from './effects.js';
+export { HomunculusApiError, HomunculusStreamError, host } from './host.js';
+export { preferences } from './preferences.js';
+export { settings } from './settings.js';
+export { shadowPanel } from './shadowPanel.js';
+export { Vrm, VrmEventSource, repeat } from './vrm.js';
+export { speech } from './speech.js';
+export { Webview, isWebviewSourceHtml, isWebviewSourceInfoHtml, isWebviewSourceInfoLocal, isWebviewSourceInfoUrl, isWebviewSourceLocal, isWebviewSourceUrl, webviewSource } from './webviews.js';
+export { signals } from './signals.js';
+export { entities } from './entities.js';
+export { app } from './app.js';
+export { mods } from './mods.js';
+export { assets } from './assets.js';
+export { sleep } from './utils.js';

package/dist/mods.cjs

@@ -0,0 +1,207 @@
+'use strict';
+
+var host = require('./host.cjs');
+
+/**
+ * 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);
+ * }
+ * ```
+ */
+exports.mods = void 0;
+(function (mods) {
+    /**
+     * 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));
+     * }
+     * ```
+     */
+    async function list() {
+        const response = await host.host.get(host.host.createUrl("mods"));
+        return await response.json();
+    }
+    mods.list = list;
+    /**
+     * 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);
+     * ```
+     */
+    async function get(modName) {
+        const response = await host.host.get(host.host.createUrl(`mods/${modName}`));
+        return await response.json();
+    }
+    mods.get = get;
+    function toRequestBody(request) {
+        return {
+            command: request.command,
+            args: request.args,
+            stdin: request.stdin,
+            timeoutMs: request.timeoutMs,
+        };
+    }
+    function toCommandEvent(raw) {
+        switch (raw.type) {
+            case "stdout":
+                return { type: "stdout", data: raw.data ?? "" };
+            case "stderr":
+                return { type: "stderr", data: raw.data ?? "" };
+            case "exit":
+                return {
+                    type: "exit",
+                    exitCode: raw.code ?? null,
+                    timedOut: raw.timedOut ?? false,
+                    signal: raw.signal,
+                };
+        }
+    }
+    /**
+     * 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;
+     *   }
+     * }
+     * ```
+     */
+    async function* streamCommand(request, signal) {
+        const stream = host.host.postStream(host.host.createUrl("commands/execute"), toRequestBody(request), signal);
+        for await (const raw of stream) {
+            yield toCommandEvent(raw);
+        }
+    }
+    mods.streamCommand = streamCommand;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    async function executeCommand(request, signal) {
+        const stdoutLines = [];
+        const stderrLines = [];
+        let exitCode = null;
+        let timedOut = false;
+        let exitSignal;
+        for await (const event of streamCommand(request, signal)) {
+            switch (event.type) {
+                case "stdout":
+                    stdoutLines.push(event.data);
+                    break;
+                case "stderr":
+                    stderrLines.push(event.data);
+                    break;
+                case "exit":
+                    exitCode = event.exitCode;
+                    timedOut = event.timedOut;
+                    exitSignal = event.signal;
+                    break;
+            }
+        }
+        return {
+            exitCode,
+            timedOut,
+            signal: exitSignal,
+            stdout: stdoutLines.join("\n"),
+            stderr: stderrLines.join("\n"),
+        };
+    }
+    mods.executeCommand = executeCommand;
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    async function menus() {
+        const response = await host.host.get(host.host.createUrl("mods/menus"));
+        return await response.json();
+    }
+    mods.menus = menus;
+})(exports.mods || (exports.mods = {}));

package/dist/mods.js

@@ -0,0 +1,207 @@
+import { host } from './host.js';
+
+/**
+ * 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);
+ * }
+ * ```
+ */
+var mods;
+(function (mods) {
+    /**
+     * 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));
+     * }
+     * ```
+     */
+    async function list() {
+        const response = await host.get(host.createUrl("mods"));
+        return await response.json();
+    }
+    mods.list = list;
+    /**
+     * 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);
+     * ```
+     */
+    async function get(modName) {
+        const response = await host.get(host.createUrl(`mods/${modName}`));
+        return await response.json();
+    }
+    mods.get = get;
+    function toRequestBody(request) {
+        return {
+            command: request.command,
+            args: request.args,
+            stdin: request.stdin,
+            timeoutMs: request.timeoutMs,
+        };
+    }
+    function toCommandEvent(raw) {
+        switch (raw.type) {
+            case "stdout":
+                return { type: "stdout", data: raw.data ?? "" };
+            case "stderr":
+                return { type: "stderr", data: raw.data ?? "" };
+            case "exit":
+                return {
+                    type: "exit",
+                    exitCode: raw.code ?? null,
+                    timedOut: raw.timedOut ?? false,
+                    signal: raw.signal,
+                };
+        }
+    }
+    /**
+     * 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;
+     *   }
+     * }
+     * ```
+     */
+    async function* streamCommand(request, signal) {
+        const stream = host.postStream(host.createUrl("commands/execute"), toRequestBody(request), signal);
+        for await (const raw of stream) {
+            yield toCommandEvent(raw);
+        }
+    }
+    mods.streamCommand = streamCommand;
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    async function executeCommand(request, signal) {
+        const stdoutLines = [];
+        const stderrLines = [];
+        let exitCode = null;
+        let timedOut = false;
+        let exitSignal;
+        for await (const event of streamCommand(request, signal)) {
+            switch (event.type) {
+                case "stdout":
+                    stdoutLines.push(event.data);
+                    break;
+                case "stderr":
+                    stderrLines.push(event.data);
+                    break;
+                case "exit":
+                    exitCode = event.exitCode;
+                    timedOut = event.timedOut;
+                    exitSignal = event.signal;
+                    break;
+            }
+        }
+        return {
+            exitCode,
+            timedOut,
+            signal: exitSignal,
+            stdout: stdoutLines.join("\n"),
+            stderr: stderrLines.join("\n"),
+        };
+    }
+    mods.executeCommand = executeCommand;
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    async function menus() {
+        const response = await host.get(host.createUrl("mods/menus"));
+        return await response.json();
+    }
+    mods.menus = menus;
+})(mods || (mods = {}));
+
+export { mods };

package/dist/preferences.cjs

@@ -0,0 +1,90 @@
+'use strict';
+
+var host = require('./host.cjs');
+
+/**
+ * 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');
+ * ```
+ */
+exports.preferences = void 0;
+(function (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);
+     * }
+     * ```
+     */
+    async function list() {
+        const response = await host.host.get(host.host.createUrl("preferences"));
+        return await response.json();
+    }
+    preferences.list = list;
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    async function load(key) {
+        try {
+            const response = await host.host.get(host.host.createUrl(`preferences/${key}`));
+            return await response.json();
+        }
+        catch (e) {
+            if (e instanceof host.HomunculusApiError && e.statusCode === 404) {
+                return undefined;
+            }
+            throw e;
+        }
+    }
+    preferences.load = load;
+    /**
+     * 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');
+     * ```
+     */
+    async function save(key, value) {
+        await host.host.put(host.host.createUrl(`preferences/${key}`), value);
+    }
+    preferences.save = save;
+})(exports.preferences || (exports.preferences = {}));

package/dist/preferences.js

@@ -0,0 +1,90 @@
+import { host, HomunculusApiError } from './host.js';
+
+/**
+ * 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');
+ * ```
+ */
+var preferences;
+(function (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);
+     * }
+     * ```
+     */
+    async function list() {
+        const response = await host.get(host.createUrl("preferences"));
+        return await response.json();
+    }
+    preferences.list = list;
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    async function load(key) {
+        try {
+            const response = await host.get(host.createUrl(`preferences/${key}`));
+            return await response.json();
+        }
+        catch (e) {
+            if (e instanceof HomunculusApiError && e.statusCode === 404) {
+                return undefined;
+            }
+            throw e;
+        }
+    }
+    preferences.load = load;
+    /**
+     * 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');
+     * ```
+     */
+    async function save(key, value) {
+        await host.put(host.createUrl(`preferences/${key}`), value);
+    }
+    preferences.save = save;
+})(preferences || (preferences = {}));
+
+export { preferences };

package/dist/settings.cjs

@@ -0,0 +1,46 @@
+'use strict';
+
+var host = require('./host.cjs');
+
+/**
+ * Settings API namespace for controlling application-level configuration.
+ *
+ * @example
+ * ```typescript
+ * const currentFps = await settings.fps();
+ * await settings.setFps(30);
+ * ```
+ */
+exports.settings = void 0;
+(function (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}`);
+     * ```
+     */
+    async function fps() {
+        const response = await host.host.get(host.host.createUrl("settings/fps"));
+        return Number(await response.json());
+    }
+    settings.fps = fps;
+    /**
+     * 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);
+     * ```
+     */
+    async function setFps(fps) {
+        await host.host.put(host.host.createUrl("settings/fps"), { fps });
+    }
+    settings.setFps = setFps;
+})(exports.settings || (exports.settings = {}));

package/dist/settings.js

@@ -0,0 +1,46 @@
+import { host } from './host.js';
+
+/**
+ * Settings API namespace for controlling application-level configuration.
+ *
+ * @example
+ * ```typescript
+ * const currentFps = await settings.fps();
+ * await settings.setFps(30);
+ * ```
+ */
+var settings;
+(function (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}`);
+     * ```
+     */
+    async function fps() {
+        const response = await host.get(host.createUrl("settings/fps"));
+        return Number(await response.json());
+    }
+    settings.fps = fps;
+    /**
+     * 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);
+     * ```
+     */
+    async function setFps(fps) {
+        await host.put(host.createUrl("settings/fps"), { fps });
+    }
+    settings.setFps = setFps;
+})(settings || (settings = {}));
+
+export { settings };