@hmcs/sdk 1.0.0

package/dist/commands.js

@@ -0,0 +1,296 @@
+import { writeFileSync } from 'node:fs';
+import { z } from 'zod';
+import { Vrm } from './vrm.js';
+
+/**
+ * Command script utilities for Desktop Homunculus mods.
+ *
+ * This module provides helpers for parsing stdin input and writing structured
+ * output in mod command scripts (`bin/` scripts invoked via the HTTP command
+ * execution API).
+ *
+ * **Input:** {@link input.parse} / {@link input.parseMenu} / {@link input.read}
+ * **Output:** {@link output.succeed} / {@link output.fail} / {@link output.write} / {@link output.writeError}
+ *
+ * @remarks
+ * This module uses Node.js APIs (`process.stdin`, `fs.writeFileSync`) and is
+ * not browser-compatible. Import from `@hmcs/sdk/commands` — it is intentionally
+ * not re-exported from the main `@hmcs/sdk` entry point.
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ * import { input, output, StdinParseError } from "@hmcs/sdk/commands";
+ *
+ * const schema = z.object({ name: z.string() });
+ *
+ * try {
+ *   const data = await input.parse(schema);
+ *   output.succeed({ greeting: `Hello, ${data.name}!` });
+ * } catch (err) {
+ *   output.fail("GREET_FAILED", (err as Error).message);
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Safely serialize a value to JSON. Returns a fallback error JSON string
+ * if serialization fails (e.g., circular references or BigInt values).
+ */
+function safeStringify(data) {
+    try {
+        return JSON.stringify(data);
+    }
+    catch {
+        return '{"code":"SERIALIZE_ERROR","message":"Failed to serialize output"}';
+    }
+}
+/**
+ * Error thrown by {@link input.parse} when stdin is empty, contains invalid JSON,
+ * or fails Zod schema validation.
+ *
+ * @example
+ * ```typescript
+ * import { input, StdinParseError } from "@hmcs/sdk/commands";
+ *
+ * try {
+ *   const data = await input.parse(schema);
+ * } catch (err) {
+ *   if (err instanceof StdinParseError) {
+ *     console.error(JSON.stringify({ code: err.code, message: err.message }));
+ *     process.exit(1);
+ *   }
+ *   throw err;
+ * }
+ * ```
+ */
+class StdinParseError extends Error {
+    code;
+    details;
+    name = "StdinParseError";
+    constructor(
+    /** Structured error code identifying the failure stage. */
+    code, message, 
+    /** For `VALIDATION_ERROR`, contains the `ZodError` instance. */
+    details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+    }
+}
+/**
+ * Input helpers for reading and parsing stdin in bin command scripts.
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ * import { input } from "@hmcs/sdk/commands";
+ *
+ * const data = await input.parse(
+ *   z.object({ name: z.string(), count: z.number() })
+ * );
+ * ```
+ */
+var input;
+(function (input) {
+    /**
+     * Read all of stdin as a UTF-8 string.
+     *
+     * Consumes the entire `process.stdin` stream via async iteration and returns
+     * the concatenated result. Useful when you need the raw string without JSON
+     * parsing or validation.
+     *
+     * @example
+     * ```typescript
+     * import { input } from "@hmcs/sdk/commands";
+     *
+     * const raw = await input.read();
+     * console.log("Received:", raw);
+     * ```
+     */
+    async function read() {
+        const chunks = [];
+        for await (const chunk of process.stdin) {
+            chunks.push(chunk);
+        }
+        return Buffer.concat(chunks).toString("utf-8");
+    }
+    input.read = read;
+    /**
+     * Read JSON from stdin and validate it against a Zod schema.
+     *
+     * Performs three steps:
+     * 1. Reads all of stdin via {@link input.read}
+     * 2. Parses the raw string as JSON
+     * 3. Validates the parsed object against the provided Zod schema
+     *
+     * @typeParam T - The output type inferred from the Zod schema
+     * @param schema - A Zod schema to validate the parsed JSON against
+     * @returns The validated and typed input object
+     * @throws {StdinParseError} With `code: "EMPTY_STDIN"` if stdin is empty or whitespace-only
+     * @throws {StdinParseError} With `code: "INVALID_JSON"` if stdin is not valid JSON
+     * @throws {StdinParseError} With `code: "VALIDATION_ERROR"` if the JSON does not match the schema
+     *
+     * @example
+     * ```typescript
+     * import { z } from "zod";
+     * import { input } from "@hmcs/sdk/commands";
+     *
+     * const data = await input.parse(
+     *   z.object({
+     *     entity: z.number(),
+     *     text: z.union([z.string(), z.array(z.string())]),
+     *     speaker: z.number().default(0),
+     *   })
+     * );
+     * ```
+     */
+    async function parse(schema) {
+        const raw = await read();
+        if (raw.trim().length === 0) {
+            throw new StdinParseError("EMPTY_STDIN", "No input received on stdin");
+        }
+        let json;
+        try {
+            json = JSON.parse(raw);
+        }
+        catch {
+            throw new StdinParseError("INVALID_JSON", `Invalid JSON: ${raw.slice(0, 200)}`);
+        }
+        const result = schema.safeParse(json);
+        if (!result.success) {
+            throw new StdinParseError("VALIDATION_ERROR", `Validation failed: ${result.error.message}`, result.error);
+        }
+        return result.data;
+    }
+    input.parse = parse;
+    /**
+     * Parse menu command stdin and return the linked VRM instance.
+     *
+     * Menu commands receive `{ "linkedVrm": <entityId> }` on stdin from the
+     * menu UI. This helper validates the input and returns a ready-to-use
+     * {@link Vrm} instance.
+     *
+     * @returns A {@link Vrm} instance for the linked entity
+     * @throws {StdinParseError} With `code: "EMPTY_STDIN"` if stdin is empty
+     * @throws {StdinParseError} With `code: "INVALID_JSON"` if stdin is not valid JSON
+     * @throws {StdinParseError} With `code: "VALIDATION_ERROR"` if `linkedVrm` is missing or not a number
+     *
+     * @example
+     * ```typescript
+     * import { input } from "@hmcs/sdk/commands";
+     *
+     * const vrm = await input.parseMenu();
+     * await vrm.setExpressions({ happy: 1.0 });
+     * ```
+     */
+    async function parseMenu() {
+        const parsed = await parse(z.object({ linkedVrm: z.number() }));
+        return new Vrm(parsed.linkedVrm);
+    }
+    input.parseMenu = parseMenu;
+})(input || (input = {}));
+/**
+ * Output helpers for writing structured results and errors in bin command scripts.
+ *
+ * @example
+ * ```typescript
+ * import { output } from "@hmcs/sdk/commands";
+ *
+ * output.succeed({ count: 42, status: "done" });
+ * ```
+ */
+var output;
+(function (output) {
+    /**
+     * Write a JSON-serialized result to stdout (fd 1).
+     *
+     * Serializes `data` with `JSON.stringify` and writes it followed by a newline
+     * to file descriptor 1 using synchronous I/O. This ensures the output is
+     * flushed before the process exits.
+     *
+     * @param data - The value to serialize as JSON and write to stdout
+     *
+     * @example
+     * ```typescript
+     * import { output } from "@hmcs/sdk/commands";
+     *
+     * output.write({ count: 42, status: "done" });
+     * // stdout receives: {"count":42,"status":"done"}\n
+     * ```
+     */
+    function write(data) {
+        writeFileSync(1, safeStringify(data) + "\n");
+    }
+    output.write = write;
+    /**
+     * Write a structured JSON error to stderr (fd 2).
+     *
+     * Serializes an object with `code` and `message` fields and writes it followed
+     * by a newline to file descriptor 2 using synchronous I/O.
+     *
+     * @param code - A machine-readable error code (e.g., `"NOT_FOUND"`, `"TIMEOUT"`)
+     * @param message - A human-readable error description
+     *
+     * @example
+     * ```typescript
+     * import { output } from "@hmcs/sdk/commands";
+     *
+     * output.writeError("NOT_FOUND", "Entity 42 does not exist");
+     * // stderr receives: {"code":"NOT_FOUND","message":"Entity 42 does not exist"}\n
+     * ```
+     */
+    function writeError(code, message) {
+        writeFileSync(2, JSON.stringify({ code, message }) + "\n");
+    }
+    output.writeError = writeError;
+    /**
+     * Write a JSON result to stdout and exit the process with code 0.
+     *
+     * This is a convenience wrapper that calls {@link output.write} followed by
+     * `process.exit(0)`. Use this as the final call in a successful bin command.
+     *
+     * @param data - The value to serialize as JSON and write to stdout
+     *
+     * @example
+     * ```typescript
+     * import { input, output } from "@hmcs/sdk/commands";
+     *
+     * const data = await input.parse(schema);
+     * const result = await doWork(data);
+     * output.succeed({ processed: result.count });
+     * ```
+     */
+    function succeed(data) {
+        write(data);
+        process.exit(0);
+    }
+    output.succeed = succeed;
+    /**
+     * Write a structured error to stderr and exit the process.
+     *
+     * This is a convenience wrapper that calls {@link output.writeError} followed by
+     * `process.exit(exitCode)`. Use this when a bin command encounters a fatal error.
+     *
+     * @param code - A machine-readable error code (e.g., `"NOT_FOUND"`, `"TIMEOUT"`)
+     * @param message - A human-readable error description
+     * @param exitCode - Process exit code (default: `1`)
+     *
+     * @example
+     * ```typescript
+     * import { output } from "@hmcs/sdk/commands";
+     *
+     * if (!response.ok) {
+     *   output.fail("API_ERROR", `Server returned ${response.status}`);
+     * }
+     * ```
+     */
+    function fail(code, message, exitCode = 1) {
+        writeError(code, message);
+        process.exit(exitCode);
+    }
+    output.fail = fail;
+})(output || (output = {}));
+
+export { StdinParseError, input, output };

