@hmcs/sdk 1.0.0

package/dist/webviews.cjs

@@ -0,0 +1,310 @@
+'use strict';
+
+var host = require('./host.cjs');
+var vrm = require('./vrm.cjs');
+
+/**
+ * Returns whether webview source is local.
+ */
+function isWebviewSourceLocal(source) {
+    return source.type === "local";
+}
+/**
+ * Returns whether webview source is url.
+ */
+function isWebviewSourceUrl(source) {
+    return source.type === "url";
+}
+/**
+ * Returns whether webview source is inline-html.
+ */
+function isWebviewSourceHtml(source) {
+    return source.type === "html";
+}
+/**
+ * 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>"));
+ * ```
+ */
+exports.webviewSource = void 0;
+(function (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) {
+        return { type: "local", id };
+    }
+    webviewSource.local = local;
+    /**
+     * 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) {
+        return { type: "url", url };
+    }
+    webviewSource.url = url;
+    /**
+     * 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) {
+        return { type: "html", content };
+    }
+    webviewSource.html = html;
+})(exports.webviewSource || (exports.webviewSource = {}));
+function isWebviewSourceInfoLocal(source) {
+    return source.type === "local";
+}
+function isWebviewSourceInfoUrl(source) {
+    return source.type === "url";
+}
+function isWebviewSourceInfoHtml(source) {
+    return source.type === "html";
+}
+/**
+ * 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.
+ */
+class Webview {
+    entity;
+    constructor(entity) {
+        this.entity = entity;
+        this.entity = entity;
+    }
+    /**
+     * Closes the webview.
+     */
+    async close() {
+        await host.host.deleteMethod(host.host.createUrl(`webviews/${this.entity}`));
+    }
+    /**
+     * Checks whether this webview has been closed.
+     *
+     * @returns A promise that resolves to true if the webview is closed
+     */
+    async isClosed() {
+        const response = await host.host.get(host.host.createUrl(`webviews/${this.entity}/is-closed`));
+        return await response.json();
+    }
+    /**
+     * Gets information about this webview.
+     *
+     * @returns A promise that resolves to the webview info
+     */
+    async info() {
+        const response = await host.host.get(host.host.createUrl(`webviews/${this.entity}`));
+        return await response.json();
+    }
+    /**
+     * Patches webview properties (offset, size, viewportSize).
+     *
+     * @param options - The properties to update
+     */
+    async patch(options) {
+        await host.host.patch(host.host.createUrl(`webviews/${this.entity}`), options);
+    }
+    /**
+     * Sets the offset of the webview.
+     *
+     * @param offset - The new offset
+     */
+    async setOffset(offset) {
+        await this.patch({ offset });
+    }
+    /**
+     * Sets the size of the webview.
+     *
+     * @param size - The new size
+     */
+    async setSize(size) {
+        await this.patch({ size });
+    }
+    /**
+     * Sets the viewport size of the webview.
+     *
+     * @param size - The new viewport size
+     */
+    async setViewportSize(size) {
+        await this.patch({ viewportSize: size });
+    }
+    /**
+     * 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"));
+     * ```
+     */
+    async navigate(source) {
+        await host.host.post(host.host.createUrl(`webviews/${this.entity}/navigate`), { source });
+    }
+    /**
+     * Reloads the webview content.
+     */
+    async reload() {
+        await host.host.post(host.host.createUrl(`webviews/${this.entity}/reload`));
+    }
+    /**
+     * Navigates the webview back in history.
+     *
+     * @example
+     * ```typescript
+     * const wv = (await Webview.list())[0];
+     * await new Webview(wv.entity).navigateBack();
+     * ```
+     */
+    async navigateBack() {
+        await host.host.post(host.host.createUrl(`webviews/${this.entity}/navigate/back`));
+    }
+    /**
+     * Navigates the webview forward in history.
+     *
+     * @example
+     * ```typescript
+     * const wv = (await Webview.list())[0];
+     * await new Webview(wv.entity).navigateForward();
+     * ```
+     */
+    async navigateForward() {
+        await host.host.post(host.host.createUrl(`webviews/${this.entity}/navigate/forward`));
+    }
+    /**
+     * Gets the VRM linked to this webview.
+     *
+     * @returns The linked VRM instance, or undefined if no VRM is linked
+     */
+    async linkedVrm() {
+        const response = await host.host.get(host.host.createUrl(`webviews/${this.entity}/linked-vrm`));
+        const entity = await response.json();
+        return entity !== null ? new vrm.Vrm(entity) : undefined;
+    }
+    /**
+     * Links this webview to a VRM entity.
+     *
+     * @param vrm - The VRM to link to this webview
+     */
+    async setLinkedVrm(vrm) {
+        await host.host.put(host.host.createUrl(`webviews/${this.entity}/linked-vrm`), { vrm: vrm.entity });
+    }
+    /**
+     * Removes the VRM link from this webview.
+     */
+    async unlinkVrm() {
+        await host.host.deleteMethod(host.host.createUrl(`webviews/${this.entity}/linked-vrm`));
+    }
+    /**
+     * Gets all open webviews.
+     *
+     * @returns A promise that resolves to an array of webview info
+     */
+    static async list() {
+        const response = await host.host.get(host.host.createUrl("webviews"));
+        return await response.json();
+    }
+    /**
+     * 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 async open(options) {
+        const response = await host.host.post(host.host.createUrl(`webviews`), options);
+        return new Webview(Number(await response.json()));
+    }
+    /**
+     * 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() {
+        // @ts-expect-error -- CEF injects WEBVIEW_ENTITY on the window object
+        const entity = window.WEBVIEW_ENTITY;
+        return entity !== undefined ? new Webview(entity) : undefined;
+    }
+}
+
+exports.Webview = Webview;
+exports.isWebviewSourceHtml = isWebviewSourceHtml;
+exports.isWebviewSourceInfoHtml = isWebviewSourceInfoHtml;
+exports.isWebviewSourceInfoLocal = isWebviewSourceInfoLocal;
+exports.isWebviewSourceInfoUrl = isWebviewSourceInfoUrl;
+exports.isWebviewSourceLocal = isWebviewSourceLocal;
+exports.isWebviewSourceUrl = isWebviewSourceUrl;

package/dist/webviews.js

@@ -0,0 +1,302 @@
+import { host } from './host.js';
+import { Vrm } from './vrm.js';
+
+/**
+ * Returns whether webview source is local.
+ */
+function isWebviewSourceLocal(source) {
+    return source.type === "local";
+}
+/**
+ * Returns whether webview source is url.
+ */
+function isWebviewSourceUrl(source) {
+    return source.type === "url";
+}
+/**
+ * Returns whether webview source is inline-html.
+ */
+function isWebviewSourceHtml(source) {
+    return source.type === "html";
+}
+/**
+ * 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>"));
+ * ```
+ */
+var webviewSource;
+(function (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) {
+        return { type: "local", id };
+    }
+    webviewSource.local = local;
+    /**
+     * 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) {
+        return { type: "url", url };
+    }
+    webviewSource.url = url;
+    /**
+     * 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) {
+        return { type: "html", content };
+    }
+    webviewSource.html = html;
+})(webviewSource || (webviewSource = {}));
+function isWebviewSourceInfoLocal(source) {
+    return source.type === "local";
+}
+function isWebviewSourceInfoUrl(source) {
+    return source.type === "url";
+}
+function isWebviewSourceInfoHtml(source) {
+    return source.type === "html";
+}
+/**
+ * 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.
+ */
+class Webview {
+    entity;
+    constructor(entity) {
+        this.entity = entity;
+        this.entity = entity;
+    }
+    /**
+     * Closes the webview.
+     */
+    async close() {
+        await host.deleteMethod(host.createUrl(`webviews/${this.entity}`));
+    }
+    /**
+     * Checks whether this webview has been closed.
+     *
+     * @returns A promise that resolves to true if the webview is closed
+     */
+    async isClosed() {
+        const response = await host.get(host.createUrl(`webviews/${this.entity}/is-closed`));
+        return await response.json();
+    }
+    /**
+     * Gets information about this webview.
+     *
+     * @returns A promise that resolves to the webview info
+     */
+    async info() {
+        const response = await host.get(host.createUrl(`webviews/${this.entity}`));
+        return await response.json();
+    }
+    /**
+     * Patches webview properties (offset, size, viewportSize).
+     *
+     * @param options - The properties to update
+     */
+    async patch(options) {
+        await host.patch(host.createUrl(`webviews/${this.entity}`), options);
+    }
+    /**
+     * Sets the offset of the webview.
+     *
+     * @param offset - The new offset
+     */
+    async setOffset(offset) {
+        await this.patch({ offset });
+    }
+    /**
+     * Sets the size of the webview.
+     *
+     * @param size - The new size
+     */
+    async setSize(size) {
+        await this.patch({ size });
+    }
+    /**
+     * Sets the viewport size of the webview.
+     *
+     * @param size - The new viewport size
+     */
+    async setViewportSize(size) {
+        await this.patch({ viewportSize: size });
+    }
+    /**
+     * 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"));
+     * ```
+     */
+    async navigate(source) {
+        await host.post(host.createUrl(`webviews/${this.entity}/navigate`), { source });
+    }
+    /**
+     * Reloads the webview content.
+     */
+    async reload() {
+        await host.post(host.createUrl(`webviews/${this.entity}/reload`));
+    }
+    /**
+     * Navigates the webview back in history.
+     *
+     * @example
+     * ```typescript
+     * const wv = (await Webview.list())[0];
+     * await new Webview(wv.entity).navigateBack();
+     * ```
+     */
+    async navigateBack() {
+        await host.post(host.createUrl(`webviews/${this.entity}/navigate/back`));
+    }
+    /**
+     * Navigates the webview forward in history.
+     *
+     * @example
+     * ```typescript
+     * const wv = (await Webview.list())[0];
+     * await new Webview(wv.entity).navigateForward();
+     * ```
+     */
+    async navigateForward() {
+        await host.post(host.createUrl(`webviews/${this.entity}/navigate/forward`));
+    }
+    /**
+     * Gets the VRM linked to this webview.
+     *
+     * @returns The linked VRM instance, or undefined if no VRM is linked
+     */
+    async linkedVrm() {
+        const response = await host.get(host.createUrl(`webviews/${this.entity}/linked-vrm`));
+        const entity = await response.json();
+        return entity !== null ? new Vrm(entity) : undefined;
+    }
+    /**
+     * Links this webview to a VRM entity.
+     *
+     * @param vrm - The VRM to link to this webview
+     */
+    async setLinkedVrm(vrm) {
+        await host.put(host.createUrl(`webviews/${this.entity}/linked-vrm`), { vrm: vrm.entity });
+    }
+    /**
+     * Removes the VRM link from this webview.
+     */
+    async unlinkVrm() {
+        await host.deleteMethod(host.createUrl(`webviews/${this.entity}/linked-vrm`));
+    }
+    /**
+     * Gets all open webviews.
+     *
+     * @returns A promise that resolves to an array of webview info
+     */
+    static async list() {
+        const response = await host.get(host.createUrl("webviews"));
+        return await response.json();
+    }
+    /**
+     * 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 async open(options) {
+        const response = await host.post(host.createUrl(`webviews`), options);
+        return new Webview(Number(await response.json()));
+    }
+    /**
+     * 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() {
+        // @ts-expect-error -- CEF injects WEBVIEW_ENTITY on the window object
+        const entity = window.WEBVIEW_ENTITY;
+        return entity !== undefined ? new Webview(entity) : undefined;
+    }
+}
+
+export { Webview, isWebviewSourceHtml, isWebviewSourceInfoHtml, isWebviewSourceInfoLocal, isWebviewSourceInfoUrl, isWebviewSourceLocal, isWebviewSourceUrl, webviewSource };

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@hmcs/sdk",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for building mods and extensions for Desktop Homunculus",
+  "author": "notelm",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    },
+    "./commands": {
+      "types": "./dist/commands.d.ts",
+      "import": "./dist/commands.js",
+      "require": "./dist/commands.cjs",
+      "default": "./dist/commands.js"
+    }
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/desktop-homunculus/typescript-sdk.git",
+    "directory": "packages/sdk"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "eventsource": "^4.1.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@types/node": "^20.19.33",
+    "eslint": "^9.39.2",
+    "rimraf": "^6.1.2",
+    "rollup": "^4.57.1",
+    "rollup-plugin-dts": "^6.3.0",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "dev": "rollup -c --configPlugin typescript --watch",
+    "build": "rollup -c --configPlugin typescript",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run"
+  }
+}