@hmcs/sdk 1.0.0

package/dist/shadowPanel.cjs

@@ -0,0 +1,46 @@
+'use strict';
+
+var host = require('./host.cjs');
+
+/**
+ * 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);
+ * ```
+ */
+exports.shadowPanel = void 0;
+(function (shadowPanel) {
+    /**
+     * Gets the current transparency level of the shadow panel.
+     *
+     * @returns A promise that resolves to the current alpha value (0-1)
+     */
+    async function alpha() {
+        const response = await host.host.get(host.host.createUrl("shadow-panel/alpha"));
+        return Number(await response.json());
+    }
+    shadowPanel.alpha = alpha;
+    /**
+     * 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);
+     * ```
+     */
+    async function setAlpha(alpha) {
+        await host.host.put(host.host.createUrl("shadow-panel/alpha"), {
+            alpha,
+        });
+    }
+    shadowPanel.setAlpha = setAlpha;
+})(exports.shadowPanel || (exports.shadowPanel = {}));

package/dist/shadowPanel.js

@@ -0,0 +1,46 @@
+import { host } from './host.js';
+
+/**
+ * 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);
+ * ```
+ */
+var shadowPanel;
+(function (shadowPanel) {
+    /**
+     * Gets the current transparency level of the shadow panel.
+     *
+     * @returns A promise that resolves to the current alpha value (0-1)
+     */
+    async function alpha() {
+        const response = await host.get(host.createUrl("shadow-panel/alpha"));
+        return Number(await response.json());
+    }
+    shadowPanel.alpha = alpha;
+    /**
+     * 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);
+     * ```
+     */
+    async function setAlpha(alpha) {
+        await host.put(host.createUrl("shadow-panel/alpha"), {
+            alpha,
+        });
+    }
+    shadowPanel.setAlpha = setAlpha;
+})(shadowPanel || (shadowPanel = {}));
+
+export { shadowPanel };

package/dist/signals.cjs

@@ -0,0 +1,158 @@
+'use strict';
+
+var host = require('./host.cjs');
+var eventsource = require('eventsource');
+
+/**
+ * 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();
+ * ```
+ */
+exports.signals = void 0;
+(function (signals) {
+    /**
+     * 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" });
+     * }
+     * ```
+     */
+    async function list() {
+        const response = await host.host.get(host.host.createUrl("signals"));
+        return await response.json();
+    }
+    signals.list = list;
+    /**
+     * 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(signal, f) {
+        const url = host.host.createUrl(`signals/${signal}`);
+        const es = new eventsource.EventSource(url);
+        es.addEventListener("message", async (event) => {
+            try {
+                const payload = JSON.parse(event.data);
+                await f(payload);
+            }
+            catch (error) {
+                console.error(`Error processing signal ${signal}:`, error);
+            }
+        });
+        return es;
+    }
+    signals.stream = stream;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    async function send(signal, payload) {
+        await host.host.post(host.host.createUrl(`signals/${signal}`), payload);
+    }
+    signals.send = send;
+})(exports.signals || (exports.signals = {}));

package/dist/signals.js

@@ -0,0 +1,158 @@
+import { host } from './host.js';
+import { EventSource } from 'eventsource';
+
+/**
+ * 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();
+ * ```
+ */
+var signals;
+(function (signals) {
+    /**
+     * 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" });
+     * }
+     * ```
+     */
+    async function list() {
+        const response = await host.get(host.createUrl("signals"));
+        return await response.json();
+    }
+    signals.list = list;
+    /**
+     * 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(signal, f) {
+        const url = host.createUrl(`signals/${signal}`);
+        const es = new EventSource(url);
+        es.addEventListener("message", async (event) => {
+            try {
+                const payload = JSON.parse(event.data);
+                await f(payload);
+            }
+            catch (error) {
+                console.error(`Error processing signal ${signal}:`, error);
+            }
+        });
+        return es;
+    }
+    signals.stream = stream;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    async function send(signal, payload) {
+        await host.post(host.createUrl(`signals/${signal}`), payload);
+    }
+    signals.send = send;
+})(signals || (signals = {}));
+
+export { signals };

package/dist/speech.cjs

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * 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);
+ * ```
+ */
+exports.speech = void 0;
+(function (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) {
+        return phonemes.map(([name, duration]) => {
+            if (name) {
+                return { duration, targets: { [name]: 1.0 } };
+            }
+            return { duration };
+        });
+    }
+    speech.fromPhonemes = fromPhonemes;
+})(exports.speech || (exports.speech = {}));

package/dist/speech.js

@@ -0,0 +1,48 @@
+/**
+ * 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);
+ * ```
+ */
+var speech;
+(function (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) {
+        return phonemes.map(([name, duration]) => {
+            if (name) {
+                return { duration, targets: { [name]: 1.0 } };
+            }
+            return { duration };
+        });
+    }
+    speech.fromPhonemes = fromPhonemes;
+})(speech || (speech = {}));
+
+export { speech };

package/dist/utils.cjs

@@ -0,0 +1,13 @@
+'use strict';
+
+/**
+ * Resolves after `ms` milliseconds (non-blocking delay).
+ *
+ * @example
+ *
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+exports.sleep = sleep;

package/dist/utils.js

@@ -0,0 +1,11 @@
+/**
+ * Resolves after `ms` milliseconds (non-blocking delay).
+ *
+ * @example
+ *
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export { sleep };