package/dist/coordinates.cjs

@@ -0,0 +1,69 @@
+'use strict';
+
+var host = require('./host.cjs');
+
+/**
+ * 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 });
+ * ```
+ */
+exports.coordinates = void 0;
+(function (coordinates) {
+    /**
+     * 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 });
+     * ```
+     */
+    async function toWorld(viewport) {
+        const url = host.host.createUrl("coordinates/to-world", viewport);
+        const response = await host.host.get(url);
+        return await response.json();
+    }
+    coordinates.toWorld = toWorld;
+    /**
+     * 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 });
+     * ```
+     */
+    async function toViewport(world) {
+        const url = host.host.createUrl("coordinates/to-viewport", world);
+        const response = await host.host.get(url);
+        return await response.json();
+    }
+    coordinates.toViewport = toViewport;
+})(exports.coordinates || (exports.coordinates = {}));

package/dist/coordinates.js

@@ -0,0 +1,69 @@
+import { host } from './host.js';
+
+/**
+ * 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 });
+ * ```
+ */
+var coordinates;
+(function (coordinates) {
+    /**
+     * 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 });
+     * ```
+     */
+    async function toWorld(viewport) {
+        const url = host.createUrl("coordinates/to-world", viewport);
+        const response = await host.get(url);
+        return await response.json();
+    }
+    coordinates.toWorld = toWorld;
+    /**
+     * 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 });
+     * ```
+     */
+    async function toViewport(world) {
+        const url = host.createUrl("coordinates/to-viewport", world);
+        const response = await host.get(url);
+        return await response.json();
+    }
+    coordinates.toViewport = toViewport;
+})(coordinates || (coordinates = {}));
+
+export { coordinates };

package/dist/displays.cjs

@@ -0,0 +1,38 @@
+'use strict';
+
+var host = require('./host.cjs');
+
+/**
+ * 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})`);
+ * });
+ * ```
+ */
+exports.displays = void 0;
+(function (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`);
+     * ```
+     */
+    async function findAll() {
+        const response = await host.host.get(host.host.createUrl("displays"));
+        return await response.json();
+    }
+    displays.findAll = findAll;
+})(exports.displays || (exports.displays = {}));

package/dist/displays.js

@@ -0,0 +1,38 @@
+import { host } from './host.js';
+
+/**
+ * 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})`);
+ * });
+ * ```
+ */
+var displays;
+(function (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`);
+     * ```
+     */
+    async function findAll() {
+        const response = await host.get(host.createUrl("displays"));
+        return await response.json();
+    }
+    displays.findAll = findAll;
+})(displays || (displays = {}));
+
+export { displays };

package/dist/effects.cjs

@@ -0,0 +1,50 @@
+'use strict';
+
+var host = require('./host.cjs');
+
+/**
+ * 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
+ * });
+ * ```
+ */
+exports.effects = void 0;
+(function (effects) {
+    /**
+     * 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
+     * });
+     * ```
+     */
+    async function stamp(asset, options) {
+        await host.host.post(host.host.createUrl(`effects/stamps`), {
+            asset,
+            ...options,
+        });
+    }
+    effects.stamp = stamp;
+})(exports.effects || (exports.effects = {}));

package/dist/effects.js

@@ -0,0 +1,50 @@
+import { host } from './host.js';
+
+/**
+ * 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
+ * });
+ * ```
+ */
+var effects;
+(function (effects) {
+    /**
+     * 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
+     * });
+     * ```
+     */
+    async function stamp(asset, options) {
+        await host.post(host.createUrl(`effects/stamps`), {
+            asset,
+            ...options,
+        });
+    }
+    effects.stamp = stamp;
+})(effects || (effects = {}));
+
+export { effects };